stitchkit 0.59.2 → 0.59.4

package/dist/index-5c8n2123.js

@@ -0,0 +1,617 @@
+import {
+  ApplicationIdSchema,
+  ApplicationShutdownResultSchema,
+  ApplicationSnapshotSchema
+} from "./index-mgf6cdkm.js";
+import {
+  ShutdownOptionsSchema
+} from "./index-dk6e56g0.js";
+
+// src/application/graph.ts
+function resolveResourceGraph(resources) {
+  const entries = resources.map((resource, declarationIndex) => ({
+    resource,
+    id: ApplicationIdSchema.parse(resource.id),
+    dependsOn: [...resource.dependsOn ?? []].map((id) => ApplicationIdSchema.parse(id)),
+    required: resource.required ?? true,
+    declarationIndex
+  }));
+  const byId = new Map;
+  for (const entry of entries) {
+    if (byId.has(entry.id)) {
+      throw new Error(`[stitchkit] createApplication: duplicate resource id "${entry.id}"`);
+    }
+    byId.set(entry.id, entry);
+  }
+  for (const entry of entries) {
+    for (const dependencyId of entry.dependsOn) {
+      const dependency = byId.get(dependencyId);
+      if (!dependency) {
+        throw new Error(`[stitchkit] createApplication: resource "${entry.id}" depends on missing resource "${dependencyId}"`);
+      }
+      if (entry.required && !dependency.required) {
+        throw new Error(`[stitchkit] createApplication: required resource "${entry.id}" cannot depend on optional resource "${dependencyId}"`);
+      }
+    }
+  }
+  const pending = new Map(entries.map((entry) => [entry.id, entry]));
+  const resolved = new Set;
+  const ordered = [];
+  while (pending.size > 0) {
+    const ready = [...pending.values()].filter((entry) => entry.dependsOn.every((id) => resolved.has(id))).sort((left, right) => left.declarationIndex - right.declarationIndex);
+    if (ready.length === 0) {
+      throw new Error(`[stitchkit] createApplication: resource dependency cycle: ${[...pending.keys()].join(", ")}`);
+    }
+    for (const entry of ready) {
+      pending.delete(entry.id);
+      resolved.add(entry.id);
+      ordered.push(entry);
+    }
+  }
+  return ordered;
+}
+
+// src/application/kernel.ts
+class ResourceCompletionBeforeReadyError extends Error {
+  constructor(resourceId, cause) {
+    super(`[stitchkit] resource "${resourceId}" completed before reaching readiness`, {
+      ...cause !== undefined && { cause }
+    });
+    this.name = "ResourceCompletionBeforeReadyError";
+  }
+}
+
+class ApplicationAdmissionError extends Error {
+  code = "APPLICATION_NOT_ACCEPTING";
+  constructor() {
+    super("Application is not accepting new operations");
+    this.name = "ApplicationAdmissionError";
+  }
+}
+function isStartResult(value) {
+  return typeof value === "object" && value !== null;
+}
+function waitForAbort(signal) {
+  if (signal.aborted)
+    return Promise.resolve();
+  return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+async function untilDeadline(work, signal) {
+  const result = await Promise.race([
+    work.then((value) => ({ settled: true, value }), (error) => ({ settled: true, error })),
+    waitForAbort(signal).then(() => ({ settled: false }))
+  ]);
+  return result;
+}
+function createApplication(config) {
+  const id = ApplicationIdSchema.parse(config.id);
+  const ordered = resolveResourceGraph(config.resources ?? []);
+  const reverse = [...ordered].reverse();
+  const records = new Map;
+  for (const entry of ordered) {
+    records.set(entry.id, {
+      entry,
+      state: "registered",
+      health: "unknown",
+      attempted: false,
+      activated: false,
+      closeInvoked: false,
+      closed: false,
+      failures: []
+    });
+  }
+  const epoch = crypto.randomUUID();
+  const listeners = new Set;
+  const lifetimeAbort = new AbortController;
+  const startupAbort = new AbortController;
+  let lifecycle = "created";
+  let revision = 0;
+  let changedAt = new Date().toISOString();
+  let accepting = false;
+  let accepted = 0;
+  let completed = 0;
+  let pending = 0;
+  let startPromise;
+  let shutdownPromise;
+  let shutdownRequested = false;
+  let activationComplete = false;
+  const pendingWaiters = new Set;
+  const aggregateHealth = () => {
+    if (lifecycle === "created" || lifecycle === "starting")
+      return "unknown";
+    let optionalUnhealthy = false;
+    for (const record of records.values()) {
+      if (record.entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+        return "unhealthy";
+      }
+      if (!record.entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+        optionalUnhealthy = true;
+      }
+    }
+    return optionalUnhealthy ? "degraded" : "healthy";
+  };
+  const isReady = () => lifecycle === "ready" && [...records.values()].every((record) => !record.entry.required || record.state === "ready" && record.health === "healthy");
+  const snapshot = () => ApplicationSnapshotSchema.parse({
+    id,
+    epoch,
+    revision,
+    lifecycle,
+    health: aggregateHealth(),
+    ready: isReady(),
+    capturedAt: new Date().toISOString(),
+    changedAt,
+    admission: { accepting, accepted, completed, pending },
+    resources: ordered.map((entry) => {
+      const record = records.get(entry.id);
+      if (!record)
+        throw new Error("Managed resource record disappeared");
+      return {
+        id: entry.id,
+        required: entry.required,
+        dependsOn: entry.dependsOn,
+        state: record.state,
+        health: record.health,
+        ready: record.state === "ready" && record.health === "healthy"
+      };
+    })
+  });
+  const publish = () => {
+    revision += 1;
+    changedAt = new Date().toISOString();
+    const value = snapshot();
+    for (const listener of listeners) {
+      try {
+        listener(value);
+      } catch {}
+    }
+    if (config.onSnapshot) {
+      Promise.resolve().then(() => config.onSnapshot?.(value)).catch(() => {});
+    }
+  };
+  const contextFor = (record, options = {}) => ({
+    applicationId: id,
+    signal: options.signal ?? lifetimeAbort.signal,
+    ...options.deadlineAt !== undefined && { deadlineAt: options.deadlineAt },
+    ...options.forceDeadlineAt !== undefined && {
+      forceDeadlineAt: options.forceDeadlineAt
+    },
+    now: () => performance.now(),
+    reportHealth(health) {
+      if (record.state === "stopped")
+        return;
+      record.health = health;
+      accepting = activationComplete && !shutdownRequested && isReady();
+      publish();
+    }
+  });
+  const markLateCompletion = (record, failure) => {
+    if (shutdownRequested || record.state === "stopping" || record.state === "stopped")
+      return;
+    if (failure)
+      record.failures.push("completion");
+    record.state = "failed";
+    record.health = "unhealthy";
+    accepting = activationComplete && isReady();
+    publish();
+  };
+  const closeAttempted = async () => {
+    const errors = [];
+    for (const entry of reverse) {
+      const record = records.get(entry.id);
+      if (!record?.attempted || record.closed)
+        continue;
+      record.state = "stopping";
+      try {
+        record.closeInvoked = true;
+        await entry.resource.close?.(contextFor(record, { signal: startupAbort.signal }));
+        record.closed = true;
+        record.state = "stopped";
+      } catch (error) {
+        record.failures.push("close");
+        record.state = "failed";
+        errors.push(error);
+      }
+      publish();
+    }
+    return errors;
+  };
+  const runStart = async () => {
+    lifecycle = "starting";
+    publish();
+    let startFailure;
+    try {
+      for (const entry of ordered) {
+        if (shutdownRequested || startupAbort.signal.aborted) {
+          throw new Error("[stitchkit] application startup interrupted by shutdown");
+        }
+        const record = records.get(entry.id);
+        if (!record)
+          throw new Error("Managed resource record disappeared");
+        const dependencyFailed = entry.dependsOn.some((dependencyId) => records.get(dependencyId)?.state !== "ready");
+        if (dependencyFailed) {
+          record.state = "failed";
+          record.health = "unhealthy";
+          record.failures.push("start");
+          publish();
+          if (entry.required) {
+            throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable dependency`);
+          }
+          continue;
+        }
+        record.attempted = true;
+        record.state = "starting";
+        publish();
+        try {
+          const started = await entry.resource.start(contextFor(record, { signal: startupAbort.signal }));
+          if (shutdownRequested || startupAbort.signal.aborted) {
+            throw new Error("[stitchkit] application startup interrupted by shutdown");
+          }
+          if (isStartResult(started)) {
+            record.runtime = started;
+            let resourceReady = started.ready === undefined;
+            let completionSettled = false;
+            let completionFailure;
+            const completion = started.completion?.then(() => {
+              completionSettled = true;
+              if (resourceReady)
+                markLateCompletion(record, false);
+            }, (error) => {
+              completionSettled = true;
+              completionFailure = error;
+              if (resourceReady)
+                markLateCompletion(record, true);
+            });
+            if (started.ready && completion) {
+              const readiness = started.ready.then(() => "ready");
+              const completionBeforeReady = completion.then(() => "completion");
+              const first = await Promise.race([readiness, completionBeforeReady]);
+              if (first === "completion") {
+                throw new ResourceCompletionBeforeReadyError(entry.id, completionFailure);
+              }
+              resourceReady = true;
+              if (completionSettled) {
+                throw new ResourceCompletionBeforeReadyError(entry.id, completionFailure);
+              }
+            } else if (started.ready) {
+              await started.ready;
+              resourceReady = true;
+            } else if (completion) {}
+          }
+          if (shutdownRequested || startupAbort.signal.aborted) {
+            throw new Error("[stitchkit] application startup interrupted by shutdown");
+          }
+          record.state = "ready";
+          record.health = "healthy";
+          publish();
+        } catch (error) {
+          if (shutdownRequested || startupAbort.signal.aborted)
+            throw error;
+          record.failures.push(error instanceof ResourceCompletionBeforeReadyError ? "completion" : record.runtime?.ready ? "ready" : "start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          publish();
+          if (entry.required)
+            throw error;
+        }
+      }
+      lifecycle = "ready";
+      publish();
+      for (const entry of ordered) {
+        if (shutdownRequested || startupAbort.signal.aborted) {
+          throw new Error("[stitchkit] application startup interrupted by shutdown");
+        }
+        const record = records.get(entry.id);
+        if (record?.state !== "ready")
+          continue;
+        const dependencyUnavailable = entry.dependsOn.some((dependencyId) => {
+          const dependency = records.get(dependencyId);
+          return dependency?.state !== "ready" || !dependency.activated;
+        });
+        if (dependencyUnavailable) {
+          record.failures.push("start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          publish();
+          if (entry.required) {
+            throw new Error(`[stitchkit] required resource "${entry.id}" has an unavailable activation dependency`);
+          }
+          continue;
+        }
+        try {
+          await entry.resource.activate?.(contextFor(record));
+          if (shutdownRequested || startupAbort.signal.aborted) {
+            throw new Error("[stitchkit] application startup interrupted by shutdown");
+          }
+          record.activated = true;
+          if (entry.required && (record.state !== "ready" || record.health !== "healthy")) {
+            throw new Error(`[stitchkit] required resource "${entry.id}" lost readiness during activation`);
+          }
+        } catch (error) {
+          if (shutdownRequested || startupAbort.signal.aborted)
+            throw error;
+          record.failures.push("start");
+          record.state = "failed";
+          record.health = "unhealthy";
+          publish();
+          if (entry.required)
+            throw error;
+        }
+      }
+      if (shutdownRequested) {
+        throw new Error("[stitchkit] application startup interrupted by shutdown");
+      }
+      if (!isReady()) {
+        throw new Error("[stitchkit] a required resource lost readiness during startup");
+      }
+      activationComplete = true;
+      accepting = isReady();
+      publish();
+      return snapshot();
+    } catch (error) {
+      startFailure = error;
+    }
+    if (!shutdownRequested) {
+      const rollbackErrors = await closeAttempted();
+      lifecycle = "failed";
+      accepting = false;
+      publish();
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError([startFailure, ...rollbackErrors], "[stitchkit] application startup and rollback failed", { cause: startFailure });
+      }
+    }
+    throw startFailure;
+  };
+  const start = () => {
+    if (startPromise)
+      return startPromise;
+    if (lifecycle !== "created") {
+      return Promise.reject(new Error(`[stitchkit] application cannot start from lifecycle "${lifecycle}"`));
+    }
+    startPromise = runStart();
+    startPromise.catch(() => {
+      return;
+    });
+    return startPromise;
+  };
+  const acquire = () => {
+    if (!accepting || !isReady())
+      return null;
+    accepted += 1;
+    pending += 1;
+    publish();
+    let released = false;
+    return {
+      get released() {
+        return released;
+      },
+      release() {
+        if (released)
+          return;
+        released = true;
+        pending -= 1;
+        completed += 1;
+        if (pending === 0) {
+          for (const waiter of pendingWaiters)
+            waiter();
+          pendingWaiters.clear();
+        }
+        publish();
+      }
+    };
+  };
+  const run = async (work) => {
+    const lease = acquire();
+    if (!lease)
+      throw new ApplicationAdmissionError;
+    try {
+      return await work();
+    } finally {
+      lease.release();
+    }
+  };
+  const waitForPending = () => {
+    if (pending === 0)
+      return Promise.resolve();
+    return new Promise((resolve) => pendingWaiters.add(resolve));
+  };
+  const shutdown = (options) => {
+    if (shutdownPromise)
+      return shutdownPromise;
+    const parsed = ShutdownOptionsSchema.parse(options ?? {});
+    const startedAt = performance.now();
+    const graceDeadlineAt = startedAt + parsed.gracePeriodMs;
+    const forceDeadlineAt = graceDeadlineAt + parsed.forceTimeoutMs;
+    shutdownRequested = true;
+    accepting = false;
+    startupAbort.abort();
+    lifecycle = lifecycle === "created" ? "stopping" : "draining";
+    publish();
+    shutdownPromise = (async () => {
+      const gracefulAbort = new AbortController;
+      let forcedReason;
+      let gracefulFailed = [...records.values()].some((record) => record.attempted && record.closeInvoked && !record.closed);
+      const force = (reason) => {
+        if (forcedReason)
+          return;
+        forcedReason = reason;
+        gracefulAbort.abort();
+        lifetimeAbort.abort();
+      };
+      const graceTimer = setTimeout(() => force("deadline"), Math.max(0, graceDeadlineAt - performance.now()));
+      const onExternalAbort = () => force("signal");
+      parsed.signal?.addEventListener("abort", onExternalAbort, { once: true });
+      if (parsed.signal?.aborted)
+        force("signal");
+      if (startPromise) {
+        await untilDeadline(startPromise.catch(() => {
+          return;
+        }), gracefulAbort.signal);
+      }
+      const gracefulContext = (record) => contextFor(record, {
+        signal: gracefulAbort.signal,
+        deadlineAt: graceDeadlineAt,
+        forceDeadlineAt
+      });
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed)
+          continue;
+        try {
+          const result = await untilDeadline(Promise.resolve(entry.resource.stopAdmission?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!result.settled)
+            break;
+          if (result.error !== undefined)
+            throw result.error;
+        } catch {
+          record.failures.push("admission");
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+        }
+      }
+      if (!gracefulAbort.signal.aborted && !gracefulFailed) {
+        const result = await untilDeadline(waitForPending(), gracefulAbort.signal);
+        if (!result.settled)
+          force("deadline");
+      }
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted || gracefulFailed)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed)
+          continue;
+        record.state = "stopping";
+        publish();
+        try {
+          const drained = await untilDeadline(Promise.resolve(entry.resource.drain?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!drained.settled) {
+            force("deadline");
+            break;
+          }
+          if (drained.error !== undefined)
+            throw drained.error;
+        } catch {
+          record.failures.push("drain");
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+          break;
+        }
+      }
+      lifecycle = "stopping";
+      publish();
+      for (const entry of reverse) {
+        if (gracefulAbort.signal.aborted || gracefulFailed)
+          break;
+        const record = records.get(entry.id);
+        if (!record?.attempted || record.closed || record.closeInvoked)
+          continue;
+        try {
+          record.closeInvoked = true;
+          const closed = await untilDeadline(Promise.resolve(entry.resource.close?.(gracefulContext(record))), gracefulAbort.signal);
+          if (!closed.settled) {
+            force("deadline");
+            break;
+          }
+          if (closed.error !== undefined)
+            throw closed.error;
+          record.closed = true;
+          record.state = "stopped";
+          publish();
+        } catch {
+          record.failures.push("close");
+          record.state = "failed";
+          gracefulFailed = true;
+          lifetimeAbort.abort();
+          publish();
+          break;
+        }
+      }
+      clearTimeout(graceTimer);
+      parsed.signal?.removeEventListener("abort", onExternalAbort);
+      const mustForce = forcedReason !== undefined || gracefulFailed;
+      const pendingOperationsAtForce = mustForce ? pending : 0;
+      if (mustForce) {
+        lifetimeAbort.abort();
+        const forceAbort = new AbortController;
+        const forceTimer = setTimeout(() => forceAbort.abort(), Math.max(0, forceDeadlineAt - performance.now()));
+        await Promise.all(reverse.map(async (entry) => {
+          const record = records.get(entry.id);
+          if (!record?.attempted || record.closed)
+            return;
+          try {
+            let cleanup;
+            if (entry.resource.force) {
+              cleanup = Promise.resolve(entry.resource.force(contextFor(record, {
+                signal: forceAbort.signal,
+                deadlineAt: graceDeadlineAt,
+                forceDeadlineAt
+              })));
+            } else if (entry.resource.close && !record.closeInvoked) {
+              record.closeInvoked = true;
+              cleanup = Promise.resolve(entry.resource.close(contextFor(record, {
+                signal: forceAbort.signal,
+                deadlineAt: graceDeadlineAt,
+                forceDeadlineAt
+              })));
+            } else if (entry.resource.close) {
+              record.failures.push("force");
+              return;
+            }
+            const forced = await untilDeadline(cleanup ?? Promise.resolve(), forceAbort.signal);
+            if (!forced.settled || forced.error !== undefined) {
+              record.failures.push("force");
+              return;
+            }
+            record.closed = true;
+            record.state = "stopped";
+          } catch {
+            record.failures.push("force");
+          }
+        }));
+        clearTimeout(forceTimer);
+      }
+      const cleanupComplete = [...records.values()].every((record) => !record.attempted || record.closed);
+      lifecycle = cleanupComplete ? "stopped" : "failed";
+      publish();
+      return ApplicationShutdownResultSchema.parse({
+        outcome: mustForce ? "forced" : "clean",
+        ...forcedReason && { reason: forcedReason },
+        cleanupComplete,
+        acceptedOperations: accepted,
+        completedOperations: completed,
+        pendingOperations: pending,
+        pendingOperationsAtForce,
+        resources: ordered.map((entry) => {
+          const record = records.get(entry.id);
+          if (!record)
+            throw new Error("Managed resource record disappeared");
+          return {
+            id: entry.id,
+            state: !record.attempted ? "not-started" : record.closed ? "closed" : "force-failed",
+            failures: record.failures
+          };
+        }),
+        durationMs: performance.now() - startedAt
+      });
+    })();
+    shutdownPromise.catch(() => {
+      return;
+    });
+    return shutdownPromise;
+  };
+  return {
+    id,
+    admission: { acquire, run },
+    start,
+    getSnapshot: snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(snapshot());
+      return () => listeners.delete(listener);
+    },
+    shutdown
+  };
+}
+
+export { ApplicationAdmissionError, createApplication };

package/dist/index-mgf6cdkm.js

@@ -0,0 +1,66 @@
+// src/application/schemas.ts
+import { z } from "zod";
+var ApplicationIdSchema = z.string().min(1).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/);
+var ApplicationLifecycleSchema = z.enum([
+  "created",
+  "starting",
+  "ready",
+  "draining",
+  "stopping",
+  "stopped",
+  "failed"
+]);
+var ApplicationHealthSchema = z.enum(["unknown", "healthy", "degraded", "unhealthy"]);
+var ManagedResourceStateSchema = z.enum([
+  "registered",
+  "starting",
+  "ready",
+  "failed",
+  "stopping",
+  "stopped"
+]);
+var NonNegativeIntegerSchema = z.number().int().nonnegative();
+var ApplicationAdmissionSnapshotSchema = z.object({
+  accepting: z.boolean(),
+  accepted: NonNegativeIntegerSchema,
+  completed: NonNegativeIntegerSchema,
+  pending: NonNegativeIntegerSchema
+}).readonly();
+var ManagedResourceSnapshotSchema = z.object({
+  id: ApplicationIdSchema,
+  required: z.boolean(),
+  dependsOn: z.array(ApplicationIdSchema).readonly(),
+  state: ManagedResourceStateSchema,
+  health: ApplicationHealthSchema,
+  ready: z.boolean()
+}).readonly();
+var ApplicationSnapshotSchema = z.object({
+  id: ApplicationIdSchema,
+  epoch: z.string().uuid(),
+  revision: NonNegativeIntegerSchema,
+  lifecycle: ApplicationLifecycleSchema,
+  health: ApplicationHealthSchema,
+  ready: z.boolean(),
+  capturedAt: z.string().datetime({ offset: true }),
+  changedAt: z.string().datetime({ offset: true }),
+  admission: ApplicationAdmissionSnapshotSchema,
+  resources: z.array(ManagedResourceSnapshotSchema).readonly()
+}).readonly();
+var ApplicationResourceShutdownSchema = z.object({
+  id: ApplicationIdSchema,
+  state: z.enum(["not-started", "closed", "force-failed"]),
+  failures: z.array(z.enum(["start", "ready", "completion", "admission", "drain", "close", "force"])).readonly()
+}).readonly();
+var ApplicationShutdownResultSchema = z.object({
+  outcome: z.enum(["clean", "forced"]),
+  reason: z.enum(["deadline", "signal"]).optional(),
+  cleanupComplete: z.boolean(),
+  acceptedOperations: NonNegativeIntegerSchema,
+  completedOperations: NonNegativeIntegerSchema,
+  pendingOperations: NonNegativeIntegerSchema,
+  pendingOperationsAtForce: NonNegativeIntegerSchema,
+  resources: z.array(ApplicationResourceShutdownSchema).readonly(),
+  durationMs: z.number().nonnegative()
+}).readonly();
+
+export { ApplicationIdSchema, ApplicationLifecycleSchema, ApplicationHealthSchema, ManagedResourceStateSchema, ApplicationAdmissionSnapshotSchema, ManagedResourceSnapshotSchema, ApplicationSnapshotSchema, ApplicationResourceShutdownSchema, ApplicationShutdownResultSchema };