Initial commit: Hermes skill fastapi-microservice

2026-09-29 09:15:08 +00:00 · 2026-09-06 13:51:25 +00:00
commit fb163f07d4
2 changed files with 261 additions and 0 deletions
@@ -0,0 +1,171 @@
+---
+name: fastapi-microservice
+description: "Bootstrap FastAPI: SQLAlchemy, auth, Docker, one-pass build."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: [fastapi, microservice, bootstrap, backend, python, docker]
+    related_skills: [task-list-execution, writing-plans]
+---
+
+# FastAPI Microservice Bootstrap
+
+## When to Use
+
+The user asks to create a new FastAPI-based microservice. Signals:
+
+- "создай каталог /opt/xxx, спланируем и напишем сервис"
+- "нужен сервис для X с API на FastAPI"
+- "bootstrap a new API service for Y"
+- Any request where the output is a Python/FastAPI server with routes, database, and external integration
+
+## Core Rules
+
+### 1. No analysis preamble — start immediately
+
+The user says "создай каталог и спланируем" — your first action is to create the directory. Do not:
+
+- ❌ Summarize the requirement back to them
+- ❌ Ask clarifying questions about scope
+- ❌ Propose technology choices for approval
+- ❌ Write a multi-step plan document before coding
+
+✅ Instead: `mkdir -p /opt/project/app` → start writing files
+
+**Investigation is part of execution, not preparation.** If you need to check Python version, installed packages, or port availability, do it as the first action of writing code, not as a preamble.
+
+### 2. Build in layers, bottom-up
+
+Write files in this order for maximum efficiency:
+
+```
+Layer 1 — Foundation
+  ├── requirements.txt
+  ├── .env.example
+  ├── __init__.py files (empty, create dirs)
+  ├── app/config.py           # pydantic-settings from env
+  ├── app/security.py         # encryption, key generation
+  ├── app/database.py         # async engine + session
+  └── app/models.py           # ORM models (User, Account, etc.)
+
+Layer 2 — Business logic
+  ├── app/converters/         # domain-specific converters
+  └── app/vk_client.py        # external API clients
+
+Layer 3 — API
+  ├── app/api/schemas.py      # Pydantic request/response
+  ├── app/api/deps.py         # auth dependencies
+  └── app/api/v1.py           # route handlers
+
+Layer 4 — Entry point
+  └── app/main.py             # FastAPI app + lifespan
+
+Layer 5 — Infrastructure
+  ├── Dockerfile
+  ├── docker-compose.yml
+  ├── Makefile
+  └── .gitignore
+```
+
+### 3. Generate secrets and verify immediately
+
+After writing code, do NOT stop at "code is written". Do:
+
+1. Generate encryption key: `python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" > secrets/token_encryption_key`
+2. Install deps: `pip install -r requirements.txt`
+3. Verify all modules import: `python3 -c "from app import ..."`
+4. Start server and test: curl health endpoint
+5. Test at least one API endpoint (e.g. convert endpoint if it's a converter service)
+
+### 4. Write all project files in one pass
+
+Do not save README.md and STATUS.md separately from code. Write them last, after the code compiles and runs:
+
+- **README.md** — API reference, usage examples, security, run instructions
+- **STATUS.md** — implementation status table, phases, architecture diagram, how to run
+- **Dockerfile** — multi-stage, slim, read-only rootfs, non-root user
+- **docker-compose.yml** — service + volume + secret + healthcheck
+- **Makefile** — dev/install/run/test/key/user commands
+
+### 5. Security by default
+
+Every microservice needs:
+
+- **Encrypted secrets** — Fernet (AES-128-CBC + HMAC-SHA256), key from file/secret, NOT in code
+- **API key auth** — sha256 hashed, not stored in plaintext
+- **API key ≠ external token** — the API key lets you *use* the service, not read the upstream token
+- **Minimal scope** — upstream tokens should have minimal permissions (e.g. VK wall scope only)
+- **Docker read-only rootfs** — only /data writable
+- **Non-root user** in Docker container
+
+Log these in README.md as a security matrix table.
+
+## Expected File Structure
+
+```
+/opt/<project-name>/
+├── app/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   ├── database.py
+│   ├── models.py
+│   ├── security.py
+│   ├── vk_client.py          # or external_api.py
+│   ├── converters/
+│   │   ├── __init__.py
+│   │   └── markdown_to_vk.py # or relevant converter
+│   └── api/
+│       ├── __init__.py
+│       ├── schemas.py
+│       ├── deps.py
+│       └── v1.py
+├── tests/
+│   └── (TODO after code)
+├── secrets/
+│   └── token_encryption_key  # NOT in git (.gitignore it)
+├── Dockerfile
+├── docker-compose.yml
+├── requirements.txt
+├── .env.example
+├── .gitignore
+├── Makefile
+├── README.md
+└── STATUS.md
+```
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Writing README before code runs | Write docs last — they reflect what's real |
+| Asking for approval on every file | Write all files in one batch, then verify |
+| Skipping security docs | Include security matrix table in README |
+| Not testing the API after writing code | Always start server and curl at least health + one endpoint |
+| Using `&` in foreground terminal command | Use `terminal(background=True)` for server, then `curl` |
+| Hand-typing code that could be written | Batch independent file writes in the same turn |
+| Explaining the design before building | Say "Начинаю" and write files — the code IS the design |
+
+## Verification Checklist
+
+After writing all code:
+
+- [ ] `pip install -r requirements.txt` succeeds
+- [ ] All modules import: `python3 -c "from app import config, database, models, security, ..."`
+- [ ] Encryption key generated and stored in secrets/
+- [ ] Encrypt/decrypt round-trip works
+- [ ] API keys generate and verify
+- [ ] Converter (if any) produces correct output
+- [ ] Server starts: `uvicorn app.main:app --host 0.0.0.0 --port N`
+- [ ] `GET /api/v1/health` returns `{"status":"ok"}`
+- [ ] At least one POST endpoint responds correctly (e.g. convert or account create)
+- [ ] Swagger UI at `/docs` returns 200
+- [ ] Dockerfile builds (if docker is available)
+
+## Related Skills
+
+- **task-list-execution** — for executing tasks from STATUS.md files
+- **writing-plans** — for multi-step implementation plans with subagent delegation
@@ -0,0 +1,90 @@
+# md2vk — FastAPI microservice example
+
+**Project:** VK wall publisher — converts Markdown to VK format_data, publishes via VK API.
+**Pattern:** FastAPI + async SQLAlchemy + SQLite + Fernet-encrypted tokens + external API client.
+
+## Architecture decisions
+
+| Decision | Choice | Why |
+|----------|--------|-----|
+| Database | SQLite + aiosqlite | Lightweight, no external deps, fits Docker |
+| ORM | SQLAlchemy 2.0 async | Async-first, well-typed, portable |
+| Token encryption | Fernet (cryptography) | AES-128-CBC + HMAC, simple API, key from file |
+| Auth | API key (sha256 hash) | API key !== VK token, token never leaves encrypted storage |
+| Markdown conversion | Custom parser | VK format_data is a niche JSON format, no lib exists |
+| HTTP client | httpx | Async, modern, timeouts by default |
+| VK API scope | wall only | Minimal permissions — can't read DMs, photos, etc. |
+
+## Layer structure
+
+```
+app/config.py          → pydantic-settings, reads TOKEN_ENCRYPTION_KEY_FILE
+app/security.py        → Fernet encrypt/decrypt + sha256 API key hash
+app/database.py        → create_async_engine, async_sessionmaker, init_db()
+app/models.py          → User, VkAccount, Publication (SQLAlchemy 2.0 mapped)
+app/vk_client.py       → VkClient class: wall.post, users.get, check_token()
+app/converters/        → markdown_to_vk(): returns list of chunks with FormatItem[]
+app/api/schemas.py     → 12 Pydantic models (Request/Response)
+app/api/deps.py        → get_current_user_from_header(), get_user_by_api_key()
+app/api/v1.py          → 6 endpoints: health, accounts CRUD, publish, convert, publications
+app/main.py            → FastAPI() + lifespan (init_db on startup)
+```
+
+## Key implementation details
+
+### Fernet key loading
+```python
+# app/config.py
+@field_validator("fernet_key", mode="before")
+@classmethod
+def load_key(cls, v: Any, info: ValidationInfo) -> str:
+    key_file = info.data.get("token_encryption_key_file")
+    if key_file and Path(key_file).exists():
+        return Path(key_file).read_text().strip()
+    raise ValueError("...")
+```
+
+### VK format_data converter
+The converter parses Markdown AST into VK's `format_data` JSON which uses offset-based formatting:
+```json
+{"version": 1, "items": [
+  {"type": "bold", "offset": 0, "length": 5},
+  {"type": "link", "offset": 12, "length": 4, "url": "https://vk.com"}
+]}
+```
+
+Handles: **bold**, *italic*, `inline_code`, [links](url), #h1-######, > quotes, ```code blocks```, ---.
+
+### API key auth dual-mode
+- **Header mode**: `Authorization: Bearer <key>` — for GET/DELETE (accounts list, delete)
+- **Body mode**: `api_key` field in POST body — for publish, create account, list publications
+- Both call `get_user_by_api_key()` which does sha256 → query User table
+
+## Verification commands from session
+
+```bash
+# Generate key
+python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" > secrets/token_encryption_key
+
+# Verify imports
+TOKEN_ENCRYPTION_KEY_FILE=secrets/token_encryption_key \
+  python3 -c "from app import config, database, models, security, vk_client; from app.converters import markdown_to_vk; from app.api import schemas, deps, v1; print('OK')"
+
+# Start server
+TOKEN_ENCRYPTION_KEY_FILE=secrets/token_encryption_key \
+  uvicorn app.main:app --host 0.0.0.0 --port 8000
+
+# Test
+curl http://localhost:8000/api/v1/health
+curl -X POST http://localhost:8000/api/v1/convert \
+  -H "Content-Type: application/json" \
+  -d '{"message_md":"**bold** text"}'
+```
+
+## Key counts (from session)
+
+- 9 source files (excluding __init__.py, config, and infrastructure)
+- ~422 lines in converter (largest module)
+- ~310 lines in API v1 router (6 endpoints)
+- 3 ORM models: User, VkAccount, Publication
+- 4 infrastructure files: Dockerfile, docker-compose.yml, Makefile, .gitignore