Crate hitbox_fn 

hitbox-fn

Function memoization for the Hitbox caching framework.

This crate provides tools for caching async function results using the hitbox FSM. It wraps function arguments and return types into the hitbox pipeline, handling cache key generation, serialization, and upstream execution.

Overview

• Cache - Pre-configured cache with backend, policy, and concurrency settings
• [#[cached]] - Attribute macro that transforms async functions into cacheable functions
• KeyExtract - Trait for types to describe their cache key contribution
• Arg / Skipped - Wrappers to include or exclude function parameters from cache keys
• FnExtractor - Bridges KeyExtract to hitbox’s Extractor trait
• FnUpstream - Adapts async functions to hitbox’s Upstream trait

Quick Start

use hitbox_fn::prelude::*;
use hitbox_moka::MokaBackend;
use std::time::Duration;

#[derive(KeyExtract)]
struct UserId(u64);

#[cached]
async fn fetch_user(id: UserId) -> Result<User, Error> {
    // expensive operation
}

// Build a reusable cache
let cache = Cache::builder()
    .backend(MokaBackend::builder().max_entries(1000).build())
    .policy(PolicyConfig::builder().ttl(Duration::from_secs(60)).build())
    .build();

// Call through cache
let user = fetch_user(UserId(42))
    .cache(&cache)
    .await?;

// With cache context (hit/miss/stale info)
let (user, ctx) = fetch_user(UserId(42))
    .cache(&cache)
    .with_context()
    .await;

// Or call directly without caching (passthrough)
let user = fetch_user(UserId(42)).await?;

Feature Flags

• derive - Enable derive macros (#[cached], #[derive(KeyExtract)], etc.) via hitbox-derive
• rkyv_format - Enable rkyv zero-copy serialization support

Modules

prelude

Prelude for convenient imports.

Structs

Arg

Wrapper for function arguments included in cache key extraction.

Args

Wrapper around tuple to satisfy orphan rule.

Cache

Pre-configured cache with backend, policy, concurrency manager, and offload manager.

CacheBuilder

Builder for Cache with typestate pattern.

FnExtractor

Generic extractor that uses KeyExtract trait to generate cache keys.

FnUpstream

Wrapper that adapts an async function to the Upstream trait.

NoBackend

Marker: no backend configured.

NoContext

Marker: no context requested in response.

NoPolicy

Marker: no policy configured.

Skipped

Wrapper for function arguments excluded from cache key extraction.

WithBackend

Marker: backend configured.

WithContext

Marker: context requested in response.

WithPolicy

Marker: policy configured.

Traits

CacheAccess

Trait for accessing cache internals.

CachedFieldClone

Marker trait for types that can be used as cached (non-skipped) fields in #[derive(CacheableResponse)].

KeyExtract

Trait for types that can contribute to a cache key.

SkippedFieldDefault

Marker trait for types that can be used as skipped fields in #[derive(CacheableResponse)].