Module relay 

iOS/watch outbound relay transport (bd-a5452f).

watchOS cannot host a TCP server (Apple TN3135), so omni endpoints (iOS extension while open, watch app, Wear service) dial OUTBOUND to a relay and omni-cli posts commands to it. Harry chose relay-in-omni-cli, so the relay is the omni serve subcommand. Protocol (apple-utils omni/docs/injection.md, “Relay protocol (omni listen)”): TCP, NDJSON (one JSON object per line).

Roles: DEVICE (registers + receives), SENDER (omni send --relay / cast), RELAY (omni serve). The DEVICE only ever receives bare InjectionCommand lines, so the device drain/apply stays trivial.

Frames:

• device -> relay: {"v":1,"op":"register","device":"<id>","platform":"...","token":"<secret>"}
• sender -> relay: {"v":1,"op":"cast","device":"<id|all>","cmd":{InjectionCommand},"token":"<secret>"}
• relay -> device: a bare InjectionCommand line
• local app -> daemon: {"v":1,"op":"subscribe","token":"..."}
• daemon -> local app: mirrored bare InjectionCommand lines
• keepalive: {"v":1,"op":"ping"} / {"v":1,"op":"pong"}

A shared token (from SOPS/env, never hard-coded) gates register + cast. Device-ids are operator-assigned (e.g. harry-watch).

Structs

Registry

The relay’s device registry: device-id -> a sender feeding that device’s single writer thread (commands + pong replies).

RelayDelivery

Outcome of a relay cast (bd-0b4e45): whether the relay acknowledged it and how many registered devices it was routed to.

RelaySender

A hold-open relay SENDER for STREAMING dispatch (bd-772cb2): connects once and writes a Cast frame per command instead of reconnecting per command (the sender side needs no register handshake — the relay routes casts to the registered devices). Lazy-connects on the first cast; reconnects on the next cast after a write error so a transient drop does not abort the stream.

ServeOptions

Options for serve.

Enums

ControlFrame

Constants

DEVICE_ALL

TOKEN_ENV

Functions

bind

Bind a relay listener on addr.

cast_via_relay

SENDER client: connect to a relay and post one or more commands for device, then read the relay’s delivery result for the first cast (bd-0b4e45) so the caller can tell whether the target device was actually connected. Casting to a plain omni daemon (which sends no result) yields acked == false.

list_relay_devices

Query a relay for the device ids currently registered (bd-bc8b5c), so omni devices --relay can show operators which cross-device endpoints are connected. Bounded: a legacy relay that does not understand list sends no devices reply, so this returns an empty list (never hangs) within the read timeout. An auth rejection surfaces as a validation error.

resolve_token

Resolve the shared token from an explicit flag or the TOKEN_ENV env var.

resolve_token_with

Pure core of resolve_token (env value injected for testability).

serve

Run the relay accept loop on listener. One thread per connection; the shared Registry routes sender casts to registered devices.

serve_with_registry

Like serve but routes through a caller-provided Registry, so the device-registration set is observable (used by tests to assert that a dead device is reaped; bd-86ab7a).