62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
|
# FlatRender V2 — Service Contracts
|
||
|
|
|
||
|
|
This directory defines all inter-service contracts. Services are loosely
|
||
|
|
coupled — they communicate via REST APIs (synchronous) and RabbitMQ
|
||
|
|
events (asynchronous). The browser connects to the Gateway over HTTPS +
|
||
|
|
WebSocket.
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
```
|
||
|
|
contracts/
|
||
|
|
├── common/ # Reusable OpenAPI components (Error, Pagination, ...)
|
||
|
|
│ └── types.yaml
|
||
|
|
├── events/ # RabbitMQ event schemas (JSON Schema)
|
||
|
|
│ ├── README.md # Event catalog with routing keys
|
||
|
|
│ ├── render.yaml
|
||
|
|
│ ├── node.yaml
|
||
|
|
│ ├── identity.yaml
|
||
|
|
│ ├── file.yaml
|
||
|
|
│ ├── tenant.yaml
|
||
|
|
│ └── notification.yaml
|
||
|
|
├── websocket/ # WebSocket message protocol
|
||
|
|
│ └── render-progress.md
|
||
|
|
└── rest/ # Per-service OpenAPI 3.0 specs
|
||
|
|
├── identity.openapi.yaml # internal
|
||
|
|
├── content.openapi.yaml # internal
|
||
|
|
├── studio.openapi.yaml # internal
|
||
|
|
├── render.openapi.yaml # internal
|
||
|
|
├── file.openapi.yaml # internal
|
||
|
|
├── notification.openapi.yaml # internal
|
||
|
|
├── node-agent.openapi.yaml # called by render orchestrator
|
||
|
|
├── gateway-public.openapi.yaml # what frontend uses
|
||
|
|
└── reseller-api.openapi.yaml # B2B API (api-key auth)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Authentication
|
||
|
|
|
||
|
|
| Surface | Auth | Carries |
|
||
|
|
|----------------------|---------------------------------|------------------------|
|
||
|
|
| Gateway public API | JWT (Bearer) | user_id, tenant_id |
|
||
|
|
| Reseller API | API key (X-API-Key + signature) | tenant_id, scopes |
|
||
|
|
| Internal service API | Service token (mTLS in prod) | service_name |
|
||
|
|
| Node Agent API | Shared secret (HMAC) | orchestrator_signature |
|
||
|
|
| WebSocket | JWT in query param `?token=...` | user_id, job_id |
|
||
|
|
|
||
|
|
## Versioning
|
||
|
|
|
||
|
|
- REST: URL prefix `/v1/...`
|
||
|
|
- Events: routing key suffix `.v1`
|
||
|
|
- WebSocket: protocol negotiation header
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
- All IDs are UUID v4
|
||
|
|
- All timestamps ISO 8601 with timezone (`2026-05-27T10:15:00Z`)
|
||
|
|
- All money fields are `_minor` integers (rial / cent)
|
||
|
|
- All durations are seconds (numeric)
|
||
|
|
- All file sizes are bytes (integer)
|
||
|
|
- Pagination: `?page=1&page_size=20` returning `PaginatedResponse<T>`
|
||
|
|
- Errors: `{ "error": { "code", "message", "details", "trace_id" } }`
|
||
|
|
- Tenant context: `X-Tenant-Id` header on internal calls (JWT carries it on public)
|