#Интеграция с Nexus Repository

OSA Proxy поддерживает статические маршруты к Sonatype Nexus Repository Manager 3 и автоматическое обнаружение репозиториев через Nexus inventory API. На этой странице собраны настройка discovery, формирование клиентских URL, передача repository context и особенности ответов о блокировке.

#Автоматическое обнаружение репозиториев

Runtime discovery получает список репозиториев Nexus и создаёт для подходящих записей динамические маршруты. Репозитории не нужно перечислять по одному в статических секциях npm, maven, pypi и других экосистем.

Обнаружение выполняется при запуске и затем периодически. Для каждого repository OSA Proxy определяет экосистему, строит upstream URL и применяет первое подходящее правило из repository-routing.

#Требования к доступу

Создайте техническую учётную запись, которой разрешены GET /service/rest/v1/repositories и просмотр репозиториев, которые должны попасть в inventory. Nexus discovery использует Basic auth.

В следующей команде NEXUS_BASE_URL — корневой URL без path, например https://nexus.example.com:

curl --fail --user "$NEXUS_USERNAME:$NEXUS_PASSWORD" \
  "$NEXUS_BASE_URL/service/rest/v1/repositories"

Credentials discovery-клиента используются только для inventory API. OSA Proxy не добавляет их автоматически в запросы пакетов к найденным upstream-репозиториям. Доступ к приватным пакетам настройте отдельно, например через входящие credentials клиента, anonymous read или доверенный reverse proxy.

#Конфигурация discovery

nexus:
  enabled: true
  base-url: https://nexus.example.com
  username: ${NEXUS_USERNAME:}
  password: ${NEXUS_PASSWORD:}
  route-mode: native
  repository-types:
    - proxy
    - group
  refresh:
    interval: 1m
  repository-routing:
    - name: npm-consumers
      package-type: npm
      name-regex: '^npm-.*$'
      scan-manifest: true
      scan-package: true
      remove-blocked-versions: true
      work-mode: strict_wait
      url-encoded-config: true
      file-type-filter: {}
    - name: swift-consumers
      package-type: swift
      name-regex: '^swift-.*$'
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait

base-url должен быть корневым URL Nexus без path, query и fragment. Для включённого discovery обязательны оба поля username и password.

Допустимые classes в repository-types: hosted, proxy, group.

#Выбор репозиториев

Для каждого package type требуется отдельное правило. Wildcard в package-type не поддерживается.

Чтобы подключить все репозитории одного типа, опустите name-regex:

repository-routing:
  - name: all-npm
    package-type: npm
    scan-manifest: true
    scan-package: true

Для фильтрации по имени используется Go regexp (RE2), а не glob. Рекомендуется ставить якоря ^ и $:

repository-routing:
  - name: team-a-npm
    package-type: npm
    name-regex: '^team-a-npm-(proxy|group)$'

Правила одного package type проверяются сверху вниз. Если repository соответствует нескольким правилам, применяется первое. Узкие regexp размещайте выше общего fallback-правила.

Поля scan-manifest, scan-package, remove-blocked-versions, work-mode, url-encoded-config, distro и file-type-filter имеют тот же смысл, что и в статической конфигурации экосистемы. Неподдерживаемая комбинация приводит к ошибке конфигурации или отклонению discovery snapshot.

#Поддерживаемые форматы

Nexus discovery поддерживает:

npm, maven, nuget, pypi, composer, cocoapods, swift, ruby, r, conan, go, debian, rpm.

Форматы Nexus нормализуются следующим образом:

docker, raw, bower, Hex и неизвестные форматы пропускаются. Swift discovery требует Nexus Repository с поддержкой формата Swift.

#Клиентские маршруты

При route-mode: native найденный repository публикуется по пути /repository/{name}. Например:

https://osa-proxy.example.com/repository/npm-proxy/

Клиенту или reverse proxy достаточно заменить host Nexus на host OSA Proxy, сохранив path.

При route-mode: flat используется /{name}. Поле route-prefix в отдельном routing rule имеет приоритет над route-mode; итоговый путь имеет вид /{route-prefix}/{name}.

Статические маршруты из секций экосистем имеют наивысший приоритет. Если путь найденного repository конфликтует со статическим маршрутом, динамический маршрут пропускается, а остальные найденные репозитории продолжают работать.

Artifactory и Nexus можно включить одновременно. В native-режиме одинаковые repository names обычно не конфликтуют:

/artifactory/api/npm/shared
/repository/shared

Одинаковые или вложенные пути разных dynamic managers считаются конфликтом. Новый snapshot в этом случае отклоняется, а OSA Proxy продолжает использовать последние успешно построенные динамические маршруты.

#Repository context в URL

Параметр url-encoded-config: true разрешает передать в запросе URL-safe Base64 metadata с адресом repository manager, именем repository и пользователем. Это нужно для применения политик CodeScoring, привязанных к конкретному Nexus repository context.

Для native route encoded-сегмент размещается после полного repository path:

/repository/npm-proxy/{base64-context}/{package-path}

Формат объекта и примеры кодирования описаны в разделе Настройка Base64 URL.

#Ответы о блокировке

Nexus получает HTTP-код из codescoring.block-status-code вместо 404. При codescoring.enable-status-line: true причина блокировки добавляется в HTTP/1.1 status line, как в плагине Nexus.

Status line поддерживает только ASCII и отсутствует в HTTP/2 и HTTP/3. Если пользователь должен увидеть причину блокировки, задайте codescoring.block-message ASCII-строкой, например Component download blocked by security policy.

Если HTTP-код правильный, но причина не отображается, проверьте reverse proxy перед Nexus. Traefik, nginx или ingress controller не должен перезаписывать HTTP/1.1 status line.

#Обновление и диагностика

Первый inventory sync выполняется при старте. Последующие sync запускаются через refresh.interval с jitter до 10%. Новые и удалённые репозитории подхватываются без перезапуска.

При ошибке HTTP, декодирования или построения маршрутов OSA Proxy сохраняет последний успешный snapshot. Успешный пустой inventory удаляет все динамические маршруты Nexus. Snapshot хранится только в памяти; после рестарта при недоступном Nexus доступны только статические маршруты.

Endpoint /healthz проверяет процесс OSA Proxy, но не состояние discovery. Используйте метрики:

• nexus_discovery_syncs_total;
• nexus_discovery_sync_duration_seconds;
• nexus_discovery_last_success_timestamp_seconds;
• nexus_discovery_active_repositories;
• nexus_discovery_repository_changes_total.

curl --fail http://localhost:8080/metrics \
  | grep '^nexus_discovery_'

Настройка второго поддерживаемого manager описана в разделе Интеграция с JFrog Artifactory.