NODEDC_PLATFORM/services/gelios-gateway

NODE.DC Gelios Gateway

Storage and read-model service for the Gelios provider domain. It has no provider credential, no provider HTTP client, no scheduler and no command transport.

Boundary

The protected Engine L2 Gelios Collector is the only component that reaches the provider and uses the Engine Credential. It submits authenticated unit intake to this Gateway. The Gateway enforces the connection scope and approved unit allowlist, persists current state/history, and exposes scoped read/SSE contracts to other Engine workflows and map consumers.

Neither a provider token nor a credential reference is accepted, stored or returned by this service.

Runtime contracts

GET /healthz is unprotected and contains no secret material.

All /internal/gelios/v1/* routes require the internal service credential:

Authorization: Bearer <NODEDC_INTERNAL_ACCESS_TOKEN>
X-NODEDC-Tenant-Id: <approved-tenant-id>
X-NODEDC-Connection-Id: <approved-connection-id>

POST /internal/gelios/v1/intake/units
GET  /internal/gelios/v1/status
GET  /internal/gelios/v1/capabilities
GET  /internal/gelios/v1/units/current
GET  /internal/gelios/v1/stream
GET  /internal/gelios/v1/data-products/fleet.positions.current.v1/snapshot
GET  /internal/gelios/v1/data-products/fleet.positions.current.v1/stream

intake/units is disabled by default. It accepts a bounded payload with a units array or an equivalent safe unit-list envelope; it does not accept a URL, method, token or command. The command catalog remains visible only as disabled ontology metadata.

The connection policy is explicit: GELIOS_UNIT_SCOPE=allowlist uses fixed GELIOS_ALLOWED_UNIT_IDS; GELIOS_UNIT_SCOPE=all accepts every unit returned by that already-approved tenant + connection, including units added later by the provider. Missing units are never deleted from storage: their stable provider IDs and last-seen history remain available to the presentation layer.

fleet.positions.current.v1 is the first provider-neutral product. Its snapshot and SSE patch stream contain semantic moving objects, position, motion, quality and active / stale / no-position state. They deliberately exclude raw telemetry and provider transport payloads. A consumer first fetches the snapshot and then attaches the stream; the stream ready event never pretends to be a complete current-state snapshot.

Storage

The database requires TimescaleDB and PostGIS. It keeps a current projection, append-only time-series snapshots, bounded restricted intake envelopes and collection audit. Raw envelopes have no browser/API route and expire according to GELIOS_RAW_RETENTION_DAYS.

Local checks

npm ci
npm run smoke