brokkr-broker::ws::handler

Rust

Axum handler for the internal /internal/ws/agent upgrade endpoint.

Auth is enforced by the same PAK middleware as the rest of the v1 API (re-used from crate::api::v1::middleware); only PAKs that resolve to an agent identity are allowed to upgrade — admin and generator PAKs get a 403. After the upgrade succeeds, a connection handle is published to the shared ConnectionRegistry and two tasks run:

• reader: pulls frames from the socket, parses them as brokkr_wire::WsMessage, and bumps the inbound counter. Future tasks (WS-05 uplink, WS-09 ingestion) will dispatch from here.
• writer: drains the control lane first, falling back to telemetry, and forwards messages to the socket. This is what guarantees the ADR’s “control plane is never starved by log/event traffic” property.

Both tasks share a cancellation token: when either ends (socket close, lane drop, decode error, etc.) the other is unblocked so the agent’s entry is removed from the registry cleanly.

Functions

fn internal_​routes

pub

fn internal_routes(
    dal: DAL,
    registry: Arc<ConnectionRegistry>,
    broadcaster: Arc<LiveBroadcaster>,
    fleet: Arc<FleetBroadcaster>,
) -> Router<DAL>

Build the standalone router that mounts the internal WS endpoint.

Mounted outside /api/v1 (so it never appears in the OpenAPI spec) but still behind the same PAK auth middleware as the rest of the authenticated surface. The registry is injected via Extension so future push code can grab it from the same handle.

Source

pub fn internal_routes(
    dal: DAL,
    registry: Arc<ConnectionRegistry>,
    broadcaster: Arc<LiveBroadcaster>,
    fleet: Arc<FleetBroadcaster>,
) -> Router<DAL> {
    Router::new()
        .route(INTERNAL_WS_PATH, get(ws_upgrade))
        .layer(Extension(registry))
        .layer(Extension(broadcaster))
        .layer(Extension(fleet))
        .layer(from_fn_with_state(
            dal,
            v1_middleware::auth_middleware::<Body>,
        ))
}

Constants

Name	Type	Value	Description
INTERNAL_WS_PATH	&str	"/internal/ws/agent"	Public path of the internal WS endpoint. Exposed as a constant so tests and the agent client (WS-03) can reference it without string drift.