# ПЛАН: универсальный файловый сервис на ВМ (API)

_Дата: 2026-08-21. Статус: РЕАЛИЗОВАНО И ЗАДЕПЛОЕНО (v1.0.0), см. `README.md` сервиса `/home/naeel/nubes/vmfiles/` и `2026-08-21-vm-upload-implemented.md`._

## Цель

Один внутренний (НЕ публичный) сервис на ВМ `5.172.178.213` (`contracts.kube5s.ru`)
для приёма/временного хранения/выдачи файлов. Потребители: **drhider**, **contracts**,
**SQS IoT**. Заменяет сырой nginx-dav `/drhider-upload/` на задокументированный,
версионированный API, чтобы любому сервису было ясно, как им пользоваться.

## Потребители и режимы
- **drhider** — браузер (PUT файла) + сервер (pull). Нужен CORS для браузера.
- **contracts** — сервер-к-серверу, много файлов из локали.
- **SQS IoT** — сервер-к-серверу.

## Технология
**FastAPI + uvicorn** (Python уже есть на ВМ).
Почему FastAPI: автогенерация OpenAPI/Swagger (`/docs`) → «как юзать» видно из коробки;
нативный streaming для больших тел.

## API v1 (контракт)

| Метод | Путь | Вход | Ответ |
|---|---|---|---|
| `POST` | `/api/v1/files` | тело=файл (raw или multipart `file`), header `X-App-Key` | `201 {"id","url","size","expires_at"}` |
| `GET` | `/api/v1/files/{id}` | header `X-App-Key` | байты файла |
| `DELETE` | `/api/v1/files/{id}` | header `X-App-Key` | `204` |
| `GET` | `/api/v1/health` | — | `{"ok":true,"version":...}` |
| `GET` | `/api/v1/docs` | — | Swagger UI (авто) |

Единые ошибки: `{"error": "...", "code": "unauthorized|not_found|too_large|expired|quota_exceeded"}`.

## Авторизация
Заголовок `X-App-Key`, по одному секрету на приложение. Ключи — в конфиге на ВМ
(файл `apps.yml`/`.env`): `drhider`, `contracts`, `sqs-iot`. Без валидного ключа — `401`.

## Хранилище и метаданные
- Файлы: `/var/lib/vmfiles/` (или `/var/www/vmfiles/`, владелец — пользователь сервиса).
- Метаданные: SQLite (`id, app, name, size, created_at, expires_at`).
- id — серверный UUID (или клиентский токен — см. «открытые вопросы»).

## Лимиты и TTL
- `max_file_size` (по умолчанию 1024m) и `quota` на приложение.
- TTL по умолчанию 30 мин (на приложение можно переопределить).
- Чистка — встроенная фоновая задача сервиса (вместо текущего cron-`find`).

## Деплой на ВМ
1. Код сервиса — в отдельной папке на ВМ (или отдельный репозиторий).
2. systemd-юнит `vmfiles.service` → `uvicorn app:app --host 127.0.0.1 --port 8769`.
3. nginx: новый `location /api/v1/ { proxy_pass http://127.0.0.1:8769; ... }`
   + `proxy_request_buffering off` (стримить большие тела) + `client_max_body_size 1024m`.
   CORS — отдать сервису (FastAPI), не nginx.
4. Проверка: `nginx -t` → reload.

## Миграция drhider
- Пока сервис поднимается — `/drhider-upload/` оставить как есть (не ломать текущее).
- После готовности — перевести `uploadFiles()` и `/api/upload_refs` на `/api/v1/files`,
  убрать dav-location и cron-`find`.

## Порядок работ
1. Скелет FastAPI + health + `/docs`.
2. `POST/GET/DELETE /files` + SQLite-метаданные + TTL-чистка.
3. `X-App-Key` авторизация + квоты.
4. systemd + nginx `proxy_pass`.
5. Тесты: curl (raw + multipart), большие файлы, expiry, quota.
6. Перевести drhider на новый API, выпилить старый dav.
7. Документ-спека (`README`/`API.md`) + примеры для contracts/SQS.

## Открытые вопросы (до «делай»)
1. Язык: FastAPI (рекомендую) или Flask?
2. id файла: сервер генерирует (POST) или клиент приносит токен (PUT)? Влияет на браузерный поток drhider.
3. Загрузка: только raw-тело или поддерживать multipart тоже?
4. Где живёт код сервиса — отдельный репозиторий на gitea или папка на ВМ?
5. Ключи приложений — придумать сейчас или сервис сгенерирует при первом старте?