docs: Disconnected event now carries a DisconnectReason - #365
Conversation
…t#956) Reflects the breaking change where events::Disconnected gained a reason field distinguishing routine server-initiated stream recycles from genuine transport failures, and documents the two additional spans (wa.conn.connect, wa.conn.read_loop) that now tag lid/pn and the err-level split between them. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0116e1C7aqCk2AdecsCpf6E6
|
Warning Review limit reached
Next review available in: 59 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 2 files
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Auto-approved: Documentation-only updates reflecting a breaking change in the underlying library: updating the Disconnected event struct shape and observability span taxonomy. No production code, logic, or infrastructure changes.
Re-trigger cubic
|
| Filename | Overview |
|---|---|
| api/transport.mdx | Adds is_clean_shutdown() documentation (impl stub + variant table) directly after the DisconnectReason enum — addresses the gap called out in the previous review thread; the table entries and their true/false values are internally consistent with the described behavior. |
| concepts/events.mdx | Updates Disconnected struct shape, field docs, and adds a migration ; the link to /api/transport#disconnected now resolves to the section that includes is_clean_shutdown() docs. |
| advanced/observability.mdx | Extends span identity coverage to wa.conn.connect and wa.conn.read_loop, and clarifies WARN vs ERROR failure levels; changes are coherent with the referenced upstream PR behavior. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
D["Transport closes"] --> E["events::Disconnected { reason }"]
E --> F{"reason.is_clean_shutdown()"}
F -->|true| G["Routine server-initiated\nstream recycle\nClient reconnects silently"]
F -->|false| H["Genuine transport failure\nLog / alert if needed"]
subgraph "DisconnectReason → is_clean_shutdown()"
R1["StreamEnded"] -->|true| G
R2["ServerClose { code: None }"] -->|true| G
R3["ServerClose { code: Some(1000 or 1001) }"] -->|true| G
R4["ServerClose { code: other }"] -->|false| H
R5["ReadError(_)"] -->|false| H
R6["Unknown"] -->|false| H
end
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
D["Transport closes"] --> E["events::Disconnected { reason }"]
E --> F{"reason.is_clean_shutdown()"}
F -->|true| G["Routine server-initiated\nstream recycle\nClient reconnects silently"]
F -->|false| H["Genuine transport failure\nLog / alert if needed"]
subgraph "DisconnectReason → is_clean_shutdown()"
R1["StreamEnded"] -->|true| G
R2["ServerClose { code: None }"] -->|true| G
R3["ServerClose { code: Some(1000 or 1001) }"] -->|true| G
R4["ServerClose { code: other }"] -->|false| H
R5["ReadError(_)"] -->|false| H
R6["Unknown"] -->|false| H
end
Reviews (4): Last reviewed commit: "docs: clarify Disconnected's Emitted wor..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ``` | ||
|
|
||
| **Fields:** | ||
| - `reason: DisconnectReason` — why the transport ended. Check `reason.is_clean_shutdown()` to tell a routine server-initiated stream recycle (WhatsApp's normal reconnect path) apart from a genuine transport failure, without parsing logs. See [`DisconnectReason`](/api/transport#disconnected) for the variants. |
There was a problem hiding this comment.
is_clean_shutdown() not documented in the linked DisconnectReason reference
The text directs users to call reason.is_clean_shutdown(), then links them to /api/transport#disconnected for the variants. However, api/transport.mdx only documents the four enum variants (ServerClose, StreamEnded, ReadError, Unknown) — there is no helper-methods section and no mention of is_clean_shutdown() anywhere in the file. A developer following the link will find the variants but no explanation of which variant(s) the method considers a clean shutdown, or that the method exists at all. The helper should be documented in api/transport.mdx alongside the enum definition.
Prompt To Fix With AI
This is a comment left during a code review.
Path: concepts/events.mdx
Line: 242
Comment:
`is_clean_shutdown()` not documented in the linked `DisconnectReason` reference
The text directs users to call `reason.is_clean_shutdown()`, then links them to `/api/transport#disconnected` for the variants. However, `api/transport.mdx` only documents the four enum variants (`ServerClose`, `StreamEnded`, `ReadError`, `Unknown`) — there is no helper-methods section and no mention of `is_clean_shutdown()` anywhere in the file. A developer following the link will find the variants but no explanation of which variant(s) the method considers a clean shutdown, or that the method exists at all. The helper should be documented in `api/transport.mdx` alongside the enum definition.
How can I resolve this? If you propose a fix, please make it concise.
concepts/events.mdx sends readers to /api/transport#disconnected for DisconnectReason details but the method it tells them to call wasn't documented there (caught by Greptile review on #365). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0116e1C7aqCk2AdecsCpf6E6
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Dismissed because Cubic found issues in a newer review.
Give is_clean_shutdown() a real function body (a bare semicolon is invalid Rust in an inherent impl, only valid in traits/externs), and drop the escaped pipes inside table-cell code spans in favor of prose (caught by cubic and Greptile review on #365). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0116e1C7aqCk2AdecsCpf6E6
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
0 issues found across 1 file (changes from recent commits).
Auto-approved: Updates documentation for Disconnected event and observability spans. Pure docs changes, no code modifications.
Re-trigger cubic
"unexpectedly" read as abnormal/error-only, but the event also fires for a routine clean server recycle — reword to say what actually distinguishes it (not client-initiated) instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0116e1C7aqCk2AdecsCpf6E6
2 participants
Summary
Reflects whatsapp-rust#956 ("typed read-loop exit — routine server recycles are not errors;
Disconnectedcarries the reason"), which merged a breaking change:events::Disconnectedis no longer a unit struct — it now carriesreason: DisconnectReasonso consumers can tell a routine server-initiated stream recycle apart from a genuine transport failure without parsing logs.Changes
concepts/events.mdx— updated theDisconnectedevent section: new struct shape with thereasonfield, an explanation ofreason.is_clean_shutdown(), a link to the existingDisconnectReasonreference inapi/transport.mdx, and a breaking-change<Note>for consumers with existingEvent::Disconnected(Disconnected)match patterns.advanced/observability.mdx— the same PR also tags thewa.conn.connectandwa.conn.read_loopspans withlid/pn(previously onlywa.conn.run,wa.iq,wa.send.messagewere tagged), and changeswa.conn.connect's failure level fromERRORtoWARN(its caller already classifies real failures). Updated the span taxonomy's "Levels" and "Account identity in spans" sections accordingly.Other PRs merged in the same batch (#949–#957) were internal performance/refactor/CI work with no user-facing API surface, so no further doc changes were needed for those.
Test plan
whatsapp-rust#956Disconnectedacross the docs repo to confirmconcepts/events.mdxandadvanced/observability.mdxwere the only files describing the changed shape/behavior (otherDisconnectedmentions are unrelated types:TransportEvent::Disconnected(DisconnectReason),IqError::Disconnected,HandshakeError::Disconnected)Generated by Claude Code
Summary by cubic
Docs updated for the breaking change:
events::Disconnectednow includesreason: DisconnectReasonso clients can tell routine server recycles from transport failures. AddedDisconnectReason::is_clean_shutdown()docs, clarified theDisconnected“Emitted” wording to include routine server recycles, and updated observability to tagwa.conn.connect/wa.conn.read_loopwithlid/pnand note the WARN vs ERROR split.Event::Disconnected(Disconnected)toEvent::Disconnected(Disconnected { reason })orEvent::Disconnected(_).Written for commit fd64032. Summary will update on new commits.