docs: document inline phash checks and ack-worker memory fields (whatsapp-rust#1116) - #441
Conversation
…sapp-rust#1116) whatsapp-rust#1116 replaced the per-message spawned task/oneshot/timer for phash validation with a map entry the read loop checks inline, swept on the keepalive tick instead of a fixed 10s timeout, and added transport_ack_queue/delivery_receipt_queue to MemoryReport now that deferred acks and receipts are served by persistent workers. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01131pxhKHtLoWBY4jaAUeJ2
|
Warning Review limit reached
Next review available in: 47 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 (2)
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. |
|
| Filename | Overview |
|---|---|
| advanced/signal-protocol.mdx | Documents task-free phash waiter registration, inline acknowledgement validation, mismatch-triggered cache invalidation, and the corrected waiter sweep lifetime. |
| api/client.mdx | Documents the two new MemoryReport queue-depth fields for persistent acknowledgement and receipt workers. |
Reviews (2): Last reviewed commit: "docs: correct phash waiter sweep-window ..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
A waiter always survives the sweep immediately after registration and is removed on the one after that, so the real time-to-live is one to two 15-30s keepalive intervals (~15-60s), not a flat 15-30s window as previously stated. Verified against ResponseWaiterMap::drop_expired_phash in whatsapp-rust#1116. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01131pxhKHtLoWBY4jaAUeJ2
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 62912a6a16
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| <Note> | ||
| The phash validation runs asynchronously in the background and does not block the send path. If the server ack times out (after 10 seconds) or the oneshot channel is dropped, the validation is silently skipped. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. | ||
| The phash check never blocks the send path. If the server's ack never arrives, nothing polls the waiter directly — it is swept out on the keepalive tick, which drops any phash waiter that has lived through a full sweep since it registered (a window of one keepalive tick, 15–30 seconds, rather than the old fixed 10-second timeout). The sweep runs before keepalive's own idle early-return, so a connection with steady inbound traffic — which skips sending pings — still gets its stale waiters cleared; a stranded waiter would otherwise read as an outstanding IQ and suppress pings for the life of the connection. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. |
There was a problem hiding this comment.
The revised note combines waiter cleanup timing, sweep ordering, ping suppression, and WhatsApp Web parity into several long compound sentences. Split these concepts into shorter sentences so readers can distinguish the cleanup behavior from its rationale, as required by the repository's documentation style.
AGENTS.md reference: AGENTS.md:L24-L25
Useful? React with 👍 / 👎.
| 3. The message stanza is sent to the server | ||
| 4. A background task (`spawn_phash_validation`) awaits the server's ack (with a 10-second timeout) | ||
| 5. The server's ack includes its own `phash` — if it differs from the local value, the client invalidates caches | ||
| 4. When the server's ack for that message ID arrives, the read loop compares its `phash` attribute against the expected value inline, with no task involved |
There was a problem hiding this comment.
This step now says the comparison runs in the read loop, but the section's unchanged Location line still names only src/send.rs and src/client.rs. The commit itself identifies src/client/node_io.rs and src/keepalive.rs as the files implementing the inline check and waiter sweep, so readers following the documented source locations will miss the behavior described here.
Useful? React with 👍 / 👎.
|
|
||
| <Note> | ||
| The phash validation runs asynchronously in the background and does not block the send path. If the server ack times out (after 10 seconds) or the oneshot channel is dropped, the validation is silently skipped. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. | ||
| The phash check never blocks the send path. If the server's ack never arrives, nothing polls the waiter directly — it is swept out on the keepalive tick, which drops any phash waiter that has lived through a full sweep since it registered (a window of one keepalive tick, 15–30 seconds, rather than the old fixed 10-second timeout). The sweep runs before keepalive's own idle early-return, so a connection with steady inbound traffic — which skips sending pings — still gets its stale waiters cleared; a stranded waiter would otherwise read as an outstanding IQ and suppress pings for the life of the connection. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. |
There was a problem hiding this comment.
A waiter can be registered at any point during an already-running 15–30-second keepalive interval, so the time until the next tick is not itself bounded to 15–30 seconds and may be nearly zero. If the waiter must survive one complete sweep interval before removal, cleanup instead occurs on a later tick and can span portions of two intervals. Replace the stated 15–30-second lifetime with the actual bounds or describe the sweep semantics without claiming this range.
Useful? React with 👍 / 👎.
|
|
||
| <Note> | ||
| The phash validation runs asynchronously in the background and does not block the send path. If the server ack times out (after 10 seconds) or the oneshot channel is dropped, the validation is silently skipped. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. | ||
| The phash check never blocks the send path. If the server's ack never arrives, nothing polls the waiter directly — it is swept out on the keepalive tick, which drops any phash waiter that has lived through a full sweep since it registered (a window of one keepalive tick, 15–30 seconds, rather than the old fixed 10-second timeout). The sweep runs before keepalive's own idle early-return, so a connection with steady inbound traffic — which skips sending pings — still gets its stale waiters cleared; a stranded waiter would otherwise read as an outstanding IQ and suppress pings for the life of the connection. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. |
There was a problem hiding this comment.
This change says phash waiters are no longer polled through a fixed timeout, but api/wacore.mdx line 202 still lists phash validation as an internal user of the runtime-agnostic timeout helper. That cross-reference now documents the removed implementation and should be updated together with this section.
Useful? React with 👍 / 👎.
|
|
||
| <Note> | ||
| The phash validation runs asynchronously in the background and does not block the send path. If the server ack times out (after 10 seconds) or the oneshot channel is dropped, the validation is silently skipped. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. | ||
| The phash check never blocks the send path. If the server's ack never arrives, nothing polls the waiter directly — it is swept out on the keepalive tick, which drops any phash waiter that has lived through a full sweep since it registered (a window of one keepalive tick, 15–30 seconds, rather than the old fixed 10-second timeout). The sweep runs before keepalive's own idle early-return, so a connection with steady inbound traffic — which skips sending pings — still gets its stale waiters cleared; a stranded waiter would otherwise read as an outstanding IQ and suppress pings for the life of the connection. This matches WhatsApp Web's approach of using phash as a best-effort staleness detector rather than a hard requirement. |
There was a problem hiding this comment.
The new text says the phash sweep runs before keepalive's idle early-return, while advanced/websocket-handling.mdx lines 1077–1082 still claim to list the loop's checks in order and put the recent-activity early-return first. Update that ordered description to include the sweep before step 1; otherwise the two pages give conflicting control-flow documentation.
Useful? React with 👍 / 👎.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
2 participants
Summary
Documents the user-visible effects of whatsapp-rust#1116, which removed four per-message tasks/buffers from the send/receive round trip. Two of its five changes touch documented behavior:
spawn_phash_validationawaiting a oneshot ack waiter registered viaregister_ack_waiter) is gone. The client now registers aPhashWaitermap entry (register_phash_waiter); the read loop compares the ack'sphashinline with no task, and only mismatches spawn a task. Waiters whose ack never arrives are no longer bound by a fixed 10s timeout — they're swept on the keepalive tick, giving a window of one keepalive tick (15–30s).MemoryReportfields.transport_ack_queueanddelivery_receipt_queue(usize) are now reported, since deferred transport acks and delivery receipts are now served by persistent workers instead of one spawned task per ack/receipt.The other three changes in #1116 (message-ID generation, message-secret drain worker,
ResponseWaiterMapinternals) are implementation details not previously documented, so no update was needed there.Changes
advanced/signal-protocol.mdx: rewrote the "How it works" steps and the trailing<Note>in the "Phash validation for stale device list detection" section.api/client.mdx: addedtransport_ack_queueanddelivery_receipt_queuerows to theMemoryReportfields table.Test plan
src/client/node_io.rs,src/client/messaging.rs,src/keepalive.rs,src/client.rs)spawn_phash_validation/register_ack_waiternamesGenerated by Claude Code
Summary by cubic
Update docs for
whatsapp-rust#1116: phash validation now runs inline via aPhashWaitermap (no per-message task; only mismatches spawn a task), and waiters are swept on the keepalive tick with a ~15–60s TTL (they survive the first sweep and are removed on the next).Also adds
transport_ack_queueanddelivery_receipt_queuetoMemoryReportfor the persistent ack/receipt workers. Updatedadvanced/signal-protocol.mdxandapi/client.mdx.Written for commit fa0d479. Summary will update on new commits.