@relkit/providers-local 0.0.0

package/dist/buckets/storage.js

@@ -0,0 +1,169 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync } from "node:fs";
+import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { assertContainedPath, encodeBucketKey, normalizeBucketKey } from "./keys.js";
+import { quarantineStateFile } from "../state.js";
+import { LocalBucketStateError } from "./types.js";
+const OBJECT_DIRECTORY = "objects";
+const OBJECT_SUFFIX = ".json";
+export function createBucketStorage(requestedRoot) {
+    const root = resolve(requestedRoot);
+    if (root === resolve("/"))
+        throw new LocalBucketStateError("Bucket root is too broad");
+    const objectRoot = join(root, OBJECT_DIRECTORY);
+    ensureDirectory(root);
+    ensureDirectory(objectRoot);
+    assertContainedPath(root, objectRoot);
+    const storage = Object.freeze({
+        root,
+        objectRoot,
+        read: (key) => readObject(objectRoot, key),
+        write: (value) => writeObject(objectRoot, value),
+        remove: (key) => removeObject(objectRoot, key),
+        list: () => listObjects(objectRoot),
+        ready: async () => {
+            await listObjects(objectRoot);
+        },
+    });
+    return storage;
+}
+async function readObject(objectRoot, key) {
+    const path = objectPath(objectRoot, key);
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return undefined;
+        throw new LocalBucketStateError("Bucket object state cannot be read");
+    }
+    try {
+        return parseObject(contents, key);
+    }
+    catch (cause) {
+        if (!(cause instanceof LocalBucketStateError))
+            throw cause;
+        quarantineStateFile(path, resolve(objectRoot, ".."));
+        return undefined;
+    }
+}
+async function writeObject(objectRoot, value) {
+    const target = objectPath(objectRoot, value.key);
+    const temporary = join(objectRoot, `.relkit-tmp-${randomUUID()}${OBJECT_SUFFIX}`);
+    try {
+        await writeFile(temporary, JSON.stringify(value), {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        await rename(temporary, target);
+    }
+    catch (cause) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        if (cause instanceof LocalBucketStateError)
+            throw cause;
+        throw new LocalBucketStateError("Bucket object write could not be committed");
+    }
+}
+async function removeObject(objectRoot, key) {
+    await rm(objectPath(objectRoot, key), { force: true });
+}
+async function listObjects(objectRoot) {
+    let entries;
+    try {
+        entries = await readdir(objectRoot, { withFileTypes: true });
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return [];
+        throw new LocalBucketStateError("Bucket object directory cannot be read");
+    }
+    const values = [];
+    for (const entry of entries) {
+        if (!entry.isFile() ||
+            !entry.name.endsWith(OBJECT_SUFFIX) ||
+            entry.name.startsWith(".relkit-")) {
+            continue;
+        }
+        const path = join(objectRoot, entry.name);
+        let contents;
+        try {
+            contents = await readFile(path, "utf8");
+        }
+        catch {
+            throw new LocalBucketStateError("Bucket object state cannot be read");
+        }
+        try {
+            values.push(parseObject(contents));
+        }
+        catch (cause) {
+            if (!(cause instanceof LocalBucketStateError))
+                throw cause;
+            quarantineStateFile(path, resolve(objectRoot, ".."));
+        }
+    }
+    return values;
+}
+function objectPath(objectRoot, key) {
+    const path = join(objectRoot, `${encodeBucketKey(key)}${OBJECT_SUFFIX}`);
+    assertContainedPath(objectRoot, path);
+    return path;
+}
+function parseObject(contents, expectedKey) {
+    try {
+        const value = JSON.parse(contents);
+        if (value.version !== 1 ||
+            typeof value.key !== "string" ||
+            (expectedKey !== undefined && value.key !== expectedKey) ||
+            !Number.isSafeInteger(value.size) ||
+            value.size < 0 ||
+            typeof value.contentHash !== "string" ||
+            typeof value.etag !== "string" ||
+            typeof value.data !== "string" ||
+            !isStringRecord(value.metadata)) {
+            throw new Error();
+        }
+        normalizeBucketKey(value.key);
+        if (value.contentType !== undefined && typeof value.contentType !== "string") {
+            throw new Error();
+        }
+        const bytes = Buffer.from(value.data, "base64");
+        if (bytes.toString("base64") !== value.data ||
+            bytes.byteLength !== value.size ||
+            value.etag !== value.contentHash ||
+            `sha256:${createHash("sha256").update(bytes).digest("hex")}` !== value.contentHash) {
+            throw new Error();
+        }
+        return value;
+    }
+    catch {
+        throw new LocalBucketStateError("Bucket object state is malformed");
+    }
+}
+function ensureDirectory(path) {
+    try {
+        const info = lstatSync(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new LocalBucketStateError("Bucket root is not a directory");
+    }
+    catch (cause) {
+        if (!cause.code?.includes("ENOENT"))
+            throw cause;
+        mkdirSync(path, { recursive: true });
+        const info = lstatSync(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new LocalBucketStateError("Bucket root is not a directory");
+    }
+}
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function isMissing(value) {
+    return value?.code === "ENOENT";
+}
+//# sourceMappingURL=storage.js.map

package/dist/buckets/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/buckets/storage.ts"],"names":[],"mappings":"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"}

package/dist/buckets/types.d.ts

@@ -0,0 +1,91 @@
+import type { BucketCapabilities, BucketCapability, BucketObjectMetadata, BucketOperation, BucketProvider } from "@relkit/buckets";
+export declare const LOCAL_BUCKET_CAPABILITIES: Readonly<BucketCapabilities>;
+export declare const LOCAL_BUCKET_RESERVED_PREFIXES: readonly string[];
+export interface LocalBucketPolicy {
+    readonly maxObjectBytes?: number;
+    readonly allowedContentTypes?: readonly string[];
+}
+export interface LocalBucketProviderOptions extends LocalBucketPolicy {
+    readonly root?: string;
+    readonly stateRoot?: string;
+    readonly policy?: LocalBucketPolicy;
+    readonly pageSize?: number;
+}
+export interface LocalBucketListOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface LocalBucketListPage {
+    readonly items: readonly string[];
+    readonly nextCursor?: string;
+}
+export interface LocalBucketObjectMetadata extends BucketObjectMetadata {
+    readonly contentHash: string;
+}
+export interface StoredLocalBucketObject {
+    readonly version: 1;
+    readonly key: string;
+    readonly size: number;
+    readonly contentHash: string;
+    readonly etag: string;
+    readonly contentType?: string;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly data: string;
+}
+export type LocalBucketProvider = Omit<BucketProvider, "list"> & {
+    readonly capabilities: Readonly<BucketCapabilities>;
+    readonly root: string;
+    readonly policy: Readonly<LocalBucketPolicy>;
+    readonly list: {
+        (prefix?: string): Promise<readonly string[]>;
+        (prefix: string | undefined, options: LocalBucketListOptions): Promise<LocalBucketListPage>;
+    };
+    readonly listPage: (prefix?: string, options?: LocalBucketListOptions) => Promise<LocalBucketListPage>;
+    readonly ready: () => Promise<void>;
+    readonly close: () => Promise<void>;
+    readonly inspector: {
+        readonly list: (request: {
+            readonly prefix?: string;
+            readonly cursor?: string;
+            readonly limit: number;
+            readonly signal: AbortSignal;
+        }) => Promise<{
+            readonly items: readonly {
+                readonly key: string;
+                readonly metadata?: BucketObjectMetadata;
+            }[];
+            readonly nextCursor?: string;
+        }>;
+        readonly preview: (request: {
+            readonly key: string;
+            readonly offset: number;
+            readonly limit: number;
+            readonly signal: AbortSignal;
+        }) => Promise<{
+            readonly bytes: Uint8Array;
+            readonly metadata: BucketObjectMetadata;
+            readonly totalBytes: number;
+        } | undefined>;
+    };
+};
+export declare class LocalBucketKeyError extends TypeError {
+    readonly code: "RELKIT_BUCKET_KEY_INVALID";
+    constructor();
+}
+export declare class LocalBucketPolicyError extends TypeError {
+    readonly code: "RELKIT_BUCKET_POLICY_INVALID";
+    constructor(message: string);
+}
+export declare class LocalBucketStateError extends Error {
+    readonly code: "RELKIT_BUCKET_STATE_INVALID";
+    constructor(message?: string);
+}
+export declare class LocalBucketPaginationError extends TypeError {
+    readonly code: "RELKIT_BUCKET_CURSOR_INVALID";
+    constructor();
+}
+export type LocalBucketUnsupportedCapability = {
+    readonly capability: BucketCapability;
+    readonly operation: BucketOperation;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/buckets/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/buckets/types.ts"],"names":[],"mappings":"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"}

package/dist/buckets/types.js

@@ -0,0 +1,34 @@
+export const LOCAL_BUCKET_CAPABILITIES = Object.freeze({
+    signedReadUrl: false,
+    signedWriteUrl: false,
+});
+export const LOCAL_BUCKET_RESERVED_PREFIXES = Object.freeze([".relkit", "__relkit"]);
+export class LocalBucketKeyError extends TypeError {
+    code = "RELKIT_BUCKET_KEY_INVALID";
+    constructor() {
+        super("Bucket key is invalid");
+        this.name = "LocalBucketKeyError";
+    }
+}
+export class LocalBucketPolicyError extends TypeError {
+    code = "RELKIT_BUCKET_POLICY_INVALID";
+    constructor(message) {
+        super(message);
+        this.name = "LocalBucketPolicyError";
+    }
+}
+export class LocalBucketStateError extends Error {
+    code = "RELKIT_BUCKET_STATE_INVALID";
+    constructor(message = "Bucket state is invalid") {
+        super(message);
+        this.name = "LocalBucketStateError";
+    }
+}
+export class LocalBucketPaginationError extends TypeError {
+    code = "RELKIT_BUCKET_CURSOR_INVALID";
+    constructor() {
+        super("Bucket list cursor or limit is invalid");
+        this.name = "LocalBucketPaginationError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/buckets/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/buckets/types.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,yBAAyB,GAAiC,MAAM,CAAC,MAAM,CAAC;IACnF,aAAa,EAAE,KAAK;IACpB,cAAc,EAAE,KAAK;CACtB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;AA+ErF,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACvC,IAAI,GAAG,2BAAoC,CAAC;IAErD;QACE,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,SAAS;IAC1C,IAAI,GAAG,8BAAuC,CAAC;IAExD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,6BAAsC,CAAC;IAEvD,YAAY,OAAO,GAAG,yBAAyB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,SAAS;IAC9C,IAAI,GAAG,8BAAuC,CAAC;IAExD;QACE,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}

package/dist/cache/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./keys.js";
+export * from "./inspector.js";
+export * from "./policy.js";
+export { createLocalCacheProvider } from "./provider.js";
+export { createLocalCacheProvider as createLocalCacheProviderForTest } from "./provider.js";
+export * from "./store.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,wBAAwB,IAAI,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAC5F,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,8 @@
+export * from "./keys.js";
+export * from "./inspector.js";
+export * from "./policy.js";
+export { createLocalCacheProvider } from "./provider.js";
+export { createLocalCacheProvider as createLocalCacheProviderForTest } from "./provider.js";
+export * from "./store.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,wBAAwB,IAAI,+BAA+B,EAAE,MAAM,eAAe,CAAC;AAC5F,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/cache/inspector.d.ts

@@ -0,0 +1,4 @@
+import { type LocalCacheProvider } from "./types.js";
+import type { LocalCacheStore } from "./store.js";
+export declare function createLocalCacheInspector(store: LocalCacheStore, clock: () => number): LocalCacheProvider["inspector"];
+//# sourceMappingURL=inspector.d.ts.map

package/dist/cache/inspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspector.d.ts","sourceRoot":"","sources":["../../src/cache/inspector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,MAAM,MAAM,GAClB,kBAAkB,CAAC,WAAW,CAAC,CA2CjC"}

package/dist/cache/inspector.js

@@ -0,0 +1,62 @@
+import { LocalCacheKeyError } from "./types.js";
+export function createLocalCacheInspector(store, clock) {
+    return Object.freeze({
+        scan: async (request) => {
+            if (request.signal.aborted)
+                throw request.signal.reason;
+            const now = clock();
+            store.purgeExpired(now);
+            const entries = store
+                .exportState()
+                .entries.map((entry) => ({ entry, key: publicKey(entry.key) }))
+                .filter(({ key }) => request.search === undefined || key.includes(request.search));
+            const start = request.cursor === undefined ? 0 : Number(request.cursor);
+            if (!Number.isSafeInteger(start) || start < 0)
+                throw new LocalCacheKeyError();
+            const selected = entries.slice(start, start + request.limit);
+            const next = start + selected.length;
+            return {
+                items: selected.map(({ entry, key }) => ({
+                    key,
+                    type: valueType(entry.value),
+                    ttlMs: entry.expiresAt === undefined ? null : Math.max(0, entry.expiresAt - now),
+                    bytes: entry.bytes,
+                })),
+                ...(next < entries.length ? { nextCursor: String(next) } : {}),
+            };
+        },
+        value: async (request) => {
+            if (request.signal.aborted)
+                throw request.signal.reason;
+            const now = clock();
+            store.purgeExpired(now);
+            const found = store
+                .exportState()
+                .entries.find((entry) => publicKey(entry.key) === request.key);
+            if (found === undefined)
+                return undefined;
+            const serialized = JSON.stringify(found.value);
+            const bytes = new TextEncoder().encode(serialized).byteLength;
+            return {
+                key: request.key,
+                type: valueType(found.value),
+                ttlMs: found.expiresAt === undefined ? null : Math.max(0, found.expiresAt - now),
+                bytes,
+                ...(bytes > request.limit ? { truncated: true } : { value: found.value, truncated: false }),
+            };
+        },
+    });
+}
+function publicKey(encoded) {
+    try {
+        const value = JSON.parse(encoded);
+        return JSON.stringify(value.key);
+    }
+    catch {
+        throw new LocalCacheKeyError();
+    }
+}
+function valueType(value) {
+    return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+//# sourceMappingURL=inspector.js.map

package/dist/cache/inspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspector.js","sourceRoot":"","sources":["../../src/cache/inspector.ts"],"names":[],"mappings":"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"}

package/dist/cache/keys.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeCacheId(value: unknown): string;
+export declare function normalizeSchemaVersion(value: unknown): string | number;
+/** Builds a deterministic namespace key without exposing the raw key to logs. */
+export declare function createLocalCacheKey(cacheId: string, schemaVersion: string | number, key: unknown): string;
+export declare function serializeLocalCacheValue(value: unknown): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/cache/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAGA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKvD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAStE;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GAAG,MAAM,EAC9B,GAAG,EAAE,OAAO,GACX,MAAM,CAMR;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM/D"}

package/dist/cache/keys.js

@@ -0,0 +1,34 @@
+import { canonicalJson } from "@relkit/contracts";
+import { LocalCacheKeyError, LocalCacheValueError } from "./types.js";
+export function normalizeCacheId(value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new LocalCacheKeyError();
+    }
+    return value.trim();
+}
+export function normalizeSchemaVersion(value) {
+    if ((typeof value !== "string" && typeof value !== "number") ||
+        (typeof value === "string" && value.trim() === "") ||
+        (typeof value === "number" && (!Number.isSafeInteger(value) || value < 0))) {
+        throw new LocalCacheKeyError();
+    }
+    return typeof value === "string" ? value.trim() : value;
+}
+/** Builds a deterministic namespace key without exposing the raw key to logs. */
+export function createLocalCacheKey(cacheId, schemaVersion, key) {
+    try {
+        return canonicalJson({ cacheId, key, schemaVersion });
+    }
+    catch {
+        throw new LocalCacheKeyError();
+    }
+}
+export function serializeLocalCacheValue(value) {
+    try {
+        return canonicalJson(value);
+    }
+    catch {
+        throw new LocalCacheValueError();
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/cache/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/cache/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IACE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;QACxD,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAClD,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,EAC1E,CAAC;QACD,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,aAA8B,EAC9B,GAAY;IAEZ,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACjC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/cache/persistence.d.ts

@@ -0,0 +1,5 @@
+import type { LocalCacheStoreState } from "./store.js";
+export declare function snapshotPath(root: string): string;
+export declare function readCacheState(path: string, cacheId: string, schemaVersion: string | number): LocalCacheStoreState | undefined;
+export declare function writeCacheState(path: string, state: LocalCacheStoreState, cacheId: string, schemaVersion: string | number): Promise<void>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/cache/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/cache/persistence.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAIvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GAAG,MAAM,GAC7B,oBAAoB,GAAG,SAAS,CAwBlC;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GAAG,MAAM,GAC7B,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/cache/persistence.js

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { canonicalJson } from "@relkit/contracts";
+import { ensureOwnedDirectory, quarantineStateFile } from "../state.js";
+import { LocalCacheStateError } from "./types.js";
+const SNAPSHOT_VERSION = 1;
+export function snapshotPath(root) {
+    return join(ensureOwnedDirectory(root), "snapshot.json");
+}
+export function readCacheState(path, cacheId, schemaVersion) {
+    let contents;
+    try {
+        contents = readFileSync(path, "utf8");
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw new LocalCacheStateError("Cache snapshot cannot be read");
+    }
+    try {
+        const state = JSON.parse(contents);
+        assertState(state, cacheId, schemaVersion);
+        return state;
+    }
+    catch (cause) {
+        if (cause instanceof LocalCacheStateError) {
+            quarantineStateFile(path, dirname(path));
+            return undefined;
+        }
+        quarantineStateFile(path, dirname(path));
+        return undefined;
+    }
+}
+export async function writeCacheState(path, state, cacheId, schemaVersion) {
+    const directory = ensureOwnedDirectory(dirname(path));
+    const temporary = join(directory, `.relkit-tmp-${randomUUID()}.json`);
+    const value = JSON.stringify({ version: SNAPSHOT_VERSION, cacheId, schemaVersion, ...state });
+    try {
+        await writeFile(temporary, value, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw new LocalCacheStateError("Cache snapshot could not be committed");
+    }
+}
+function assertState(state, cacheId, schemaVersion) {
+    if (!isRecord(state) ||
+        state.version !== SNAPSHOT_VERSION ||
+        state.cacheId !== cacheId ||
+        state.schemaVersion !== schemaVersion ||
+        !isCount(state.sequence) ||
+        !Array.isArray(state.entries) ||
+        !isCount(state.bytes) ||
+        !isCount(state.evictions) ||
+        !isCount(state.hits) ||
+        !isCount(state.misses) ||
+        state.entries.some((entry) => !validEntry(entry))) {
+        throw new LocalCacheStateError("Cache snapshot metadata is malformed");
+    }
+    if (state.entries.some((entry) => !isCanonicalKey(entry.key))) {
+        throw new LocalCacheStateError("Cache snapshot key metadata is malformed");
+    }
+    if (state.entries.some((entry) => new TextEncoder().encode(entry.key).byteLength +
+        new TextEncoder().encode(canonicalJson(entry.value)).byteLength !==
+        entry.bytes)) {
+        throw new LocalCacheStateError("Cache snapshot entry size metadata is malformed");
+    }
+    const bytes = state.entries.reduce((total, entry) => total + entry.bytes, 0);
+    const sequence = state.entries.reduce((maximum, entry) => Math.max(maximum, entry.lastUsed), 0);
+    if (bytes !== state.bytes || sequence > state.sequence) {
+        throw new LocalCacheStateError("Cache snapshot counters are malformed");
+    }
+}
+function validEntry(value) {
+    return (isRecord(value) &&
+        typeof value.key === "string" &&
+        isCount(value.bytes) &&
+        isCount(value.lastUsed) &&
+        (value.expiresAt === undefined || isCount(value.expiresAt)) &&
+        isCanonicalValue(value.value));
+}
+function isCanonicalKey(value) {
+    try {
+        return canonicalJson(JSON.parse(value)) === value;
+    }
+    catch {
+        return false;
+    }
+}
+function isCanonicalValue(value) {
+    try {
+        canonicalJson(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=persistence.js.map

package/dist/cache/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/cache/persistence.ts"],"names":[],"mappings":"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"}

package/dist/cache/policy.d.ts

@@ -0,0 +1,9 @@
+import { type CacheOperationContext } from "@relkit/cache";
+import { type LocalCachePolicy, type LocalCacheProviderOptions } from "./types.js";
+export declare function normalizePolicy(options: LocalCacheProviderOptions): LocalCachePolicy;
+export declare function normalizeTtl(value: unknown, policy: LocalCachePolicy): number | undefined;
+export declare function assertActive(context: CacheOperationContext | undefined, clock: () => number): number;
+export declare function readClock(clock: () => number): number;
+export declare function byteLength(value: string): number;
+export declare function clone(value: unknown): unknown;
+//# sourceMappingURL=policy.d.ts.map

package/dist/cache/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/cache/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAEpB,wBAAgB,eAAe,CAAC,OAAO,EAAE,yBAAyB,GAAG,gBAAgB,CAkBpF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAUzF;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,qBAAqB,GAAG,SAAS,EAC1C,KAAK,EAAE,MAAM,MAAM,GAClB,MAAM,CAOR;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,MAAM,GAAG,MAAM,CAMrD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE7C"}