Core API (server-core)
The Core API is the main REST service of FLAME Hub. It manages analyses, projects, nodes, registries, and master images, and coordinates workflows through AMQP messaging.
Running
# Development (from repo root)
npm run server-api
# CLI
npm run cli --workspace=apps/server-core -- start
# Docker
docker run -e ... privateaim/hub core cli startDependencies
- Database — MySQL, PostgreSQL, or SQLite
- Authup — OAuth2 identity provider
- Redis — pub/sub and caching
- RabbitMQ — AMQP message bus (for worker communication)
- Harbor (optional) — Docker registry for analysis images
Environment Variables
Service-Specific
| Variable | Default | Description |
|---|---|---|
HARBOR_URL | — | Harbor registry URL |
TELEMETRY_URL | — | Telemetry service URL |
MASTER_IMAGES_OWNER | PrivateAim | GitHub owner for master images |
MASTER_IMAGES_REPOSITORY | master-images | GitHub repository name |
MASTER_IMAGES_BRANCH | master | GitHub branch |
SKIP_PROJECT_APPROVAL | false | Skip project approval workflow |
SKIP_ANALYSIS_APPROVAL | false | Skip analysis approval workflow |
Inherited
See Shared Configuration and Database Configuration.
Key Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET/POST/DELETE | /analyses | Analysis CRUD (update is POST /analyses/:id) |
GET/POST/DELETE | /projects | Project CRUD |
GET/POST/DELETE | /nodes | Node CRUD |
GET/POST/DELETE | /registries | Registry CRUD |
GET/DELETE | /master-images | Master image read + delete (POST /master-images/command runs sync/build) |
GET/POST | /nodes/:id/client/credentials | Read / update the node's OAuth2 client credentials (secret, name, display name) — usable by the node's own client or a NODE_UPDATE manager |
GET | /nodes/:id/registry/credentials | Read the node's own registry project (Harbor robot) credentials — accessible to the node's own client without any management permission |
GET/POST | /analyses/:id/client/credentials | Read / rotate the analysis's OAuth2 client credentials |
POST | /analyses/:id/storage/token | Mint a storage capability token for buckets and files of the analysis (see below) |
GET | /docs | Swagger/OpenAPI documentation |
GET/HEAD | /livez, /readyz | Anonymous liveness and readiness probes (see Health endpoints) |
Response Shapes
Every entity endpoint answers with a { data, meta } envelope — the record (or the record array) under data, response-scoped extras under meta. Query-capable GETs additionally advertise the endpoint's queryable vocabulary at meta.schema; mutations carry meta: {}.
Four surfaces of this service deliberately stay flat, because they are protocol, credential or bulk-delete shapes rather than entity records:
| Endpoint | Shape |
|---|---|
GET / | { version, timestamp } — service metadata |
POST /services/:id/hook, POST /services/:id/command | null (202) — Harbor webhook / command protocol |
GET/POST /nodes/:id/client/credentials, GET/POST /analyses/:id/client/credentials, GET /nodes/:id/registry/credentials, POST /analyses/:id/storage/token | credential payloads |
DELETE /analysis-logs, DELETE /analysis-node-logs | null (202) |
GET /analyses/:id/client/permissions is a collection but carries no meta.schema — it proxies Authup ClientPermission records, for which no Hub-side query schema exists.
See API Reference for the full contract and the meta.schema reading rules.
Storage Capability Tokens
POST /analyses/:id/storage/token mints a short-lived, resource-scoped token that server-storage accepts instead of the caller's login. A browser then reaches only the buckets and files of one analysis, for only the requested actions.
POST /analyses/:id/storage/token
Authorization: Bearer <access token>
{ "cap": ["bucket:<bucketId>:read,write", "bucketFile:<fileId>:read"], "lifetime": 60 }| Field | Description |
|---|---|
cap | 1 to 32 entries type:id:actions (actions comma-separated). Types bucket (read, write, delete) and bucketFile (read, delete). id is the storage bucket or file id. |
lifetime | Optional, seconds, 1 to 3600 (default 3600). |
The answer is flat (no { data, meta } envelope): { "token": "...", "expiresAt": "<ISO date>" }.
Core decides access first, then exchanges the caller's access token for a capability token at Authup (RFC 8693), acting as the Hub client (CLIENT_ID). Every entry must belong to the analysis in the path, and the caller must be allowed every requested action:
| Action | Rule |
|---|---|
read | The file read rule of the bucket's type: CODE needs any participation, TEMP an approved node, RESULT an approved node plus analysis_result_read |
write | The file create rule: CODE owner and unlocked, RESULT/TEMP system or participant uploader |
delete | The file delete rule: owner plus a writable bucket |
| Status | Cause |
|---|---|
| 200 | Token minted |
| 400 | Malformed entry, unsupported type or action, or an entry outside the analysis (the whole request fails) |
| 401 | No access token, or core refused it |
| 403 | An action is not allowed |
| 404 | Unknown analysis |
| 501 | AUTHUP_URL is not configured |
| 502 | Authup refused the exchange (any refusal, including invalid_grant) or is unreachable (check the deployment setup) |
Architecture
The Core API follows the hexagonal architecture with:
- Domain services for each entity (validation, permission checks, business logic)
- AMQP aggregators consuming events from other services (builder, distributor, storage, authup)
- AMQP task consumers for registry and analysis metadata processing
- TypeORM subscribers publishing domain events on entity changes
Read Cache
The lookup of the node or analysis bound to a calling client, made whenever a node or analysis client reads analyses, their nodes, buckets and files, registry projects or credentials, is cached for up to 60 seconds (QueryCache from @privateaim/server-db-kit). A write to a node or analysis through its entity (save, remove) drops the affected entries when its transaction commits. Raw SQL drops nothing and a criteria update or delete does not reach every entry, so such a write can be answered stale until the entry expires. The entries live in Redis when REDIS_CONNECTION_STRING is set (key prefix hub-core), else in process memory; see Read cache (Redis) for the Redis requirements and for running several replicas.
Stuck Builds and Distributions
A build or distribution that stays starting/started while its analysis has not been written for 15 minutes is treated as orphaned (e.g. the worker died mid-run). Every 5 minutes — and once at start — server-core re-runs the build/distribution check for such analyses when AMQP is configured. Without AMQP the reconciler is not scheduled: no external worker can consume its checks from the local memory bus. If the image is not there, the check result marks the process failed, so it can be started again. Ordinary status and heartbeat saves no longer query Authup for an unchanged, non-null analysis client binding. Creating an analysis or saving it with a missing/changed binding still provisions or checks its client. Deleting a client remotely is not repaired by an unrelated status save. The public analysis update API does not accept clientId, so recovery requires administrative intervention; do not rely on background progress traffic to repair deleted clients. This fast path covers saves of loaded rows, not arbitrary partial TypeORM saves.
A running worker keeps its analysis fresh with progress events and a 5-minute heartbeat, so a long build or push is not mistaken for a stuck one; a worker progress event that changes nothing writes the analysis at most once a minute. The heartbeat stops once a single step has sent no progress for 2 hours, so a hung build or push makes its analysis stale. That alone does not recover it: with a single worker, the check waits behind the hung run in the same queue, so recovery needs a worker restart, a second worker replica, or RabbitMQ's consumer_timeout ending the hung delivery.
A distribution whose check can never decide — its analysis has no nodes, no registry, or a node without a registry project — is reported as still running, so it is failed once stale like a missing image. A late finish from the worker does not revive a build or distribution that was already marked failed (or reset): only a process still starting/started can finish.
Master-image builds are not covered: they have no check command, and starting a new build takes over one that has been stale for 15 minutes. A fresh starting or started build refuses another BUILD. A takeover renews the claim timestamp even if it was already starting. A dispatch error leaves that fresh claim active: the broker may have accepted the command despite a missing confirmation. Worker outcomes are still recorded after the request fails. If nothing was delivered, retry only after the 15-minute stale threshold; an immediate retry is refused to avoid launching a second build. Worker start/progress/failure/finish events apply only while the build is active; late events cannot overwrite a terminal or reset state. Master-image workers do not send the analysis heartbeat: a healthy Docker step silent for over 15 minutes can still be reclaimed. Events still have no run identifier, so a previous run's delayed event can affect a later active run.
Registry project renames
Updates to a node or registry project's externalName start an asynchronous same-registry migration: copy and verify artifacts, provision destination credentials, then switch the active registry-project binding. Until success, record reads and credential requests continue to return the source namespace. The source project and its robot remain available after cutover; consumers derive image locations from the binding rather than a stored image URL column. Master-image project renames are rejected.
Pause writers and drain distributions before renaming. Source inventory checks are not a fence against concurrent external pushes. See Registry project renames for rollout, retries, retained sources and manual retirement requirements.
Approval Workflows
By default, projects and analyses require administrator approval before execution. This can be disabled for development:
SKIP_PROJECT_APPROVAL=true
SKIP_ANALYSIS_APPROVAL=trueSee Approval Workflows for details on the approval process.