Ilia Denisov
166 lines
3.5 KiB
Markdown
166 lines
3.5 KiB
Markdown
# Configuration and Contract Examples
|
|
|
|
Example values that complement `../README.md` §4 and the OpenAPI
|
|
contract.
|
|
|
|
## Local `.env`
|
|
|
|
```dotenv
|
|
# HTTP and gRPC listeners
|
|
BACKEND_HTTP_LISTEN_ADDR=:8080
|
|
BACKEND_GRPC_PUSH_LISTEN_ADDR=:8081
|
|
|
|
# Postgres
|
|
BACKEND_POSTGRES_DSN=postgres://galaxy:galaxy@localhost:5432/galaxy_backend?sslmode=disable&search_path=backend
|
|
|
|
# SMTP relay (mailpit by default for dev)
|
|
BACKEND_SMTP_HOST=localhost
|
|
BACKEND_SMTP_PORT=1025
|
|
BACKEND_SMTP_FROM=galaxy-backend@galaxy.test
|
|
BACKEND_SMTP_TLS_MODE=none
|
|
|
|
# Docker
|
|
BACKEND_DOCKER_HOST=unix:///var/run/docker.sock
|
|
BACKEND_DOCKER_NETWORK=galaxy-dev
|
|
|
|
# Game engine
|
|
BACKEND_GAME_STATE_ROOT=/var/lib/galaxy-game
|
|
|
|
# Admin bootstrap
|
|
BACKEND_ADMIN_BOOTSTRAP_USER=bootstrap
|
|
BACKEND_ADMIN_BOOTSTRAP_PASSWORD=change-me-immediately
|
|
|
|
# GeoLite2
|
|
BACKEND_GEOIP_DB_PATH=/var/lib/galaxy/geoip.mmdb
|
|
|
|
# Telemetry (stdout for dev)
|
|
BACKEND_OTEL_TRACES_EXPORTER=stdout
|
|
BACKEND_OTEL_METRICS_EXPORTER=stdout
|
|
```
|
|
|
|
The above is enough for `go run ./backend/cmd/backend` to boot
|
|
locally. Required-but-empty admin variables can be set to `bootstrap`
|
|
and any non-empty password; rotate immediately after first sign-in.
|
|
|
|
## Public REST examples
|
|
|
|
### `POST /api/v1/public/auth/send-email-code`
|
|
|
|
```http
|
|
POST /api/v1/public/auth/send-email-code HTTP/1.1
|
|
Host: backend.internal
|
|
Content-Type: application/json
|
|
Accept-Language: en-US
|
|
|
|
```
|
|
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
The `Accept-Language` header is captured as `preferred_language` for
|
|
the new account; the body schema rejects unknown fields, so locale
|
|
must travel through the header.
|
|
|
|
### `POST /api/v1/public/auth/confirm-email-code`
|
|
|
|
```http
|
|
POST /api/v1/public/auth/confirm-email-code HTTP/1.1
|
|
Host: backend.internal
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Internal REST examples (gateway-only)
|
|
|
|
```http
|
|
GET /api/v1/internal/sessions/5e7ae3e6-3f4f-4d59-9b9b-2f2c3d2e0a91 HTTP/1.1
|
|
Host: backend.internal
|
|
```
|
|
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
```http
|
|
POST /api/v1/internal/sessions/5e7ae3e6-.../revoke HTTP/1.1
|
|
Host: backend.internal
|
|
```
|
|
|
|
## Admin REST examples
|
|
|
|
```http
|
|
GET /api/v1/admin/mail/deliveries?page=1&page_size=10 HTTP/1.1
|
|
Host: backend.internal
|
|
Authorization: Basic <base64 of bootstrap:secret>
|
|
```
|
|
|
|
```http
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Resend on a `sent` row returns `409 Conflict`:
|
|
|
|
```http
|
|
POST /api/v1/admin/mail/deliveries/{id}/resend HTTP/1.1
|
|
Authorization: Basic ...
|
|
```
|
|
|
|
```http
|
|
HTTP/1.1 409 Conflict
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Standard error envelope
|
|
|
|
Every error response across the four route groups uses:
|
|
|
|
```json
|
|
{"error": {"code": "<machine_readable>", "message": "<human_readable>"}}
|
|
```
|
|
|
|
The closed set of `code` values lives in
|
|
`components/schemas/ErrorBody` of `../openapi.yaml`.
|