tf_registry/HISTORY/docs-service-plan.md

План: отдельный сервис документации (Node.js)

Целевая архитектура

S3 (nubes-terraform-registry)  — статика документации, только docs/*
Node.js-сервис                 — раздаёт /docs/* + кеш с TTL
registry (Go)                  — только Terraform-протокол:
                                 /.well-known/*, /v1/providers/*, /v1/proxy

Что выносится из registry

• Маршрут /docs/ и функция docsHandler (удаляются из server/main.go и server/docs.go).
• Провайдерская логика (discoveryHandler, router, proxyHandler, rootHandler, healthz/readyz) — НЕ меняется.

Соглашения для сервиса документации (перенос из бывшего server/docs.go)

Файл docs.go не является уникальным активом; он описывает обычный маппинг URL → S3-ключ. При переносе на Node.js достаточно воспроизвести три правила:

1. Формат S3-ключей документации:

   docs/<namespace>/<name>/<version>/<rest>
   при пустом rest → docs/<namespace>/<name>/<version>/index.html
   

2. Fallback-цепочка при неизвестном пути: точный путь → <путь>/index.html (если путь похож на каталог) → корневой index.html.

3. Content-Type: через mime.TypeByExtension; fallback на text/html; charset=utf-8 для index.html/.html, иначе application/octet-stream.

4. Добавить то, чего в сервисе документации будет больше, чем в docs.go: in-memory кеш с TTL (например, 60–300 сек) и заголовок Cache-Control.

Endpoint Node.js-сервиса

GET /docs/<namespace>/<name>/<version>/<rest>

Переменные окружения (общие с registry)

• S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY (точки доступа — как в secrets/env.txt).

DNS / Ingress

• /docs/* → Node.js-сервис.
• /.well-known/*, /v1/providers/*, /v1/proxy → registry.
• Тот же домен tf-registry.containerk8s.services.ngcloud.ru, пути разводятся в Ingress. (При отдельном поддомене потребуется переписывать ссылки в HTML.)

Порядок работ

1. Вынести /docs/ из registry (этот шаг).
2. Написать Node.js-сервис (маппинг + кеш + Content-Type).
3. Dockerfile + образ в gitea + деплой сервиса.
4. Ingress-правило для /docs/*.
5. Переписать генератор документации под новые соглашения (отдельная задача).
6. Smoke-тесты: HTML 200, CSS/JS 200, ссылки валидны.

Статус

• Вынести документацию из 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/<ns>/<name>/<version>/<rest>; пустой 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-сервису относится только как «потребитель» результата.