docs: document stanza interception and DecryptedPayload event from whatsapp-rust#1239/#1240/#1241 - #492
docs: document stanza interception and DecryptedPayload event from whatsapp-rust#1239/#1240/#1241#492jlucaso1 wants to merge 3 commits into
Conversation
Reflects whatsapp-rust#1239, #1240, and #1241.
Reflects whatsapp-rust#1239, #1240, and #1241.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 32 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. 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 |
|
| Filename | Overview |
|---|---|
| advanced/plugins.mdx | Documents the stanza-interception capability, registration lifecycle, panic isolation, diagnostics, and responsibility for claimed Signal-bearing stanzas. |
| api/client.mdx | Documents the interceptor and decrypted-payload lease APIs; the revised interception note consistently states that claimed stanzas undergo no Signal processing. |
| concepts/events.mdx | Adds the opt-in DecryptedPayload event contract, fields, ordering, serialization behavior, and usage example. |
Reviews (2): Last reviewed commit: "docs(client): interception precedes Sign..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 3 files
Confidence score: 4/5
advanced/plugins.mdxcurrently states that a stanza path leaves “nothing decrypted, no session mutated, no prekey consumed,” but that conflicts with theadd_stanza_interceptorbehavior described inapi/client; this can mislead plugin authors into unsafe assumptions about signal durability and interceptor side effects. Align the two sections (or explicitly scope when each statement is true) so readers get one consistent contract.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="advanced/plugins.mdx">
<violation number="1" location="advanced/plugins.mdx:216">
P2: The "Interaction with Signal durability" claim that a claimed stanza involves "nothing decrypted, no session mutated, no prekey consumed" directly contradicts the sibling `add_stanza_interceptor` section in api/client.mdx (same PR stack), which states a claimed `<message>` "has already been decrypted or not by the time an interceptor sees it, exactly as the built-in handler would have found it". A plugin author reading both pages gets opposite guidance about whether claiming advances Signal state/prekeys, which undercuts the no-durability-contract rationale here. Reconcile the two: either the interceptor runs after decryption (keeping the client.mdx framing) and this section must not claim zero Signal work, or interception truly precedes all Signal work and client.mdx needs correcting.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
|
||
| ### Interaction with Signal durability | ||
|
|
||
| Interception runs *before* the built-in pipeline, so a claimed stanza is one the client did no Signal work on at all: nothing decrypted, no session mutated, no prekey consumed. There's no half-advanced state to reconcile, which is what makes claiming safe to reason about and needs no dedicated durability contract. |
There was a problem hiding this comment.
P2: The "Interaction with Signal durability" claim that a claimed stanza involves "nothing decrypted, no session mutated, no prekey consumed" directly contradicts the sibling add_stanza_interceptor section in api/client.mdx (same PR stack), which states a claimed <message> "has already been decrypted or not by the time an interceptor sees it, exactly as the built-in handler would have found it". A plugin author reading both pages gets opposite guidance about whether claiming advances Signal state/prekeys, which undercuts the no-durability-contract rationale here. Reconcile the two: either the interceptor runs after decryption (keeping the client.mdx framing) and this section must not claim zero Signal work, or interception truly precedes all Signal work and client.mdx needs correcting.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At advanced/plugins.mdx, line 216:
<comment>The "Interaction with Signal durability" claim that a claimed stanza involves "nothing decrypted, no session mutated, no prekey consumed" directly contradicts the sibling `add_stanza_interceptor` section in api/client.mdx (same PR stack), which states a claimed `<message>` "has already been decrypted or not by the time an interceptor sees it, exactly as the built-in handler would have found it". A plugin author reading both pages gets opposite guidance about whether claiming advances Signal state/prekeys, which undercuts the no-durability-contract rationale here. Reconcile the two: either the interceptor runs after decryption (keeping the client.mdx framing) and this section must not claim zero Signal work, or interception truly precedes all Signal work and client.mdx needs correcting.</comment>
<file context>
@@ -141,11 +142,80 @@ impl ClientPlugin for SearchPlugin {
+
+### Interaction with Signal durability
+
+Interception runs *before* the built-in pipeline, so a claimed stanza is one the client did no Signal work on at all: nothing decrypted, no session mutated, no prekey consumed. There's no half-advanced state to reconcile, which is what makes claiming safe to reason about and needs no dedicated durability contract.
+
+What it does mean is that the claim is final. The ack that follows tells the server not to redeliver, so a claimed `<message>` stays undecrypted forever, and a claimed `<notification type="encrypt">` is a prekey top-up that never happens. A plugin claiming stanzas that carry Signal state takes over that responsibility whole — see [Signal Protocol](/advanced/signal-protocol) for what that involves. Match narrowly.
</file context>
There was a problem hiding this comment.
Same contradiction Greptile flagged on the api/client.mdx side — fixed there in b58f0e4, so this line's framing ("nothing decrypted, no session mutated, no prekey consumed") is now the reconciled, correct account: interception truly precedes all Signal work. Nothing to change here in advanced/plugins.mdx.
Generated by Claude Code
A claimed <message> is never decrypted — the client does no Signal work at all on a claimed stanza. Fixes ambiguous wording flagged in PR review.
![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).
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.
Re-trigger cubic
|
@claude solve conflicts |
|
Closing rather than resolving conflicts: this PR duplicates work. Three concurrent runs of the same automated task (for the same whatsapp-rust PR stack, #1239/#1240/#1241) produced three docs PRs here — #490, this one (#492), and #493. #490 merged first (01:27 UTC, ~1 minute before this one was opened) and covers the same three files with equivalent-or-better content: it documents the same Since main now has #490's version of Generated by Claude Code |
2 participants
Summary
Documentation for a three-PR stack that shipped together in whatsapp-rust:
Client::add_stanza_interceptor, theStanzaInterceptortrait, and theInterceptionenum: a seam that lets a consumer claim a decoded stanza before the built-in pipeline, instead of watching it get nacked.Event::DecryptedPayload, gated byClient::acquire_decrypted_payload_forwarding(): hands over a decrypted<enc>payload before the client tries to decode it into awa::Message, so a payload this build can't decode isn't just lost.PluginCapability::StanzaInterception/PluginStanzaInterception: the plugin-host wrapper over #1239's interceptor seam, adding panic isolation and terminal-shutdown invalidation for untrusted plugin code.Changes
api/client.mdx— new### add_stanza_interceptorand### acquire_decrypted_payload_forwardingsections under Protocol Operations, and astanza_interceptorsrow in theMemoryReportfields table.concepts/events.mdx—DecryptedPayloadadded to theEventenum listing, and a new## Decrypted payload events/### DecryptedPayloadsection documenting its fields and gating.advanced/plugins.mdx—PluginCapability::StanzaInterceptionadded to the capabilities table and overview sentence; new## Stanza interceptionsection (registration, panic isolation, terminal invalidation, Signal-durability interaction); removed "no ingress interception of inbound stanzas" from the top<Note>and the "What's not supported yet" section (pre-ack decisions are still unsupported); Diagnostics section extended to mention the new per-plugin counters.Out of scope
api/client.mdx's existingset_raw_node_forwarding(&self, enabled: bool)section documents a signature that predates this stack — the actual method isacquire_raw_node_forwarding(self: &Arc<Self>) -> RawNodeLease. That drift isn't caused by #1239/#1240/#1241 (the lease-based API was already in place before this stack), so it's left alone here rather than folded into an unrelated docs PR.No changes to
changelog/, per standing instructions that changelog entries are human-authored only.Generated by Claude Code
Summary by cubic
Documents stanza interception and decrypted-payload forwarding, clarifying that interception happens before Signal decryption and decode. Adds client APIs and a plugin capability with safety notes and diagnostics.
add_stanza_interceptorwithStanzaInterceptor/InterceptionandInterceptorHandle(RAII). Runs before the pipeline and Signal decryption; first-claim wins; preserves required acks; excludes connection-critical stanzas.Event::DecryptedPayloadandacquire_decrypted_payload_forwarding(lease-gated). Fires after unpadding and before decode; forwardsByteswithout copies and skips serialization.PluginCapability::StanzaInterception/PluginStanzaInterceptionwrapper over client interception, with panic isolation and terminal-shutdown invalidation. Diagnostics include per-pluginstanza_interceptorsand interception panic counters; health degrades on panics.api/client(interception + decrypted-payload sections, interception-before-decryption note,MemoryReport.stanza_interceptors),concepts/events(DecryptedPayload), andadvanced/plugins(capability table, stanza interception, “Interaction with Signal durability,” and note clarified to “no pre-ack decisions”).Written for commit b58f0e4. Summary will update on new commits.