docs: correct the delivery-retry paragraph — the SDK never auto-resends - #16
Merged
Conversation
The README claimed an unconfirmed send is "retried automatically every 3 s,
up to 3 times", waiting out a mid-reconnect socket for up to 15 s, with
FAILED landing only after "~12 s fully offline". None of that matches the
code, and it has been wrong since the 0.8.0 manual-retry change.
Coordinator.trackDelivery never retransmits. It waits for the server echo
and fails the draft when the echo can't arrive:
- sentEpoch == 0 (never reached an open socket) -> fails immediately,
not after ~12 s
- the connection drops or the open-epoch changes while still pending
-> breaks out and fails at that moment
- otherwise withTimeoutOrNull(SEND_CONFIRM_TIMEOUT_MS = 10_000L), then
failPending()
The companion comment is explicit: "No auto-resend - the user retries
explicitly", as is the 0.8.0 CHANGELOG entry ("one retry = one send",
adopted to kill duplicate delivery on reconnect).
This matters beyond accuracy: the old wording framed the host app's retry
button as a backstop for the SDK's own retry ladder, so an integrator could
reasonably conclude it was optional. It isn't - it's the only path from
FAILED back to a send.
examples/chat/views/02-standard/README.md and the CHANGELOG already
described the real behaviour; the top-level README was the outlier. No
code change - documentation only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
One paragraph in the README, rewritten to match the code.
Why
The "Delivery state & retry" section claimed:
Every specific in that sentence is wrong.
Coordinator.trackDeliverynever retransmits — it waits for the server echo and fails the draft as soon as the echo can't arrive:sentEpoch == 0)SEND_CONFIRM_TIMEOUT_MS= 10 s, thenFAILEDThe companion comment says it outright —
// No auto-resend — the user retries explicitly— and this has been the deliberate design since 0.8.0, where auto-resend-on-reconnect was removed to stop duplicate delivery (CHANGELOG: "one retry = one send").Why it's worth fixing rather than leaving
The old wording framed the host app's retry button as a backstop for the SDK's own retry ladder — something you add after the SDK gives up. An integrator could reasonably read that as optional. It isn't: it is the only path from
FAILEDback to a send, so an app built on the old text silently strands failed messages.This also propagated outward — it was copied into the published Android SDK docs page, which is being corrected separately.
Corroboration
examples/chat/views/02-standard/README.md:264and the 0.8.0 CHANGELOG entry both already describe the real behaviour. The top-level README was the only place still carrying the old claim.Scope
Documentation only — no code change. Verified against
v0.9.0.