@intx/tool-packaging 0.2.2

package/dist/cache.d.ts

@@ -0,0 +1,89 @@
+export interface TarballCacheConfig {
+    readonly rootDir: string;
+    readonly maxBytes: number;
+}
+export interface TarballCache {
+    get(integrity: string): Promise<Uint8Array | null>;
+    /**
+     * Presence probe. Returns true when an entry for `integrity` is
+     * resident on disk. Cheaper than `get` for callers that only need
+     * to decide whether a fetch is required — `has` checks file
+     * existence without reading bytes or touching atime.
+     */
+    has(integrity: string): Promise<boolean>;
+    put(integrity: string, bytes: Uint8Array): Promise<void>;
+    /**
+     * Mark the cache entry for `integrity` as poisoned and remove its
+     * tarball bytes immediately so a subsequent `extractTarball` call
+     * cannot reuse the on-disk extraction. The extraction directory's
+     * physical reclaim is deferred until every in-flight reader released
+     * by `extractTarball` has dropped its reference, so an evict that
+     * races a concurrent `hardlinkTree` walk of the same extraction does
+     * not pull the tree out from under the walk and surface as ENOENT.
+     *
+     * Until every reader releases, the on-disk extraction is left in
+     * place but is no longer reachable via a fresh `extractTarball`
+     * (because the tarball blob is gone). Callers that need the bytes
+     * back must re-fetch and `put` them, which will trigger a fresh
+     * extraction into a new directory once the deferred reclaim
+     * completes.
+     */
+    evict(integrity: string): Promise<void>;
+    /**
+     * Unpack the cached tarball for `integrity` into a content-addressable
+     * extraction directory and return its absolute path along with a
+     * `release` callback the caller MUST invoke when it is done walking
+     * the directory. The directory is reference-counted: a concurrent
+     * `evict` for the same integrity defers the physical removal of the
+     * extraction tree until every outstanding `release` has been called.
+     *
+     * The same path is returned on subsequent calls without re-extracting;
+     * concurrent callers for the same integrity each get a path to a
+     * fully-populated directory and each get their own `release` handle.
+     *
+     * Throws if `integrity` is not present in the cache; callers must
+     * `put` (or otherwise materialize) the bytes first.
+     */
+    extractTarball(integrity: string): Promise<{
+        readonly dir: string;
+        readonly release: () => void;
+    }>;
+    /**
+     * Walk the cache tree and remove any staged tmp paths left behind
+     * by a `put` or `extractTarball` that crashed between staging and
+     * the final rename. Callers should invoke this once at sidecar
+     * boot, before any apply runs. Idempotent: a no-op if the tree
+     * holds no orphans.
+     *
+     * Orphans take the shape `<entryDir>/tarball.tgz.tmp.<pid>.<rand>`
+     * (from `put`) and `<entryDir>/extracted.tmp.<pid>.<rand>` (from
+     * `extractTarball`). The single-process contract means a tmp path
+     * surviving across boots cannot be in use by another process; it
+     * is always safe to remove.
+     */
+    sweepOrphans(): Promise<void>;
+    /** Test-only: total bytes currently stored. */
+    size(): Promise<number>;
+}
+/**
+ * Thrown by `put` when supplied bytes do not match the supplied
+ * integrity. The cache never stores bytes that fail this check.
+ */
+export declare class TarballIntegrityMismatchError extends Error {
+    readonly integrity: string;
+    constructor(integrity: string);
+}
+/**
+ * Construct a TarballCache rooted at `config.rootDir`.
+ *
+ * **Single-process contract.** Pointing two sidecar processes at the
+ * same cache root is unsupported. The pid-prefixed staging path is
+ * decorative for intra-process races — it keeps two concurrent puts
+ * in the same process from clobbering each other's tmp files — but
+ * cross-process races on the same integrity can still collide during
+ * the final rename (one process moves the staged file into place, the
+ * other's rename overwrites or fails depending on the platform's
+ * rename-over-existing semantics). The atomicity guarantees in this
+ * module assume a single owning process per `rootDir`.
+ */
+export declare function createTarballCache(config: TarballCacheConfig): TarballCache;