123 lines
6.1 KiB
Markdown
123 lines
6.1 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, ссылки валидны.
|
||
|
||
## Статус
|
||
|
||
- [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/<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-сервису относится только как «потребитель» результата.
|