diff --git a/HISTORY/docs-service-plan.md b/HISTORY/docs-service-plan.md index f9598af..b77fd29 100644 --- a/HISTORY/docs-service-plan.md +++ b/HISTORY/docs-service-plan.md @@ -64,7 +64,59 @@ GET /docs//// ## Статус -- [ ] Вынести документацию из registry -- [ ] Node.js-сервис +- [x] Вынести документацию из registry (v0.0.6) +- [ ] Node.js-сервис (отдельная репа) - [ ] Деплой + Ingress - [ ] Переписанный генератор + +--- + +# План (принципиальный) — отдельная репа + +Код — в отдельной репе, сюда только итоговый результат. + +## Принципы + +1. **Разделение по ответственности.** + - registry — только Terraform-протокол (уже сделано, v0.0.6). + - docs-сервис — только раздача статики `/docs/*`. + - S3 — только хранилище статики, prefix `docs/`. + +2. **Сервис документации = статический сервер, не приложение.** + Никакого рендеринга и шаблонов. Одна функция: URL → S3-ключ → файл. + +3. **Язык — Node.js.** + Лёгкий, быстрый, встроенный кеш, тот же S3 SDK. (nginx — запасной вариант, если не нужен код.) + +4. **Кеш обязателен.** + in-memory кеш с TTL (60–300 сек) + `Cache-Control`. Это решает исходную проблему «тормозит и кеширует». + +5. **Один домен, пути разводятся в Ingress.** + - `/docs/*` → docs-сервис + - `/.well-known/*`, `/v1/providers/*`, `/v1/proxy` → registry + Отдельный поддомен не нужен — тогда не придётся переписывать ссылки в HTML. + +6. **Доступ к S3 — те же credentials, но только к `docs/*`.** + Ключ доступа с правом чтения `docs/`, без доступа к провайдерским артефактам. + +## Соглашения из бывшего docs.go (перенести на Node) + +- S3-ключ: `docs////`; пустой `rest` → `index.html`. +- Fallback: точный путь → `<путь>/index.html` → корневой `index.html`. +- Content-Type по расширению; `index.html` → `text/html; charset=utf-8`. + +## Минимальный объём сервиса + +- `GET /docs/:ns/:name/:version/*` → S3-ключ → отдать файл + кеш. +- Dockerfile → образ в gitea → деплой. +- Ingress-правило для `/docs/*`. + +## Что отдаётся обратно в эту репу + +- Только ссылка на репу + итоговый Dockerfile/конфиг, если договоримся держать деплой-артефакты здесь. +- Сам код docs-сервиса — в отдельной репе. + +## Генератор — отдельная задача (НЕ входит в этот план) + +- Переписывается отдельно, чтобы ссылки на ассеты были корректны. +- К docs-сервису относится только как «потребитель» результата.