Skip to content

Routing model and matching

Design draft

This is the implementation contract for Routing version 1.

Route record

Field Type Meaning
route_id int Server-assigned immutable id
name string Unique name, 1–128 characters
enabled int 0 or 1
priority int Lower value is evaluated first
group_mask string Wildcard group mask; default *
symbol_mask string Wildcard symbol mask; default *
action_mask uint64 Request actions
order_type_mask uint64 BUY/SELL directions
volume_from int Inclusive minimum; 0 means unbounded
volume_to int Inclusive maximum; 0 means unlimited
target int Execution target
target_name string Dealer pool or Virtual Dealer profile
timeout_ms int Dealing timeout; 0 means target default
comment string Administrative comment, max 256
create_time int64 Server timestamp
update_time int64 Server timestamp

Flags

Action Value
ROUTE_ACTION_MARKET_OPEN 1
ROUTE_ACTION_MARKET_CLOSE 2
ROUTE_ACTION_PARTIAL_CLOSE 4
ROUTE_ACTION_ALL 7
Order type Value
ROUTE_TYPE_BUY 1
ROUTE_TYPE_SELL 2
ROUTE_TYPE_ALL 3

Pending placement/activation, SL/TP, Stop Out, and Close By are outside version 1. For closing, order type means the existing position direction.

Targets

Target Value Behavior
INTERNAL 0 Continue current execution flow immediately
MANUAL_DEALER 1 Defer to manual Dealing Center queue
VIRTUAL_DEALER 2 Defer to a Virtual Dealer profile
REJECT 3 Reject before execution flow
GATEWAY 4 Reserved and rejected by version 1 configuration API

Matching

Routes use ORDER BY priority ASC, route_id ASC. A route matches only if it is enabled and action, direction, group mask, symbol mask, and both volume bounds match. All conditions use AND. The first match wins; action chaining is not supported in version 1.

No match returns:

{"route_id":0,"route_name":"SYSTEM_DEFAULT","target":0,"target_name":"INTERNAL"}

Persistence and runtime cache

RoutingManager owns a separate bases/routing.db, migrations, CRUD, backup, and an immutable cache snapshot:

struct ExecutionRouteSnapshot {
    uint64_t version;
    std::vector<ExecutionRouteRecord> ordered_routes;
};

Runtime resolution never queries SQLite. A mutation is validated and persisted transactionally, then a complete new snapshot is atomically published. In-flight requests retain their acquired snapshot, and every decision returns snapshot_version.

Validation

  • Masks cannot be zero or contain unknown bits.
  • Volumes cannot be negative; when both bounds are non-zero, volume_from <= volume_to.
  • timeout_ms is 0–600000.
  • Names are unique.
  • Version 1 accepts targets 0–3 only.
  • Empty target_name selects the default manual pool or Virtual Dealer profile.