bridged Bus contract

Mirrored from services/bridged/CHANGELOG.md, where releases update it. The component's page is bridged. This page describes the current main branch of MixOS.

0.2.0

  • Additive: auth: "key" (instance config 0.2.0). The first line is params.key, the secret is the 64-hex content of token_file, read on every connect before any bytes are sent. A missing, unreadable or unusable key is rc 11 with no connection; the retry after backoff_s reads it again. status works before the key exists and never shows it. Token and none modes are unchanged. Bus verbs and registry classes are unchanged.

0.1.0

First version. A Bus bridge to an external application's line-delimited JSON control channel, one instance per application (bridged@<app>), answering <app>.call, .commands, .execute, .inspect, .screenshot and .status with rc 0 (the app's result), 10 (the app's error), 11 (connect, auth, transport or timeout) or 12 (a bad request).

  • Instance config 0.1.0 (docs/spec/bridge/): <etc>/bridge/<app>.conf.mix, <etc> = $MIXOS_ETC or /etc/mixos, or $BRIDGED_CONFIG; keys host (loopback only), port, auth (token or none), token_file, timeout_s, connect_timeout_s, backoff_s, max_line, instance.
  • Start checks, also as mix bridged.mix --check <app>: the Bus service-name rule, and no name that a registered verb already starts with (read from the installed verb registry, failing closed). A refusal exits 2 with RUNTIME, NAME_INVALID, NAME_RESERVED, REGISTRY, CONFIG or TOKEN.
  • The name may not start with mixos- (mix --serve strips it) or be one of the broker's (noded, noded-*, the session-name shape).
  • The token is redacted from every error, result and last_error; the token file must be 0600. localhost connects as 127.0.0.1.
  • A reply without a boolean ok drops the connection (rc 11, then backoff).
  • The unit runs bridged.mix --start <app>: the start checks in process, then mix --serve as a child (Mix has no exec), exiting with the child's code. A documented refusal exits 2 and is never restarted (RestartPreventExitStatus=2); an unexpected start error exits 3, and it, a crash or a broken install is a rate-limited failure. A clean stop exits 143 (SuccessExitStatus=143). Run --start under the unit: outside systemd it has no parent-death protection. BRIDGED_MIX and the .env file must be administrator-controlled.
  • Writes draw on the same transport budget as connect and reads (timeout_s): every tcp_send gets the time left as {timeout}, and a send that runs out is rc 11 with the connection dropped. Local encoding and scheduling cannot be interrupted and can run past it. Requires Mix >= 0.112.1; an older Mix is refused at start (RUNTIME).
  • max_line bounds both directions exactly: an encoded request over it is refused with rc 12 before the connection is touched; a reply line over it is rc 11 with the connection dropped, even when it arrives whole in one read.
  • The unit is sandboxed (no capabilities or new privileges, read-only file system with private /tmp, loopback-only IP by IPAddressAllow=localhost and IPAddressDeny=any; a non-loopback Bus needs a drop-in). systemd-analyze security exposure 4.0 (OK).
  • Documented residuals: loopback port squatting after the app dies (a unix-socket channel would close it), a direct mix --serve briefly holding a refused name, and the reverse name collision being the verb-registry gate's to refuse.
  • The six verbs are declared in docs/spec/bus/verbs.conf.mix as the bridged instance family (<app>.<verb>, members: "instances"), in the registry's schema 3. Installing the registry is a separate deployed prerequisite, and this entry does not claim a live installation.
  • The bridge tests run in tools/mix_tests.mix. Their mix binary is BRIDGED_MIX, else MIXOS_TEST_MIX, else /opt/mixos/bin/mix; the Bus test's noded is --noded, else MIXOS_TEST_NODED, else the installed one.
  • The over-max_line reply test asserts rc 11 and the transport: prefix, not the wording of Mix's line-limit error, which the current Mix changed.

Ported from a private prototype (a serve citizen and its core, version 0.3.0), with the instance-config path rule, the serve-name guard and the --check mode added, and its tests moved from a socat stand-in to one written in Mix on tcp_listen.

This page as Markdown · This page describes the current main branch of MixOS.