Claudio Ortolina
70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
---
|
|
id: ML-151
|
|
title: Document Assets.Cache TTL and cache invalidation strategy
|
|
status: Done
|
|
assignee: []
|
|
created_date: "2026-04-30 10:48"
|
|
updated_date: "2026-04-30 12:04"
|
|
labels:
|
|
- documentation
|
|
- assets
|
|
dependencies: []
|
|
references:
|
|
- lib/music_library/assets/cache.ex
|
|
priority: low
|
|
---
|
|
|
|
## Description
|
|
|
|
<!-- SECTION:DESCRIPTION:BEGIN -->
|
|
|
|
`Assets.Cache` (`lib/music_library/assets/cache.ex`) uses an ETS table with TTL for caching binary asset data. When assets are updated (e.g., a new cover is uploaded), the cache relies on TTL-based expiry — there is no explicit invalidation.
|
|
|
|
The TTL duration and the rationale for TTL-only invalidation (vs. explicit purge) are not documented in the module or in the architecture docs.
|
|
|
|
Add a `@moduledoc` to `Assets.Cache` that explains:
|
|
|
|
- The TTL value and where it's configured
|
|
- The invalidation strategy (TTL-based expiry) and why explicit invalidation is/isn't needed
|
|
- Update `docs/architecture.md` if the design decision has architectural relevance
|
|
<!-- SECTION:DESCRIPTION:END -->
|
|
|
|
## Acceptance Criteria
|
|
|
|
<!-- AC:BEGIN -->
|
|
|
|
- [x] #1 `Assets.Cache` `@moduledoc` documents the TTL value and where it is configured
|
|
- [x] #2 The invalidation strategy (TTL-based expiry) is explained with rationale
|
|
- [x] #3 Any architectural implications are captured in `docs/architecture.md`
|
|
<!-- AC:END -->
|
|
|
|
## Implementation Plan
|
|
|
|
<!-- SECTION:PLAN:BEGIN -->
|
|
|
|
## Plan
|
|
|
|
### What we're documenting
|
|
|
|
`Assets.Cache` is an ETS-based cache for transformed binary asset data. Assets are stored by SHA256 hash and are immutable (write-once). The cache key is `{payload, format}`.
|
|
|
|
### Key facts to document
|
|
|
|
- **TTL**: `@one_week_seconds` = 7 days, defined as a module attribute
|
|
- **Pruning**: `prune/0` defaults to 7-day TTL, called every 12h by `PruneAssetCache` Oban cron worker
|
|
- **Invalidation strategy**: TTL-based expiry only — no explicit invalidation
|
|
|
|
### Rationale
|
|
|
|
Explicit invalidation isn't needed because:
|
|
|
|
1. Assets are content-addressable (SHA256) and immutable — updates create new hashes, so old entries are never requested again
|
|
2. Periodic pruning (every 12h) cleans up stale entries
|
|
3. ETS table is in-memory, cleared on restart
|
|
|
|
### Changes
|
|
|
|
1. Expand `@moduledoc` in `lib/music_library/assets/cache.ex`
|
|
2. Expand the `Assets.Cache` entry in `docs/architecture.md` Business Logic Modules table
|
|
<!-- SECTION:PLAN:END -->
|