# План: отдельный сервис документации (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-сервису относится только как «потребитель» результата.