docs: план отдельного сервиса документации (принципы, отдельная репа)

2026-09-02 07:45:37 +03:00
parent c3e75f11d6
commit 391223e61e
1 changed files with 54 additions and 2 deletions
@@ -64,7 +64,59 @@ GET /docs/<namespace>/<name>/<version>/<rest>

 ## Статус

- [ ] Вынести документацию из 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/<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-сервису относится только как «потребитель» результата.