Simple Caching

[Rongmario]

Summary

Add a responsive caching API for instances or global states (user home)

Goals

• Support instance (<gameDir>/.cleanroom/cache) and global (~/.cleanroom/cache) locations, can be changed with system property overrides
• Default to the .cleanroom/cache directory and never allow backtracking out of it. Only the root itself or nested paths are accepted, and symlinks are forbidden
• Hashing. Caller-supplied SHA-256 values are strictly verified and unknown values are pinned on first use and verified on later access
• Ingest via:
  • Web
  • ClassLoader resources
  • Path/File
  • From String/byte[]/ByteBuffer
• Use NIO/NIO2 throughout
• Support ATOMIC_MOVE
• Support offline use, a cold miss under offline conditions throws a typed exception instead of an empty file
• Provide a fluent builder API with sync and async terminals, safe for concurrent use

Non Goals

• Download API
• A general-purpose HTTP client
• Quota management or background eviction
• An in-memory object cache
• Guarantees beyond SHA-256's standard collision resistance. The hash is recorded per entry so the algorithm can be versioned later.

Motivation

Every downloaded or generated artifact in the loader currently has the same pattern of fetching once, reuse across restarts, survive offline, never corrupt, never write outside its directory.

Without a shared API each call site re-implements URL.openStream(), Files.copy() etc. Which may inherit bugs such as

• Partial files after interruption
• Silent corruption on reads
• Path traversal from untrusted filenames

A single cache with staged copy, locked verification and recovery gives bootstrapped files, downloads, generated files consistency.

Description

Roots

Cache cache = Cache.instance();  // <gameDir>/.cleanroom/cache
Cache global = Cache.global();   // ~/.cleanroom/cache

Overrides system properties: cleanroom.cache.root.instance, cleanroom.cache.root.global

Confinement

All paths when being resolved, rejects:

• Absolute paths
• Drive letters
• UNC prefixes
• NUL bytes

Escaping .. throws an exception; interior a/../b collapses harmlessly.

Every existing root and entry component is inspected with no-follow attributes and any symbolic links are rejected.

Model

cache.namespace("mod_id").fromUrl(url).version("4.0.0").expectSha256(hex).get(); // Blocking, asyncGet() too?
cache.namespace("properties").fromString("k=1", "UTF_8").put("default.properties"); // Async
cache.namespace("jars").fromFile(p).expectSha256(hex).relocate("dep.jar");

Web fetches use JDK HttpClient (redirects, 10s/30s timeouts) with conditional GET.

• 304 appends refreshed URL metadata

• 200 applies the selected content policy

• 5xx remains an HTTP error

• revalidateIf(Duration): returns warm entries until the duration expires, default to refresh in the background.

• noStale(): disables time-based refresh

• version(String): gives versioning to each cache entry, to be refreshed if the version is greater.

Concurrency

Accepted on both saving and getting (by default?)

Hashing (TBD)

• SHA256
• Allow other kinds of hashes?
• Hash to be empty file, file name: <hash>.<hash_algorithm>

Dependencies

• JDK HttpClient, NIO2, MessageDigest SHA-256. No new external dependencies

References

No response

Guidelines

• I have and will continue to adhere to the guidelines