Skip to content

Add memo interop, tag flush parity, and versioned chunks (1.16.0) - #58

Merged
iazaran merged 5 commits into
mainfrom
memo-tags-chunks
Oct 20, 2026
Merged

iazaran merged 5 commits into
mainfrom
memo-tags-chunks

Conversation

@iazaran

@iazaran iazaran commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

This is release 1.16.0. It answers three community requests (tag-driven flushing of chunked data, Cache::memo() interoperability, and "smart-tagging" of chunks), aligns SmartCache with Laravel 13.33/13.34, and ships the four fixes deferred from 1.15.

  • The SmartCache contract is unchanged.
  • One opt-in config key is added: memo.native, default false.
  • Entries written by 1.15 are read unchanged, and 1.15 and 1.16 read each other's entries.
  • A few defects are fixed in ways that change behavior. Each has an upgrade note in the CHANGELOG, also listed below.

Tests: vendor/bin/phpunit reports 678 passing (605 before, 2 pre-existing skips). I also ran the suite locally on Laravel 12.70, 11.57, 10.50 and 9.x; the native-memo tests skip before 12.9, as expected.

There are 71 new tests in tests/Unit/V116FeaturesTest.php, plus 2 in EnumeratesCacheKeysTest. Of the 71, 54 fail on 1.15.0. The other 17 are labelled guards. They pin behavior that must not change, cover the opt-in native memo mode (which 1.15 does not have), or protect against a race or cost the new chunk, registry, index, and dependency handling could introduce. 16 of the guards pass on 1.15; the 17th fails there only because it uses the new registry constant.

Community requests

1. tags() / tag contract

SmartCache already had tags() and flushTags(), and flushTags() already deleted chunk keys, _sc_meta and _sc_dna. The real gap was SmartCache::tags('reports')->flush(): it wiped the entire store, while Laravel's Cache::tags()->flush() clears only the tag. Docs before 1.15 showed that call as the way to clear tagged entries.

  • tags(...)->flush() now clears only those tags (your call). A plain flush(), or a flush() after any other cache call, still clears the store. tags([])->flush() removes nothing.
  • tags('a', 'b') works like Laravel (previously b was dropped), and enum tag names are accepted. supportsTags() is true, since SmartCache's own tag index works on every store.
  • Fixed: tags('t')->putMany([...]) tagged only the first key, so flushTags('t') left the others stale.

2. Cache::memo() interop (opt-in, your call)

smart-cache.memo.native = true (Laravel 12.9+) builds SmartCache::memo() on Laravel's Cache::memo(). There is one memo layer per store, shared with Cache::memo() and every other memo() call, and Laravel clears it between requests and jobs. SmartCache still compresses, chunks and restores above it.

Edge cases handled:

  • add() stays atomic. Laravel's memoized store has no add(), so the write goes to the store, and SmartCache reads that key from the store for the rest of the request.
  • rememberWithLock() reads a value another process stored.
  • Locks and the drivers.* settings come from the store below the memo layer.

Separately, memo() fixes that apply in both modes:

  • SmartCache's bookkeeping is no longer read through the memo layer. A remembered dedup record made memo()->put() skip a needed write and report success, and tag-index updates dropped other processes' entries.
  • memo()->flush() now clears the memo layer.

3. Chunk lifecycle (versioned chunks, your call)

  • Each chunked write uses new chunk keys (_sc_chunk_{key}_{version}_{index}). The replaced entry's chunks are deleted only after the new entry is stored. Previously chunks were rewritten in place, so a concurrent reader could get rows from both versions without any error.
  • Shrinking a chunked value no longer leaves trailing chunks behind (forever, for forever() keys).
  • A read whose chunks are gone re-reads the entry and follows up to three replacements. It evicts only an entry that is still stored and broken, and it evicts the entry right after confirming it.
  • A store that rejects a chunk (Memcached E2BIG) no longer produces an entry that can never be read while put() returns true. The value falls back to compression.
  • Dedup never skips a chunked write, and put() with a TTL ≤ 0 deletes the chunks too.

Deferred 1.15 findings (all included, your call)

  • Redis SCAN prefixes. Scanned keys now have the connection and cache prefixes removed, and keys of other subsystems on the same connection are ignored. As a result, smart-cache:clear --force deletes keys on Redis for the first time; see the upgrade note.
  • Orphan-chunk registry. It is now populated for chunked values stored without expiry. Entries merge, so a concurrent writer that lost stays registered. cleanupOrphanChunks() also removes registered chunks the current entry no longer uses, and runs under a metadata lock. Plain writes never read the registry.
  • LazyChunkedCollection. It throws on a missing chunk instead of returning partial data. flexible()'s stale path loads it before refreshing, and materialize() is new.
  • Managed-key index. Persisting it re-reads the index under the metadata lock and applies only this instance's changes. clearManaged() starts from the stored index.

Other fixes from the audit

  • Laravel 13 parity:
    • Enum keys everywhere; they threw "could not be converted to string".
    • string()/integer()/float()/boolean()/array(), missing() and rememberWithWarmth(). These fell through to the raw repository and returned the internal wrapper on optimized keys.
    • Closure TTLs, and DateInterval durations in flexible().
  • Disabled strategies still decode their entries. Turning compression, chunking or encryption off used to return internal wrappers until expiry (forever for rememberForever()).
  • Invalidation:
    • Namespaced flushPatterns(), invalidateModel() and model patterns now also match the namespace's keys.
    • Placeholders also resolve with the model's original values, including after commit.
    • Enum-cast placeholders no longer throw from save().
    • Dependencies follow the namespace. Tenants using the same key names shared one edge in _sc_dependencies, so one tenant's invalidate() consumed it and another tenant's dependent key went stale.
      • Under a namespace, dependsOn() now also stores a namespaced copy of the edge, and invalidate() follows that copy first.
      • It then follows the un-namespaced edges exactly as before. That edge is still written, so 1.15 servers keep invalidating during a rolling deploy, and dependencies declared before the upgrade keep working.
      • Without a namespace, nothing changes.
  • Queue workers: they refresh SmartCache's loaded state before each job, on the Looping event, keeping the namespace. A refresh job queued without a namespace no longer runs in a namespace leaked by an earlier job.
  • KeyWritten: it carries the write's tags, and fires for forever(), add() and flexible().
  • Circuit breaker: reading the state no longer lets a re-opened breaker close after one success.
  • Stampede protection: the XFetch check used the TTL as the recompute time and refreshed about 37% of reads right after a write. It now uses the measured time.
  • Smart sizing: no longer forces 100-item chunks that exceed the driver limit.
  • Metadata locks: they retry every 25 ms instead of 250 ms.

Upgrade notes (also in CHANGELOG)

  • tags(...)->flush() now clears only those tags. Because the facade is one shared instance, a tags() call left unused (for example, when computing the value throws) also makes a later flush() in the same request tag-only. That is the same pending-tags behavior that has always tagged the next write.
  • smart-cache:clear --force on Redis now deletes every non-SmartCache key of that cache store. That is roughly cache:clear for the store. Shared keys such as illuminate:queue:restart are included.
  • Chunk storage during a rolling deploy. A 1.15 server that reads a chunked key exactly while a 1.16 server rewrites it can find the old chunks gone:
    • with self-healing on (the default), it evicts the entry once;
    • with self-healing off, it returns the internal wrapper for that read.
      In the same race, a 1.15-only fleet silently mixed rows.
  • Lazy loading throws on a missing chunk.
  • Stampede protection refreshes early far less often.

Reviews

  • Three audit agents (strategies, services and commands, Repository parity) produced the fix list.

  • Codex found 8 issues; 7 are fixed with tests, and initial commit with package scaffold #1 (1.15 readers during a rolling deploy) is documented as an upgrade note:

    • re-read chains could still evict the newest entry;
    • tags([])->flush() wiped the store;
    • native add() was invisible to the memo layer;
    • concurrent forever writes lost registry entries;
    • a rewritten key dropped out of the index;
    • empty bulk calls kept a later flush() tag-only;
    • the rolling-deploy eviction.

    Its 8th point is kept as designed and stated in the CHANGELOG: after a lock timeout the update runs without the lock, which is the existing best-effort locking.

  • Fable, two passes. It confirmed the four decisions are implemented. Fixed with tests:

    • after a native rememberWithLock(), the memo layer kept the earlier miss;
    • native memo on a store without locks logged a lock warning on every miss;
    • every write had started reading the chunk registry;
    • a self-heal timing window could evict a value written meanwhile.

    Documented: the pending-tags flush caveat and the rolling-deploy details.

Not in this PR (need a decision)

  • reset() does not restore withJitter() / withCircuitBreaker() toggles. Restoring them would break apps that set them once at boot in Octane.
  • The dashboard's GET / and /health run healthCheck(), which prunes expired index entries and broken chunked entries. They are safe deletions, but they happen on GET.

Docs

  • Updated README, docs/index.html, CHANGELOG (1.16.0), SECURITY.md (maintained line → 1.16.x), config comments, and test counts.
  • Also fixed two existing doc errors:
    • the API reference said memo() returns a MemoizedCacheDriver;
    • the orphan-cleanup section claimed cleanup runs "when a chunked key expires and is accessed".

🤖 Generated with Claude Code

- tags(...)->flush() flushes only those tags, like Laravel's
  Cache::tags()->flush(); a plain flush() still clears the store.
- Opt-in smart-cache.memo.native builds memo() on Laravel's
  Cache::memo() (12.9+); bookkeeping is never memoized in either mode.
- Chunked writes use versioned chunk keys and delete the replaced
  entry's chunks once the new entry is stored; rejected chunk writes
  fall back; forever chunks are registered for cleanup-chunks.
- Laravel 13 Repository parity: enum keys, typed getters, missing(),
  rememberWithWarmth(), Closure TTLs, variadic tags, flexible()
  DateInterval durations, tagged putMany() tags every key.
- Deferred 1.15 fixes: Redis SCAN prefixes, chunk registry, lazy
  chunk partial data, managed-key index lost updates.
- Disabled strategies still decode their entries; namespaced pattern
  and model invalidation; original-value placeholders; queue worker
  state refresh; KeyWritten tags; circuit breaker and XFetch fixes.
- Follow up to three replacements when a chunked entry's chunks are
  gone, and evict only an entry that is still stored and broken.
- tags([])->flush() removes nothing; empty many()/getMultiple()/
  deleteMultiple() calls count as cache calls for a later flush().
- Merge chunk-registry entries so a concurrent forever() write that
  lost keeps its chunks registered; log when the registry cannot be
  stored.
- Re-assert rewritten keys in the managed-key index at the next persist.
- Native memo: keys added or read past the memo layer are read from
  the store for the rest of the request; locks come from the store
  below the memo layer.
- Document the pending-tags flush caveat and the rolling-deploy effect
  on 1.15 readers.
- Skip the chunk registry entirely for writes that add or delete no
  chunks; every put() had started reading it.
- Self-healing evicts the entry right after the read that confirms it
  is broken, before the slower chunk and registry cleanup.
- flexible() and getRaw() read keys added past a native memo layer
  from the store, as get() and has() do.
- Note that Laravel's own Cache::memo() keeps its earlier miss after a
  SmartCache add(); update test counts.
The dependency map stored keys without the namespace, so tenants using
the same key names shared one edge: one tenant's invalidate() consumed
it and another tenant's dependent key stayed stale.

Under a namespace, dependsOn() now also stores the edge with the
namespace on both ends, and invalidate() follows that copy first. The
un-namespaced edge is still written and followed exactly as before, so
1.15 servers keep invalidating during a rolling deploy and dependencies
declared before the upgrade keep working. Without a namespace nothing
changes.
@iazaran
iazaran merged commit 28edaff into main Oct 20, 2026
24 checks passed
@iazaran
iazaran deleted the memo-tags-chunks branch October 20, 2026 19:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant