pelican-engine 0.0.0-stage → 0.3.1

package/lib/runtime/resources.js

@@ -0,0 +1,648 @@
+export class ResourceError extends Error {
+    diagnostic;
+    code;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.diagnostic = diagnostic;
+        this.name = "ResourceError";
+        this.code = diagnostic.code;
+    }
+}
+let managerSequence = 0;
+const messages = {
+    TC_RESOURCE_INVALID_IDENTITY: "Resource type and key must be non-empty strings.",
+    TC_RESOURCE_INVALID_LOADER: "A loader requires load and dispose functions.",
+    TC_RESOURCE_LOADER_EXISTS: "A loader is already registered for this resource type.",
+    TC_RESOURCE_LOADER_MISSING: "Register a loader for this resource type before acquiring it.",
+    TC_RESOURCE_INVALID_DESCRIPTOR: "Descriptors must be finite, acyclic JSON data without accessors or custom prototypes.",
+    TC_RESOURCE_DESCRIPTOR_CONFLICT: "This type/key already has a different descriptor; release the old identity before replacing it.",
+    TC_RESOURCE_INVALID_SCOPE: "Use an open scope created by this resource manager.",
+    TC_RESOURCE_DISPOSED: "The resource manager has been disposed.",
+    TC_RESOURCE_CANCELLED: "This consumer was cancelled or its ownership was released.",
+    TC_RESOURCE_LOAD_FAILED: "Resource loading failed; the identity can be acquired again to retry.",
+    TC_RESOURCE_DISPOSE_FAILED: "Resource disposal failed; other owned resources will still be released.",
+    TC_RESOURCE_STALE_HANDLE: "Resource handle is stale, foreign, or has an incorrect type.",
+    TC_RESOURCE_NOT_READY: "The resource is still loading.",
+    TC_RESOURCE_INVALID_SNAPSHOT: "Resource snapshot format, uniqueness, state, or descriptor validation failed.",
+    TC_RESOURCE_ESTIMATE_FAILED: "Resource byte estimate is unavailable or invalid; bytes remain unknown.",
+    TC_RESOURCE_OBSERVER_FAILED: "A resource event observer failed and was detached.",
+};
+/** Descriptors/exceptions never enter diagnostics. URL credentials/query/fragment are removed. */
+function safeIdentity(value) {
+    if (value === undefined)
+        return null;
+    return value
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/\s]*@/gi, "$1[redacted]@")
+        .split(/[?#]/, 1)[0]
+        .replace(/[\r\n\x00-\x1f]/g, "_")
+        .slice(0, 160);
+}
+/** Stricter than JSON.stringify: never silently lose identity data or invoke getters/toJSON. */
+function jsonData(input, seen = new Set()) {
+    if (input === null || typeof input === "string" || typeof input === "boolean")
+        return input;
+    if (typeof input === "number" && Number.isFinite(input))
+        return Object.is(input, -0) ? 0 : input;
+    if (typeof input !== "object" || input === null || seen.has(input))
+        throw new Error("invalid JSON");
+    const proto = Object.getPrototypeOf(input);
+    if (!Array.isArray(input) && proto !== Object.prototype && proto !== null)
+        throw new Error("invalid prototype");
+    if (Object.getOwnPropertySymbols(input).length)
+        throw new Error("symbol property");
+    seen.add(input);
+    try {
+        const properties = Object.getOwnPropertyDescriptors(input);
+        if (Array.isArray(input)) {
+            if (Object.keys(properties).length !== input.length + 1)
+                throw new Error("sparse/extended array");
+            const result = [];
+            for (let i = 0; i < input.length; i++) {
+                const property = properties[String(i)];
+                if (!property || !("value" in property) || !property.enumerable)
+                    throw new Error("invalid array member");
+                result.push(jsonData(property.value, seen));
+            }
+            return result;
+        }
+        const result = {};
+        for (const key of Object.keys(properties).sort()) {
+            const property = properties[key];
+            if (!("value" in property) || !property.enumerable)
+                throw new Error("accessor/non-enumerable");
+            Object.defineProperty(result, key, {
+                value: jsonData(property.value, seen),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        return result;
+    }
+    finally {
+        seen.delete(input);
+    }
+}
+function freezeData(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freezeData(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export class ResourceManager {
+    id = ++managerSequence;
+    loaders = new Map();
+    identities = new Map();
+    slots = new Map();
+    generations = [];
+    free = [];
+    scopes = new Map();
+    scopeSequence = 0;
+    disposed = false;
+    disposePromise;
+    loads = new Set();
+    disposals = new Set();
+    observers = new Set();
+    diagnostics = [];
+    events = [];
+    sequence = 0;
+    historyLimit;
+    counters = {
+        loadsStarted: 0,
+        loadsCompleted: 0,
+        loadsFailed: 0,
+        loadsAborted: 0,
+        disposalsStarted: 0,
+        disposalsCompleted: 0,
+        disposalsFailed: 0,
+        staleResultsDisposed: 0,
+        consumerCancellations: 0,
+        peakEntries: 0,
+    };
+    constructor(options = {}) {
+        this.historyLimit = options.historyLimit ?? 256;
+        if (!Number.isSafeInteger(this.historyLimit) || this.historyLimit < 0)
+            throw new RangeError("historyLimit must be a nonnegative safe integer");
+    }
+    registerLoader(type, loader) {
+        this.assertOpen("register");
+        this.identity(type, "_", "register");
+        if (!loader ||
+            typeof loader.load !== "function" ||
+            typeof loader.dispose !== "function" ||
+            (loader.estimateBytes !== undefined &&
+                typeof loader.estimateBytes !== "function"))
+            throw this.error("TC_RESOURCE_INVALID_LOADER", "register", { type });
+        if (this.loaders.has(type))
+            throw this.error("TC_RESOURCE_LOADER_EXISTS", "register", { type });
+        this.loaders.set(type, {
+            load: loader.load.bind(loader),
+            dispose: loader.dispose.bind(loader),
+            estimateBytes: loader.estimateBytes?.bind(loader),
+        });
+    }
+    createScope(nameOrParent, parent) {
+        this.assertOpen("acquire");
+        const parentToken = typeof nameOrParent === "string" ? parent : (nameOrParent ?? parent);
+        const parentState = parentToken === undefined
+            ? undefined
+            : this.scope(parentToken, "acquire");
+        const state = {
+            token: undefined,
+            closed: false,
+            consumers: new Set(),
+            children: new Set(),
+            parent: parentState,
+        };
+        const token = Object.freeze({
+            manager: this.id,
+            id: ++this.scopeSequence,
+            get released() {
+                return state.closed;
+            },
+            release: () => this.releaseScope(state),
+        });
+        state.token = token;
+        this.scopes.set(token, state);
+        parentState?.children.add(state);
+        return token;
+    }
+    async acquire(type, key, descriptor, scope, options = {}) {
+        this.assertOpen("acquire");
+        this.identity(type, key, "acquire");
+        const owner = this.scope(scope, "acquire");
+        const normalized = this.descriptor(descriptor, "acquire", { type, key });
+        const canonical = JSON.stringify(normalized);
+        const loader = this.loaders.get(type);
+        if (!loader)
+            throw this.error("TC_RESOURCE_LOADER_MISSING", "acquire", { type, key });
+        if (options.signal?.aborted)
+            throw this.error("TC_RESOURCE_CANCELLED", "cancel", { type, key });
+        let entry = this.identities.get(type)?.get(key);
+        if (entry && entry.canonical !== canonical)
+            throw this.error("TC_RESOURCE_DESCRIPTOR_CONFLICT", "acquire", {
+                type,
+                key,
+            });
+        const fresh = entry === undefined;
+        if (!entry) {
+            const index = this.free.pop() ?? this.generations.length;
+            const generation = (this.generations[index] ?? 0) + 1;
+            this.generations[index] = generation;
+            entry = {
+                type,
+                key,
+                canonical,
+                descriptor: freezeData(normalized),
+                loader,
+                handle: Object.freeze({ manager: this.id, index, generation, type }),
+                controller: new AbortController(),
+                state: "pending",
+                current: true,
+                consumers: new Set(),
+                bytes: { status: "unknown" },
+            };
+            let byKey = this.identities.get(type);
+            if (!byKey)
+                this.identities.set(type, (byKey = new Map()));
+            byKey.set(key, entry);
+            this.slots.set(index, entry);
+            this.counters.peakEntries = Math.max(this.counters.peakEntries, this.slots.size);
+        }
+        const target = entry;
+        const promise = new Promise((resolve, reject) => {
+            const consumer = {
+                entry: target,
+                scope: owner,
+                active: true,
+                waiting: true,
+                resolve: resolve,
+                reject,
+            };
+            target.consumers.add(consumer);
+            owner.consumers.add(consumer);
+            if (options.signal) {
+                const abort = () => {
+                    void this.releaseConsumer(consumer, "cancel");
+                };
+                options.signal.addEventListener("abort", abort, { once: true });
+                consumer.detach = () => options.signal.removeEventListener("abort", abort);
+            }
+            if (target.state === "loaded")
+                this.deliver(consumer);
+        });
+        if (fresh)
+            this.startLoad(target);
+        return promise;
+    }
+    get(handle) {
+        const entry = this.entryFor(handle, "get");
+        if (entry.state !== "loaded")
+            throw this.error("TC_RESOURCE_NOT_READY", "get", entry);
+        return entry.value;
+    }
+    /** Own references only for a specified scope; deduplicates multiple leases. */
+    snapshot(scope) {
+        this.assertOpen("snapshot");
+        const entries = scope === undefined
+            ? [...this.slots.values()]
+            : [
+                ...new Set([...this.scope(scope, "snapshot").consumers].map((c) => c.entry)),
+            ];
+        entries.sort((a, b) => a.type < b.type
+            ? -1
+            : a.type > b.type
+                ? 1
+                : a.key < b.key
+                    ? -1
+                    : a.key > b.key
+                        ? 1
+                        : 0);
+        return {
+            format: "pelican.resources",
+            version: 1,
+            resources: entries.map((e) => ({
+                type: e.type,
+                key: e.key,
+                descriptor: jsonData(e.descriptor),
+                state: e.state,
+            })),
+        };
+    }
+    /** Additively rebuild identities into scope. Rollback releases only this transaction's references. */
+    async restore(snapshot, scope, options = {}) {
+        this.assertOpen("restore");
+        const owner = this.scope(scope, "restore");
+        const validated = this.validateSnapshot(snapshot);
+        // Validate every conflict and loader before changing a single live reference.
+        for (const resource of validated.resources) {
+            if (!this.loaders.has(resource.type))
+                throw this.error("TC_RESOURCE_LOADER_MISSING", "restore", resource);
+            const live = this.identities.get(resource.type)?.get(resource.key);
+            if (live && live.canonical !== JSON.stringify(resource.descriptor))
+                throw this.error("TC_RESOURCE_DESCRIPTOR_CONFLICT", "restore", resource);
+        }
+        if (options.signal?.aborted)
+            throw this.error("TC_RESOURCE_CANCELLED", "restore");
+        const transaction = this.createScope(scope);
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        options.signal?.addEventListener("abort", abort, { once: true });
+        try {
+            const pending = validated.resources.map((resource) => this.acquire(resource.type, resource.key, resource.descriptor, transaction, { signal: controller.signal }));
+            const leases = await Promise.all(pending);
+            if (owner.closed || this.disposed || options.signal?.aborted)
+                throw this.error("TC_RESOURCE_CANCELLED", "restore");
+            const temporary = this.scope(transaction, "restore");
+            for (const consumer of temporary.consumers) {
+                consumer.scope = owner;
+                owner.consumers.add(consumer);
+            }
+            temporary.consumers.clear();
+            await transaction.release();
+            this.emit("TC_RESOURCE_RESTORED", "restore");
+            return leases;
+        }
+        catch (error) {
+            controller.abort();
+            await transaction.release();
+            throw error;
+        }
+        finally {
+            options.signal?.removeEventListener("abort", abort);
+        }
+    }
+    inspect() {
+        const entries = [...this.slots.values()].map((e) => ({
+            handle: e.handle,
+            key: safeIdentity(e.key),
+            type: safeIdentity(e.type),
+            state: e.state,
+            refCount: e.consumers.size,
+            bytes: { ...e.bytes },
+        }));
+        const knownBytes = entries.reduce((sum, e) => sum + (e.bytes.status === "known" ? e.bytes.value : 0), 0);
+        const unknownEntries = entries.filter((e) => e.bytes.status === "unknown").length;
+        const pending = entries.filter((e) => e.state === "pending").length;
+        return {
+            disposed: this.disposed,
+            owned: {
+                entries: entries.length,
+                pending,
+                loaded: entries.length - pending,
+                references: entries.reduce((sum, e) => sum + e.refCount, 0),
+                scopes: this.scopes.size,
+                inFlightLoads: this.loads.size,
+                inFlightDisposals: this.disposals.size,
+            },
+            bytes: unknownEntries
+                ? { status: "unknown", knownBytes, unknownEntries }
+                : { status: "known", value: knownBytes, knownBytes, unknownEntries },
+            entries,
+            counters: { ...this.counters },
+        };
+    }
+    getDiagnostics() {
+        return this.diagnostics.map((d) => ({ ...d }));
+    }
+    getEvents() {
+        return this.events.map((e) => ({ ...e }));
+    }
+    subscribe(observer) {
+        this.assertOpen("observe");
+        this.observers.add(observer);
+        return () => {
+            this.observers.delete(observer);
+        };
+    }
+    /** Includes ignored-abort loaders; callers must bound this wait for untrusted providers. */
+    async whenIdle() {
+        while (this.loads.size || this.disposals.size)
+            await Promise.all([...this.loads, ...this.disposals]);
+    }
+    /** Invalidates ownership immediately; does not wait for a loader ignoring abort. */
+    dispose() {
+        if (this.disposePromise)
+            return this.disposePromise;
+        this.disposed = true;
+        let complete;
+        this.disposePromise = new Promise((resolve) => {
+            complete = resolve;
+        });
+        const closing = [...this.scopes.values()].map((scope) => this.releaseScope(scope));
+        void Promise.all([...closing, ...this.disposals]).then(complete);
+        this.observers.clear();
+        return this.disposePromise;
+    }
+    startLoad(entry) {
+        this.counters.loadsStarted++;
+        const task = Promise.resolve().then(async () => {
+            if (!entry.current)
+                return;
+            this.emit("TC_RESOURCE_LOAD_STARTED", "load", entry);
+            try {
+                const value = await entry.loader.load(entry.descriptor, entry.controller.signal);
+                this.counters.loadsCompleted++;
+                if (!entry.current || this.disposed) {
+                    this.counters.staleResultsDisposed++;
+                    await this.disposeValue(entry, value);
+                    return;
+                }
+                entry.value = value;
+                entry.state = "loaded";
+                if (entry.loader.estimateBytes) {
+                    try {
+                        const bytes = entry.loader.estimateBytes(value);
+                        if (typeof bytes === "number" &&
+                            Number.isSafeInteger(bytes) &&
+                            bytes >= 0)
+                            entry.bytes = { status: "known", value: bytes };
+                        else if (bytes !== undefined)
+                            this.error("TC_RESOURCE_ESTIMATE_FAILED", "load", entry, "warning");
+                    }
+                    catch {
+                        this.error("TC_RESOURCE_ESTIMATE_FAILED", "load", entry, "warning");
+                    }
+                }
+                for (const consumer of [...entry.consumers])
+                    this.deliver(consumer);
+                this.emit("TC_RESOURCE_LOADED", "load", entry);
+            }
+            catch {
+                this.counters.loadsFailed++;
+                if (!entry.current)
+                    return;
+                const failure = this.error("TC_RESOURCE_LOAD_FAILED", "load", entry);
+                this.invalidate(entry);
+                for (const consumer of [...entry.consumers])
+                    this.finishConsumer(consumer, failure);
+                this.emit("TC_RESOURCE_LOAD_FAILED", "load", entry);
+            }
+        });
+        this.loads.add(task);
+        void task.then(() => {
+            this.loads.delete(task);
+        });
+    }
+    deliver(consumer) {
+        if (!consumer.active || !consumer.waiting)
+            return;
+        consumer.waiting = false;
+        consumer.detach?.();
+        const lease = Object.freeze({
+            handle: consumer.entry.handle,
+            get released() {
+                return !consumer.active;
+            },
+            release: () => this.releaseConsumer(consumer, "release"),
+        });
+        consumer.resolve(lease);
+    }
+    finishConsumer(consumer, failure) {
+        consumer.active = false;
+        consumer.detach?.();
+        consumer.entry.consumers.delete(consumer);
+        consumer.scope.consumers.delete(consumer);
+        if (consumer.waiting && failure) {
+            consumer.waiting = false;
+            consumer.reject(failure);
+        }
+    }
+    releaseConsumer(consumer, mode) {
+        if (consumer.releasePromise)
+            return consumer.releasePromise;
+        if (!consumer.active)
+            return Promise.resolve();
+        const entry = consumer.entry;
+        const failure = consumer.waiting
+            ? this.error("TC_RESOURCE_CANCELLED", mode, entry)
+            : undefined;
+        this.finishConsumer(consumer, failure);
+        if (mode === "cancel")
+            this.counters.consumerCancellations++;
+        const last = entry.current && entry.consumers.size === 0;
+        if (last) {
+            this.invalidate(entry);
+            if (entry.state === "pending") {
+                this.counters.loadsAborted++;
+                entry.controller.abort();
+                this.emit("TC_RESOURCE_LOAD_ABORTED", "cancel", entry);
+            }
+        }
+        consumer.releasePromise =
+            last && entry.state === "loaded"
+                ? this.disposeValue(entry, entry.value)
+                : Promise.resolve();
+        this.emit("TC_RESOURCE_RELEASED", mode, entry);
+        return consumer.releasePromise;
+    }
+    releaseScope(scope) {
+        if (scope.releasePromise)
+            return scope.releasePromise;
+        scope.closed = true;
+        this.scopes.delete(scope.token);
+        scope.parent?.children.delete(scope);
+        let complete;
+        scope.releasePromise = new Promise((resolve) => {
+            complete = resolve;
+        });
+        void Promise.all([
+            ...[...scope.children].map((child) => this.releaseScope(child)),
+            ...[...scope.consumers].map((consumer) => this.releaseConsumer(consumer, "release")),
+        ]).then(complete);
+        return scope.releasePromise;
+    }
+    disposeValue(entry, value) {
+        this.counters.disposalsStarted++;
+        const task = Promise.resolve().then(async () => {
+            try {
+                await entry.loader.dispose(value);
+                this.counters.disposalsCompleted++;
+                this.emit("TC_RESOURCE_DISPOSED", "dispose", entry);
+            }
+            catch {
+                this.counters.disposalsFailed++;
+                this.error("TC_RESOURCE_DISPOSE_FAILED", "dispose", entry);
+                this.emit("TC_RESOURCE_DISPOSE_FAILED", "dispose", entry);
+            }
+            finally {
+                entry.value = undefined;
+            }
+        });
+        this.disposals.add(task);
+        void task.then(() => {
+            this.disposals.delete(task);
+        });
+        return task;
+    }
+    invalidate(entry) {
+        if (!entry.current)
+            return;
+        entry.current = false;
+        this.slots.delete(entry.handle.index);
+        const byKey = this.identities.get(entry.type);
+        if (byKey.get(entry.key) === entry)
+            byKey.delete(entry.key);
+        if (!byKey.size)
+            this.identities.delete(entry.type);
+        this.free.push(entry.handle.index);
+    }
+    entryFor(handle, mode) {
+        const entry = handle && this.slots.get(handle.index);
+        if (!entry ||
+            handle.manager !== this.id ||
+            handle.generation !== entry.handle.generation ||
+            handle.type !== entry.type)
+            throw this.error("TC_RESOURCE_STALE_HANDLE", mode);
+        return entry;
+    }
+    scope(token, mode) {
+        const scope = this.scopes.get(token);
+        if (!scope || scope.closed)
+            throw this.error("TC_RESOURCE_INVALID_SCOPE", mode);
+        return scope;
+    }
+    identity(type, key, mode) {
+        if (typeof type !== "string" ||
+            !type.length ||
+            typeof key !== "string" ||
+            !key.length)
+            throw this.error("TC_RESOURCE_INVALID_IDENTITY", mode);
+    }
+    descriptor(value, mode, identity) {
+        try {
+            return jsonData(value);
+        }
+        catch {
+            throw this.error("TC_RESOURCE_INVALID_DESCRIPTOR", mode, identity);
+        }
+    }
+    assertOpen(mode) {
+        if (this.disposed)
+            throw this.error("TC_RESOURCE_DISPOSED", mode);
+    }
+    validateSnapshot(input) {
+        let snapshot;
+        try {
+            snapshot = jsonData(input);
+        }
+        catch {
+            throw this.error("TC_RESOURCE_INVALID_SNAPSHOT", "restore");
+        }
+        const invalid = () => this.error("TC_RESOURCE_INVALID_SNAPSHOT", "restore");
+        if (!snapshot ||
+            Array.isArray(snapshot) ||
+            typeof snapshot !== "object" ||
+            snapshot.format !== "pelican.resources" ||
+            snapshot.version !== 1 ||
+            !Array.isArray(snapshot.resources) ||
+            Object.keys(snapshot).sort().join() !== "format,resources,version")
+            throw invalid();
+        const identities = new Map();
+        for (const item of snapshot.resources) {
+            if (!item ||
+                Array.isArray(item) ||
+                typeof item !== "object" ||
+                Object.keys(item).sort().join() !== "descriptor,key,state,type" ||
+                typeof item.type !== "string" ||
+                !item.type.length ||
+                typeof item.key !== "string" ||
+                !item.key.length ||
+                (item.state !== "pending" && item.state !== "loaded"))
+                throw invalid();
+            let keys = identities.get(item.type);
+            if (!keys)
+                identities.set(item.type, (keys = new Set()));
+            if (keys.has(item.key))
+                throw invalid();
+            keys.add(item.key);
+        }
+        return snapshot;
+    }
+    error(code, mode, identity, severity = "error") {
+        const diagnostic = Object.freeze({
+            code,
+            mode,
+            severity,
+            key: safeIdentity(identity?.key),
+            type: safeIdentity(identity?.type),
+            message: messages[code] ?? "Resource operation failed.",
+        });
+        this.retain(this.diagnostics, diagnostic);
+        return new ResourceError(diagnostic);
+    }
+    emit(code, mode, entry) {
+        const event = Object.freeze({
+            sequence: ++this.sequence,
+            code,
+            mode,
+            key: safeIdentity(entry?.key),
+            type: safeIdentity(entry?.type),
+            handle: entry
+                ? Object.freeze({ ...entry.handle, type: safeIdentity(entry.type) })
+                : null,
+        });
+        this.retain(this.events, event);
+        for (const observer of [...this.observers]) {
+            try {
+                observer(event);
+            }
+            catch {
+                this.observers.delete(observer);
+                this.error("TC_RESOURCE_OBSERVER_FAILED", "observe", entry, "warning");
+            }
+        }
+    }
+    retain(history, item) {
+        if (!this.historyLimit)
+            return;
+        history.push(item);
+        if (history.length > this.historyLimit)
+            history.shift();
+    }
+}
+export function createResourceManager(options) {
+    return new ResourceManager(options);
+}