docs(events): document Event::SentFrame and the with_stats → with_observers rename - #502
Conversation
…servers rename whatsapp-rust#1260 added Event::SentFrame / Client::acquire_sent_frame_forwarding() as the outbound counterpart of RawNode, and renamed NoiseSocket::with_stats to with_observers (now taking a SendObservers struct instead of Option<Arc<SessionStats>>), with the same change threading through do_handshake's last parameter. - concepts/events.mdx: add SentFrame to the Event enum listing and a new "Sent frame events" section modeled on DecryptedPayload's. - api/client.mdx: add acquire_sent_frame_forwarding, modeled on acquire_decrypted_payload_forwarding. - advanced/websocket-handling.mdx: document SendObservers, update the with_observers/sender_task signatures, and note the breaking rename.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Warning Review limit reached
Next review available in: 14 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/websocket-handling.mdx | Documents SendObservers, the renamed socket and handshake APIs, and a corrected six-argument connection walkthrough. |
| api/client.mdx | Adds the public sent-frame forwarding lease contract and a correctly ordered registration example. |
| concepts/events.mdx | Adds Event::SentFrame, its payload semantics, exclusions, decoding guidance, and corrected observer-accounting cross-reference. |
Sequence Diagram
sequenceDiagram
participant Consumer
participant Client
participant NoiseSender
participant Transport
participant EventBus
Consumer->>Client: acquire_sent_frame_forwarding()
Client->>NoiseSender: enable SentFrame tap
NoiseSender->>Transport: send encrypted frame
Transport-->>NoiseSender: write accepted
NoiseSender->>EventBus: publish Event::SentFrame(plaintext)
EventBus-->>Consumer: dispatch event
Reviews (4): Last reviewed commit: "docs(websocket): clarify with_sent_frame..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
…reference Per Greptile review on PR #502: - The Connect walkthrough's do_handshake call still showed the pre-SendObservers argument list; updated it to match the real call site in src/client/lifecycle.rs. - SentFrame's SessionStats reference pointed at advanced/observability.mdx, which doesn't document SessionStats; point it at the websocket-handling page that actually covers it.
![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: c2a3d0935d
ℹ️ 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".
| ```rust | ||
| use wacore::types::events::{ChannelEventHandler, Event}; | ||
|
|
||
| let _lease = client.acquire_sent_frame_forwarding(); |
There was a problem hiding this comment.
When the connected client can send concurrently—for example, from a keepalive, acknowledgement worker, or another task—acquiring the lease here activates publication before the handler is registered. Any frame sent between these statements is dispatched without this consumer and is lost, which undermines the documented session-recording use case. Register the handler first, then acquire the lease so every frame produced after activation has a receiver.
Useful? React with 👍 / 👎.
Per Codex review on PR #502: acquiring the lease first activates forwarding immediately, so a frame sent between the lease call and register_handler would dispatch to no one. Swap the order in the example.
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Per cubic review on PR #502: the breaking-change note described chaining .with_sent_frames(...) without flagging that it (and sent_frame_tap) are pub(crate), so a reader outside the crate could try to call it and hit a privacy error. Spell out the pub/pub(crate) split and point at Client::acquire_sent_frame_forwarding() as the actual public entry point.
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
2 participants
Summary
Documents whatsapp-rust#1260 ("observe what the client sends, not only what it receives"), which added a new opt-in
Event::SentFrame— the outbound counterpart ofEvent::RawNode— and, as part of wiring it in, made a breaking rename toNoiseSocket's constructor anddo_handshake's last parameter.Event::SentFramecarries the marshaled plaintext of every frame the noise sender hands to the transport, gated by a newClient::acquire_sent_frame_forwarding() -> SentFrameLease. It covers every send path, including the ones that hand pre-marshaled bytes straight to the socket (acks, delivery receipts, direct-encoded IQs) that the existingwait_for_sent_nodewaiter never saw.NoiseSocket::with_stats(..., stats: Option<Arc<SessionStats>>)is nowNoiseSocket::with_observers(..., observers: SendObservers), anddo_handshake's last parameter changed the same way.SendObserversis one struct carrying both the existingSessionStatshook and the newSentFrametap, so future observers plug in there instead of widening these constructors again.Changes
concepts/events.mdx— addedSentFrameto theEventenum listing and a new "Sent frame events" section, modeled on the existingDecryptedPayloadsection (same lease-gated pattern).api/client.mdx— added### acquire_sent_frame_forwarding, modeled onacquire_decrypted_payload_forwarding.advanced/websocket-handling.mdx— documented the newSendObserversstruct, updated thewith_observers/sender_taskcode blocks anddo_handshakesignature, and called out the breaking rename with<Note>blocks in both spots.Not changed
changelog/*.mdx— left untouched per standing instructions (changelog entries are human-authored only).advanced/observability.mdx— checked; it only covers thetracingfeature and has noNoiseSocket/SessionStatscontent to update.api/transport.mdx— checked; it documents theTransporttrait, notNoiseSocket, so nothing there referenceswith_stats.Note for a maintainer
While researching this, I noticed
concepts/events.mdxandapi/client.mdxcurrently describeRawNodeas toggle-gated (client.set_raw_node_forwarding(bool)), but the currentwhatsapp-rustsource (src/client/accessors.rs) only exposes a lease-basedacquire_raw_node_forwarding() -> RawNodeLease— there's noset_raw_node_forwardingin the source anymore. That's a pre-existing staleness unrelated to PR #1260, so I left it out of this PR's scope, but it's worth a follow-up doc fix.Generated by Claude Code
Summary by cubic
Documents the new outbound event
Event::SentFrameand the breaking rename fromwith_statstowith_observers. Clarifies that.with_sent_frames(...)is crate-internal and that consumers should useClient::acquire_sent_frame_forwarding().New Features
Event::SentFramedocs and examples inconcepts/events.mdx(opt-in via lease; covers all send paths).Client::acquire_sent_frame_forwarding()toapi/client.mdxwith usage notes; example registers the handler before acquiring the lease.SendObserversinadvanced/websocket-handling.mdx, including how it publishes sent frames and the public vs crate-internal wiring.do_handshake(...)call signature and theSessionStatscross-link.Migration
NoiseSocket::with_stats(..., Option<Arc<SessionStats>>)→NoiseSocket::with_observers(..., SendObservers).do_handshakelast parameter nowobservers: SendObservers(wasstats: Option<Arc<SessionStats>>).SendObservers::with_stats(stats); for none,SendObservers::default().Client::acquire_sent_frame_forwarding()..with_sent_frames(...)andsent_frame_taparepub(crate)and used internally.Written for commit f803956. Summary will update on new commits.