fix(interop)!: reject double-dot interop segments (LAB-5906)

[27Bslash6]

Summary

Interop mode now rejects any namespace or operation segment containing ... The segment grammar ^[a-z0-9][a-z0-9._-]{0,63}$ permits .., but the CachekitIO server rejects .. anywhere in a key. Previously the SDK accepted such segments and produced keys that returned 400 on every CachekitIO request while working on other backends. The rule now applies on every backend, so a segment that is valid on one backend is valid on all.

Modified Public APIs

• cachekit.interop.validate_segment(name, segment): raises InteropError when the value contains ...
  • The error message is: invalid interop {name} {value!r}: must not contain '..', because the CachekitIO server rejects '..' anywhere in a key.
  • The check runs after the grammar match and before the reserved-namespace (ns, nsapi) check.
  • The docstring now documents the rule.
• generate_interop_key(...) and validate_interop_config(...): inherit the rejection through validate_segment.
• Interop decoration: a .. segment surfaces as ConfigurationError at decoration time, before any call is made.
• Accepted inputs: segments with a lone . remain valid, including a trailing dot (get.), a dotted namespace (app.v1) and multi-dot names (a.b.c, users.fetch.by_id).

An inline comment explains why a per-segment check covers the whole key: the : delimiters separate the segments and the args hash is hex, so any .. in a key must lie inside one segment.

Conformance Fixture

• The vendored-fixture pins now reference interop-mode.json 1.2.0 from fix(interop)!: forbid double-dot inside interop segments (LAB-5906) protocol#94.
  • The SHA-256 pin is now 702613766d1b92bc3a337627a96b9aedc89abfeb4d9208c2bb00c9539a0a1f40.
  • The expected key-vector count goes from 34 to 35.
  • The expected error-vector count goes from 11 to 13.
• .secrets.baseline updates only line numbers for existing fixture hex strings and the generated_at timestamp.

Documentation

docs/features/interop-mode.md states the .. rule, and that both segment rules apply on every backend, in two places:

• the cross-SDK contract section
• the guardrails table row for ConfigurationError at decoration time

Tests

• test_interop_model.py: new TestDoubleDotSegments class.
  • Asserts that both keygen and config validation reject a..b, x..y, users.v1..beta, a...b and x...
  • Asserts that lone-dot segments are accepted.
• test_interop_decorator.py:
  • Decoration raises ConfigurationError for a .. namespace and for a .. operation.
  • The lone_dots_stay_valid vector decorates and writes exactly the pinned key.
• test_interop_vectors.py: updated SHA and count pins.

Breaking Change

An interop namespace or operation containing .. now fails at decoration time with ConfigurationError on all backends. Affected segments must be renamed, and their keys become a full cache miss.

---

Summary

The interop/v1 segment pattern admits .. inside a segment (a..b), but the CachekitIO server rejects .. anywhere in a key (cache-key-format.md → Server-Side Requirements, the Traversal row). So this SDK accepted such a segment and minted a key that fails with 400 on every CachekitIO request, while the same key works on other backends. cachekit-io/protocol#94 forbids .. in either segment; this PR implements it.

Changes

• validate_segment (src/cachekit/interop.py) raises InteropError for a namespace or operation containing .., after the grammar check. Decoration surfaces it as ConfigurationError, on every backend. A lone . stays valid, including at the end of a segment.
• Re-vendors interop-mode.json 1.2.0 byte-for-byte from cachekit-io/protocol#94 (sha256 702613766d1b92bc3a337627a96b9aedc89abfeb4d9208c2bb00c9539a0a1f40; 35 key / 13 error vectors) and updates the sha and count pins. The new vectors are reject_double_dot_namespace (a..b), reject_double_dot_operation (x..) and lone_dots_stay_valid (app. / users.fetch.by_id).
• docs/features/interop-mode.md states the rule in the cross-SDK contract and the guardrails table.
• Tests: tests/unit/protocol/test_interop_model.py (keygen and config reject a..b, x..y, users.v1..beta, a...b, x..; accept app.v1, get., a.b.c), test_interop_decorator.py (decoration raises ConfigurationError for a .. namespace and operation; lone_dots_stay_valid decorates and writes the pinned key), and the vector suite's sha and count pins (test_interop_vectors.py).
• .secrets.baseline: timestamp only.

Merge order

Merge cachekit-io/protocol#94 first. The vendored fixture must stay byte-identical to test-vectors/interop-mode.json at its merge commit (sha256 above).

Breaking

An interop namespace or operation containing .. now raises ConfigurationError at decoration time, on every backend. Rename the segment; its keys become a full cache miss. Before this change, such a key already failed on CachekitIO.

Release notes read the breaking note from this block:

BEGIN_COMMIT_OVERRIDE
fix(interop)!: reject double-dot interop segments (LAB-5906) (#391)

BREAKING CHANGE: an interop namespace or operation containing .. now raises ConfigurationError at decoration time, on every backend; the manual generate_interop_key helper raises InteropError. Rename the segment; its keys become a full cache miss.
END_COMMIT_OVERRIDE

Test plan

• uv run ruff check src/ tests/ and uv run ruff format --check src/ tests/
• uv run pytest tests/unit/ tests/critical/ -m "not slow": 3445 passed, 23 skipped
• uv run pytest docs/features/interop-mode.md src/cachekit/interop.py (markdown and doctests): passed
• With the new check removed, the new .. tests and both reject_double_dot_* vectors fail

[coderabbitai]

Warning

Review limit reached

Next included review available in 40 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e4ec887b-3959-4bbe-b51c-3eece0bbd2b6

📥 Commits

Reviewing files that changed from the base of the PR and between 49f722c and 98652c4.

📒 Files selected for processing (7)

• .secrets.baseline
• docs/features/interop-mode.md
• src/cachekit/interop.py
• tests/unit/protocol/fixtures/interop-mode.json
• tests/unit/protocol/test_interop_decorator.py
• tests/unit/protocol/test_interop_model.py
• tests/unit/protocol/test_interop_vectors.py

---

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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!