-
Notifications
You must be signed in to change notification settings - Fork 0
Runtime Routing Control
Runtime routing control is an optional local control plane for inspecting, replacing, or disabling the active process-local routing snapshot.
For deployment workflow and socket permission guidance, see Operations and Deployment and Security Model.
It is disabled unless the active configuration contains:
control:
unix:
enabled: true
socket_path: /run/aismixer/control.sock
socket_mode: "0660"
max_request_bytes: 1048576Adding control: or control.unix: without enabled: true does not enable the server.
The current transport is a POSIX Unix-domain socket using newline-delimited JSON frames. Normal framing is one JSON object followed by a newline. A final frame terminated by EOF is also accepted, but transports send newline-terminated frames under normal operation.
The socket parent directory must already exist. AISMixer does not currently create /run/aismixer, and installer/systemd provisioning for that runtime directory is not yet automatic.
Filesystem ownership, group, and mode on the socket path are the current authorization boundary. There are no application-level authentication tokens.
The routing-control protocol is versioned JSON. Current protocol version is 1.
Supported methods:
| Method | Purpose |
|---|---|
routing.status |
Return generation, enabled flag, zone names, route names, and target IDs. |
routing.replace |
Compile and atomically install a candidate routing section. |
routing.disable |
Atomically install a disabled routing snapshot and return to legacy broadcast mode. |
Every request carries a request_id. Responses return the same request_id so clients can correlate replies.
routing.replace and routing.disable may include expected_generation. This is optimistic concurrency control. If the running generation differs, the server rejects the request with stale_generation and includes the expected and actual generation numbers.
routing.replace compiles and validates the full candidate routing section before changing runtime state. If compilation fails, the active snapshot remains unchanged.
If validation succeeds and the optional generation check passes, RoutingState atomically replaces the active immutable RoutingTable snapshot and increments the process-local generation.
The replacement is not persistent. It does not update config.yaml, does not write a routing file, and disappears after process restart.
Runtime control operates inside one running AISMixer process. Multiprocessing coordination, cross-process synchronization, and IPC are not implemented.
forward_loop captures one routing snapshot per IngressEvent, so a successful control update affects subsequent events only.
Do not assume a globally installed aismixerctl command yet. From a repository checkout or copied service directory, use python3 aismixerctl.py.
python3 aismixerctl.py --socket /run/aismixer/control.sock statuspython3 aismixerctl.py --socket /run/aismixer/control.sock replace --file examples/routing-update.yaml --expected-generation 3python3 aismixerctl.py --socket /run/aismixer/control.sock disable --expected-generation 4replace --file accepts either a full config containing top-level routing: or a direct routing update file containing top-level zones: and routes:.
See: