ADR 0028 — Композиция SDK с сохранением публичного API
Статус: принято. Дата: 2026-09-25.
Контекст
Аудит выявил 984 строки кода в SDK transport и 921 в его классе. Один класс совмещал HTTP, авторизацию запросов, каталог, управление доступом и алгоритмы передачи. Добавление новых интеграций увеличивало эту концентрацию ответственности. Требуется сохранить существующих потребителей и поведение при сетевых отказах.
Решение
ArkvoryClient — явный facade с композицией вместо наследования от универсального транспорта. Его 68 прежних методов остаются доступны; identity, administration и inRepository() сохраняют свои имена и типы. Forwarders используют Parameters ответственного модуля, чтобы не дублировать сигнатуры реализации.
Внутри одного workspace выделены discovery, identity, users/groups, service accounts/policies, credentials/delegations, catalog, assets, storage/retention, upload operations, upload workflow и download workflow. Эти модули не становятся самостоятельными пакетами или публичными точками импорта. SDK по-прежнему зависит только от contracts и стандартных браузерных API.
Общий HttpPort содержит только request, bounded JSON parsing и JSON call. HttpTransport централизует формирование URL/заголовков, получение текущего credential, запрет redirects, AbortSignal и нормализацию ошибок. Он не знает о репозиториях, ролях или бизнес-операциях. Авторизация остаётся серверной; namespace клиента не является границей безопасности.
Настройки повторов валидируются один раз. Повторяются только прежние безопасные transfer-сценарии; метаданные и выдача секретов не получают автоматических повторов. Upload workflow получает узкий порт status/parts/complete, download workflow — artifact. В composition root эти порты реализует facade, сохраняя прежнее поведение переопределённых публичных методов. HTTP и алгоритмы Range/checksum/backpressure не дублируются.
Последствия и проверка
Удаляются исключения ARCH-012 и ARCH-013; новые модули соблюдают общие лимиты 500/300/100 без новых исключений. Декомпозиция не меняет HTTP-контракт, права, схему БД, публикацию пакета SDK или гарантии HA.
tests/fixtures/sdk-legacy.d.ts — снимок публичных методов из собранного SDK на 81703c5. Строгий TS consumer компилируется через публичный package export; сравниваются ключи, аргументы, результаты и конструктор. Снимок нельзя автоматически переписывать ради прохождения теста. Изменение внешнего контракта требует отдельного review. Совместимость private/deep imports и рефлексии над внутренними классами не является публичным контрактом.
HTTP-регрессии проверяют deployment prefix, кодирование идентификаторов, обновление credential, запрет его передачи по redirect, безопасные ошибки и сохранение override hooks. Существующие fault tests проверяют обрывы, тайм-ауты, отмену, потерянные ответы, Range и целостность. Приёмка проходит через quick и release: реальные PostgreSQL/HTTP, браузер и оба сценария 5 GiB. Это не заменяет отложенную двухсерверную приёмку.