@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/sidecar-allocation/capability-policy.d.ts

@@ -0,0 +1,27 @@
+import { type SidecarCapabilityDeclaration, type SidecarCapabilityRule, type TenantSidecarCapabilityPolicy } from "@intx/types";
+export type EffectiveSidecarCapabilityPolicy = {
+    readonly tenantPolicies: readonly TenantSidecarCapabilityPolicy[];
+    readonly probeRules?: readonly SidecarCapabilityRule[];
+    readonly workflowRules: readonly SidecarCapabilityRule[];
+};
+export type SidecarCapabilityMismatch = {
+    readonly capability: string;
+    readonly expected: "available" | "blocked";
+    readonly actual: "available" | "blocked" | "unknown";
+    readonly rule: SidecarCapabilityRule;
+    readonly source: {
+        readonly kind: "tenant";
+        readonly tenantId: string;
+    } | {
+        readonly kind: "probe";
+    } | {
+        readonly kind: "workflow";
+    };
+};
+export type SidecarCapabilityMatch = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly mismatches: readonly SidecarCapabilityMismatch[];
+};
+export declare function matchSidecarCapabilityPolicy(policy: EffectiveSidecarCapabilityPolicy, declarations: readonly SidecarCapabilityDeclaration[]): SidecarCapabilityMatch;

package/dist/sidecar-allocation/capability-policy.js

@@ -0,0 +1,124 @@
+import { parseSidecarCapabilitySelector, } from "@intx/types";
+export function matchSidecarCapabilityPolicy(policy, declarations) {
+    const tenantPolicies = policy.tenantPolicies.map((tenantPolicy) => ({
+        ...tenantPolicy,
+        rules: tenantPolicy.rules.map(parseRule),
+    }));
+    const probeRules = (policy.probeRules ?? []).map(parseRule);
+    const workflowRules = policy.workflowRules.map(parseRule);
+    const parsedDeclarations = declarations.map(parseDeclaration);
+    const boundaries = collectBoundaries(tenantPolicies.flatMap(({ rules }) => rules.map(({ selector }) => selector)), probeRules.map(({ selector }) => selector), workflowRules.map(({ selector }) => selector), parsedDeclarations.map(({ selector }) => selector));
+    const mismatches = [];
+    for (const boundary of boundaries) {
+        const capability = formatSelector(boundary);
+        for (const tenantPolicy of tenantPolicies) {
+            const resolved = resolveRules(tenantPolicy.rules, boundary);
+            if (resolved !== null) {
+                addMismatch(mismatches, resolved.rule, resolveDeclarations(parsedDeclarations, boundary), capability, { kind: "tenant", tenantId: tenantPolicy.tenantId });
+            }
+        }
+        const probeRule = resolveRules(probeRules, boundary);
+        if (probeRule !== null) {
+            addMismatch(mismatches, probeRule.rule, resolveDeclarations(parsedDeclarations, boundary), capability, { kind: "probe" });
+        }
+        const workflowRule = resolveRules(workflowRules, boundary);
+        if (workflowRule !== null) {
+            addMismatch(mismatches, workflowRule.rule, resolveDeclarations(parsedDeclarations, boundary), capability, { kind: "workflow" });
+        }
+    }
+    return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+}
+function addMismatch(mismatches, rule, declaration, capability, source) {
+    const expected = rule.effect === "require" ? "available" : "blocked";
+    const actual = declaration?.declaration.state ?? "unknown";
+    if (actual === expected)
+        return;
+    mismatches.push({ capability, expected, actual, rule, source });
+}
+function resolveRules(rules, boundary) {
+    let winner = null;
+    for (const candidate of rules) {
+        if (!selectorAppliesToBoundary(candidate.selector, boundary))
+            continue;
+        if (winner === null ||
+            candidate.specificity > winner.specificity ||
+            (candidate.specificity === winner.specificity &&
+                candidate.rule.effect === "block" &&
+                winner.rule.effect === "require")) {
+            winner = candidate;
+        }
+    }
+    return winner;
+}
+function resolveDeclarations(declarations, boundary) {
+    let winner = null;
+    for (const candidate of declarations) {
+        if (!selectorAppliesToBoundary(candidate.selector, boundary))
+            continue;
+        if (winner === null ||
+            candidate.specificity > winner.specificity ||
+            (candidate.specificity === winner.specificity &&
+                candidate.declaration.state === "blocked" &&
+                winner.declaration.state === "available")) {
+            winner = candidate;
+        }
+    }
+    return winner;
+}
+function parseRule(rule) {
+    const selector = parseSelector(rule.capability);
+    return {
+        rule,
+        selector,
+        specificity: selector.segments.length,
+    };
+}
+function parseDeclaration(declaration) {
+    const selector = parseSelector(declaration.capability);
+    return {
+        declaration,
+        selector,
+        specificity: selector.segments.length,
+    };
+}
+function parseSelector(capability) {
+    const selector = parseSidecarCapabilitySelector(capability);
+    if (selector === null) {
+        throw new Error(`Invalid sidecar capability selector: ${JSON.stringify(capability)}`);
+    }
+    return selector;
+}
+function collectBoundaries(...selectorGroups) {
+    const boundaries = new Map();
+    for (const selectors of selectorGroups) {
+        for (const selector of selectors) {
+            boundaries.set(`${selector.kind}:${formatSelector(selector)}`, selector);
+        }
+    }
+    return [...boundaries.values()];
+}
+function selectorAppliesToBoundary(selector, boundary) {
+    if (selector.kind === "exact") {
+        return (boundary.kind === "exact" &&
+            segmentsEqual(selector.segments, boundary.segments));
+    }
+    if (!isSegmentPrefix(selector.segments, boundary.segments))
+        return false;
+    return (boundary.kind === "prefix" ||
+        selector.segments.length < boundary.segments.length);
+}
+function isSegmentPrefix(prefix, segments) {
+    return (prefix.length <= segments.length &&
+        prefix.every((segment, index) => segment === segments[index]));
+}
+function segmentsEqual(left, right) {
+    return (left.length === right.length &&
+        left.every((segment, index) => segment === right[index]));
+}
+function formatSelector(selector) {
+    if (selector.kind === "exact")
+        return selector.segments.join(":");
+    if (selector.segments.length === 0)
+        return "*";
+    return `${selector.segments.join(":")}:*`;
+}

package/dist/sidecar-allocation/contracts.d.ts

@@ -0,0 +1,101 @@
+import type { SidecarCapabilityDeclaration } from "@intx/types";
+export type EnsureSidecarRequest = {
+    /** Cancellation is best effort; a cancelled ensure has an uncertain outcome. */
+    readonly signal?: AbortSignal;
+    readonly allocationId: string;
+    readonly generation: number;
+    readonly tenantId: string;
+    readonly anchorRunId: string;
+    readonly sidecarId: string;
+    readonly token: string;
+    readonly hubWebSocketUrl: string;
+};
+export type DestroySidecarRequest = {
+    /** Cancellation never confirms destruction; the Hub may retry cleanup. */
+    readonly signal?: AbortSignal;
+    readonly allocationId: string;
+    readonly generation: number;
+    readonly sidecarId: string;
+    /**
+     * Optional provider handle recorded after ensure returns. A Hub crash can
+     * occur after capacity is created but before this value is persisted, so
+     * destroy must always be able to identify the capacity from allocationId,
+     * generation, and sidecarId alone.
+     */
+    readonly externalRef?: string;
+};
+export declare const SidecarOperationFailure: import("arktype/internal/variants/object.ts").ObjectType<{
+    kind: "rejected";
+    code: string;
+    message: string;
+    retryable: boolean;
+}, {}>;
+export type SidecarOperationFailure = typeof SidecarOperationFailure.infer;
+/**
+ * Acceptance means the requested infrastructure exists, not that it is ready.
+ * Rejection means no infrastructure exists for this generation (ensure-only;
+ * destroy rejections below carry no such guarantee); a provisioner must throw
+ * when it cannot determine whether the request took effect.
+ */
+export declare const EnsureSidecarResult: import("arktype/internal/variants/object.ts").ObjectType<{
+    kind: "rejected";
+    code: string;
+    message: string;
+    retryable: boolean;
+} | {
+    kind: "accepted";
+    externalRef?: string;
+}, {}>;
+export type EnsureSidecarResult = typeof EnsureSidecarResult.infer;
+/**
+ * Destruction confirms the capacity is gone and older ensure calls are fenced.
+ * A non-retryable rejection stops automatic cleanup; capacity may still exist.
+ */
+export declare const DestroySidecarResult: import("arktype/internal/variants/object.ts").ObjectType<{
+    kind: "rejected";
+    code: string;
+    message: string;
+    retryable: boolean;
+} | {
+    kind: "destroyed";
+}, {}>;
+export type DestroySidecarResult = typeof DestroySidecarResult.infer;
+export interface SidecarProvisioner {
+    readonly id: string;
+    readonly apiVersion: 1;
+    /** Stable, non-secret identity for the backend configuration. */
+    readonly bindingFingerprint: string;
+    readonly capabilities: readonly SidecarCapabilityDeclaration[];
+    /**
+     * Converges infrastructure for this generation. Implementations must be
+     * idempotent and reject generations older than one they have observed.
+     * Honour the request signal where possible. A late completion must still
+     * respect a concurrent destroy's fence, even if cancellation was ignored.
+     */
+    ensure(request: EnsureSidecarRequest): Promise<EnsureSidecarResult>;
+    /**
+     * Idempotently destroys the allocation and fences older ensure calls so a
+     * delayed request cannot recreate infrastructure after destruction. It must
+     * succeed without an externalRef; that value is only an optional optimization.
+     */
+    destroy(request: DestroySidecarRequest): Promise<DestroySidecarResult>;
+}
+export type SidecarCredentialIdentity = {
+    readonly kind: "allocated";
+    readonly sidecarId: string;
+    readonly allocationId: string;
+    readonly tenantId: string;
+    readonly anchorRunId: string;
+    readonly workflowRunAddress: string;
+    readonly generation: number;
+} | {
+    readonly kind: "probe";
+    readonly sidecarId: string;
+    readonly allocationId: string;
+    readonly tenantId: string;
+    readonly generation: number;
+};
+export interface SidecarCredentialResolver {
+    resolve(token: string): Promise<SidecarCredentialIdentity | null>;
+    isCurrent(identity: SidecarCredentialIdentity, use: "registration" | "readiness" | "routing"): Promise<boolean>;
+}

package/dist/sidecar-allocation/contracts.js

@@ -0,0 +1,26 @@
+import { type } from "arktype";
+// Provisioner results cross a plugin boundary, so they are validated at
+// runtime rather than trusted from the declared return type.
+export const SidecarOperationFailure = type({
+    kind: "'rejected'",
+    code: "string",
+    message: "string",
+    retryable: "boolean",
+});
+/**
+ * Acceptance means the requested infrastructure exists, not that it is ready.
+ * Rejection means no infrastructure exists for this generation (ensure-only;
+ * destroy rejections below carry no such guarantee); a provisioner must throw
+ * when it cannot determine whether the request took effect.
+ */
+export const EnsureSidecarResult = type({
+    kind: "'accepted'",
+    "externalRef?": "string",
+}).or(SidecarOperationFailure);
+/**
+ * Destruction confirms the capacity is gone and older ensure calls are fenced.
+ * A non-retryable rejection stops automatic cleanup; capacity may still exist.
+ */
+export const DestroySidecarResult = type({
+    kind: "'destroyed'",
+}).or(SidecarOperationFailure);

package/dist/sidecar-allocation/index.d.ts

@@ -0,0 +1,5 @@
+export { chooseFirstSidecarProvisioner, createSidecarPluginRegistry, type CreateSidecarPluginRegistryOpts, type SidecarPluginRegistry, type SidecarProvisionerChooser, type SidecarProvisionerSelection, } from "./plugin-registry.js";
+export { matchSidecarCapabilityPolicy, type EffectiveSidecarCapabilityPolicy, type SidecarCapabilityMatch, type SidecarCapabilityMismatch, } from "./capability-policy.js";
+export { DestroySidecarResult, EnsureSidecarResult, SidecarOperationFailure, type DestroySidecarRequest, type EnsureSidecarRequest, type SidecarCredentialIdentity, type SidecarCredentialResolver, type SidecarProvisioner, } from "./contracts.js";
+export { createSidecarAllocationReconciler, type SidecarAllocationReconciler, type SidecarAllocationReconcilerDeps, } from "./reconciler.js";
+export type { SidecarReconciliationContext } from "./operation.js";

package/dist/sidecar-allocation/index.js

@@ -0,0 +1,4 @@
+export { chooseFirstSidecarProvisioner, createSidecarPluginRegistry, } from "./plugin-registry.js";
+export { matchSidecarCapabilityPolicy, } from "./capability-policy.js";
+export { DestroySidecarResult, EnsureSidecarResult, SidecarOperationFailure, } from "./contracts.js";
+export { createSidecarAllocationReconciler, } from "./reconciler.js";

package/dist/sidecar-allocation/operation.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_SIDECAR_OPERATION_TIMEOUT_MS = 120000;
+export type SidecarReconciliationContext = {
+    readonly signal: AbortSignal;
+    readonly leaseId: string;
+};
+export declare class SidecarOperationTimeoutError extends Error {
+    constructor(operation: string, timeoutMs: number);
+}
+/** Stops waiting on cancellation or an optional deadline, even if work ignores the signal. */
+export declare function runSidecarOperation<T>(operation: string, timeoutMs: number | undefined, run: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;

package/dist/sidecar-allocation/operation.js

@@ -0,0 +1,54 @@
+export const DEFAULT_SIDECAR_OPERATION_TIMEOUT_MS = 120_000;
+export class SidecarOperationTimeoutError extends Error {
+    constructor(operation, timeoutMs) {
+        super(`${operation} timed out after ${String(timeoutMs)}ms`);
+        this.name = "SidecarOperationTimeoutError";
+    }
+}
+/** Stops waiting on cancellation or an optional deadline, even if work ignores the signal. */
+export async function runSidecarOperation(operation, timeoutMs, run, signal) {
+    if (timeoutMs !== undefined &&
+        (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)) {
+        throw new Error("Sidecar operation timeout must be a positive integer");
+    }
+    signal?.throwIfAborted();
+    const controller = new AbortController();
+    const cancel = () => {
+        controller.abort(signal?.reason instanceof Error
+            ? signal.reason
+            : new Error(`${operation} cancelled`));
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    let rejectAborted;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAborted = () => {
+            reject(controller.signal.reason);
+        };
+        controller.signal.addEventListener("abort", rejectAborted, { once: true });
+    });
+    const timer = timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            controller.abort(new SidecarOperationTimeoutError(operation, timeoutMs));
+        }, timeoutMs);
+    // A deadline must never keep the process alive on its own: in-flight work
+    // always holds its own handles, and a bare 120s timer would stall teardown
+    // and test runners after everything else settled.
+    timer?.unref?.();
+    try {
+        return await Promise.race([
+            Promise.resolve().then(() => {
+                controller.signal.throwIfAborted();
+                return run(controller.signal);
+            }),
+            aborted,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", cancel);
+        if (rejectAborted !== undefined) {
+            controller.signal.removeEventListener("abort", rejectAborted);
+        }
+    }
+}

package/dist/sidecar-allocation/plugin-registry.d.ts

@@ -0,0 +1,24 @@
+import type { SidecarProvisioner } from "./contracts.js";
+import { type EffectiveSidecarCapabilityPolicy, type SidecarCapabilityMismatch } from "./capability-policy.js";
+export type SidecarProvisionerSelection = {
+    readonly ok: true;
+    readonly provisioner: SidecarProvisioner;
+} | {
+    readonly ok: false;
+    readonly reason: "no_match";
+    readonly mismatches: Readonly<Record<string, readonly SidecarCapabilityMismatch[]>>;
+};
+/** Selects one provisioner from the capability-matched candidates. */
+export type SidecarProvisionerChooser = (candidates: readonly SidecarProvisioner[]) => SidecarProvisioner | Promise<SidecarProvisioner>;
+export type SidecarPluginRegistry = {
+    /** Missing plugins return null so reconciliation can stop fail-closed. */
+    getProvisioner(id: string): SidecarProvisioner | null;
+    selectProvisioner(policy: EffectiveSidecarCapabilityPolicy): Promise<SidecarProvisionerSelection>;
+};
+export type CreateSidecarPluginRegistryOpts = {
+    /** Ordered candidates; the default chooser selects the first match. */
+    readonly provisioners: readonly SidecarProvisioner[];
+    readonly chooser?: SidecarProvisionerChooser;
+};
+export declare function chooseFirstSidecarProvisioner(candidates: readonly SidecarProvisioner[]): SidecarProvisioner;
+export declare function createSidecarPluginRegistry({ provisioners, chooser, }: CreateSidecarPluginRegistryOpts): SidecarPluginRegistry;

package/dist/sidecar-allocation/plugin-registry.js

@@ -0,0 +1,61 @@
+import { type } from "arktype";
+import { SidecarCapabilityDeclaration } from "@intx/types";
+import { matchSidecarCapabilityPolicy, } from "./capability-policy.js";
+export function chooseFirstSidecarProvisioner(candidates) {
+    const first = candidates[0];
+    if (first === undefined) {
+        throw new Error("No matching sidecar provisioners are available");
+    }
+    return first;
+}
+export function createSidecarPluginRegistry({ provisioners, chooser = chooseFirstSidecarProvisioner, }) {
+    const provisionersById = new Map();
+    for (const provisioner of provisioners) {
+        validateId(provisioner.id);
+        if (provisioner.apiVersion !== 1) {
+            throw new Error(`Unsupported sidecar provisioner API version for ${provisioner.id}: ${String(provisioner.apiVersion)}`);
+        }
+        if (provisioner.bindingFingerprint.trim() === "") {
+            throw new Error(`Sidecar provisioner ${provisioner.id} requires a binding fingerprint`);
+        }
+        const capabilities = SidecarCapabilityDeclaration.array()(provisioner.capabilities);
+        if (capabilities instanceof type.errors) {
+            throw new Error(`Invalid capability declarations on sidecar provisioner ${provisioner.id}: ${capabilities.summary}`);
+        }
+        if (provisionersById.has(provisioner.id)) {
+            throw new Error(`Duplicate sidecar provisioner id: ${provisioner.id}`);
+        }
+        provisionersById.set(provisioner.id, provisioner);
+    }
+    return {
+        getProvisioner(id) {
+            return provisionersById.get(id) ?? null;
+        },
+        async selectProvisioner(policy) {
+            const mismatches = {};
+            const candidates = [];
+            for (const provisioner of provisionersById.values()) {
+                const match = matchSidecarCapabilityPolicy(policy, provisioner.capabilities);
+                if (match.ok) {
+                    candidates.push(provisioner);
+                }
+                else {
+                    mismatches[provisioner.id] = match.mismatches;
+                }
+            }
+            if (candidates.length === 0) {
+                return { ok: false, reason: "no_match", mismatches };
+            }
+            const provisioner = await chooser(candidates);
+            if (!candidates.includes(provisioner)) {
+                throw new Error("Sidecar provisioner chooser returned a provisioner outside the matching candidates");
+            }
+            return { ok: true, provisioner };
+        },
+    };
+}
+function validateId(id) {
+    if (id.trim() === "") {
+        throw new Error("Sidecar provisioner id must be non-empty");
+    }
+}

package/dist/sidecar-allocation/reconciler.d.ts

@@ -0,0 +1,54 @@
+import type { SidecarAllocation, SidecarAllocationStore } from "@intx/db";
+import type { AllocatedSidecarTarget, SidecarAllocationRouter } from "../ws/sidecar-handler.js";
+import type { SidecarPluginRegistry } from "./plugin-registry.js";
+import { type SidecarReconciliationContext } from "./operation.js";
+type AllocationStore = Pick<SidecarAllocationStore, "beginReplacement" | "beginUnrecoverableRelease" | "bindInitialSidecar" | "bindReplacementSidecar" | "claimNextReconcilable" | "extendReconciliationLease" | "failWithoutInfrastructure" | "listActive" | "isReconciliationLeaseCurrent" | "markAllocated" | "markConnectionLost" | "markConnectionReady" | "markDestroyFailed" | "markReleased" | "parkReconciliation" | "scheduleReconnectIfUnscheduled" | "scheduleRetry" | "wakeReconciliation">;
+export type SidecarAllocationReconcilerDeps = {
+    readonly allocationStore: AllocationStore;
+    readonly plugins: SidecarPluginRegistry;
+    readonly router: Pick<SidecarAllocationRouter, "fenceAllocation" | "isAllocatedSidecarReady" | "retireAllocation" | "waitForAllocatedSidecar">;
+    readonly hubWebSocketUrl: string;
+    /**
+     * Resolve the previous attempt's deferred mail under the newly claimed
+     * lease, before connection waits or cleanup.
+     */
+    readonly onInitializationRecovery?: (allocation: SidecarAllocation, reconciliation: SidecarReconciliationContext) => Promise<void>;
+    /** Idempotently restores and deploys one connected allocation generation. */
+    readonly onReady?: (allocation: SidecarAllocation, reconciliation: SidecarReconciliationContext) => Promise<void>;
+    /**
+     * Replace an allocated worker after its reconnect grace expires. Disabled by
+     * default because Hub recovery does not restore arbitrary sidecar or
+     * isolation-container filesystem state, so automatic continuation could run
+     * without state the previous worker produced.
+     */
+    readonly enableAutomaticReplacementRecovery?: boolean;
+    readonly leaseDurationMs?: number;
+    readonly connectTimeoutMs?: number;
+    readonly operationTimeoutMs?: number;
+    /**
+     * Bounds admitted claims, active reconciliation, and retained allocation
+     * queries or writes.
+     */
+    readonly maxConcurrentClaims?: number;
+    readonly retryDelayMs?: (attempt: number) => number;
+    readonly now?: () => Date;
+    readonly createSidecarId?: () => string;
+    readonly createToken?: () => string;
+    readonly createLeaseId?: () => string;
+};
+export type SidecarAllocationReconciler = {
+    /** Rebuild all trust fences before accepting allocated connections. */
+    initialize(): Promise<void>;
+    /** Starts a durable reconnect grace period for the exact lost generation. */
+    handleDisconnect(target: AllocatedSidecarTarget): Promise<void>;
+    /** Wakes recovery as soon as the exact generation reconnects. */
+    handleConnected(target: AllocatedSidecarTarget): Promise<void>;
+    /** Repairs allocated generations left unscheduled after a lost event write. */
+    repairUnscheduledConnections(): Promise<void>;
+    /** Reconcile at most one due allocation. Returns false when none are due. */
+    reconcileNext(): Promise<boolean>;
+    /** Drain the currently due queue, bounded to catch accidental hot loops. */
+    reconcileUntilIdle(maxIterations?: number): Promise<number>;
+};
+export declare function createSidecarAllocationReconciler({ allocationStore, plugins, router, hubWebSocketUrl, onInitializationRecovery, onReady, enableAutomaticReplacementRecovery, leaseDurationMs, connectTimeoutMs, operationTimeoutMs, maxConcurrentClaims, retryDelayMs, now, createSidecarId, createToken, createLeaseId, }: SidecarAllocationReconcilerDeps): SidecarAllocationReconciler;
+export {};