docs: remove the simd feature and document table-driven packed encoding - #505
Conversation
whatsapp-rust#1262 drops the `simd` Cargo feature and portable_simd entirely; default features now build on stable Rust with no toolchain workaround needed. Update installation.mdx (EN/PT) to drop the nightly prerequisite, the simd feature row, and the disable-simd instructions, and rewrite the packed nibble/hex encoding section in advanced/binary-protocol.mdx to describe the NIBBLE_ENC/HEX_ENC lookup tables that replaced the match ladders and SIMD fast path. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ixTnvivkbqYADYM2hoMMj
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
📝 WalkthroughWalkthroughThe changes update packed-encoding documentation and revise English and Portuguese installation guidance. The guides now state that stable Rust 1.94+ supports the default feature set and clarify the limited workspace use of nightly Rust. ChangesPacked Encoding Documentation
Stable Rust Installation Guidance
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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/binary-protocol.mdx | Documents the table-driven packed encoding and now includes all digit and uppercase hexadecimal mappings omitted by the earlier revision. |
| installation.mdx | Removes obsolete SIMD/nightly consumer guidance and accurately distinguishes downstream stable builds from nightly-only workspace and Docker optimization flags. |
| pt/installation.mdx | Mirrors the stable-toolchain and removed-SIMD guidance in the Portuguese installation documentation. |
Reviews (3): Last reviewed commit: "docs(binary-protocol): fix stale pack_he..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@advanced/binary-protocol.mdx`:
- Line 485: Rename the “Hex Packing” heading in the Hex Packing section to “Hex
packing,” preserving the existing heading level and surrounding documentation.
- Around line 473-479: Update both lookup-table snippets in
advanced/binary-protocol.mdx: at lines 473-479, map b'0'..=b'9' to 0..=9 before
the existing punctuation and padding assignments; at lines 494-498, map
b'0'..=b'9' to 0..=9 and b'A'..=b'F' to 10..=15 before the padding assignment,
preserving PACK_INVALID for all other entries.
- Around line 457-458: Split the documentation at advanced/binary-protocol.mdx
lines 457-458 into concise sentences covering table selection, pair packing,
stack buffering, and OR-accumulator validity checking separately. Also split
lines 504-505 into separate sentences for removed paths, benchmark results,
decoder-table details, and exhaustive-test coverage; make no code changes.
In `@installation.mdx`:
- Line 10: Split the independent documentation facts into concise, active-voice,
second-person sentences at installation.mdx lines 10-10 and 175-175, and
pt/installation.mdx lines 10-10 and 132-132. Separate the Rust version, MSRV,
edition, stable-support, and command-behavior statements as applicable; in
Portuguese, change “funciona” to “funcionam” when both commands remain the
subject.
- Line 178: The toolchain-scope statements must account for all documented
nightly-only flags, including -Zbuild-std. Update the corresponding wording at
installation.mdx lines 178-178 and pt/installation.mdx lines 135-135 to include
-Zbuild-std alongside -Zshare-generics and lld/ICF linking, or narrow the “only”
claim to the exact configuration it describes.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: b1a6f02e-1e3f-4cd9-9288-f5b8fe9e2f11
📒 Files selected for processing (3)
advanced/binary-protocol.mdxinstallation.mdxpt/installation.mdx
| Nibble and hex packing share one code path, `write_packed_bytes`: an ASCII→nibble lookup table (`NIBBLE_ENC` or `HEX_ENC`, picked by `data_type`) maps each input byte to its packed nibble, pairs are packed two at a time into a stack buffer, and validity is checked once via an OR accumulator (`seen`) instead of per pair — that is what lets the pair loop unroll. | ||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Split the overloaded documentation sentences.
Each sentence combines several independent implementation claims. Split the claims so readers can identify the encoding flow and the historical performance rationale.
advanced/binary-protocol.mdx#L457-L458: separate table selection, pair packing, stack buffering, and validity checking.advanced/binary-protocol.mdx#L504-L505: separate removed paths, benchmark result, decoder-table detail, and exhaustive-test coverage.
As per coding guidelines, "Keep sentences concise — one idea per sentence in documentation."
📍 Affects 1 file
advanced/binary-protocol.mdx#L457-L458(this comment)advanced/binary-protocol.mdx#L504-L505
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@advanced/binary-protocol.mdx` around lines 457 - 458, Split the documentation
at advanced/binary-protocol.mdx lines 457-458 into concise sentences covering
table selection, pair packing, stack buffering, and OR-accumulator validity
checking separately. Also split lines 504-505 into separate sentences for
removed paths, benchmark results, decoder-table details, and exhaustive-test
coverage; make no code changes.
Source: Coding guidelines
|
|
||
| - **Rust nightly** (default) — required only by the default `simd` feature, which uses the unstable `portable_simd` API. The project pins `nightly-2026-06-16` via `rust-toolchain.toml`. | ||
| - **Rust 1.94 or newer** — the workspace MSRV. Edition 2024 itself needs no nightly, so stable works once `simd` is off. See [Using stable Rust](#using-stable-rust). | ||
| - **Rust 1.94 or newer** — the workspace MSRV, and all default features build on **stable Rust**. See [Using stable Rust](#using-stable-rust). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Split the long documentation statements.
Each location combines multiple independent facts. Use concise sentences. Address the reader as “you” or “você”. In Portuguese, change funciona to funcionam if the two commands remain the subject.
installation.mdx#L10-L10: Separate the Rust version, MSRV, and stable-feature statements.installation.mdx#L175-L175: Separate edition, MSRV, stable support, and command behavior.pt/installation.mdx#L10-L10: Separate the Rust version, MSRV, and stable-feature statements.pt/installation.mdx#L132-L132: Separate the stable-Rust statements and correct the verb agreement.
As per coding guidelines, use active voice and second person, and keep one idea per sentence.
📍 Affects 2 files
installation.mdx#L10-L10(this comment)installation.mdx#L175-L175pt/installation.mdx#L10-L10pt/installation.mdx#L132-L132
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@installation.mdx` at line 10, Split the independent documentation facts into
concise, active-voice, second-person sentences at installation.mdx lines 10-10
and 175-175, and pt/installation.mdx lines 10-10 and 132-132. Separate the Rust
version, MSRV, edition, stable-support, and command-behavior statements as
applicable; in Portuguese, change “funciona” to “funcionam” when both commands
remain the subject.
Source: Coding guidelines
Address review feedback on #505: - NIBBLE_ENC/HEX_ENC excerpts were missing the digit-range loops they documented, so copying them verbatim produced tables that reject all normal input. Show the real initializer code. - The nightly-toolchain note named only two of the three nightly-only build flags the docs describe elsewhere (missed -Zbuild-std, used by the Docker image build); scope the claim to match. - Sentence-case the "Hex packing" heading to match its sibling. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ixTnvivkbqYADYM2hoMMj
![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: 370960f4cf
ℹ️ 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".
| whatsapp-rust uses Rust **edition 2024** and declares an MSRV of **1.94**, both of which stable Rust supports. The one nightly-only piece is the default `simd` feature, which uses Rust's unstable `portable_simd` API for optimized binary protocol encoding/decoding. The project itself pins `nightly-2026-06-16` via `rust-toolchain.toml`. | ||
|
|
||
| To compile on **stable Rust**, disable the `simd` feature by setting `default-features = false`. You must do this on **both** `whatsapp-rust` and `wacore` — otherwise Cargo's [feature unification](https://doc.rust-lang.org/cargo/reference/features.html#feature-unification) will re-enable SIMD through the `wacore` dependency: | ||
| whatsapp-rust uses Rust **edition 2024** and declares an MSRV of **1.94**, both of which stable Rust supports, and the default feature set has no nightly-only dependency — `cargo build`/`cargo add whatsapp-rust` works with **stable Rust** out of the box, no feature flags to disable. |
There was a problem hiding this comment.
For readers following the crates.io snippet above (whatsapp-rust = "0.7"), this assertion is false: the repository's release record says 0.7.0 is the published 0.7 release and that its default simd feature requires nightly (changelog/2026-08-07-release-0-7-0.mdx:2-10,37). Until a 0.7.x containing #1262 is published, cargo add whatsapp-rust followed by a stable build selects 0.7.0 and fails on portable_simd; retain the opt-out instructions for registry users or clearly scope stable-by-default to the post-#1262 git revision.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fair catch on the mechanics — Cargo.toml on main is still version = "0.7.0" and release.yml is workflow_dispatch-only, so the crates.io 0.7.0 published alongside changelog/2026-08-07-release-0-7-0.mdx does in fact still need nightly for its default features. #1262 hasn't shipped in a crates.io release yet.
That said, I'm leaving this as-is rather than adding a "still on 0.7.0" caveat or restoring the opt-out instructions: this docs site's established pattern (see e.g. #504, #503, #502, #499, #500, all merged the same day as their corresponding whatsapp-rust PRs) is to document current main behavior immediately on merge, ahead of the next crates.io publish — release-specific doc sync happens separately when a version is actually cut (e.g. #480 for the 0.7.0 release itself). Re-adding nightly/opt-out instructions here would be inconsistent with that convention and would need to be torn out again the moment the next release ships. Given the human maintainer already excludes the changelog from this kind of automated update and handles releases manually, I'll leave the release-timing gap to that same process rather than encode it here.
Generated by Claude Code
| static NIBBLE_ENC: [u8; 256] = { | ||
| let mut table = [PACK_INVALID; 256]; | ||
| // '0'..='9' → 0..=9 |
There was a problem hiding this comment.
As written, NIBBLE_ENC initializes every entry to PACK_INVALID and only overrides -, ., and NUL; the comment does not actually populate 0–9. The new HEX_ENC excerpt similarly omits both the digit and A–F assignments. Readers using these as the documented implementation would reject all numeric and hexadecimal input, so include the initialization loops or mark the omitted lines explicitly with an ellipsis.
Useful? React with 👍 / 👎.
|
|
||
| The encoder/decoder automatically falls back to scalar code paths when SIMD is disabled. There is no functional difference — only a minor performance difference in binary protocol operations. | ||
| <Note> | ||
| The project's own `rust-toolchain.toml` still pins a nightly compiler (`nightly-2026-06-16`), but only for two build-time flags used by the workspace's own CI and Docker builds — `-Zshare-generics` and lld/ICF linking in `.cargo/config.toml` — not for any language feature the published crates need. That pin governs building the whatsapp-rust workspace itself; it has no effect on your project when you depend on whatsapp-rust from crates.io or git. |
There was a problem hiding this comment.
This claim that the pin exists only for the two listed items omits -Zbuild-std, even though the Docker section at installation.mdx:244 says the image uses it and line 292 identifies it as nightly-only. Conversely, lld/ICF linking is not the second unstable Rust flag that explains the nightly toolchain. Source builders therefore get an incomplete rationale for the pin; replace lld/ICF here with -Zbuild-std or avoid claiming the list is exhaustive.
Useful? React with 👍 / 👎.
![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 and verified against the latest diff
Confidence score: 4/5
advanced/binary-protocol.mdxhas inconsistent lookup-table examples: the text says digits/A–F map to 0–15, but the shown initializer omits those entries, so readers copying it can end up with incorrect hex decoding behavior in their own implementations—update the table snippet (or comment) so both excerpts agree and include a quick sanity-check example.
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/binary-protocol.mdx">
<violation number="1" location="advanced/binary-protocol.mdx:473">
P2: The two lookup-table excerpts are internally inconsistent: the comment claims digits/A-F map to 0-15, but the shown initializers never set those entries, so any reader copying the snippet gets a table where digits resolve to PACK_INVALID — contradicting the "'1' → 1" / "Packed: 0x12" example in the same block. Add the digit and A-F mapping loops (or drop the misleading comments) to both NIBBLE_ENC and HEX_ENC.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| _ => panic!("Invalid nibble"), | ||
| /// ASCII to nibble for `NIBBLE_8`: digits plus the two punctuation characters | ||
| /// a phone number can carry. | ||
| static NIBBLE_ENC: [u8; 256] = { |
There was a problem hiding this comment.
P2: The two lookup-table excerpts are internally inconsistent: the comment claims digits/A-F map to 0-15, but the shown initializers never set those entries, so any reader copying the snippet gets a table where digits resolve to PACK_INVALID — contradicting the "'1' → 1" / "Packed: 0x12" example in the same block. Add the digit and A-F mapping loops (or drop the misleading comments) to both NIBBLE_ENC and HEX_ENC.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At advanced/binary-protocol.mdx, line 473:
<comment>The two lookup-table excerpts are internally inconsistent: the comment claims digits/A-F map to 0-15, but the shown initializers never set those entries, so any reader copying the snippet gets a table where digits resolve to PACK_INVALID — contradicting the "'1' → 1" / "Packed: 0x12" example in the same block. Add the digit and A-F mapping loops (or drop the misleading comments) to both NIBBLE_ENC and HEX_ENC.</comment>
<file context>
@@ -466,58 +468,42 @@ Strings containing only digits, dash, and dot are packed into 4 bits per charact
-}
+/// ASCII to nibble for `NIBBLE_8`: digits plus the two punctuation characters
+/// a phone number can carry.
+static NIBBLE_ENC: [u8; 256] = {
+ let mut table = [PACK_INVALID; 256];
+ // '0'..='9' → 0..=9
</file context>
| static NIBBLE_ENC: [u8; 256] = { | |
| static NIBBLE_ENC: [u8; 256] = { | |
| let mut table = [PACK_INVALID; 256]; | |
| // '0'..='9' → 0..=9 | |
| for (i, b) in (b'0'..=b'9').enumerate() { | |
| table[b as usize] = i as u8; | |
| } | |
| table[b'-' as usize] = 10; | |
| table[b'.' as usize] = 11; | |
| table[0] = 15; // padding for an odd-length string | |
| table | |
| }; |
There was a problem hiding this comment.
All reported issues were addressed across 3 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
The Unpacking section still pointed readers at pack_hex, the match-ladder function the Packed Encoding rewrite above it replaced with HEX_ENC. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ixTnvivkbqYADYM2hoMMj
Dismissed because a newer commit was pushed; Greptile will re-review the current head.
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
2 participants
Summary
Documents whatsapp-rust#1262, which removes the
simdCargo feature andportable_simdentirely after measuring it wasn't earning its keep. Default features now build on stable Rust with no toolchain workaround.installation.mdx(EN + PT): drop the "Rust nightly required by default" prerequisite, remove thesimdrow from the feature-flags table, collapse the now-identical "Nightly (default)" / "Stable Rust"CodeGroupsnippets into one, and rewrite "Using stable Rust" — stable now just works out of the box; the repo's ownrust-toolchain.tomlnightly pin is scoped to internal build flags (-Zshare-generics, lld/ICF) that don't affect downstream consumers.advanced/binary-protocol.mdx: rewrite the packed nibble/hex encoding section to describe theNIBBLE_ENC/HEX_ENClookup tables that replaced both thematch-ladder functions and theportable_simdfast path, with updated code excerpts and source line references.advanced/websocket-handling.mdx's "SIMD Encryption" section (hardware AES-NI via theaes-gcmcrate) is unrelated to this change and was left as-is. Per the task instructions, the changelog was not touched — that's added by a human.Test plan
simdfeature orportable_simd(searched the whole repo)wacore/binary/src/encoder.rsonmainpost-merge#using-stable-rust/#usando-rust-stable) still resolve after the section rewriteGenerated by Claude Code
Summary by cubic
Removes the
simdfeature andportable_simdfrom the docs and documents the new table-driven packed encoding (NIBBLE_ENC/HEX_ENC). Defaults now build on stable Rust; EN/PT installation steps are simplified.Bug Fixes
-Zbuild-stdwith correct scope; sentence-case the “Hex packing” heading.HEX_ENCinstead of the removedpack_hex.Migration
simdnightly workarounds and drop directwacoreoverrides — usewhatsapp-rust = "0.7"with defaults.Written for commit de0d70c. Summary will update on new commits.
Summary by CodeRabbit