refactor(msgpack): typed error for check_msgpack_structure (LAB-6496)

[27Bslash6]

Summary

This PR replaces the String error returned by check_msgpack_structure with a dedicated error type, MsgpackStructureError. It also corrects some documentation.

Public API changes

• check_msgpack_structure(bytes: &[u8], max_depth: usize)
  • Return type changes from Result<(), String> to Result<(), MsgpackStructureError>.
• New export: cachekit_core::MsgpackStructureError, re-exported from lib.rs alongside the function.
  • It is a tuple struct with a private String field, so downstream code cannot construct it or destructure it.
  • It derives Debug, Clone, PartialEq, Eq and thiserror::Error.
  • Its Display (#[error("{0}")]) is the bare rejection reason with no prefix, for example nests deeper than 100 levels.
  • The rustdoc says the wording is stable within a minor version, so callers may match on the leading words.

Behavioral compatibility

• Every rejection message is unchanged, and all error sites now build the error through a private reject() helper.
• ByteStorage::retrieve still formats decode pre-scan: {what} through Display, so ByteStorageError::DeserializationFailed messages are identical.
• Code that compared against Err(String) must switch to .to_string() or .unwrap_err().to_string(), as the updated doctests do.

Internal changes

• MAX_DEPTH = 100 moves from a module-level const into decode_envelope. This removes the duplicated #[cfg(all(feature = "compression", feature = "checksum", feature = "messagepack"))].
• A new unit test, the_error_is_a_std_error, checks at compile time that the type is std::error::Error + Send + Sync + 'static.
• The unit-test helper check() maps the error to String, so existing assertions stay unchanged.

Documentation

• Module doc: shortened. It no longer says SDK bindings already call the function, only that it is exported for them. It also drops two sentences:
  • that depth counts every collection header, which the function docs and inline comment still cover;
  • that the walk needs no optional dependency.
• Allocation note: now states the bound as at most min(max_depth, bytes.len()) u64s. It no longer says "nothing proportional to the input".
• README.md and SECURITY.md: both now name MsgpackStructureError and describe its prefix-free Display.

[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: 3f8dca6a-0989-4b17-b033-af51cc8f04b2

📥 Commits

Reviewing files that changed from the base of the PR and between f29965d and ce24241.

📒 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 MessagePack structural pre-scan now returns a public MsgpackStructureError whose displayed text is the bare rejection reason. The crate re-exports the error type. The envelope decode depth limit remains 100 and is declared within decode_envelope.

Changes

MessagePack structural pre-scan

Layer / File(s)	Summary
Typed pre-scan error and integration src/msgpack_bounds.rs, src/lib.rs, src/byte_storage.rs, README.md, SECURITY.md	The pre-scan and its rejection paths now use MsgpackStructureError. The crate re-exports the type, and tests and documentation reflect the updated error contract. decode_envelope declares its unchanged depth limit locally.

Priority: ⬇️ Low

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

Change: Refactor

Merge Risk: ⚪ Minimal · up to ce242

The public error contract and existing decode message are preserved; no concrete merge-blocking risk remains.

Security Architecture Review

Security architecture risk: ⚪ Minimal · up to ce242

The typed error changes how callers handle validation failures without changing the reviewed input controls, decoding order, or execution authority. No material security risk introduced or worsened by this change was identified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The observed exposure remains callers supplying untrusted MessagePack to the existing scanner or ByteStorage APIs. Exporting the error type changes failure handling, not the authority of those callers. Downstream SDK enforcement remains unverified.

Trust Boundaries and Controls

• observed — The structural scan remains an enforced gate before envelope deserialization, including recursive handling of unknown map values. Malformed lengths, unsupported markers, excessive depth, and incomplete input return errors rather than continuing to the typed decoder.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 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: replacing the string error with a typed error for check_msgpack_structure.
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 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 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.}

[kodus-27b]

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.