Module interop 

Interop mode (interop/v1): cross-SDK cache keys and plain-MessagePack values. Interop mode (interop/v1): language-neutral cache keys and plain-MessagePack values.

Implements the cross-SDK key and value formats from protocol/spec/interop-mode.md, byte-verified against protocol/test-vectors/interop-mode.json (see tests/interop_vector_tests.rs).

Key format

{namespace}:{operation}:{args_hash}

namespace and operation are user-supplied, validated against ^[a-z0-9][a-z0-9._-]{0,63}$ (full-string). args_hash is the Blake2b-256 digest (lowercase hex) of the canonical MessagePack encoding of the flat argument array. Unlike auto mode, there is no func: segment — the operation identity is explicit, so every SDK computes the same key for the same logical call.

Why a hand-rolled encoder

The spec makes the encoding normative: shortest-form integer/str/bin/array/map headers, float64-only floats, map keys sorted by Unicode code point, sets sorted by encoded bytes, and integral-float collapse. rmp-serde happens to emit shortest forms but provides no sorting, no set semantics, and no number canonicalization — hashing whatever serde produces would make key equality an implementation accident. The closed [InteropValue] model plus an explicit encoder is the only way to guarantee byte-identical hashes across SDKs.

Values

Interop values are plain MessagePack documents — no ByteStorage envelope, no LZ4, no checksum. cachekit-rs already writes plain MessagePack natively (via crate::serializer), so regular crate::CacheKit::set output is interop-readable as-is. Reads are the sharp edge: interop readers MUST consume exactly one MessagePack document and reject trailing bytes — see [deserialize].

Example

use cachekit::interop::{interop_key, InteropValue};

let key = interop_key("users", "get_user", &[InteropValue::from(42i64)]).unwrap();
assert_eq!(
    key,
    "users:get_user:61598716255080080f6456eb065c2e51badfaa4320b0efe97469c29cffee8875"
);

Enums

InteropValue

A value in the closed interop/v1 argument data model.

Functions

canonical_args

Encode the flat argument array to canonical MessagePack (argument profile: number canonicalization applies, so integral floats collapse to ints).

deserialize

Deserialize an interop-mode MessagePack document, consuming exactly one document and rejecting trailing bytes (spec MUST).

interop_key

Generate an interop/v1 cache key: {namespace}:{operation}:{args_hash}.

serialize_value

Encode a single value to canonical MessagePack (value profile: floats are not collapsed — a float value 2.0 stays float64 so it round-trips as a float).