71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# План: отдельный сервис документации (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
|
||
- [ ] Переписанный генератор
|