shardmap

shardmap is the embedded Rust map/cache crate for shard-kv. It gives applications a cloneable, sharded in-process handle with byte-oriented keys and values, TTL support, memory-limit eviction, lock helpers, prepared-key lookups, and native semantic-cache APIs.

Use shardmap when you want an embedded Rust cache. Use the repository's shardcache server package when you need a TCP service.

Install

[dependencies]
shardmap = "0.1.0"

Quick Start

use shardmap::ShardMap;

let cache = ShardMap::new();

cache.insert_slice(b"user:42", b"ready");
let value = cache.get_owned(b"user:42").unwrap();

assert_eq!(value.as_ref(), b"ready");

ShardMap is a cheap cloneable handle. Clones share the same underlying sharded store and can be moved into worker threads.

Feature Overview

Run any example with:

cargo run -p shardmap --example basic_map

Point-Key Map Operations

Use the default ShardMap for a 64-stripe shared embedded map, or ShardMapWithShards<N> when you want to choose the stripe count at compile time.

use shardmap::ShardMap;

let cache = ShardMap::with_capacity(1024);

cache.insert_slice(b"job:1", b"queued");
assert!(cache.contains_key(b"job:1"));

if let Some(mut value) = cache.get_mut(b"job:1") {
    value.set_slice(b"running");
}

assert_eq!(cache.remove(b"job:1").unwrap().as_ref(), b"running");
assert!(!cache.contains_key(b"job:1"));

Use get_owned when you want refcounted bytes after the shard read lock has been released. Use get/get_ref when a short borrowed guard is enough.

TTL, Eviction, And Cache Configuration

TTL values are relative milliseconds. A None TTL means the value does not expire because of time.

use shardmap::ShardMap;

let cache = ShardMap::new();
cache.insert_slice_with_ttl(b"session:1", b"active", Some(30_000));

assert!(cache.contains_key(b"session:1"));

CacheOptions configures the shared-handle cache. Memory limits are enforced inside each stripe, using the selected eviction policy.

use shardmap::{CacheOptions, ShardMap};
use shardmap::config::EvictionPolicy;

let cache = ShardMap::with_options(CacheOptions {
    capacity_hint: Some(32_768),
    total_memory_bytes: Some(256 * 1024 * 1024),
    eviction_policy: EvictionPolicy::Lru,
    ..CacheOptions::default()
});

assert_eq!(cache.shard_count(), 64);

EvictionPolicy::Lru and EvictionPolicy::Lfu are available in the default crate. EvictionPolicy::Prefix is available with the prefix-eviction feature for prefix-group cache workloads.

Prepared Keys And Concurrency

For repeated hot lookups, prepare the key once and reuse the route metadata.

use shardmap::ShardMap;

let cache = ShardMap::new();
cache.insert_slice(b"feature:alpha", b"enabled");

let prepared = cache.prepare_key(b"feature:alpha");
let value = cache.get_prepared_owned(&prepared).unwrap();

assert_eq!(value.as_ref(), b"enabled");

Cloned handles share the same storage, so applications can move a clone into each worker thread and keep using normal map operations.

Entry API And Routing

Use entry when the update naturally depends on whether the key is already present.

use bytes::Bytes;
use shardmap::ShardMap;

let cache = ShardMap::new();
let value = cache.entry(Bytes::from_static(b"job:42"))
    .or_insert(Bytes::from_static(b"queued"));

assert_eq!(value.value().unwrap(), b"queued");

Use route_key when your application already partitions work by shard and wants to send a key to its owning worker.

use shardmap::ShardMapWithShards;

let cache = ShardMapWithShards::<8>::new();
let route = cache.route_key(b"user:42");

assert!(route.shard_id < cache.shard_count());

Lock Helpers

The lock helpers are useful for process-local coordination in embedded mode. They acquire only when the key is absent or expired, release only when the stored token matches, and renew by extending the TTL for the matching token.

use shardmap::ShardMap;

let cache = ShardMap::new();

assert!(cache.try_acquire_lock(b"lock:job:1", b"worker-a", 5_000));
assert!(!cache.try_acquire_lock(b"lock:job:1", b"worker-b", 5_000));
assert!(cache.renew_lock(b"lock:job:1", b"worker-a", 5_000));
assert!(cache.release_lock(b"lock:job:1", b"worker-a"));

Use the server surface when multiple processes or machines need to coordinate through one lock table.

Semantic Cache

Semantic cache entries attach a normalized embedding to the same point-key value. Lookups search live semantic entries and return the best match at or above the requested score.

use shardmap::ShardMap;

let cache = ShardMap::new();
cache.insert_semantic_slice(b"prompt:cat", b"cached cat answer", &[1.0, 0.0])?;
cache.insert_semantic_slice(b"prompt:dog", b"cached dog answer", &[0.0, 1.0])?;

let matched = cache.semantic_search(&[0.9, 0.1], 0.75)?.unwrap();

assert_eq!(matched.key.as_slice(), b"prompt:cat");
assert_eq!(matched.value.as_ref(), b"cached cat answer");
# Ok::<(), shardmap::SemanticCacheError>(())

Plain writes to a key clear its semantic embedding, so semantic hits cannot return a value whose embedding describes an older payload. Repeated exact semantic queries use an internal query-result cache; call disable_semantic_query_cache when benchmarking the cold vector path.

Governance Metadata

Cross-user semantic cache entries can carry opaque governance metadata. Entries written through the default semantic APIs return None; applications that need cross-user authorization can opt into the governance API layer and pass a predicate that must approve the metadata before the cached value is released.

use shardmap::ShardMap;

let cache = ShardMap::new();
cache.insert_semantic_slice_with_governance(
    b"prompt:cat",
    b"cached cat answer",
    &[1.0, 0.0],
    b"tenant=acme;doc=cat-faq;policy=v1",
)?;

let matched = cache
    .semantic_search_with_governance_filter(&[1.0, 0.0], 0.75, |metadata| {
        metadata == Some(b"tenant=acme;doc=cat-faq;policy=v1".as_slice())
    })?
    .unwrap();

assert_eq!(matched.value.as_ref(), b"cached cat answer");
assert_eq!(
    matched.governance.as_deref(),
    Some(b"tenant=acme;doc=cat-faq;policy=v1".as_slice())
);
# Ok::<(), shardmap::SemanticCacheError>(())

The intended data model is:

The cache does not parse governance bytes. Callers can encode tenant, group, source document, policy version, retention tier, region, or audit context in whatever format they already use, then decide whether a semantically close candidate may release its cached value.

Optional Server, Protocol, And Persistence Internals

The crate also contains the storage internals used by the shardcache server: command parsing, RESP/SCNP protocol code, persistence, replication, and server transport modules. Those surfaces are feature-gated so embedded users do not compile server code by default.

Most applications should start with ShardMap. Use lower-level modules only when you are building a custom server, embedding the protocol layer, or wiring storage into a specialized runtime.

API Shape

• ShardMap: default embedded map/cache handle.
• ShardCache: cache-flavored alias for ShardMap.
• ShardMapWithShards<N>: embedded handle with an explicit stripe count.
• CacheOptions: embedded capacity, memory, routing, and lock options.
• get_owned and get_prepared_owned: return refcounted bytes after releasing the shard read lock.
• entry, get_mut, try_insert_slice, and lock helpers: DashMap-style mutation and coordination APIs.
• insert_semantic_slice and semantic_search: native semantic-cache APIs.
• semantic_search_with_governance_filter: semantic cache lookup with request-specific authorization.

Features

License

Licensed under Apache-2.0.