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 | 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, enforces legacy timeout/pending limits, and remains the compatibility default. | Implemented | Automated | Documented | Elixir channel/concurrency/chunk tests, Python legacy forwarding tests, SDK BridgeTransport tests, and legacy Docker/hosted E2E. |
| BRG-004 | A frontend can explicitly choose WebSocket-only, HTTP-only, or hybrid bridge operation. HTTP-only discovery, pairing, validation, event polling, and proxying do not require a frontend WebSocket, and an absent mode selects WebSocket. | Implemented | Automated | Documented | SDK factory/HTTP tests, HTTP-only E2E, mobile default unit test, and iOS/Android mode-selector E2E. |
| BRG-005 | 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 | Saved frontend bridge connections retain server identity, pairing credential, and optional explicit mode; old records without a mode reconstruct as WebSocket, mode changes reuse authorization, foreground recovery uses the selected transport lifecycle, and rollback is an explicit reconstruction rather than request replay. | Implemented | Automated; mobile host lifecycle inspected | Documented | Shared record and reconstruction helper tests cover absent/WebSocket/HTTP/hybrid modes with one saved token; SDK resume tests and iOS/Android selector/rollback E2E cover the selected transport behavior. |
| BRG-014 | WebSocket remains the product default and HTTP/hybrid remain opt-in until transfer-safety, bounded load/soak, physical-device network behavior, and rollback have been accepted through a separately approved default-switch rollout. | Implemented baseline | Human rollout gate pending; simulator rollback automated | Documented | Factory/mobile defaults, simulator mode/rollback tests, this specification, and the active task's explicit default-switch exclusion. |
Primary task evidence:
tasks/20260610-mobile-message-refresh-performance/050-plain-http-bridge-large-payload-path.md
Delivery evidence:
61140c0e— opt-in HTTP/hybrid implementation70346cec— Docker, cluster, hosted-edge, and native verification hardening