@forgezero/runtime 0.1.1 → 0.1.3

package/dist/jobs.js

@@ -6,6 +6,275 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/queue.ts
+class QueueStoppedError extends Error {
+  constructor() {
+    super("queue: stopped before this task could run");
+    this.name = "QueueStoppedError";
+  }
+}
+
+class QueueKeyStoppedError extends Error {
+  key;
+  constructor(key) {
+    super(`queue: key ${key} is stopped`);
+    this.key = key;
+    this.name = "QueueKeyStoppedError";
+  }
+}
+
+class TaskCancelledError extends Error {
+  constructor() {
+    super("queue: task cancelled");
+    this.name = "TaskCancelledError";
+  }
+}
+var DEFAULT_RETRY = {
+  attempts: 1,
+  backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
+};
+function createQueue(options = {}) {
+  const width = options.width ?? 8;
+  const retry = { ...DEFAULT_RETRY, ...options.retry };
+  if (!Number.isSafeInteger(width) || width < 1) {
+    throw new RangeError("queue: width must be a positive integer");
+  }
+  if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
+    throw new RangeError("queue: retry attempts must be a positive integer");
+  }
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const lanes = new Map;
+  const running = new Set;
+  const paused = new Set;
+  const stoppedKeys = new Set;
+  let sequence = 0;
+  let globallyPaused = false;
+  let accepting = true;
+  let aborted = false;
+  let completed = 0;
+  let failed = 0;
+  const idle = [];
+  const announceIdle = () => {
+    if (running.size > 0)
+      return;
+    for (const lane of lanes.values())
+      if (lane.length > 0)
+        return;
+    while (idle.length > 0)
+      idle.shift()();
+  };
+  function pump() {
+    if (globallyPaused || aborted) {
+      announceIdle();
+      return;
+    }
+    for (const [key, lane] of lanes) {
+      if (running.size >= width)
+        break;
+      if (running.has(key) || paused.has(key) || lane.length === 0)
+        continue;
+      execute(key);
+    }
+    announceIdle();
+  }
+  async function execute(key) {
+    running.add(key);
+    try {
+      const lane = lanes.get(key);
+      const entry = lane?.[0];
+      if (entry && !globallyPaused && !paused.has(key) && !aborted) {
+        lane.shift();
+        await attempt(entry);
+      }
+    } finally {
+      running.delete(key);
+      const remaining = lanes.get(key);
+      if (remaining?.length === 0)
+        lanes.delete(key);
+      else if (remaining) {
+        lanes.delete(key);
+        lanes.set(key, remaining);
+      }
+      pump();
+    }
+  }
+  async function attempt(entry) {
+    if (entry.cancelled) {
+      entry.reject(new TaskCancelledError);
+      return;
+    }
+    for (;; ) {
+      entry.attempt += 1;
+      try {
+        const value = await entry.run();
+        completed += 1;
+        entry.resolve(value);
+        return;
+      } catch (cause) {
+        if (entry.attempt >= retry.attempts || entry.cancelled || aborted) {
+          failed += 1;
+          entry.reject(cause);
+          return;
+        }
+        const delay = retry.backoffMs(entry.attempt);
+        if (!Number.isFinite(delay) || delay < 0) {
+          failed += 1;
+          entry.reject(new RangeError("queue: retry backoff must be a non-negative finite number"));
+          return;
+        }
+        await sleep(delay);
+      }
+    }
+  }
+  return {
+    run(key, handler, ...args) {
+      const id = `q_${++sequence}`;
+      if (!accepting || stoppedKeys.has(key)) {
+        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+        refused.catch(() => {
+          return;
+        });
+        return { id, key, result: refused };
+      }
+      let resolve;
+      let reject;
+      const result = new Promise((ok, no) => {
+        resolve = ok;
+        reject = no;
+      });
+      const entry = {
+        id,
+        key,
+        run: async () => handler(...args),
+        resolve,
+        reject,
+        attempt: 0,
+        cancelled: false
+      };
+      const lane = lanes.get(key);
+      if (lane)
+        lane.push(entry);
+      else
+        lanes.set(key, [entry]);
+      pump();
+      return { id, key, result };
+    },
+    cancel(id) {
+      for (const [key, lane] of lanes) {
+        const index = lane.findIndex((entry2) => entry2.id === id);
+        if (index === -1)
+          continue;
+        const [entry] = lane.splice(index, 1);
+        entry.cancelled = true;
+        entry.reject(new TaskCancelledError);
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+        announceIdle();
+        return true;
+      }
+      return false;
+    },
+    pauseKey(key) {
+      paused.add(key);
+    },
+    resumeKey(key) {
+      paused.delete(key);
+      pump();
+    },
+    stopKey(key) {
+      stoppedKeys.add(key);
+      paused.delete(key);
+      const lane = lanes.get(key);
+      if (!lane)
+        return 0;
+      let removed = 0;
+      for (const entry of lane.splice(0)) {
+        removed += 1;
+        entry.cancelled = true;
+        entry.reject(new QueueKeyStoppedError(key));
+      }
+      if (!running.has(key))
+        lanes.delete(key);
+      announceIdle();
+      return removed;
+    },
+    startKey(key) {
+      const changed = stoppedKeys.delete(key);
+      pump();
+      return changed;
+    },
+    pause() {
+      globallyPaused = true;
+    },
+    resume() {
+      globallyPaused = false;
+      pump();
+    },
+    snapshot() {
+      let queued = 0;
+      for (const lane of lanes.values())
+        queued += lane.length;
+      return {
+        running: running.size,
+        queued,
+        keys: lanes.size,
+        paused: globallyPaused,
+        pausedKeys: [...paused],
+        stoppedKeys: [...stoppedKeys],
+        completed,
+        failed
+      };
+    },
+    whenIdle() {
+      if (running.size === 0 && [...lanes.values()].every((lane) => lane.length === 0)) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => idle.push(resolve));
+    },
+    async stop(deadlineMs = 30000) {
+      if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 0) {
+        throw new RangeError("queue: stop deadline must be a non-negative integer");
+      }
+      accepting = false;
+      const before = { completed, failed };
+      globallyPaused = false;
+      paused.clear();
+      pump();
+      let timedOut = false;
+      let deadlineHandle;
+      const deadline = new Promise((resolve) => {
+        deadlineHandle = setTimeout(() => {
+          timedOut = true;
+          resolve();
+        }, deadlineMs);
+      });
+      await Promise.race([this.whenIdle(), deadline]);
+      if (!timedOut && deadlineHandle !== undefined)
+        clearTimeout(deadlineHandle);
+      if (timedOut)
+        aborted = true;
+      let abandoned = 0;
+      for (const lane of lanes.values()) {
+        abandoned += lane.length;
+        for (const entry of lane.splice(0))
+          entry.reject(new QueueStoppedError);
+      }
+      abandoned += running.size;
+      for (const [key, lane] of lanes) {
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+      }
+      announceIdle();
+      return {
+        completed: completed - before.completed,
+        failed: failed - before.failed,
+        abandoned,
+        timedOut
+      };
+    }
+  };
+}
+
 // src/jobs.ts
 var systemClock = {
   now: () => Date.now(),
@@ -83,10 +352,13 @@ function createScheduler(options) {
     { key: job.key, label: job.label, state: "stopped", consecutiveFailures: 0, runs: 0, skippedLocked: 0 }
   ]));
   const timers = new Map;
-  const inFlight = new Map;
+  let work = createQueue({ width: Math.max(1, jobs.size) });
+  let workStopped = false;
+  let restartBlocked = false;
   let controller = new AbortController;
   let paused = false;
   let running = false;
+  const submit = (job) => work.run(job.key, execute, job).result;
   async function execute(job) {
     const report = reports.get(job.key);
     const leaseMs = job.leaseMs ?? (job.every ? everyMs(job.every) * 4 : 60000);
@@ -132,17 +404,22 @@ function createScheduler(options) {
       timers.delete(job.key);
       if (!running || paused)
         return;
-      const work = execute(job).finally(() => {
-        inFlight.delete(job.key);
-        schedule(job, everyMs(job.every));
+      submit(job).then(() => schedule(job, everyMs(job.every)), () => {
+        return;
       });
-      inFlight.set(job.key, work);
     }, delayMs));
   }
   return {
     start() {
       if (running)
         return;
+      if (restartBlocked) {
+        throw new Error("scheduler: cannot restart after an incomplete drain while abandoned work may still run");
+      }
+      if (workStopped) {
+        work = createQueue({ width: Math.max(1, jobs.size) });
+        workStopped = false;
+      }
       running = true;
       paused = false;
       controller = new AbortController;
@@ -152,15 +429,18 @@ function createScheduler(options) {
         schedule(job, job.startDelayMs ?? spreadOf(job.key, Math.min(interval, 30000)));
       }
     },
-    async stop() {
+    async stop(deadlineMs = 30000) {
       running = false;
       controller.abort();
       for (const timer of timers.values())
         clearTimeout(timer);
       timers.clear();
-      await Promise.allSettled([...inFlight.values()]);
+      const drained = await work.stop(deadlineMs);
+      workStopped = true;
+      restartBlocked = drained.timedOut;
       for (const report of reports.values())
         report.state = "stopped";
+      return drained;
     },
     pause() {
       paused = true;
@@ -185,12 +465,7 @@ function createScheduler(options) {
       const job = jobs.get(key);
       if (!job)
         throw new Error(`No job named "${key}".`);
-      const existing = inFlight.get(key);
-      if (existing)
-        await existing;
-      const work = execute(job).finally(() => inFlight.delete(key));
-      inFlight.set(key, work);
-      await work;
+      await submit(job);
       return { ...reports.get(key) };
     },
     status: () => [...reports.values()].map((report) => ({ ...report })),

package/dist/pipeline.d.ts

@@ -1,11 +1,12 @@
 /**
- * Deciding whether a push should cause a deploy, and what that deploy is.
+ * Deciding whether a push should cause a deploy.
  *
  * A webhook receiver is a public endpoint that runs commands on your machines
  * when something posts to it. Everything worth getting right is in the gap
- * between those two facts, so this module holds the decisions and none of the
- * doing: no network, no shell, no clone. What it produces is a PLAN, and
- * something else carries it out.
+ * between those two facts, so this module holds trigger verification and none
+ * of the doing: no network, no shell, no clone, and no executable plan. The
+ * agent later reads the only deployment definition from the exact checked-out
+ * commit.
  *
  * That split is not tidiness. It means the interesting cases — a forged
  * signature, a push to a branch nobody deploys, two pushes racing, a repository
@@ -21,8 +22,8 @@
  * matters when reading logs during an incident.
  */
 export declare class PipelineError extends Error {
-    readonly code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'WRONG_REPOSITORY' | 'NO_SECRET';
-    constructor(code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'WRONG_REPOSITORY' | 'NO_SECRET', message: string);
+    readonly code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'NO_SECRET';
+    constructor(code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'NO_SECRET', message: string);
 }
 export declare const GIT_PROVIDERS: readonly ["github", "gitlab", "generic"];
 export type GitProvider = (typeof GIT_PROVIDERS)[number];
@@ -73,50 +74,23 @@ export interface PushEvent {
  * failure every time somebody opened an issue.
  */
 export declare function parsePush(provider: GitProvider, body: unknown): PushEvent | null;
-export interface PipelineConfig {
+export interface DeployTrigger {
     provider: GitProvider;
     /** `owner/name`. Compared against the delivery. */
     repository: string;
     /** Only this branch deploys. One branch per pipeline, deliberately. */
     branch: string;
-    /** Where the checkout lives on the compute. */
-    workdir: string;
-    /** Shell steps, in order. Empty means clone only. */
-    steps: readonly string[];
-    cloneUrl: string;
 }
-export declare const PLAN_ACTIONS: readonly ["clone", "fetch", "checkout", "run"];
-export type PlanAction = (typeof PLAN_ACTIONS)[number];
-export interface PlanStep {
-    action: PlanAction;
-    command: string;
-    /** Shown to an operator. Never contains a credential. */
-    label: string;
-}
-/**
- * The commands that would deploy this push, in order.
- *
- * `clone` and `fetch` are both emitted, guarded on the directory existing,
- * because a runner cannot know in advance whether the first deploy has
- * happened — and branching on that in the caller means two code paths where one
- * of them is exercised once per compute, ever.
- *
- * The commit is checked out by SHA rather than by branch. A branch moves: a
- * deploy that fetched and then checked out `main` could deploy a commit that
- * arrived after the one that triggered it, so the thing tested is not the thing
- * shipped. The SHA is what the webhook said, so what deploys is what fired.
- */
-export declare function planDeploy(config: PipelineConfig, event: PushEvent): PlanStep[];
 /**
  * Should this delivery deploy at all?
  *
- * Separate from `planDeploy` so "we received it and deliberately did nothing"
- * is a first-class outcome with a reason attached. A receiver that silently
+ * "We received it and deliberately did nothing" is a first-class outcome with
+ * a reason attached. A receiver that silently
  * ignored non-matching branches would be indistinguishable from one that is
  * broken, and the first question during an incident is always whether the hook
  * arrived.
  */
-export declare function shouldDeploy(config: PipelineConfig, event: PushEvent | null): {
+export declare function shouldDeploy(config: Pick<DeployTrigger, 'repository' | 'branch'>, event: PushEvent | null): {
     deploy: boolean;
     reason: string;
 };

package/dist/pipeline.js

@@ -72,31 +72,6 @@ function parsePush(provider, body) {
     message: typeof payload.head_commit?.message === "string" ? String(payload.head_commit.message) : undefined
   };
 }
-var PLAN_ACTIONS = ["clone", "fetch", "checkout", "run"];
-function planDeploy(config, event) {
-  if (event.repository !== config.repository) {
-    throw new PipelineError("WRONG_REPOSITORY", `That delivery is for ${event.repository}, and this pipeline deploys ${config.repository}.`);
-  }
-  const dir = config.workdir;
-  return [
-    {
-      action: "clone",
-      command: `[ -d ${dir}/.git ] || git clone ${config.cloneUrl} ${dir}`,
-      label: "clone if this is the first deploy"
-    },
-    { action: "fetch", command: `git -C ${dir} fetch --prune origin`, label: "fetch" },
-    {
-      action: "checkout",
-      command: `git -C ${dir} checkout --detach ${event.commit}`,
-      label: `check out ${event.commit.slice(0, 8)}`
-    },
-    ...config.steps.map((step) => ({
-      action: "run",
-      command: `cd ${dir} && ${step}`,
-      label: step
-    }))
-  ];
-}
 function shouldDeploy(config, event) {
   if (!event)
     return { deploy: false, reason: "Not a branch push — nothing to deploy." };
@@ -113,9 +88,7 @@ export {
   webhookPath,
   verifyWebhook,
   shouldDeploy,
-  planDeploy,
   parsePush,
   PipelineError,
-  PLAN_ACTIONS,
   GIT_PROVIDERS
 };

package/dist/queue.d.ts

@@ -44,9 +44,8 @@ export interface QueueOptions {
     /** How many keys may run at once. Ordering within a key is unaffected. */
     width?: number;
     retry?: Partial<RetryPolicy>;
-    /** Injected so tests need no timers and no wall clock. */
+    /** Retry delay injection. Shutdown deadlines use a cancellable native timer. */
     sleep?: (ms: number) => Promise<void>;
-    now?: () => number;
 }
 export interface DrainReport {
     completed: number;
@@ -58,6 +57,10 @@ export interface DrainReport {
 export declare class QueueStoppedError extends Error {
     constructor();
 }
+export declare class QueueKeyStoppedError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
 export declare class TaskCancelledError extends Error {
     constructor();
 }
@@ -69,12 +72,22 @@ export declare function createQueue(options?: QueueOptions): {
      * rather than an id to poll — the previous `enqueue` returned only
      * `{ id, duplicate }` and had nowhere to put an answer.
      */
-    run<T>(key: string, handler: () => Promise<T> | T): QueueTask<T>;
+    run<Args extends unknown[], T>(key: string, handler: (...args: Args) => Promise<T> | T, ...args: Args): QueueTask<T>;
     /** Remove a task that has not started. Running work is left alone. */
     cancel(id: string): boolean;
     /** Hold one key. Work already running for it finishes. */
     pauseKey(key: string): void;
     resumeKey(key: string): void;
+    /**
+     * Close one key and reject everything for it that has not started.
+     *
+     * JavaScript cannot safely kill an arbitrary running function. The current
+     * handler is therefore allowed to finish; every pending handler is removed,
+     * and future submissions are refused until `startKey()` is explicit.
+     */
+    stopKey(key: string): number;
+    /** Re-open a key deliberately; pausing and stopping are not aliases. */
+    startKey(key: string): boolean;
     /** Hold everything. New submissions are accepted and wait. */
     pause(): void;
     resume(): void;
@@ -85,6 +98,7 @@ export declare function createQueue(options?: QueueOptions): {
         keys: number;
         paused: boolean;
         pausedKeys: string[];
+        stoppedKeys: string[];
         completed: number;
         failed: number;
     };