Skip to content

perf(core): NAPI and wasm bindings read through retrieve_data (LAB-12132) - #323

Merged
27b-merge-warden[bot] merged 2 commits into
mainfrom
lab-12132-bindings-retrieve-data
Nov 16, 2026
Merged

27b-merge-warden[bot] merged 2 commits into
mainfrom
lab-12132-bindings-retrieve-data

Conversation

@27Bslash6

Copy link
Copy Markdown
Contributor

Both bindings' ByteStorage.unpack now calls cachekit-core's ByteStorage::retrieve_data instead of retrieve. retrieve returns (data, format) and both bindings dropped the format, a String allocated and freed on every read. retrieve_data runs the same decode, checks and errors and skips that allocation (cachekit-io/cachekit-core#146). The JS-visible return value and error mapping are unchanged: the error still goes through e.to_string() into GenericFailure (NAPI) and JsError (wasm).

retrieve_data first ships in cachekit-core 0.7.5, so both crates now require cachekit-core = "0.7.5" (was "0.7.0"), and a fresh resolve cannot pick a core without it.

Commits

  1. perf(deps): bump cachekit-core to 0.7.5: Cargo.toml requirement and lock in both crates. Only cachekit-core moved in either lock (0.7.4 → 0.7.5, cargo update -p cachekit-core --precise 0.7.5). 0.7.5 also rewrites the core's store of envelopes under 64 B (cachekit-io/cachekit-core#148) and decodes the envelope in one bounded pass on retrieve (cachekit-io/cachekit-core#150), so this commit moves both halves of an envelope round trip on its own.
  2. perf(core): read through retrieve_data in the NAPI and wasm bindings: the two call sites, plus the two docs that name the read call (SECURITY.md, the header of test/protocol/decode-bounds.protocol.test.ts).

Measurement

Instructions per op from bench/ir.mjs on three builds, so the call swap is measured apart from the version bump:

  • a: main (core 0.7.4, retrieve)
  • b: commit 1 (core 0.7.5, retrieve)
  • c: commit 2, this head (core 0.7.5, retrieve_data)

The workloads are the existing envelope ones: one pack plus one unpack per op, at 40 B (*-envelope-40b) and 1,055 B of msgpack (*-envelope). pack is the same code in b and c, so the b → c delta is the read alone.

workload a Ir/op b Ir/op c Ir/op b → c (the swap) a → c (this PR)
napi-envelope-40b 15,550 12,904 12,743 −161 (−1.25%) −18.05%
napi-envelope (1,055 B) 46,005 44,015 43,720 −295 (−0.67%) −4.97%
wasm-envelope-40b 13,917 10,592 10,383 −209 (−1.97%) −25.39%
wasm-envelope (1,055 B) 59,135 56,640 56,417 −223 (−0.39%) −4.60%

A/A floor: each cell is the median of 5 repeats, and the largest spread, (max − min) / median, across all 12 cells is 0.0039% (wasm-envelope on b, about 2 Ir/op). The smallest swap delta, −223 Ir/op, is about 100× that. Build c measured the same Ir/op in two separate runs (once against b, once against a).

Run with Node 24.21.0, valgrind 3.22.0, linux-x64, ir.mjs --only napi-envelope,napi-envelope-40b,wasm-envelope,wasm-envelope-40b --jobs 4, each tree a separate worktree outside this checkout at paths of equal length, built with pnpm build and build:wasm; the three build hashes differ. This PR's Instruction counts check measures a → c on GitHub-hosted runners.

Sibling paths

Store and retrieve: only retrieve changes; pack already calls store with no format to discard. NAPI and wasm: both change. validate calls ByteStorage::validate, which in 0.7.5 is already retrieve_data(..).is_ok(), so it stays.

Tests

  • pnpm lint, pnpm type-check, pnpm type-check:tests: pass.
  • pnpm test against the NAPI binding built from this head: 2,893 passed, 1 skipped. That includes the 92 decode-bounds protocol vectors through the NAPI unpack.
  • pnpm --filter @cachekit-io/cachekit test:workers against the wasm binding built from this head: 307 passed, which runs the same decode-bounds vectors through the wasm unpack inside workerd.
  • cargo clippy --release -- -D warnings: clean on both crates (wasm32 target for core-wasm). cargo fmt --check: clean on core-ts, the crate the pre-commit hook checks.

Docs

SECURITY.md and the decode-bounds test header named ByteStorage::retrieve as the read call; both now name retrieve_data. The test header also now describes 0.7.5's decode: lengths checked against the input in one pass, with the pre-scan for any envelope that pass declines. The decompression bound SECURITY.md states is unchanged in 0.7.5. No README or API doc names the call.

Closes LAB-12132

0.7.5 adds ByteStorage::retrieve_data, which the bindings' read path
needs, and raises the requirement so a fresh resolve cannot pick a core
without it.
Both unpack paths called ByteStorage::retrieve and dropped the format
String it allocates on every read. retrieve_data runs the same decode,
checks and errors without that allocation, so the JS-visible value and
error mapping are unchanged.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Summary by CodeRabbit

  • Bug Fixes
    • Updated the TypeScript and WebAssembly packages to use the latest core library, improving compatibility with bounded decompression.
    • Both packages now retrieve unpacked data directly.
  • Documentation
    • Clarified which retrieval method handles bounded decompression and how envelope lengths are checked before reading.

Walkthrough

The TypeScript and WebAssembly bindings update their cachekit-core dependency to version 0.7.5. Their unpack methods call retrieve_data directly. The security and protocol test documentation now describe the updated method.

Changes

cachekit-core API update

Layer / File(s) Summary
Dependency and unpack updates
packages/cachekit-core-ts/Cargo.toml, packages/cachekit-core-wasm/Cargo.toml, packages/cachekit-core-ts/src/lib.rs, packages/cachekit-core-wasm/src/lib.rs, SECURITY.md, packages/cachekit/test/protocol/decode-bounds.protocol.test.ts
Both bindings update cachekit-core from 0.7.0 to 0.7.5 and call retrieve_data from their unpack methods. The documentation updates its method and version references.

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Refactor

Suggested reviewers: kodus-27b

Merge Risk: Minimal · up to cadd8

This change moves the TypeScript and WebAssembly bindings to cachekit-core 0.7.5 and has unpack read through retrieve_data, which avoids allocating an unused format string. Behavior and error mapping are expected to stay the same. No concrete merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: the NAPI and wasm bindings now read through cachekit-core's retrieve_data instead of retrieve, which the objectives and description both confirm. It also carries a per…
Description check Passed The description is specific and on-topic. It explains the ByteStorage.unpack switch from retrieve to retrieve_data, the dropped format String, the cachekit-core bump from 0.7.0 to 0.7.5, the error map…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: the NAPI and wasm bindings now read through cachekit-core's retrieve_data instead of retrieve, which the objectives and description both confirm. It also carries a perf type and the LAB-12132 ticket reference. Nothing in it describes work absent from the changeset.

Full details: Description check

Explanation

The description is specific and on-topic. It explains the ByteStorage.unpack switch from retrieve to retrieve_data, the dropped format String, the cachekit-core bump from 0.7.0 to 0.7.5, the error mapping, the commit structure, benchmarks, and test results. It matches the raw summary and objectives.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 18d16b6 and cadd898.

Files ignored due to path filters: 2

  • packages/cachekit-core-ts/Cargo.lock is excluded by !**/*.lock
  • packages/cachekit-core-wasm/Cargo.lock is excluded by !**/*.lock
Files selected for processing: 6

  • SECURITY.md
  • packages/cachekit-core-ts/Cargo.toml
  • packages/cachekit-core-ts/src/lib.rs
  • packages/cachekit-core-wasm/Cargo.toml
  • packages/cachekit-core-wasm/src/lib.rs
  • packages/cachekit/test/protocol/decode-bounds.protocol.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@kodus-27b

kodus-27b Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration
Interacting with Kody
  • Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

  • Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

  • Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
  • Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
  • Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
  • Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
  • API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
  • Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
  • Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
  • Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
  • Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
  • Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).
Current Kody Configuration
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ✅

Access your configuration settings here.

Kody Code Review — 1 suggested fix.
Paste the prompt below to your agent and all review fixed at once!

🛠️ Open Agent Prompt
A code review identified the following issues in this pull request.
Each section describes what was found and includes a reference implementation where available.

Files involved:
- packages/cachekit-core-ts/Cargo.toml:17

---

### [1/1] packages/cachekit-core-ts/Cargo.toml:17
Issue identified during code review:
WHAT: The `cachekit-core` dependency is bumped from 0.7.0 to 0.7.5 in a dependency manifest. No vulnerability or supply-chain evidence is visible for the new version.
WHY: Dependency changes must be checked for known CVEs and unexpected transitive changes. This crate enables the `encryption` feature, so supply-chain risk matters more here.
HOW: Add `cargo audit` or OSV output for cachekit-core 0.7.5 to the PR description. Confirm Cargo.lock is updated in the same PR, and note any transitive dependency changes.

---

Review each issue in context, use the reference implementations as guidance, and apply fixes that are consistent with the surrounding codebase.

Comment thread packages/cachekit-core-ts/Cargo.toml Resolved
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

Copy link
Copy Markdown

Instruction counts: PASS

Head cadd898 against base 18d16b6201288fcf0fa7014c0e7b35f76e735f2c, Node v24.22.2, valgrind-3.26.0. Instructions per op on the main thread (bench:ir --compare); median of the repeats, A/A = (max − min) / median. A workload fails above +2.00% and warns above +1.00% (its own threshold: plaintext-set-1mb at +10.00%, napi-encrypted at +4.00%, warning at half); an A/A over 0.40% reads INCONCLUSIVE.

workload base Ir/op head Ir/op delta A/A base / head verdict
napi-envelope 45,512 43,456 -4.52% 0.00% / 0.00% improved
napi-envelope-40b 16,070 13,573 -15.54% 0.00% / 0.00% improved
wasm-envelope 58,979 56,265 -4.60% 0.00% / 0.00% improved
wasm-envelope-40b 14,532 10,970 -24.51% 0.00% / 0.00% improved
secure-get-l1-hit 50,841 49,197 -3.23% 0.00% / 0.00% improved
secure-wrap-l1-hit-100b 58,709 57,061 -2.81% 0.00% / 0.00% improved
All 41 workloads: 6 improved, 35 ok
workload base Ir/op head Ir/op delta A/A base / head verdict
l1-get-hit 1,203 1,203 0.00% 0.00% / 0.00% ok
l1-set-at-capacity-1k 6,374 6,374 0.00% 0.00% / 0.00% ok
l1-set-at-capacity-10k 4,156 4,156 0.00% 0.00% / 0.00% ok
l1-set-at-capacity-100k 4,353 4,353 0.00% 0.00% / 0.00% ok
plaintext-set-1kb 219,745 219,650 -0.04% 0.00% / 0.00% ok
plaintext-set-10kb 1,849,123 1,849,018 -0.01% 0.00% / 0.00% ok
plaintext-set-100kb 18,088,126 18,087,782 -0.00% 0.00% / 0.00% ok
plaintext-set-64b 43,149 43,051 -0.23% 0.00% / 0.00% ok
plaintext-set-64b-metrics 48,397 48,247 -0.31% 0.00% / 0.01% ok
plaintext-set-1kb-metrics 224,392 224,273 -0.05% 0.00% / 0.01% ok
plaintext-set-1mb 178,111,607 178,091,130 -0.01% 0.00% / 0.00% ok
plaintext-set-containers 1,400,478 1,400,363 -0.01% 0.00% / 0.00% ok
keygen 12,356 12,356 0.00% 0.00% / 0.00% ok
keygen-1kb 276,267 276,266 -0.00% 0.00% / 0.00% ok
keygen-wasm 15,931 15,931 0.00% 0.00% / 0.00% ok
keygen-wasm-1kb 315,757 315,757 0.00% 0.00% / 0.00% ok
serializer-roundtrip 379,774 379,774 0.00% 0.00% / 0.00% ok
napi-envelope 45,512 43,456 -4.52% 0.00% / 0.00% improved
napi-envelope-40b 16,070 13,573 -15.54% 0.00% / 0.00% improved
napi-envelope-64kb 498,934 497,015 -0.38% 0.00% / 0.00% ok
wasm-envelope 58,979 56,265 -4.60% 0.00% / 0.00% improved
wasm-envelope-40b 14,532 10,970 -24.51% 0.00% / 0.00% improved
wasm-envelope-64kb 904,560 901,819 -0.30% 0.00% / 0.00% ok
napi-encrypted 44,414 44,411 -0.01% 0.00% / 0.00% ok
napi-encrypted-64kb 849,903 850,214 +0.04% 0.00% / 0.00% ok
wasm-encrypted 324,820 324,831 +0.00% 0.00% / 0.00% ok
wasm-encrypted-64kb 32,108,145 32,108,176 +0.00% 0.00% / 0.00% ok
secure-set-get 486,884 484,865 -0.41% 0.00% / 0.00% ok
secure-set-100b 72,270 72,175 -0.13% 0.00% / 0.00% ok
get-l1-hit 2,113 2,112 -0.05% 0.00% / 0.00% ok
secure-get-l1-hit 50,841 49,197 -3.23% 0.00% / 0.00% improved
wrap-l1-hit 17,021 17,021 0.00% 0.00% / 0.00% ok
wrap-l1-hit-metrics 16,977 16,977 0.00% 0.00% / 0.00% ok
get-l2-hit-metrics 236,700 234,473 -0.94% 0.01% / 0.00% ok
get-l2-hit-l1-metrics 243,316 241,164 -0.88% 0.01% / 0.00% ok
secure-wrap-l1-hit-100b 58,709 57,061 -2.81% 0.00% / 0.00% improved
secure-wrap-l1-hit-10kb 1,518,345 1,516,419 -0.13% 0.00% / 0.00% ok
secure-wrap-l1-hit-1mb 238,789,345 238,779,741 -0.00% 0.05% / 0.05% ok
wrap-l1-hit-cachekitio 17,047 17,046 -0.01% 0.00% / 0.00% ok
wrap-l1-hit-int-cachekitio 2,363 2,363 0.00% 0.00% / 0.00% ok
wrap-l1-hit-int 2,352 2,352 0.00% 0.00% / 0.00% ok

Run log

@27b-merge-warden
27b-merge-warden Bot merged commit a78e74f into main Nov 16, 2026
28 checks passed
@27b-merge-warden
27b-merge-warden Bot deleted the lab-12132-bindings-retrieve-data branch November 16, 2026 03:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant