Merge branch 'osa_proxy_52' into 'master'

changelog for osa-proxy-2025-52-0

See merge request CodeScoring/docs!569

Author: amaksimovv

docs/changelog/proxy-changelog.en.md

@@ -5,6 +5,21 @@ hide:
 
 # OSA Proxy Changelog
 
+### [2025.52.0] - 2025-12-23
+
+#### Added
+
+- Added caching of policy checking results in Redis with TTL and background refresh support. See [documentation](/osa-proxy/config-caching.en)
+- Added a proactive cache refresh mechanism based on a timer
+- Added Swagger UI for API documentation (`/api/swagger`)
+- Added REST API for cache management (`/api/cache`)
+- Added header updates (`Last-Modified`, `ETag`) for manifests. This ensures manifests stay up to date with the latest security policies
+
+#### Changed
+
+- Increased default value of `max-in-memory-size` config variable from 50MB to 150MB (for processing large manifests)
+- Optimized NPM manifest processing using a stream processor to increase processing speed for large files and reduce garbage collector load
+
 ### [2025.48.3] - 2025-12-08
 
 #### Fixed

docs/changelog/proxy-changelog.md

@@ -5,6 +5,21 @@ hide:
 
 # OSA Proxy Changelog
 
+### [2025.52.0] - 2025-12
+
+#### Добавлено
+
+- Добавлено кэширование результатов проверки политик в Redis с поддержкой TTL и фонового обновления. Подробнее в [документации](/osa-proxy/config-caching)
+- Добавлен механизм проактивного обновления кэша по таймеру
+- Добавлен Swagger UI для документации API (`/api/swagger`)
+- Добавлен REST API для управления кэшем (`/api/cache`)
+- Добавлено обновление заголовков (`Last-Modified`, `ETag`) для манифестов. Это решает проблему "устаревших" манифестов, с точки зрения политик.
+
+#### Изменено
+
+- Увеличено значение по умолчанию для переменной конфигурации `max-in-memory-size` с 50MB до 150MB (для обработки больших манифестов)
+- Оптимизирована обработка манифестов NPM с использованием потокового процессора для повышения скорости обработки больших файлов и снижения нагрузки для сборщика мусора
+
 ### [2025.48.3] - 2025-12-08
 
 #### Исправлено

docs/osa-proxy/config-caching.en.md

@@ -0,0 +1,43 @@
+---
+hide:
+  - footer
+---
+
+# Redis and сaching сonfiguration
+
+To improve performance and reduce load on the CodeScoring platform, caching of policy checking results ([Judge service](/on-premise/containers-description.en/)) is supported. Caching requires a Redis connection.
+
+!!! example "Redis and Caching Settings"
+
+    ```yaml
+    spring:
+      data:
+        redis:
+          host: localhost
+          port: 6379
+          database: 0         # Database number (optional)
+          password: password  # Optional
+          timeout: 2000ms
+
+    cache:
+      judge:
+        enabled: true  # Enable caching (default is false)
+        ttl: 24h       # Time-to-live for cache entries
+        refresh-after: 30m  # Time after which an entry is considered stale and needs refresh (but can still be served from cache)
+        proactive-refresh-enabled: true # Enable proactive (background) cache refresh
+        proactive-refresh-interval: 2h  # Interval for background refresh task
+        key-prefix: "cs:judge:" # Prefix for Redis keys
+    ```
+
+!!! note "Cache TTL prolongation specifics"
+
+    Proactive refresh does not prolong the TTL (time-to-live) of a cache entry. The TTL is only extended when data is read from the cache by actual user requests. This ensures that only frequently requested components remain in the cache, while rarely used ones are automatically removed from Redis.
+
+## Swagger UI
+
+OSA Proxy provides Swagger UI for API documentation and cache management.
+
+- **URL:** `http://<osa-proxy-host>:<port>/api/swagger`
+- **Available operations:**
+    - Clear cache by PURL
+    - Clear cache by package type

docs/osa-proxy/config-caching.md

@@ -0,0 +1,43 @@
+---
+hide:
+  - footer
+---
+
+# Настройка Redis и кэширования
+
+Для повышения производительности и снижения нагрузки на платформу CodeScoring поддерживается кэширование результатов работы политик (вердиктов [сервиса Judge](/on-premise/containers-description/)). Для работы кэширования требуется подключение к Redis.
+
+!!! example "Настройки Redis и кэширования"
+
+    ```yaml
+    spring:
+      data:
+        redis:
+          host: localhost
+          port: 6379
+          database: 0         # Номер базы данных (опционально)
+          password: password  # Опционально
+          timeout: 2000ms
+
+    cache:
+      judge:
+        enabled: true  # Включение кэширования (по умолчанию false)
+        ttl: 24h       # Время жизни записи в кэше
+        refresh-after: 30m  # Время, после которого запись считается устаревшей и требует обновления (но все еще может быть отдана из кэша)
+        proactive-refresh-enabled: true # Включение проактивного (фонового) обновления кэша
+        proactive-refresh-interval: 2h  # Интервал запуска фонового обновления
+        key-prefix: "cs:judge:" # Префикс для ключей в Redis
+    ```
+
+!!! note "Особенности продления времени жизни (TTL) в кэше"
+
+    Проактивное обновление не продлевает TTL (время жизни) записи в кэше. TTL продлевается только при чтении данных из кэша реальными запросами пользователей. Это позволяет автоматически удалять из Redis редко запрашиваемые пакеты и хранить только востребованные данные.
+
+## Swagger UI
+
+OSA Proxy предоставляет Swagger UI для просмотра документации API и управления кэшем.
+
+- **URL:** `http://<osa-proxy-host>:<port>/api/swagger`
+- **Доступные операции:**
+    - Очистка кэша по PURL
+    - Очистка кэша по типу пакета

docs/osa-proxy/config.en.md

@@ -158,7 +158,7 @@ Configuration of **OSA Proxy** is done via the `application.yml` file:
     spring:
       http:
         codecs:
-          max-in-memory-size: 50MB (this is the default setting, already included in the application; increase it if you encounter very large manifests)
+          max-in-memory-size: 150MB (this is the default setting, already included in the application; increase it if you encounter very large manifests)
     ```
 
 ## Retry policies and circuit breaker for platform requests

docs/osa-proxy/config.md

@@ -162,7 +162,7 @@ hide:
     spring:
       http:
         codecs:
-          max-in-memory-size: 50MB (это настройка по умолчанию, уже включенная в приложение, увеличьте ее, если вы столкнулись с очень большими манифестами)
+          max-in-memory-size: 150MB (это настройка по умолчанию, уже включенная в приложение, увеличьте ее, если вы столкнулись с очень большими манифестами)
     ```
 
 ## Политики повторных попыток и circuit breaker для запросов к платформе:

docs/osa-proxy/index.en.md

@@ -51,6 +51,10 @@ OSA Proxy automatically modifies responses from original repositories:
 - Removes blocked versions from metadata;
 - Recalculates checksums of modified manifests to maintain the correct format.
 
+### Policy results caching
+
+To speed up request processing and reduce platform load, policy validation results (verdicts from [Judge service](/on-premise/containers-description.en/)) are cached in Redis. Background updates of outdated records are supported.
+
 ## Work modes
 
 Package scanning behavior is controlled by the `work-mode` parameter. Depending on the selected value, the scanning, waiting, and blocking logic changes. The following modes are supported:

docs/osa-proxy/index.md

@@ -51,6 +51,10 @@ OSA Proxy автоматически модифицирует ответы от
 - удаляет заблокированные версии из метаданных;
 - пересчитывает контрольные суммы изменённых манифестов, чтобы сохранить корректность формата.
 
+### Кэширование результатов проверки политик
+
+Для ускорения обработки запросов и снижения нагрузки на платформу поддерживается кэширование результатов проверки политик (вердиктов [сервиса Judge](/on-premise/containers-description/) в Redis. Поддерживается фоновое обновление устаревших записей.
+
 ## Режимы работы
 
 Поведение сканирования пакетов регулируется параметром `work-mode`. В зависимости от выбранного значения меняется логика обработки сканирования, ожидания и блокировки. Поддерживаются следующие режимы:

docs/osa-proxy/protocols.en.md

@@ -110,6 +110,28 @@ This section contains data formats and response modification rules for each supp
   ]
 }
 ```
+
+## Go
+
+### Processed files
+
+- Version list (`/@v/list`)
+- `.zip` — module archives
+
+### Version list modifications
+
+- Blocked versions are removed from the version list
+
+## Debian
+
+### Processed files
+
+- `.deb` — package files
+
+!!! warning "Debian scanning specifics"
+
+    For Debian, only package scanning is supported. Modification of manifests (`Packages` files) is not performed.
+
 ## Behavior in case of complete package blocking
 
 In a scenario where all available versions of a requested package are blocked by security policies, OSA Proxy returns a message indicating that all versions are blocked.
@@ -139,4 +161,10 @@ curl http://localhost:8080/codescoring-npm/package_name
 Although the NuGet client might display the reason for blocking all packages in the console, a direct `curl` request also allows for status confirmation:
 ```bash
 curl http://localhost:8080/codescoring-nuget/nuget-api/v3/registration5-gz-semver2/newtonsoft.json/index.json
+```
+
+### Go
+
+```bash
+curl http://localhost:8080/codescoring-go/module_name/@v/list
 ```

docs/osa-proxy/protocols.md

@@ -111,6 +111,28 @@ hide:
   ]
 }
 ```
+
+## Go
+
+### Обрабатываемые файлы
+
+- Список версий (`/@v/list`)
+- `.zip` — архивы модулей
+
+### Модификация списка версий
+
+- Из списка версий удаляются заблокированные версии.
+
+## Debian
+
+### Обрабатываемые файлы
+
+- `.deb` — файлы пакетов
+
+!!! warning "Особенности сканирования Debian"
+
+    Для Debian поддерживается только сканирование пакетов. Модификация манифестов (файлов `Packages`) не производится.
+
 ## Поведение при полной блокировке пакета
 
 В случае, когда все доступные версии запрашиваемого пакета заблокированы политиками безопасности, OSA Proxy возвращает сообщение о блокировке всех версий.
@@ -141,3 +163,9 @@ curl http://localhost:8080/codescoring-npm/имя_пакета
 ```bash
 curl http://localhost:8080/codescoring-nuget/nuget-api/v3/registration5-gz-semver2/newtonsoft.json/index.json
 ```
+
+### Go
+
+```bash
+curl http://localhost:8080/codescoring-go/имя_модуля/@v/list
+```