docs: document all changes and web-console plan

- doc/progress.md: funcs global service v0.1.x, URLs, next steps - doc/decisions/log.md: storage architecture, funcs service decision, web-console plan - doc/api/design.md: current + planned endpoints (/source, PATCH trigger) - doc/architecture/overview.md: funcs-service component, S3 storage diagram
2026-03-18 16:38:18 +03:00
parent 38bb494ed5
commit a3528ff4fe
8 changed files with 1490 additions and 8 deletions
@@ -0,0 +1,159 @@
+# API Design
+
+Последнее обновление: 2026-03-18
+
+## Базовый URL
+
+```
+http://<operator-host>:9090/v1
+```
+
+Локально: `http://localhost:9090/v1`
+В кластере: `http://sless-operator.sless.svc.cluster.local:9090/v1`
+Публично: `https://sless.kube5s.ru/v1/...` (через Ingress)
+
+**Реализованные эндпоинты:**
+
+```
+GET    /v1/namespaces/{ns}/functions
+POST   /v1/namespaces/{ns}/functions
+GET    /v1/namespaces/{ns}/functions/{name}
+DELETE /v1/namespaces/{ns}/functions/{name}
+POST   /v1/namespaces/{ns}/functions/{name}/upload
+GET    /v1/namespaces/{ns}/triggers
+POST   /v1/namespaces/{ns}/triggers
+GET    /v1/namespaces/{ns}/triggers/{name}
+DELETE /v1/namespaces/{ns}/triggers/{name}
+GET    /v1/namespaces/{ns}/functions/{name}/invocations
+```
+
+**Запланированные эндпоинты (ветка feat/web-console):**
+
+```
+GET    /v1/namespaces/{ns}/functions/{name}/source    ← НОВЫЙ: код из S3 zip
+PATCH  /v1/namespaces/{ns}/triggers/{name}            ← НОВЫЙ: enable/disable триггера
+```
+
+**Глобальный сервис funcs (не оператор):**
+
+```
+GET    https://sless.kube5s.ru/funcs/<namespace>      ← без токена, plain text / HTML
+GET    https://sless.kube5s.ru/funcs?token=<jwt>      ← с токеном
+GET    https://sless.kube5s.ru/health                 ← liveness probe
+```
+
+## Аутентификация
+
+```
+Authorization: Bearer <cloud-token>
+```
+
+Токен — JWT от `auth-api`. Middleware в операторе:
+1. Извлекает `sub` из payload (без проверки подписи — доверяет Ingress)
+2. Вычисляет namespace: `SHA256(sub)[:8]` hex → `sless-{16 hex символов}`
+3. Проверяет что запрошенный `{namespace}` совпадает с вычисленным
+
+## Ресурсы
+
+### Functions
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| GET | /functions | Список функций |
+| POST | /functions | Создать функцию |
+| GET | /functions/{id} | Получить функцию |
+| PUT | /functions/{id} | Обновить функцию |
+| DELETE | /functions/{id} | Удалить функцию |
+
+### Versions (код функции)
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| GET | /functions/{id}/versions | Список версий |
+| POST | /functions/{id}/versions | Загрузить новый код (multipart zip) |
+| GET | /functions/{id}/versions/{ver} | Получить версию |
+| POST | /functions/{id}/versions/{ver}/activate | Активировать версию |
+
+### Triggers
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| GET | /functions/{id}/triggers | Список триггеров |
+| POST | /functions/{id}/triggers | Создать триггер (HTTP/Cron) |
+| DELETE | /functions/{id}/triggers/{tid} | Удалить триггер |
+
+### Invocations (вызов и логи)
+
+| Метод | Путь | Описание |
+|-------|------|----------|
+| POST | /functions/{id}/invoke | Синхронный вызов |
+| GET | /functions/{id}/invocations | История вызовов |
+| GET | /functions/{id}/invocations/{iid} | Детали вызова + логи |
+
+## Upload endpoint
+
+```
+POST /v1/namespaces/{namespace}/functions/{name}/upload
+Content-Type: multipart/form-data
+Authorization: Bearer <token>
+
+field: code = <zip-file>
+```
+
+Процесс:
+1. Принимает zip (max 32MB)
+2. Распаковывает zip
+3. Генерирует `Dockerfile` (`FROM naeel/sless-runtime-{runtime}:latest\nCOPY . /app/function/`)
+4. Перепаковывает в `tar.gz` (kaniko требует tar format)
+5. Загружает в S3: `contexts/{ns}/{name}/{timestamp}.tar.gz`
+6. Обновляет `fn.Spec.S3Key` → контроллер видит изменение и запускает kaniko Job
+
+Ответ `200 OK`:
+```json
+{"message": "build queued", "phase": "Pending", "s3_key": "contexts/..."}
+```
+
+## Поддерживаемые runtime (v1)
+
+- `python3.11` — реализован и протестирован
+- `go1.21` — планируется
+- `nodejs20` — планируется
+
+## Модель Function
+
+```json
+{
+  "id": "fn-uuid",
+  "name": "my-function",
+  "description": "...",
+  "runtime": "python3.11",
+  "entrypoint": "handler.handle",
+  "memory_mb": 128,
+  "timeout_sec": 30,
+  "env_vars": {"KEY": "value"},
+  "active_version": "1",
+  "status": "active",
+  "created_at": "...",
+  "updated_at": "..."
+}
+```
+
+## Модель Trigger
+
+```json
+{
+  "id": "tr-uuid",
+  "type": "http",
+  "url": "https://sless.api.ngcloud.ru/invoke/fn-uuid",
+  "created_at": "..."
+}
+```
+
+```json
+{
+  "id": "tr-uuid",
+  "type": "cron",
+  "schedule": "0 * * * *",
+  "created_at": "..."
+}
+```