Skip to content

Fix hybrid expiry, unsafe folder names and lock contention - #6

Merged
gabors merged 7 commits into
masterfrom
fix/hybrid-expiry-and-locking
Nov 7, 2026
Merged

gabors merged 7 commits into
masterfrom
fix/hybrid-expiry-and-locking

Conversation

@gabors

@gabors gabors commented Nov 7, 2026

Copy link
Copy Markdown
Member

Fixes

  • Hybrid expiry: the memory copy used MemoryConfig.expiry, so an object could stay readable after its file expired. An object now has one expiry, and entry(ofType:forKey:) reports the same date from memory and from disk.
  • Folder names: with name: "", the cache folder was directory itself, so purging and removeAll() deleted files that weren't the cache's. ../escaped created its folder outside directory. Names that aren't a single folder now throw CocoaError(.fileWriteInvalidFileName) before any files are touched.
  • Lock contention: a memory hit took about 1µs when idle, but 0.9s while a different key was doing a 1s encode. Encoding and decoding now run outside the locks, and memory hits don't wait for disk. A read won't put an object back into memory if it was removed or replaced while decoding.

Not fixed: reading with a different type

Files don't record the type they were written with, so reading as another type depends on the kind of storage. For example, on disk a Data? read as Data returns JSON rather than the original bytes. A real fix needs a file format change, so this is documented for now. The four known cases are recorded with withKnownIssue, so a test run flags it if one gets fixed.

Behaviour changes

Both are in the changelog, and they're worth weighing when choosing the version number (the changelog currently says 5.0.1):

  • A DiskConfig name with a /, like "Images/Thumbnails", used to create nested folders and now throws at startup. This is the one change that could break a working app.
  • MemoryConfig.expiry is ignored when there's a disk. This shouldn't change which objects can be read, because an expired memory copy already fell back to the file, but it can change the date entry reports.

Tests

  • Added tests that compare all kinds of storage, cover the config's default expiry and bad folder names, and use storage from many threads.
  • Added a Thread Sanitizer job to CI.

Run locally:

  • swift test passes on macOS, five runs in a row, with the four known issues above.
  • swift test --sanitize=thread reported no races in three runs.
  • xcodebuild test passes on the iOS Simulator.

Run against the code from before these fixes, the expiry, folder name and slow encode/disk tests fail. The test for Codable code calling back into the storage kills the test process partway through. With only the removed-object check taken out, its test fails too.

The new CI job and the watchOS, tvOS, visionOS and Mac Catalyst builds haven't run yet; this PR is their first run.

Not in this PR

  • Version tag
  • LICENSE.md, which still needs its full text and copyright lines
  • GitHub description and topics
  • Playgrounds, which haven't been run

- An object in hybrid storage has one expiry, so the copy in memory can't
  outlive the file. MemoryConfig.expiry is only used by memory-only storage.
- Refuse DiskConfig names that aren't a single folder, because purging or
  removeAll() could delete files outside the cache.
- Encode and decode outside the locks, and serve memory hits without waiting
  for another object's disk access.
- Document that objects should be read with the type they were written as.
- Add tests that compare all kinds of storage, cover the config's default
  expiry and use storage from many threads. Run Thread Sanitizer in CI.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unrelated key mutations can prevent memory-cache refills, while calculating expiry before acquiring locks can cause writes to succeed with already-expired objects.

2 open issues
What changed in this PR

This PR addresses hybrid-cache expiry, unsafe cache folder names, and lock contention while documenting existing cross-type read limitations.

Changes:

  • Shares one expiry between memory and disk and rejects unsafe folder names.
  • Moves encoding and decoding outside locks and guards against stale memory refills.
  • Adds parity and concurrency tests, Thread Sanitizer CI, and behavior-change documentation.
File Description
Tests/​CacheTests/​TestSupport.swift Adds shared file-operation hooks and concurrency helpers.
Tests/​CacheTests/​StorageTests.swift Moves the file-manager helper into shared test support.
Tests/​CacheTests/​ParityTests.swift Tests storage parity, expiry, and folder-name validation.
Tests/​CacheTests/​ConcurrencyTests.swift Tests concurrent access, contention, reentrancy, and memory refills.
Sources/​Cache/​Storage/​Storage.swift Documents initialization errors and cross-type read limitations.
Sources/​Cache/​Storage/​HybridStorage.swift Shares expiry, bypasses disk locks for memory hits, and guards refills.
Sources/​Cache/​Storage/​DiskStorage.swift Validates folder names and separates serialization from locked file access.
Sources/​Cache/​Configuration/​MemoryConfig.swift Clarifies that default expiry applies only to memory-only storage.
Sources/​Cache/​Configuration/​DiskConfig.swift Documents folder-name restrictions.
README.md Clarifies requirements, read types, folder names, and hybrid expiry.
CHANGELOG.md Records fixes and compatibility changes.
.github/​workflows/​ci.yml Adds a Thread Sanitizer test job.

Review effort: Balanced

A relative expiry was turned into a date before waiting for the lock, so a
slow write to another key used up the object's lifetime, and could leave it
expired by the time it was saved.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A critical validation flaw allows cache names containing NUL characters to alias the storage directory, causing removeAll() to delete unrelated files.

1 open issue
2 previously missed issues

In code that hasn't changed since last review

Medium severity Resolve relative expiry after the disk write

Sources/​Cache/​Storage/​HybridStorage.swift:63

The relative expiry is resolved before acquiring the disk lock and writing the file, so a short-lived hybrid object can already be expired when setObject returns if it waits behind a cache-miss read or diskSize(), or the write itself is slow. Resolve the expiry inside DiskStorage.write after writing the bytes, and return that same expiry for the memory copy. Add a regression test that blocks a disk read rather than another hybrid writer.

Medium severity Bound the wait when a background write fails

Tests/​CacheTests/​TestSupport.swift:116

If the background write throws before reaching Gate.enter()—for example, a file write fails before the attributes hook—whileHeldUp discards the error and waits here forever. The timeout in enter() cannot help because that method never runs, so these tests hang until CI kills the job instead of reporting a failure. Bound this wait too and record the timeout.

2 resolved since last review

Review effort: Balanced

Comment thread Sources/Cache/Storage/DiskStorage.swift Resolved
A DiskConfig name with a NUL passed the folder-name check. File system
calls stop reading a path at a NUL, so purging could act on files far
outside the cache, and it deleted every non-.cache file it found,
subfolders included.

- Refuse names with control characters, and a directory with a NUL
- Purging and removeAll() only delete hash-named files directly in the
  cache folder, checking each one is really inside it
- removeAll() deletes those files instead of the whole folder
- Don't look inside subfolders

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Relative expiry is calculated before acquiring the disk lock, so contention from disk reads or size checks can cause setObject to save an already-expired object.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Resolve object expiry after acquiring the disk lock

Sources/​Cache/​Storage/​HybridStorage.swift:63

The hybrid lock now protects expiry calculation from other writes, but diskSize() and disk reads bypass that lock and can still hold the disk lock. If that wait exceeds the relative expiry, setObject saves an already-expired object because this line has already fixed its deadline. Resolve the expiry inside DiskStorage.write after acquiring the disk lock, and return the concrete expiry for the memory copy.

1 resolved since last review

Review effort: Balanced

Hybrid storage worked out a relative expiry before taking the disk's
lock, which disk reads and diskSize() hold without the hybrid lock.
Waiting for them could use up the expiry, saving an object that had
already expired. The disk now works out the date itself and hybrid
storage gives the copy in memory the same one.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because a finding omitted from the published review identifies a test wait that can hang indefinitely when a background operation fails before signalling entry.

No open issues 🎉

Review effort: Balanced

The gate waited without a limit for the other thread to get there, so a
write that failed before reaching it hung the test.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the cache safety and responsiveness improvements.

No open issues 🎉

Review effort: Balanced

Gabor Shaio added 2 commits November 7, 2026 16:28
Tests that blocked waiting for work on DispatchQueue.global() took every
cooperative thread on CI's three-core runners, which left that queue no
thread to run the work on, so the test run hung until it timed out.
On macOS 26, adding a NUL to a folder's URL gives file:///, so a URL that
was meant to be refused for its NUL arrived as the root folder instead.
The name is now joined to the directory as a string and checked, and the
root folder is refused.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the cache expiry, path-safety, and locking changes.

No open issues 🎉

Review effort: Balanced

@gabors
gabors merged commit 0385dbf into master Nov 7, 2026
8 checks passed
@gabors
gabors deleted the fix/hybrid-expiry-and-locking branch November 7, 2026 23:26
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.

2 participants