docs: убрать документацию из registry (оставить только провайдеры), v0.0.6

2026-09-02 07:34:18 +03:00
parent 5e81c06124
commit c3e75f11d6
3 changed files with 71 additions and 116 deletions
@@ -0,0 +1,70 @@
+# План: отдельный сервис документации (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
+- [ ] Node.js-сервис
+- [ ] Деплой + Ingress
+- [ ] Переписанный генератор