content-hash-cache-pattern

Topics in the source

• Content-Hash File Cache Pattern
• When to Activate
• Core Pattern
• 1. Content-Hash Based Cache Key
• 2. Frozen Dataclass for Cache Entry
• 3. File-Based Cache Storage
• 4. Service Layer Wrapper (SRP)
• Key Design Decisions

Cache expensive file processing results (PDF parsing, text extraction, image analysis) using SHA-256 content hashes as cache keys. Unlike path-based caching, this approach survives file moves/renames and auto-invalidates when content changes. Building file processing pipelines (PDF, images, text extraction) Processing cost is high and same files are processed repeatedly Need a --cache/--no-cache CLI option Want to add caching to existing pure functions without modifying them Use file content (not path) as the cache key: Why content hash? File rename/move = cache hit. Content change = automatic invalidation. No index file needed. Each cache entry is stored as {hash}.json — O(1) lookup by hash, no index file required. Keep the processing function pure. Add caching as a separate service layer. | Decision | Rationale | |----------|-----------| | SHA-256 content hash | Path-independent, auto-invalidates on content change | | {hash}.json file naming | O(1) lookup, no index file needed | | Service layer wrapper | SRP: extraction stays pure, cache is a separate concern | | Manual JSON serialization | Full control over frozen dataclass serialization | | Corruption returns None | Graceful de

This is an excerpt. Refer to the complete source and its current requirements.