How omid/kash works
Project Type & Purpose
• This is a Rust library (not a full-stack application) with a focus on caching and memoizing function calls.
• The README highlights that it uses macros to intercept function calls, check for cached results, and otherwise call the original function.
• It supports various caching strategies (in-memory, disk-based, Redis-based) and includes examples for different use cases, including async scenarios.
Components from the File Structure
• Top-Level Files & Directories:
• Cargo.toml, Makefile, and README.md indicate this is a library project.
• The examples directory shows usage patterns in different contexts.
• The src directory (with lib.rs and stores submodules) provides core library functionality and implementations of different cache stores.
• The kash_macros directory contains the macro definition and helper routines. This area is key since it generates the caching code at compile-time.
• The tests directory has integration/functional tests for verifying the functionality with different caching backends.
• Architectural Pattern Indicator:
• The project is modular. The core caching logic is separated from the macros and store implementations.
• The “stores” in src and their corresponding modules (i.e., disk.rs, redis.rs) show that the design follows the strategy pattern for caching (you may select among different cache store strategies).
Key Elements to Capture
a. Main Components:
• User-defined functions decorated with #[kash]: Illustrate how application code benefits from function memoization.
• Kash Macro Processor (kash_macros): Show how the macro transforms a function into one that wraps caching logic. Highlight sub-components for “common”, “io” (with disk and redis), and “mem”.
• Core Library (src/lib.rs): Acts as the integration layer which ties together the generated code from macros with the underlying caching stores.
• Cache Store Implementations (src/stores): Include specific modules for disk and redis caching.
• External Dependencies: Illustrate the use of external crates such as ahash for hashing, redis libraries, and possibly tokio for asynchronous operations.
b. Relationships and Interactions:
• When a user calls a decorated function, the expanded macro logic first checks the corresponding cache store (whether in-memory, disk, or redis) before invoking the function.
• The macro (in kash_macros) encapsulates logic for cache key generation, validation (using TTLs or size limits), and error handling with Rust’s Result types.
• For async functions, interactions with the async runtime (tokio) and connection management for redis are also depicted.
• How function calls flow from user code to the macro-enhanced function.
• The caching decision process (cache hit versus cache miss).
• Integration between the core library and the specific caching store implementations.
c. Architectural Patterns or Principles:
• Modularity: The separation between macro generation and store implementations.
• Strategy Pattern: Different caching strategies (disk, redis, memory) chosen based on configuration and feature flags.
• Decorator Pattern: The #[kash] macro “decorates” functions to transparently add caching behavior.
d. Relevant Technologies & Frameworks:
• Rust language constructs (using Cargo, modules, macros).
• Redis and the specific async connection managers for handling async caching.
• Disk caching possibly using file system operations under a configurable directory.
• Hashing through the ahash crate.