Skip to content

Gateways

A gateway is a separate executable managed by st-server. GatewayManager starts the process, connects to it over loopback TCP, authenticates the connection, sends the provider configuration and monitors runtime health.

During module initialization the server scans immediate child directories of gates/. A directory enters the immutable adapter catalog only when its manifest is valid, its protocol version is supported, and its declared executable passes path and permission checks. Gateway configurations are instances of these adapters: one adapter binary can be started multiple times for different provider accounts. Every instance has independent credentials, port and runtime state.

Gateways can participate in execution routing and can publish quote batches into the server quote pipeline when supported by the selected adapter.

Lifecycle

STOPPED → STARTING → CONNECTING → HANDSHAKING → CONFIGURING
        → PROVIDER_CONNECTING → READY

On a failure the runtime enters CRASHED. When automatic restart is enabled it continues through RESTART_BACKOFF and starts a new child process. DEGRADED means that the process is connected but the provider reported a non-ready state.

All commands require SESSION_ADMIN.

Configuration

Field Type Description
id integer Server-assigned gateway identifier.
name string Unique display name, 1–128 characters.
description string Optional description, up to 512 characters.
type string Adapter type; must match manifest.json.
binary string Executable path relative to the server's gates/ directory.
enabled boolean Whether the gateway may run.
bind_host string Loopback address; currently 127.0.0.1 or ::1.
port integer Optional fixed TCP port. 0 or an omitted field selects a free loopback port for every process start.
provider_config object Complete adapter-specific configuration, including endpoints and credentials when required.
startup_timeout_ms integer Time allowed to establish the gateway connection. Minimum 100 ms.
heartbeat_interval_ms integer Heartbeat interval. Minimum 100 ms.
heartbeat_timeout_ms integer Receive timeout; must exceed the heartbeat interval.
restart_enabled boolean Enables restart after a crash or disconnect.
restart_initial_delay_ms integer Initial restart delay.
restart_max_delay_ms integer Maximum exponential backoff delay.

In the first protocol iteration provider_config is stored as JSON and is returned only through commands restricted to SESSION_ADMIN. Field-level encryption is intentionally deferred to a later protocol revision. The object is sent to the child gateway only after successful bootstrap authentication and must not be written to logs.

Symbol mapping

A quote-producing gateway has separately managed mapping records:

{"gateway_id":3,"provider_symbol":"EUR/USD","source_name":"EURUSD","quote_enabled":true,"execution_enabled":true}

GatewayManager uses the same record in both directions. Incoming QUOTE_BATCH symbols are converted from provider_symbol to source_name when quote_enabled is true. Outgoing execution symbols are converted from SymbolRecord.source to provider_symbol when execution_enabled is true. Matching is exact and case-sensitive. An unmapped symbol passes unchanged.

Both lookup directions are held in the gateway runtime context, so quote and execution processing do not parse mapping JSON or access the database. The normalized quote source name is then resolved through SymbolRecord.source, which may target one or multiple internal symbols.

These records are separate from provider_config and from an adapter's symbols specifications. Adapter symbol entries may still contain subscription, contract-size, volume, and other provider-specific settings, but server-side symbol-name mapping is managed through the dedicated methods. QuotePolicy itself contains only provider identities and does not contain symbol names or wildcard rules.

Mappings are persisted in gateway_symbol_mappings. Mapping writes restart an enabled gateway so the new immutable runtime lookup is installed.

Commands