Skip to content

Bridge connectivity requirements

Status values describe the complete requirement. Partial evidence is recorded without promoting an incompletely covered requirement to verified.

ID Requirement Implementation Verification Documentation Evidence
BRG-001 While a server is registered through its bridge control connection, the bridge maintains one cluster-visible server record keyed by its stable server_id and containing supported display metadata. Every bridge node exposes that record through supported discovery interfaces, the record is removed when registration ends, and health retains the established status, node, cluster-size, active-server, and active-session fields. Implemented Automated Documented Registry, takeover, process-down, WebSocket discovery, HTTP discovery, health, and two-node Docker integration tests.
BRG-002 A frontend can pair with an available server by completing the time-bounded code-verification flow and receiving a signed pairing credential bound to server and client identity. While valid and the server is available, the frontend can re-establish or validate access without another code through either supported control transport. Invalid, expired, tampered, or server-mismatched credentials do not grant access. Implemented Automated Documented Pairing manager attempts/expiry, signed-token tampering/expiry, legacy and HTTP resume mismatch/invalid/unavailable-server routes, owner-node validation, Docker legacy/HTTP pairing, and SDK E2E tests.
BRG-003 Explicit legacy development WebSocket mode preserves the established Phoenix app/server channel contract, creates ephemeral sessions from valid pairings, supports concurrent small and chunked UTF-8 proxy requests/responses, and enforces legacy timeout/pending limits. Implemented Automated Documented Unchanged BridgeTransport, Elixir/Python regression suites, SDK tests, and local real legacy E2E.
BRG-004 HTTP is the normal frontend product mode and omitted SDK mode selects HTTP. Explicit legacy WebSocket/hybrid constructors remain available for development. HTTP discovery, pairing, validation, event polling, and proxying require no frontend WebSocket or automatic fallback. Implemented Automated Documented Factory/HTTP/no-fallback tests, historical-record App tests, Docker SDK 5/5, cluster App integration, and iOS/Android settings and real-bridge Detox.
BRG-005 Explicit legacy hybrid mode routes only exact GET /events and GET /events?... requests through the legacy WebSocket transport; all control and other application requests use HTTP, and no HTTP failure is automatically replayed over WebSocket. Implemented Automated Documented SDK matcher/routing/no-fallback tests and real hybrid E2E with production adapters.
BRG-006 HTTP bridge protocol v1 provides capability negotiation, discovery, pairing request/confirmation, pairing validation, authenticated opaque-path proxying, and direction-scoped request-download/response-upload routes while server request/response metadata and cancellation remain versioned WebSocket control events. Implemented Automated Documented Elixir router/token tests, Python v2 metadata tests, SDK HTTP tests, and local/hosted E2E.
BRG-007 Requests selected for HTTP move request and response bodies as backpressured raw bytes without JSON text framing or base64 conversion. JSON/text preserve the frontend transport result contract and non-text responses remain binary. Implemented Automated Documented Coordinator/router byte tests, Python raw-stream tests, SDK binary/parsing tests, multi-megabyte JSON and binary E2E, and cross-node raw transfer E2E.
BRG-008 Pairing, frontend proxy, and body-transfer credentials are signed, expire, and are scoped to their intended identity and boundary. Bridge credentials and hop-by-hop/stale framing headers are not forwarded to the local application or viewer, while application Authorization remains available. Implemented Automated Documented Pairing/transfer token tampering, expiry, direction, request/server mismatch, duplicate attachment/replay, HTTP resume errors, Python header filtering, and CloudFront forwarding validation.
BRG-009 HTTP transfers apply atomic active-transfer admission, bounded request and response bytes, one consumer/uploader per direction, backpressure, timeout, cancellation, and deterministic cleanup after normal completion or any frontend/server/consumer/uploader failure. Implemented Automated Documented Supervisor saturation, request/response limits, invalid/duplicate attachment, timeout, all four monitored peer-loss cases, coordinator removal, Python phase cancellation/task-map cleanup, and real cluster/SDK E2E.
BRG-010 HTTP pairing and each transfer leg can reach different healthy bridge nodes behind a non-sticky load balancer; cluster routing preserves identity, order, and completion without JSON/base64 body conversion. Implemented Automated Documented Two-node HAProxy test confirms pairing plus a 1.2 MB request and 900 KB response whose proxy/download/upload legs span both nodes.
BRG-011 The subsystem converges after connection loss: dead registrations disappear, duplicate server identities follow the configured takeover/reject policy, superseded Python clients stop, valid pairings can resume with fresh legacy sessions or HTTP validation, and bridge restart does not require re-pairing when identity and signing configuration remain stable. Implemented Automated Documented Takeover/down tests, superseded Python test, heartbeat/reconnect SDK tests, app resume tests, and self-managed bridge restart E2E.
BRG-012 Viewer responses support negotiated gzip at the Phoenix origin, secure supported edges retain HTTP/2 and may supply Brotli, bridge control/proxy/transfer traffic is not cached, and required methods, query strings, WebSocket headers, and bridge/application authentication headers cross the edge. Implemented Automated configuration and gzip; hosted HTTP/2 manually confirmed Documented Deployment configuration tests, gzip E2E, CloudFormation validation, and live CloudFront HTTP/2/configuration inspection.
BRG-013 Mobile uses HTTP for new and historical saved bridge records unless an app-wide development override is active. IDs, URLs, server identity, pairing credentials, and cache ownership remain intact; new records persist HTTP independently of diagnostics. Foreground recovery uses the active transport, and preference changes affect later construction without replay/replacement. Implemented Automated; foreground adapter inspected Documented Historical mode matrix, retained repair/in-flight request tests, cluster App integration, Docker restart/resume, and iOS/Android native pairing/relaunch/saved reopen.
BRG-014 The separately approved HTTP product-default rollout retains explicit legacy diagnosis/rollback. Automated mobile verification precedes human mobile UX review; desktop bridge implementation starts only after the user's review confirmation. Approval and earlier transport evidence do not count as new human verification. Mobile implemented; desktop deferred Human review pending Documented SDK/component, real bridge/cluster/restart, and iOS/Android native checks pass. Review builds and walkthrough are available; human confirmation remains open. Physical-network and bounded-soak checks have not been rerun.
BRG-015 The Python server starts bridge and Bonjour only from explicit process-local runtime configuration; inherited integration environment names cannot activate or configure either service, advanced bridge transport controls have validated application settings and documented defaults, and changing process-owned integration settings requires restart. Implemented Automated Documented Python settings, CLI isolation, and server lifecycle tests; frontend SDK explicit-runner bridge E2E; application configuration and bridge adapter guides.
BRG-016 Home's connection modal shows saved bridge URLs first; selecting one discovers servers immediately, Add New Bridge enables manual input, successful discovery saves before pairing, and removal preserves paired server credentials. Endpoints persist independently with optional labels and last-use timestamps. Implemented Automated Documented Public store and hook tests, cluster App integration, and iOS/Android native discovery-before-pairing, saved endpoint reuse, independent deletion, message send/response, and paired reopen.
BRG-017 Home exposes a general Development Settings window with bridge transport as its first section. App-wide legacy overrides persist separately, reset to HTTP, preserve independent settings, hydrate before bridge opens, and give an explicit diagnostic path for older bridges lacking HTTP v1. Implemented Automated Documented Preference preservation/hydration, capability/no-fallback tests, and iOS/Android Home-menu settings selection, relaunch persistence, reset, and HTTP-only normal wizard.

Primary task evidence:

  • tasks/20260610-mobile-message-refresh-performance/050-plain-http-bridge-large-payload-path.md

Delivery evidence:

  • 61140c0e — opt-in HTTP/hybrid implementation
  • 70346cec — Docker, cluster, hosted-edge, and native verification hardening