feat(msgpack): export check_msgpack_structure as the shared structural walk (LAB-2735)

[27Bslash6]

Makes check_msgpack_structure(bytes, max_depth), the header-only MessagePack walk that ByteStorage::retrieve and validate already run as their pre-scan, public API at the crate root. cachekit-py's extension and cachekit-rs each keep their own copy of this walk today. They will call this one instead, so there is one shared structural walk rather than three copies that can drift.

What changed

• check_msgpack_structure is pub and re-exported as cachekit_core::check_msgpack_structure. The algorithm is byte-for-byte unchanged.
• The module is no longer feature-gated. The walk uses no optional dependency, so it is available under every feature set, including --no-default-features. Only the unit test that builds a real envelope stays behind the envelope features.
• The envelope's MAX_DEPTH = 100 moved next to decode_envelope in byte_storage.rs, since it is the envelope's bound, not the walk's. decode_envelope keeps its decode pre-scan: prefix.
• The rustdoc states the contract. The walk takes the depth bound from the caller, counts every array or map header as a level (an empty one included), and allocates at most one u64 per open collection (8 KiB at depth 1024). It returns the bare reason with no prefix. It does not enforce the protocol's 32..=1024 range on max_depth, so choosing the bound is the caller's job.
• A doc-test covers the empty-collection depth rule and a declared-length overclaim.
• SECURITY.md → Envelope decode bounds and the README describe the public walk.

Release

The commit type is feat. With bump-minor-pre-major, release-please will propose 0.7.0 rather than the pending 0.6.1. That matches how this crate has shipped every additive API so far (0.3.0, 0.6.0), and the SDKs that call the new function have to raise their pin to the release that carries it anyway. If this merges before the open release PR, one release carries both the envelope pre-scan and this export.

Tests

Run locally: cargo fmt --check, cargo clippy --all-features -- -D warnings, cargo test --all-features (including the new doc-test and tests/decode_bounds_vectors.rs, tests/wire_format_vectors.rs, tests/dual_decode.rs), cargo test --features ffi, and cargo test --no-default-features --lib msgpack_bounds. cargo clippy --no-default-features -- -D warnings reports the same two byte_storage.rs warnings as main (an unused Instant import and an unread default_format field) and nothing new.

Summary by CodeRabbit

• New Features
  • Added a public check for validating the structure of untrusted MessagePack data. It is available regardless of feature configuration and lets callers set the maximum nesting depth.
• Documentation
  • Clarified how MessagePack checks are used during envelope decoding, how rejection reasons are reported, and how callers can use the public check.

[kodus-27b]

Code Review Could Not Complete ⚠️

The review failed before suggestions could be generated.

Reason: Rate limit reached on the provider (openai_compatible). Try again in a few minutes.

After fixing the issue, comment @kody review on this PR to re-run the review.

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.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

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

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.

​

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: cachekit-io/cachekit-core/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 6c1ca5c2-9a07-4fd6-827b-4f613425ee36

📥 Commits

Reviewing files that changed from the base of the PR and between 60e9318 and 10ec41d.

📒 Files selected for processing (5)

• README.md
• SECURITY.md
• src/byte_storage.rs
• src/lib.rs
• src/msgpack_bounds.rs

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

---

Walkthrough

The structural MessagePack check is now a public, feature-independent API. Envelope decoding uses the crate-root function with a depth limit of 100 and retains its pre-scan error mapping. The README and security documentation describe the API and rejection messages.

Changes

MessagePack structural check

Layer / File(s)	Summary
Expose the structural check API src/msgpack_bounds.rs, src/lib.rs, SECURITY.md, README.md	check_msgpack_structure is public and re-exported from the crate root. Documentation describes its caller-supplied depth limit and rejection reason.
Use the public check in envelope decoding src/byte_storage.rs, src/msgpack_bounds.rs, README.md	Envelope decoding calls the crate-root function with a depth limit of 100. Scan failures retain the DeserializationFailed variant and decode pre-scan: prefix. The test depth limit is private, and the real-envelope test is gated on the required features.

Priority: ⬇️ Low

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

Change: Feature

Merge Risk: ⚪ Minimal · up to 10ec4

The change exposes the structural check while preserving the described envelope pre-scan behavior. No actionable merge-blocking regression is established in the supplied review context.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 10ec4

The public API preserves the existing envelope protections and clearly documents its structural-only limits. No introduced security defect was established. Downstream integration remains unverified, so callers’ handling of depth limits and complete validation is still uncertain.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Attacker-controlled serialized input can consume CPU and stack-vector heap in the invoking process. The public helper does not impose an input-size ceiling, so direct consumers must supply resource policy. External service, tenant, and SDK exposure is not established by the available evidence.

Trust Boundaries and Controls

• observed — The scanner checks collection depth, declared payload lengths, pending element counts, truncation, and reserved markers before decoding. It does not authenticate input or grant authority. Exporting it does not bypass the shown ByteStorage paths, which still apply their fixed depth and subsequent validation controls.

Resilience and Maintainability Implications

• observed — The walk bounds outstanding declared elements against remaining input rather than allocating collections from their declared lengths. Depth checks occur before opening another collection and include empty collections, preserving the existing protection against forged nesting and length claims.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: exporting check_msgpack_structure as a shared MessagePack structural walk. It matches the pull request objectives and changed files.
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: Docstring Coverage

Explanation

Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}