Offline operation, reconnect, and errors
Keep local work available and recover each independent data path explicitly.
Keep valid local data available during network loss. Distinguish local saves, stopped live paths, and pending remote lookups so one failed path does not disable the application.
Separate readiness and connectivity
Local readiness means the session can use its configured storage and local APIs. Network readiness means the configured transport phase is ready to attempt its work. Neither promises that a particular peer is reachable or authorized.
Run connection and reconnect work in the background. Observe state through the selected API. Do not block UI startup on a network request. Keep unsaved form input distinct from a successful local commit.
Recover each data path
| Path | While disconnected | After reconnect |
|---|---|---|
| Durable records | Valid local saves remain committed | Resume authorized scope synchronization |
| Event notifications | Local acceptance does not imply remote delivery | Read saved context rather than assume live-event replay |
| Live samples | Mark the last sample stale or unavailable | Discover a current descriptor and open a new subscription |
| Request and reply | Bound the deadline | Retry only under the application's idempotency policy |
| Binary content | Keep available local bytes | Resume or request content through its own transfer policy |
A current stream and a synchronized record can have different freshness. Display their timestamps independently. Do not overwrite a newer sample with late replicated state merely because that state arrived later.
Use structured failures
Handle stable error codes and structured fields, not message text. Bindings represent failures as result values or typed exceptions.
| Failure | Meaning and response |
|---|---|
InvalidArgument | Correct malformed inputs before retry |
SchemaMismatch | Use the expected schema and compatible decoder |
Unauthorized | Obtain authority accepted for the exact action and resource |
Revoked | Stop affected delivery and repair authority |
NotFound | Handle a definitive absence in the attempted resolution context |
PendingState | Keep asynchronous resolution state within a deadline |
Unavailable | No permitted live path currently completes the operation |
StaleDescriptor | Discover a current descriptor without changing producer identity silently |
CapacityExceeded | Apply explicit bounded admission or shedding policy |
Canceled | Stop work owned by the canceled operation |
Closed | Recreate the ended subscription or other handle. Replace the session only if that session ended |
StorageFailure | Preserve input and diagnose storage without claiming a commit |
An unavailable peer does not imply a nonexistent record. A timeout does not prove a remote side effect did not occur. An authorization failure is not a transient network error.
Bound retries and concurrency
Set deadlines, retry delays, and maximum in-flight work per operation. Use backoff only for permitted transient retries. Stop on cancellation, closed sessions, incompatible schemas, and authority failures until the cause changes.
Retry pending state only when the structured error is PendingState. Keep attempts and total elapsed time bounded.
Keep event receipt independent from record resolution and live sample workers. Bound worker count and queue size. Report capacity rejection instead of silently discarding work or starting unlimited tasks.
Shut down in ownership order
Shut down in this order:
- Await cancellation of event receivers.
- Cancel and join their state and stream workers.
- Close messaging operations and sockets.
- Retire producer resources.
- Shut down the session through its documented binding operation.
- Dispose of session handles before starting a replacement.
Cancellation of one subscription does not cancel every reader. An event without a stream reference does not terminate a previously opened stream. Follow stream lifetime rules rather than inferring lifecycle from missing optional fields.