Use the reviewed realtime contract
Driver realtime behavior spans provider connection, authenticated room joins, screen listeners, reconnect handlers, local updates, notifications, vibration, and cleanup. A connected socket or received event is transport—not authorization, durable state, ordering, or exactly-once delivery.
The current contract is source-api-only. Runtime/provider success and complete
listener cleanup are not accepted.
Availability
The socket provider can connect after session loading independently of whether authenticated product rooms are ready. Home, order lists, order details, messages, profile and Root register different logical room/listener sets under different user, token, connectivity and lifecycle gates.
Connection status UI indicates provider state only. It is not proof that the current Driver joined every required room, left old rooms, or received all authorized events.
Prerequisites
- Authenticate and authorize before every room join and event application.
- Use logical room descriptors publicly; keep room names and identifiers private.
- Bind listeners to screen/session/project generations.
- Make reconnect joins idempotent and cleanup symmetric.
- Re-read authoritative API state before applying consequential event payloads.
- Define ordering, deduplication, replay, stale-event and exactly-once policy.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Socket provider | Connection transport and low-level lifecycle |
| Session/project owner | Generation, authenticated identity, teardown on change |
| Room coordinator | Join/leave exact logical scopes with authorization |
| Screen/controller | Add/remove named listeners symmetrically |
| API owner | Authoritative order/message/user state |
| Event reducer | Validate type, scope, revision and dedupe before local update |
| Notification/native owner | Vibration/push/navigation effects separate from socket receipt |
| Observability owner | Listener/room counts, reconnect, stale/drop/dedupe and cleanup receipts |
Inputs and result
Inputs are authenticated session/project generation, provider connection, logical room set, registered event types and last authoritative revisions.
Safe results distinguish connection, room-join acknowledgement, listener registration, received event, reauthorized refresh, applied local update, and cleanup. No single boolean or event proves all stages.
Current listeners can append messages, reorder/update/remove order cards, merge order detail, update Driver/profile state, trigger vibration/navigation hints, or request reads. These effects must validate current actor/order/project scope and revision before application.
Security and privacy
- Never use socket room membership as authorization.
- Never trust event actor/order/project/audience without server-side scope and a reauthorized read when consequential.
- Do not expose room names, socket IDs, tokens, payloads, contact/order/message values or private listener findings publicly.
- Clear rooms/listeners on logout, account/project change, unmount and provider replacement.
- Keep sockets, push notifications and deep-link navigation as separate inputs.
Limits and failure states
| State | Required interpretation |
|---|---|
| Connected | Transport exists; auth/rooms/listeners unknown |
| Disconnected/reconnecting | Events may be missing/stale; re-read required |
| Room joined | Candidate subscription, not data authorization |
| Event received | Untrusted incremental hint |
| Local card/bubble/profile changed | Reducer effect, not durable backend receipt |
| Reconnect event | Joins/listeners may duplicate without idempotency |
| Screen unmounted | Cleanup requested, not proven complete |
| Connection status updated | Provider UI only |
Current source has incomplete cleanup: anonymous connect/order-registration listeners in Messages are not fully removed, logistics detail cannot prove zero raw connect listeners, and async background setup cleanup can be retained. Exactly-once and complete cleanup claims are excluded.
Troubleshooting
The socket is connected but data is stale
Re-read the authorized API state. Connection does not prove correct rooms, revisions, missed events, or provider health.
An event appears twice
Inspect listener/room counts, reconnect generations and dedupe keys. Do not apply a consequential mutation twice.
A screen updates after unmount/logout
Treat it as cleanup/security failure. Stop the consumer, invalidate the session generation and review every listener/room/provider cleanup receipt.
Order/message/profile views disagree
Each consumer has its own reducer and read timing. Reconcile through authorized current reads, not event arrival order.
Connection status modal says Update
That control/provider state does not prove reconnection, room recovery, or data currentness. Require explicit lifecycle receipts.
Related guides: Use the communication contract · Use the order query contract · Authenticated bootstrap · Run governed evidence safely