oc2token 0.1.0

package/dist/src/cache/store.js

@@ -0,0 +1,396 @@
+import { join, resolve } from "node:path";
+import { DomainError } from "../domain/errors.js";
+import { CacheLock } from "./lock.js";
+import { nodeCacheFileSystem, systemCacheClock, systemCacheProcess, systemCacheRandom } from "./filesystem.js";
+import { CACHE_FORMAT, CURRENT_CACHE_SCHEMA_VERSION, MANIFEST_FILE_NAME, } from "./types.js";
+import { deserializeSnapshot, migrateManifestDocument, normalizeRecord, parseManifest, parseRecords, sanitizeSnapshot, serializeRecords, sha256, toDomainRecord, } from "./schema.js";
+const TEMP_PREFIX = ".oc2token-";
+const TEMP_SUFFIX = ".tmp";
+function errorCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+function missing(error) {
+    return errorCode(error) === "ENOENT";
+}
+function isFutureSchema(error) {
+    return error instanceof DomainError && /future schema/i.test(error.message);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function snapshotGeneration(snapshot) {
+    if (isRecord(snapshot) && Number.isSafeInteger(snapshot.generation) && snapshot.generation >= 0) {
+        return snapshot.generation;
+    }
+    return 0;
+}
+function clockNow(clock) {
+    const value = clock.now?.() ?? clock.wallNow?.();
+    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+        throw new DomainError("invalid-date", "cache clock must return a valid Date");
+    }
+    return value;
+}
+function recordsFromSnapshot(snapshot) {
+    if (isRecord(snapshot) && Array.isArray(snapshot.records)) {
+        return snapshot.records;
+    }
+    return [];
+}
+function normalizeRecords(records) {
+    return records.map((record) => normalizeRecord(record));
+}
+async function quietUnlink(fs, path) {
+    try {
+        await fs.unlink(path);
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+}
+export class NormalizedCacheStore {
+    directory;
+    manifestPath;
+    fs;
+    clock;
+    process;
+    random;
+    lock;
+    recoverOrphans;
+    static sequence = 0;
+    // Chains are process-wide so two store instances targeting the same path do
+    // not race even when their callers are otherwise unrelated.
+    static commitChains = new Map();
+    constructor(directoryOrOptions, dependencies = {}) {
+        const options = typeof directoryOrOptions === "string"
+            ? { ...dependencies, directory: directoryOrOptions }
+            : directoryOrOptions;
+        const directory = options.directory ?? options.rootDir;
+        if (!directory) {
+            throw new DomainError("cache-unavailable", "A cache directory is required");
+        }
+        this.directory = resolve(directory);
+        this.manifestPath = join(this.directory, MANIFEST_FILE_NAME);
+        this.fs = options.fs ?? nodeCacheFileSystem;
+        this.clock = options.clock ?? systemCacheClock;
+        this.process = options.process ?? systemCacheProcess;
+        this.random = options.random ?? systemCacheRandom;
+        this.recoverOrphans = options.recoverOrphans ?? true;
+        const lockDependencies = {
+            fs: this.fs,
+            clock: this.clock,
+            process: this.process,
+            random: this.random,
+            staleLockMs: options.staleLockMs,
+        };
+        this.lock = new CacheLock(this.directory, lockDependencies);
+    }
+    async ensureDirectory() {
+        await this.fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+    }
+    nextName(kind, generation = 0) {
+        NormalizedCacheStore.sequence += 1;
+        const owner = this.random.uuid().replace(/[^a-zA-Z0-9-]/g, "");
+        return `${kind}-${generation}-${this.process.pid}-${owner}-${NormalizedCacheStore.sequence}`;
+    }
+    async syncDirectory() {
+        // Directory fsync is necessary for rename durability on POSIX. Some fake
+        // filesystems do not model directory handles, so this operation is best
+        // effort and can be replaced by a test adapter.
+        try {
+            const directoryHandle = await this.fs.open(this.directory, "r");
+            try {
+                await directoryHandle.sync();
+            }
+            finally {
+                await directoryHandle.close();
+            }
+        }
+        catch (error) {
+            if (errorCode(error) === "EISDIR" || errorCode(error) === "EINVAL" || errorCode(error) === "ENOTSUP") {
+                return;
+            }
+            throw error;
+        }
+    }
+    async writeUniqueAndRename(contents, target, tempKind) {
+        const temp = join(this.directory, `${TEMP_PREFIX}${this.nextName(tempKind)}${TEMP_SUFFIX}`);
+        let handle;
+        try {
+            handle = await this.fs.open(temp, "wx", 0o600);
+            try {
+                await handle.writeFile(contents);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await this.fs.rename(temp, target);
+            await this.syncDirectory();
+        }
+        catch (error) {
+            await quietUnlink(this.fs, temp);
+            throw error;
+        }
+    }
+    async currentManifestVersion() {
+        try {
+            const contents = await this.fs.readFile(this.manifestPath, "utf8");
+            const parsed = migrateManifestDocument(JSON.parse(contents));
+            return parsed.value.manifestVersion;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** Remove only OC2Token's own temporary files, never arbitrary cache files. */
+    async recoverOrphanTemps() {
+        return this.recoverOrphanTempsInternal(false);
+    }
+    async recoverOrphanTempsInternal(underOwnedLock) {
+        const removed = [];
+        const skipped = [];
+        const errors = [];
+        let entries;
+        try {
+            entries = await this.fs.readdir(this.directory);
+        }
+        catch (error) {
+            if (missing(error))
+                return { removed, skipped, errors };
+            return { removed, skipped, errors: [{ file: this.directory, error }] };
+        }
+        if (!underOwnedLock) {
+            try {
+                await this.fs.stat(this.lock.lockPath);
+                // An active writer may still own one of the temp files. Leave all
+                // temps untouched until its lock is gone.
+                return {
+                    removed,
+                    skipped: entries.filter((entry) => this.isTemp(entry)),
+                    errors,
+                };
+            }
+            catch (error) {
+                if (!missing(error)) {
+                    return { removed, skipped, errors: [{ file: this.lock.lockPath, error }] };
+                }
+            }
+        }
+        for (const entry of entries) {
+            if (!this.isTemp(entry))
+                continue;
+            try {
+                await this.fs.unlink(join(this.directory, entry));
+                removed.push(entry);
+            }
+            catch (error) {
+                if (missing(error)) {
+                    skipped.push(entry);
+                }
+                else {
+                    errors.push({ file: entry, error });
+                }
+            }
+        }
+        return { removed, skipped, errors };
+    }
+    isTemp(entry) {
+        return entry.startsWith(TEMP_PREFIX) && entry.endsWith(TEMP_SUFFIX);
+    }
+    async readDetailed() {
+        if (this.recoverOrphans) {
+            await this.recoverOrphanTemps();
+        }
+        let manifestContents;
+        try {
+            manifestContents = await this.fs.readFile(this.manifestPath, "utf8");
+        }
+        catch (error) {
+            if (missing(error))
+                return { status: "empty" };
+            return { status: "unavailable", reason: "cache_unavailable", stale: true, error };
+        }
+        let parsedManifest;
+        try {
+            parsedManifest = parseManifest(manifestContents);
+        }
+        catch (error) {
+            return {
+                status: "unavailable",
+                reason: isFutureSchema(error) ? "future_schema" : "cache_corrupt",
+                stale: true,
+                error,
+            };
+        }
+        const manifest = parsedManifest.value;
+        let recordsContents;
+        try {
+            recordsContents = await this.fs.readFile(join(this.directory, manifest.recordFile), "utf8");
+        }
+        catch (error) {
+            return { status: "unavailable", reason: "cache_corrupt", stale: true, error };
+        }
+        if (Buffer.byteLength(recordsContents, "utf8") !== manifest.recordBytes || sha256(recordsContents) !== manifest.recordSha256) {
+            return {
+                status: "unavailable",
+                reason: "cache_corrupt",
+                stale: true,
+                error: new DomainError("cache-corrupt", "The cache record file failed manifest integrity checks"),
+            };
+        }
+        let parsedRecords;
+        try {
+            parsedRecords = parseRecords(recordsContents);
+        }
+        catch (error) {
+            return {
+                status: "unavailable",
+                reason: isFutureSchema(error) ? "future_schema" : "cache_corrupt",
+                stale: true,
+                error,
+            };
+        }
+        const records = parsedRecords.value.records.map(toDomainRecord);
+        return {
+            status: "available",
+            snapshot: deserializeSnapshot(manifest.snapshot, records),
+            records,
+            manifest,
+            migrated: parsedManifest.migrated || parsedRecords.migrated,
+        };
+    }
+    async read(options) {
+        if (options?.signal?.aborted) {
+            throw new DomainError("cancelled", "The cache read was cancelled");
+        }
+        const result = await this.readDetailed();
+        return result.status === "available" ? result.snapshot : null;
+    }
+    async commitNormalized(snapshot, records) {
+        try {
+            await this.ensureDirectory();
+        }
+        catch (error) {
+            return { status: "cache_unavailable", snapshot, records, error };
+        }
+        let lockResult;
+        try {
+            lockResult = await this.lock.tryAcquire();
+        }
+        catch (error) {
+            return { status: "cache_unavailable", snapshot, records, error };
+        }
+        if (lockResult.status === "busy") {
+            return { status: "cache_busy", snapshot, records, owner: lockResult.owner };
+        }
+        try {
+            // We hold the lock, so no other process can be writing a temp file.
+            await this.recoverOrphanTempsInternal(true);
+            const recordsContents = serializeRecords(records);
+            const generation = snapshotGeneration(snapshot);
+            const recordFile = `records-${generation}-${this.nextName("record")}.json`;
+            await this.writeUniqueAndRename(recordsContents, join(this.directory, recordFile), "records");
+            const manifest = {
+                format: CACHE_FORMAT,
+                schemaVersion: CURRENT_CACHE_SCHEMA_VERSION,
+                manifestVersion: (await this.currentManifestVersion()) + 1,
+                complete: true,
+                generation,
+                createdAt: clockNow(this.clock).toISOString(),
+                recordFile,
+                recordBytes: Buffer.byteLength(recordsContents, "utf8"),
+                recordSha256: sha256(recordsContents),
+                snapshot: sanitizeSnapshot(snapshot),
+            };
+            const manifestContents = `${JSON.stringify(manifest)}\n`;
+            await this.writeUniqueAndRename(manifestContents, this.manifestPath, "manifest");
+            const normalizedRecords = records.map((record) => toDomainRecord(normalizeRecord(record)));
+            return { status: "committed", snapshot, records: normalizedRecords, manifest, recordFile };
+        }
+        catch (error) {
+            return { status: "cache_unavailable", snapshot, records, error };
+        }
+        finally {
+            await lockResult.release();
+        }
+    }
+    /**
+     * Commit is non-blocking across processes: a held lock returns cache_busy and
+     * leaves the caller's correct in-memory snapshot untouched. Calls in this
+     * process are serialized for the complete record+manifest publication.
+     */
+    async commitDetailed(snapshot, records = recordsFromSnapshot(snapshot)) {
+        const normalized = normalizeRecords(records);
+        const previous = NormalizedCacheStore.commitChains.get(this.directory) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(() => this.commitNormalized(snapshot, records));
+        NormalizedCacheStore.commitChains.set(this.directory, current);
+        try {
+            return await current;
+        }
+        finally {
+            if (NormalizedCacheStore.commitChains.get(this.directory) === current) {
+                NormalizedCacheStore.commitChains.delete(this.directory);
+            }
+        }
+    }
+    async commit(snapshot, options) {
+        if (options?.signal?.aborted) {
+            throw new DomainError("cancelled", "The cache commit was cancelled");
+        }
+        const result = await this.commitDetailed(snapshot);
+        if (result.status === "cache_busy") {
+            throw new DomainError("cache-busy", "Another OC2Token process owns the cache lock", {
+                retryable: true,
+            });
+        }
+        if (result.status === "cache_unavailable") {
+            throw new DomainError("cache-unavailable", "The cache commit could not be published", {
+                cause: result.error,
+                retryable: true,
+            });
+        }
+    }
+}
+export const FileCacheStore = NormalizedCacheStore;
+export const SnapshotCacheStore = NormalizedCacheStore;
+/** Domain-facing facade: detailed callers can inspect cache_busy via commitDetailed. */
+export class SnapshotStoreAdapter {
+    detailed;
+    constructor(detailed) {
+        this.detailed = detailed;
+    }
+    async read(_options) {
+        const result = await this.detailed.readDetailed();
+        return result.status === "available" ? result.snapshot : null;
+    }
+    async commit(snapshot, options) {
+        if (options?.signal?.aborted) {
+            throw new DomainError("cancelled", "The cache commit was cancelled");
+        }
+        const result = await this.detailed.commitDetailed(snapshot);
+        if (result.status === "cache_busy") {
+            throw new DomainError("cache-busy", "Another OC2Token process owns the cache lock", {
+                retryable: true,
+            });
+        }
+        if (result.status === "cache_unavailable") {
+            throw new DomainError("cache-unavailable", "The cache commit could not be published", {
+                cause: result.error,
+                retryable: true,
+            });
+        }
+    }
+}
+export function createSnapshotStore(options) {
+    return new SnapshotStoreAdapter(new NormalizedCacheStore(options));
+}
+export function createNormalizedCacheStore(options) {
+    return new NormalizedCacheStore(options);
+}
+//# sourceMappingURL=store.js.map

package/dist/src/cache/store.js.map

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

package/dist/src/cache/types.d.ts

@@ -0,0 +1,130 @@
+import type { ProviderKind } from "../domain/index.js";
+import type { StoredSnapshot, UsageRecord } from "../domain/index.js";
+export type { StoredSnapshot, UsageRecord };
+export declare const CACHE_FORMAT: "oc2token.normalized-cache";
+export declare const RECORDS_FORMAT: "oc2token.normalized-records";
+export declare const MANIFEST_FILE_NAME: "manifest.json";
+export declare const LOCK_DIRECTORY_NAME: ".lock";
+export declare const CURRENT_CACHE_SCHEMA_VERSION: 2;
+export interface CacheFileHandle {
+    writeFile(data: string): Promise<void>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface CacheFileStat {
+    readonly mtimeMs: number;
+    readonly isFile?: () => boolean;
+    readonly isDirectory?: () => boolean;
+}
+/** The smallest filesystem surface needed by the crash-safe store. */
+export interface CacheFileSystem {
+    mkdir(path: string, options?: {
+        readonly recursive?: boolean;
+        readonly mode?: number;
+    }): Promise<void>;
+    open(path: string, flags: string, mode?: number): Promise<CacheFileHandle>;
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rm(path: string, options?: {
+        readonly recursive?: boolean;
+        readonly force?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<readonly string[]>;
+    stat(path: string): Promise<CacheFileStat>;
+}
+export interface CacheClock {
+    /** `now` is the cache-local spelling; `wallNow` accepts the shared domain Clock seam. */
+    now?(): Date;
+    wallNow?(): Date;
+}
+export interface CacheProcess {
+    readonly pid: number;
+    readonly hostname: string;
+    isAlive?(pid: number): Promise<boolean> | boolean;
+}
+export interface CacheRandom {
+    uuid(): string;
+}
+export interface CacheDependencies {
+    readonly fs?: CacheFileSystem;
+    readonly clock?: CacheClock;
+    readonly process?: CacheProcess;
+    readonly random?: CacheRandom;
+}
+export type CacheReadUnavailableReason = "cache_busy" | "cache_corrupt" | "future_schema" | "cache_unavailable";
+export interface CacheOwner {
+    readonly pid: number;
+    readonly host: string;
+    readonly start: string;
+    readonly owner: string;
+}
+export interface CacheManifest {
+    readonly format: typeof CACHE_FORMAT;
+    readonly schemaVersion: number;
+    readonly manifestVersion: number;
+    readonly complete: true;
+    readonly generation: number;
+    readonly createdAt: string;
+    readonly recordFile: string;
+    readonly recordBytes: number;
+    readonly recordSha256: string;
+    readonly snapshot: unknown;
+    readonly providerFingerprints?: Record<ProviderKind, string>;
+}
+export interface CacheReadAvailable {
+    readonly status: "available";
+    readonly snapshot: StoredSnapshot;
+    readonly records: readonly UsageRecord[];
+    readonly manifest: CacheManifest;
+    readonly migrated: boolean;
+}
+export interface CacheReadEmpty {
+    readonly status: "empty";
+}
+export interface CacheReadUnavailable {
+    readonly status: "unavailable";
+    readonly reason: CacheReadUnavailableReason;
+    readonly stale: true;
+    readonly error?: unknown;
+    readonly owner?: CacheOwner;
+}
+export type CacheReadResult = CacheReadAvailable | CacheReadEmpty | CacheReadUnavailable;
+export interface CacheCommitSuccess {
+    readonly status: "committed";
+    readonly snapshot: StoredSnapshot;
+    readonly records: readonly UsageRecord[];
+    readonly manifest: CacheManifest;
+    readonly recordFile: string;
+}
+export interface CacheCommitBusy {
+    /** The caller must keep using this in-memory snapshot and retry later. */
+    readonly status: "cache_busy";
+    readonly snapshot: StoredSnapshot;
+    readonly records: readonly UsageRecord[];
+    readonly owner?: CacheOwner;
+}
+export interface CacheCommitUnavailable {
+    readonly status: "cache_unavailable";
+    readonly snapshot: StoredSnapshot;
+    readonly records: readonly UsageRecord[];
+    readonly error: unknown;
+}
+export type CacheCommitResult = CacheCommitSuccess | CacheCommitBusy | CacheCommitUnavailable;
+export interface OrphanRecoveryResult {
+    readonly removed: readonly string[];
+    readonly skipped: readonly string[];
+    readonly errors: readonly {
+        readonly file: string;
+        readonly error: unknown;
+    }[];
+}
+export interface CacheStoreOptions extends CacheDependencies {
+    /** Absolute or relative directory owned by OC2Token. */
+    readonly directory?: string;
+    /** Alias accepted for callers that call the path a root directory. */
+    readonly rootDir?: string;
+    readonly staleLockMs?: number;
+    /** Set false only for a controlled recovery tool; normal readers leave it true. */
+    readonly recoverOrphans?: boolean;
+}

package/dist/src/cache/types.js

@@ -0,0 +1,6 @@
+export const CACHE_FORMAT = "oc2token.normalized-cache";
+export const RECORDS_FORMAT = "oc2token.normalized-records";
+export const MANIFEST_FILE_NAME = "manifest.json";
+export const LOCK_DIRECTORY_NAME = ".lock";
+export const CURRENT_CACHE_SCHEMA_VERSION = 2;
+//# sourceMappingURL=types.js.map

package/dist/src/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cache/types.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,YAAY,GAAG,2BAAoC,CAAC;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,6BAAsC,CAAC;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAwB,CAAC;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAgB,CAAC;AACpD,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAU,CAAC"}

package/dist/src/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+interface CliIO {
+    readonly stdin: NodeJS.ReadStream;
+    readonly stdout: NodeJS.WriteStream;
+    readonly stderr: NodeJS.WriteStream;
+}
+export declare function main(args?: string[], io?: CliIO): Promise<number>;
+export {};