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