@hypequery/deployment 0.2.0 → 0.4.0

package/dist/runtime-materialization.js

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareProtocolDeploymentReleaseEnvelope } from '@hypequery/protocol';
+import { validateDeploymentActivationRecord } from './activation.js';
+import { verifyDeploymentBundle, } from './bundle.js';
+const DEFAULT_STABILITY_ATTEMPTS = 4;
+const MAX_STABILITY_ATTEMPTS = 16;
+export class DeploymentRuntimeMaterializationError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'DeploymentRuntimeMaterializationError';
+        this.code = code;
+    }
+}
+function materializationError(code, message, cause) {
+    return new DeploymentRuntimeMaterializationError(code, message, { cause });
+}
+function sameTarget(left, right) {
+    return left.project === right.project && left.environment === right.environment;
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+async function readArtifact(bundleDirectory, artifact) {
+    const artifactPath = path.join(bundleDirectory, ...artifact.path.split('/'));
+    let handle;
+    try {
+        const initial = await lstat(artifactPath);
+        if (initial.isSymbolicLink() || !initial.isFile() || initial.size !== artifact.byteLength) {
+            throw new Error('Runtime artifact is not the declared bounded regular file.');
+        }
+        handle = await open(artifactPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size !== artifact.byteLength) {
+            throw new Error('Runtime artifact changed before materialization.');
+        }
+        const bytes = await handle.readFile();
+        if (bytes.byteLength !== artifact.byteLength || sha256(bytes) !== artifact.sha256) {
+            throw new Error('Runtime artifact bytes do not match the closed bundle manifest.');
+        }
+        await handle.close();
+        handle = undefined;
+        return Uint8Array.from(bytes);
+    }
+    catch (error) {
+        try {
+            await handle?.close();
+        }
+        catch {
+            // Preserve the validation failure that made this artifact unusable.
+        }
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_ARTIFACT_INVALID', 'A deployment runtime artifact could not be materialized.', error);
+    }
+}
+function artifactSnapshot(input, bytes) {
+    const materialized = Uint8Array.from(bytes);
+    return Object.freeze({
+        runtime: input.runtime,
+        artifactSha256: input.artifactSha256,
+        byteLength: materialized.byteLength,
+        entrypoints: Object.freeze([...input.entrypoints]),
+        read: () => Uint8Array.from(materialized),
+    });
+}
+async function materializeActivation(activation, releases) {
+    let stored;
+    try {
+        stored = await releases.read(activation.releaseIdentity);
+    }
+    catch (error) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_RELEASE_INVALID', 'The active deployment release could not be revalidated.', error);
+    }
+    if (!stored) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_RELEASE_NOT_FOUND', 'The active deployment release was not found.');
+    }
+    let release;
+    let releaseIdentity;
+    try {
+        const prepared = prepareProtocolDeploymentReleaseEnvelope(stored.release);
+        release = prepared.release;
+        releaseIdentity = prepared.identity;
+    }
+    catch (error) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_RELEASE_INVALID', 'The active deployment release envelope is invalid.', error);
+    }
+    if (stored.releaseIdentity !== activation.releaseIdentity
+        || releaseIdentity !== activation.releaseIdentity
+        || !sameTarget(release.target, activation.target)
+        || release.bundleIdentity !== stored.bundle.identity) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_RELEASE_INVALID', 'The active deployment release is inconsistent with its activation or bundle.');
+    }
+    let bundle;
+    try {
+        bundle = await verifyDeploymentBundle(stored.bundle.directory);
+    }
+    catch (error) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_RELEASE_INVALID', 'The active deployment bundle could not be revalidated.', error);
+    }
+    if (bundle.identity !== stored.bundle.identity
+        || bundle.identity !== release.bundleIdentity) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_RELEASE_INVALID', 'The active deployment bundle identity is inconsistent.');
+    }
+    const entrypoints = new Map();
+    const queries = [];
+    for (const query of bundle.contract.queries) {
+        const implementation = query.implementation;
+        if (implementation.kind !== 'runtime-reference')
+            continue;
+        const names = entrypoints.get(implementation.artifactSha256) ?? [];
+        names.push(implementation.entrypoint);
+        entrypoints.set(implementation.artifactSha256, names);
+        queries.push(Object.freeze({
+            query: query.name,
+            runtime: implementation.runtime,
+            artifactSha256: implementation.artifactSha256,
+            entrypoint: implementation.entrypoint,
+        }));
+    }
+    const artifacts = [];
+    for (const artifact of bundle.manifest.artifacts) {
+        const bytes = await readArtifact(bundle.directory, artifact);
+        artifacts.push(artifactSnapshot({
+            runtime: artifact.runtime,
+            artifactSha256: artifact.sha256,
+            entrypoints: [...new Set(entrypoints.get(artifact.sha256) ?? [])].sort(),
+        }, bytes));
+    }
+    artifacts.sort((left, right) => left.artifactSha256.localeCompare(right.artifactSha256));
+    queries.sort((left, right) => left.query.localeCompare(right.query));
+    return Object.freeze({
+        target: activation.target,
+        activation,
+        release,
+        releaseIdentity,
+        bundleIdentity: bundle.identity,
+        deployment: bundle.contract,
+        artifacts: Object.freeze(artifacts),
+        queries: Object.freeze(queries),
+    });
+}
+function stabilityAttempts(input) {
+    const value = input ?? DEFAULT_STABILITY_ATTEMPTS;
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_STABILITY_ATTEMPTS) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_CONFIGURATION', `maxStabilityAttempts must be between 1 and ${MAX_STABILITY_ATTEMPTS}.`);
+    }
+    return value;
+}
+export function createDeploymentRuntimeMaterializer(options) {
+    const maximumAttempts = stabilityAttempts(options.maxStabilityAttempts);
+    if (!constants.O_NOFOLLOW) {
+        throw materializationError('HQ_RUNTIME_MATERIALIZATION_CONFIGURATION', 'Runtime materialization requires filesystem no-follow support.');
+    }
+    async function currentActivation(target) {
+        try {
+            const activation = await options.activations.current(target);
+            if (!activation)
+                return undefined;
+            const validated = validateDeploymentActivationRecord(activation);
+            if (!sameTarget(validated.target, target)) {
+                throw new Error('Deployment activation target does not match the requested target.');
+            }
+            return validated;
+        }
+        catch (error) {
+            throw materializationError('HQ_RUNTIME_MATERIALIZATION_ACTIVATION_UNAVAILABLE', 'Deployment activation state could not be read.', error);
+        }
+    }
+    return Object.freeze({
+        async current(target) {
+            for (let attempt = 0; attempt < maximumAttempts; attempt += 1) {
+                const activation = await currentActivation(target);
+                if (!activation)
+                    return undefined;
+                const snapshot = await materializeActivation(activation, options.releases);
+                const confirmed = await currentActivation(target);
+                if (!confirmed)
+                    return undefined;
+                if (confirmed.revision === activation.revision)
+                    return snapshot;
+            }
+            throw materializationError('HQ_RUNTIME_MATERIALIZATION_UNSTABLE_ACTIVATION', 'Deployment activation changed repeatedly during runtime materialization.');
+        },
+    });
+}

package/dist/runtime-supervisor.d.ts

@@ -0,0 +1,72 @@
+import type { ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+import type { DeploymentRuntimeMaterializer, DeploymentRuntimeQueryBinding, DeploymentRuntimeSnapshot } from './runtime-materialization.js';
+export type DeploymentRuntimeSupervisorErrorCode = 'HQ_RUNTIME_SUPERVISOR_CONFIGURATION' | 'HQ_RUNTIME_SUPERVISOR_CLOSED' | 'HQ_RUNTIME_NOT_READY' | 'HQ_RUNTIME_QUERY_NOT_FOUND' | 'HQ_RUNTIME_QUERY_NOT_EXECUTABLE' | 'HQ_RUNTIME_START_FAILED' | 'HQ_RUNTIME_HEALTH_FAILED' | 'HQ_RUNTIME_INVOCATION_FAILED' | 'HQ_RUNTIME_RECONCILE_UNSTABLE' | 'HQ_RUNTIME_ABORTED';
+export declare class DeploymentRuntimeSupervisorError extends Error {
+    readonly code: DeploymentRuntimeSupervisorErrorCode;
+    constructor(code: DeploymentRuntimeSupervisorErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface DeploymentRuntimeInstanceInvocation {
+    readonly query: string;
+    readonly binding: DeploymentRuntimeQueryBinding;
+    readonly argument: unknown;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentRuntimeInstance {
+    healthCheck(input: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    invoke(input: DeploymentRuntimeInstanceInvocation): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface DeploymentRuntimeFactory {
+    start(snapshot: DeploymentRuntimeSnapshot, input: {
+        readonly signal?: AbortSignal;
+    }): Promise<DeploymentRuntimeInstance>;
+}
+export interface DeploymentRuntimeInvocation {
+    readonly target: ProtocolDeploymentReleaseTarget;
+    /** Reject the invocation unless this exact activation generation is active. */
+    readonly activationRevision?: string;
+    readonly query: string;
+    readonly argument: unknown;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentRuntimeStatus {
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly activationRevision: string;
+    readonly releaseIdentity: string;
+    readonly bundleIdentity: string;
+}
+export type DeploymentRuntimeReconcileResult = {
+    readonly status: 'activated';
+    readonly runtime: DeploymentRuntimeStatus;
+} | {
+    readonly status: 'already-current';
+    readonly runtime: DeploymentRuntimeStatus;
+} | {
+    readonly status: 'deactivated';
+    readonly previous: DeploymentRuntimeStatus;
+} | {
+    readonly status: 'no-active-release';
+};
+export interface DeploymentRuntimeSupervisor {
+    reconcile(target: ProtocolDeploymentReleaseTarget, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<DeploymentRuntimeReconcileResult>;
+    invoke(input: DeploymentRuntimeInvocation): Promise<unknown>;
+    status(target: ProtocolDeploymentReleaseTarget): DeploymentRuntimeStatus | undefined;
+    close(): Promise<void>;
+}
+export interface DeploymentRuntimeSupervisorOptions {
+    readonly materializer: DeploymentRuntimeMaterializer;
+    readonly factory: DeploymentRuntimeFactory;
+    /** In-flight drain deadline from 0 through 300,000 milliseconds. */
+    readonly drainTimeoutMs?: number;
+    /** Activation-stability attempts from 1 through 16. */
+    readonly maxReconcileAttempts?: number;
+    readonly onBackgroundError?: (error: unknown) => void;
+}
+export declare function createDeploymentRuntimeSupervisor(options: DeploymentRuntimeSupervisorOptions): DeploymentRuntimeSupervisor;
+//# sourceMappingURL=runtime-supervisor.d.ts.map

package/dist/runtime-supervisor.d.ts.map

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

package/dist/runtime-supervisor.js

@@ -0,0 +1,258 @@
+const DEFAULT_DRAIN_TIMEOUT_MS = 30_000;
+const DEFAULT_RECONCILE_ATTEMPTS = 4;
+const MAX_DRAIN_TIMEOUT_MS = 5 * 60_000;
+const MAX_RECONCILE_ATTEMPTS = 16;
+export class DeploymentRuntimeSupervisorError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'DeploymentRuntimeSupervisorError';
+        this.code = code;
+    }
+}
+function supervisorError(code, message, cause) {
+    return new DeploymentRuntimeSupervisorError(code, message, { cause });
+}
+function boundedInteger(input, fallback, maximum, name, allowZero = false) {
+    const value = input ?? fallback;
+    if (!Number.isSafeInteger(value) || value < (allowZero ? 0 : 1) || value > maximum) {
+        throw supervisorError('HQ_RUNTIME_SUPERVISOR_CONFIGURATION', `${name} must be an integer between ${allowZero ? 0 : 1} and ${maximum}.`);
+    }
+    return value;
+}
+function targetKey(target) {
+    return JSON.stringify([target.project, target.environment]);
+}
+function sameTarget(left, right) {
+    return left.project === right.project && left.environment === right.environment;
+}
+function status(generation) {
+    const snapshot = generation.snapshot;
+    return Object.freeze({
+        target: snapshot.target,
+        activationRevision: snapshot.activation.revision,
+        releaseIdentity: snapshot.releaseIdentity,
+        bundleIdentity: snapshot.bundleIdentity,
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw supervisorError('HQ_RUNTIME_ABORTED', 'The runtime operation was aborted.', signal.reason);
+    }
+}
+function binding(snapshot, queryName) {
+    const query = snapshot.deployment.queries.find(candidate => candidate.name === queryName);
+    if (!query) {
+        throw supervisorError('HQ_RUNTIME_QUERY_NOT_FOUND', `Runtime query not found: ${queryName}`);
+    }
+    if (query.implementation.kind !== 'runtime-reference') {
+        throw supervisorError('HQ_RUNTIME_QUERY_NOT_EXECUTABLE', `Query is portable and does not use a supervised runtime: ${queryName}`);
+    }
+    const resolved = snapshot.queries.find(candidate => candidate.query === queryName);
+    if (!resolved) {
+        throw supervisorError('HQ_RUNTIME_QUERY_NOT_EXECUTABLE', `Runtime query binding is unavailable: ${queryName}`);
+    }
+    return resolved;
+}
+export function createDeploymentRuntimeSupervisor(options) {
+    const drainTimeoutMs = boundedInteger(options.drainTimeoutMs, DEFAULT_DRAIN_TIMEOUT_MS, MAX_DRAIN_TIMEOUT_MS, 'drainTimeoutMs', true);
+    const maxReconcileAttempts = boundedInteger(options.maxReconcileAttempts, DEFAULT_RECONCILE_ATTEMPTS, MAX_RECONCILE_ATTEMPTS, 'maxReconcileAttempts');
+    const active = new Map();
+    const updates = new Map();
+    const background = new Set();
+    const backgroundFailures = [];
+    let closed = false;
+    let closePromise;
+    function ensureOpen() {
+        if (closed)
+            throw supervisorError('HQ_RUNTIME_SUPERVISOR_CLOSED', 'Runtime supervisor is closed.');
+    }
+    async function drain(generation) {
+        if (generation.draining)
+            return;
+        generation.draining = true;
+        if (generation.inFlight > 0) {
+            await new Promise(resolve => {
+                let settled = false;
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    generation.drained = undefined;
+                    resolve();
+                };
+                generation.drained = finish;
+                const timer = setTimeout(finish, drainTimeoutMs);
+                timer.unref();
+            });
+        }
+        await generation.instance.close();
+    }
+    function drainInBackground(generation) {
+        const operation = drain(generation).catch(error => {
+            backgroundFailures.push(error);
+            options.onBackgroundError?.(error);
+        });
+        background.add(operation);
+        void operation.finally(() => background.delete(operation));
+    }
+    async function safeClose(instance) {
+        try {
+            await instance.close();
+        }
+        catch (error) {
+            backgroundFailures.push(error);
+            options.onBackgroundError?.(error);
+        }
+    }
+    async function performReconcile(target, signal) {
+        for (let attempt = 0; attempt < maxReconcileAttempts; attempt += 1) {
+            ensureOpen();
+            throwIfAborted(signal);
+            const snapshot = await options.materializer.current(target);
+            ensureOpen();
+            throwIfAborted(signal);
+            const key = targetKey(target);
+            const existing = active.get(key);
+            if (!snapshot) {
+                if (!existing)
+                    return Object.freeze({ status: 'no-active-release' });
+                active.delete(key);
+                drainInBackground(existing);
+                return Object.freeze({ status: 'deactivated', previous: status(existing) });
+            }
+            if (!sameTarget(snapshot.target, target)) {
+                throw supervisorError('HQ_RUNTIME_START_FAILED', 'The materialized runtime snapshot does not match the requested target.');
+            }
+            if (existing?.snapshot.activation.revision === snapshot.activation.revision) {
+                return Object.freeze({ status: 'already-current', runtime: status(existing) });
+            }
+            let candidate;
+            try {
+                candidate = await options.factory.start(snapshot, { signal });
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    throw supervisorError('HQ_RUNTIME_ABORTED', 'The runtime operation was aborted while starting a candidate.', error);
+                }
+                if (error instanceof DeploymentRuntimeSupervisorError)
+                    throw error;
+                throw supervisorError('HQ_RUNTIME_START_FAILED', 'The candidate deployment runtime could not be started.', error);
+            }
+            try {
+                ensureOpen();
+                throwIfAborted(signal);
+                await candidate.healthCheck({ signal });
+            }
+            catch (error) {
+                await safeClose(candidate);
+                if (error instanceof DeploymentRuntimeSupervisorError)
+                    throw error;
+                throw supervisorError('HQ_RUNTIME_HEALTH_FAILED', 'The candidate deployment runtime did not become ready.', error);
+            }
+            let confirmed;
+            try {
+                ensureOpen();
+                throwIfAborted(signal);
+                confirmed = await options.materializer.current(target);
+                ensureOpen();
+                throwIfAborted(signal);
+            }
+            catch (error) {
+                await safeClose(candidate);
+                throw error;
+            }
+            if (confirmed?.activation.revision !== snapshot.activation.revision) {
+                await safeClose(candidate);
+                continue;
+            }
+            const generation = {
+                snapshot,
+                instance: candidate,
+                inFlight: 0,
+                draining: false,
+            };
+            const previous = active.get(key);
+            active.set(key, generation);
+            if (previous)
+                drainInBackground(previous);
+            return Object.freeze({ status: 'activated', runtime: status(generation) });
+        }
+        throw supervisorError('HQ_RUNTIME_RECONCILE_UNSTABLE', 'Deployment activation changed repeatedly while starting a runtime.');
+    }
+    function serialize(key, operation) {
+        const previous = updates.get(key) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        const tracked = current.finally(() => {
+            if (updates.get(key) === tracked)
+                updates.delete(key);
+        });
+        updates.set(key, tracked);
+        return tracked;
+    }
+    return Object.freeze({
+        async reconcile(target, reconcileOptions = {}) {
+            ensureOpen();
+            return await serialize(targetKey(target), () => performReconcile(target, reconcileOptions.signal));
+        },
+        async invoke(input) {
+            ensureOpen();
+            throwIfAborted(input.signal);
+            const generation = active.get(targetKey(input.target));
+            if (!generation) {
+                throw supervisorError('HQ_RUNTIME_NOT_READY', 'No deployment runtime is ready for target.');
+            }
+            if (input.activationRevision !== undefined
+                && generation.snapshot.activation.revision !== input.activationRevision) {
+                throw supervisorError('HQ_RUNTIME_NOT_READY', 'The requested deployment runtime generation is not ready for target.');
+            }
+            const resolved = binding(generation.snapshot, input.query);
+            generation.inFlight += 1;
+            try {
+                return await generation.instance.invoke({
+                    query: input.query,
+                    binding: resolved,
+                    argument: input.argument,
+                    signal: input.signal,
+                });
+            }
+            catch (error) {
+                if (error instanceof DeploymentRuntimeSupervisorError)
+                    throw error;
+                throw supervisorError('HQ_RUNTIME_INVOCATION_FAILED', 'The deployment runtime invocation failed.', error);
+            }
+            finally {
+                generation.inFlight -= 1;
+                if (generation.draining && generation.inFlight === 0)
+                    generation.drained?.();
+            }
+        },
+        status(target) {
+            const generation = active.get(targetKey(target));
+            return generation ? status(generation) : undefined;
+        },
+        close() {
+            if (closePromise)
+                return closePromise;
+            closed = true;
+            closePromise = (async () => {
+                await Promise.allSettled([...updates.values()]);
+                const generations = [...active.values()];
+                active.clear();
+                const results = await Promise.allSettled(generations.map(generation => drain(generation)));
+                await Promise.allSettled([...background]);
+                const failures = [
+                    ...backgroundFailures,
+                    ...results
+                        .filter((result) => result.status === 'rejected')
+                        .map(result => result.reason),
+                ];
+                if (failures.length > 0) {
+                    throw new AggregateError(failures, 'One or more deployment runtimes could not be closed.');
+                }
+            })();
+            return closePromise;
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/deployment",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Provider-neutral deployment verification and intake for Hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@hypequery/protocol": "0.6.0"
+    "@hypequery/protocol": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",
@@ -41,6 +41,6 @@
     "dev": "tsc --project tsconfig.json --watch",
     "lint": "eslint --ext .ts \"src/**/*.ts\"",
     "test": "vitest run",
-    "types": "tsc --project tsconfig.json --noEmit"
+    "types": "tsc --project tsconfig.json --noEmit && tsc --project tsconfig.test.json"
   }
 }