Operate and evolveOffline operation, reconnect, and errors

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

PathWhile disconnectedAfter reconnect
Durable recordsValid local saves remain committedResume authorized scope synchronization
Event notificationsLocal acceptance does not imply remote deliveryRead saved context rather than assume live-event replay
Live samplesMark the last sample stale or unavailableDiscover a current descriptor and open a new subscription
Request and replyBound the deadlineRetry only under the application's idempotency policy
Binary contentKeep available local bytesResume 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.

FailureMeaning and response
InvalidArgumentCorrect malformed inputs before retry
SchemaMismatchUse the expected schema and compatible decoder
UnauthorizedObtain authority accepted for the exact action and resource
RevokedStop affected delivery and repair authority
NotFoundHandle a definitive absence in the attempted resolution context
PendingStateKeep asynchronous resolution state within a deadline
UnavailableNo permitted live path currently completes the operation
StaleDescriptorDiscover a current descriptor without changing producer identity silently
CapacityExceededApply explicit bounded admission or shedding policy
CanceledStop work owned by the canceled operation
ClosedRecreate the ended subscription or other handle. Replace the session only if that session ended
StorageFailurePreserve 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:

  1. Await cancellation of event receivers.
  2. Cancel and join their state and stream workers.
  3. Close messaging operations and sockets.
  4. Retire producer resources.
  5. Shut down the session through its documented binding operation.
  6. 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.