@forgezero/runtime 0.1.0

package/dist/pipeline.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Deciding whether a push should cause a deploy, and what that deploy is.
+ *
+ * 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.
+ *
+ * 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
+ * that is not the one configured — are all testable without a git server, and
+ * they are the cases that decide whether this endpoint is a deploy trigger or a
+ * remote shell.
+ *
+ * ## The signature is checked before anything is parsed
+ *
+ * A JSON body from an unauthenticated caller is attacker-controlled input. It
+ * gets verified first and parsed second, so a malformed payload from a forged
+ * sender is rejected as forged rather than as malformed — the distinction
+ * 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);
+}
+export declare const GIT_PROVIDERS: readonly ["github", "gitlab", "generic"];
+export type GitProvider = (typeof GIT_PROVIDERS)[number];
+/**
+ * Is this delivery really from the repository we configured?
+ *
+ * Each provider proves it differently, and the differences are not cosmetic:
+ *
+ *   GITHUB   `x-hub-signature-256: sha256=<hex>` — an HMAC over the raw body.
+ *   GITLAB   `x-gitlab-token: <secret>` — the secret itself, compared whole.
+ *   GENERIC  the same HMAC shape as GitHub, for anything self-hosted.
+ *
+ * GitLab's scheme is weaker — the secret travels on every delivery rather than
+ * a signature derived from it — and that is GitLab's decision, not one made
+ * here. It is compared in constant time anyway, because the alternative leaks
+ * how much of a guess was right.
+ *
+ * The RAW body is required, not a re-serialised object. `JSON.parse` followed by
+ * `JSON.stringify` reorders keys and drops whitespace, so the bytes hashed stop
+ * being the bytes sent and every signature fails — which reads as a
+ * misconfigured secret and sends people to change the wrong thing.
+ */
+export declare function verifyWebhook(args: {
+    provider: GitProvider;
+    secret: string;
+    rawBody: string;
+    headers: Record<string, string | undefined>;
+}): void;
+export interface PushEvent {
+    /** `refs/heads/main` reduced to `main`. */
+    branch: string;
+    commit: string;
+    /** `owner/name`, however the provider spells it. */
+    repository: string;
+    pushedBy?: string;
+    message?: string;
+}
+/**
+ * What happened, in one shape.
+ *
+ * Providers disagree about every field name, and normalising here means the
+ * deploy logic never learns which forge it is talking to — that is the point of
+ * `generic` existing at all.
+ *
+ * A delivery that is not a branch push returns `null` rather than throwing. Tag
+ * pushes, branch deletions, pings and issue comments all arrive on the same
+ * endpoint, and treating them as errors would make a healthy integration log a
+ * failure every time somebody opened an issue.
+ */
+export declare function parsePush(provider: GitProvider, body: unknown): PushEvent | null;
+export interface PipelineConfig {
+    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
+ * 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): {
+    deploy: boolean;
+    reason: string;
+};
+/**
+ * The webhook URL a forge should be pointed at.
+ *
+ * The TENANT is in the path and the pipeline key is the unguessable part. That
+ * split is not cosmetic: without the tenant, resolving a delivery means
+ * searching every realm for a matching key, and the only way to do that is a
+ * cross-realm query — which in this codebase means widening the allow-list that
+ * exists to make realm-boundary erosion visible. Naming the tenant makes the
+ * lookup an ordinary scoped read.
+ *
+ * The tenant slug is not a secret; it is in every URL a tenant uses. The key is
+ * 12 random bytes, and the SIGNATURE is what authorises — a correct URL with a
+ * wrong signature deploys nothing.
+ */
+export declare const webhookPath: (tenant: string, pipelineKey: string) => string;

package/dist/pipeline.js

@@ -0,0 +1,121 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/pipeline.ts
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+
+class PipelineError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PipelineError";
+  }
+}
+var GIT_PROVIDERS = ["github", "gitlab", "generic"];
+function equal(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let at = 0;at < a.length; at += 1)
+    difference |= a[at] ^ b[at];
+  return difference === 0;
+}
+var encoder = new TextEncoder;
+var hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+function verifyWebhook(args) {
+  if (!args.secret) {
+    throw new PipelineError("NO_SECRET", "This connection has no webhook secret, so nothing can be verified.");
+  }
+  const lowered = new Map(Object.entries(args.headers).map(([key, value]) => [key.toLowerCase(), value]));
+  const header = (name) => lowered.get(name.toLowerCase());
+  if (args.provider === "gitlab") {
+    const presented2 = header("x-gitlab-token") ?? "";
+    if (!equal(encoder.encode(presented2), encoder.encode(args.secret))) {
+      throw new PipelineError("BAD_SIGNATURE", "That delivery did not carry the configured token.");
+    }
+    return;
+  }
+  const presented = header("x-hub-signature-256") ?? header("x-fz-signature-256") ?? "";
+  const expected = `sha256=${hex(hmac(sha256, encoder.encode(args.secret), encoder.encode(args.rawBody)))}`;
+  if (!equal(encoder.encode(presented), encoder.encode(expected))) {
+    throw new PipelineError("BAD_SIGNATURE", "That delivery did not match the configured secret.");
+  }
+}
+var branchOf = (ref) => ref.replace(/^refs\/heads\//, "");
+function parsePush(provider, body) {
+  if (typeof body !== "object" || body === null) {
+    throw new PipelineError("MALFORMED_EVENT", "That delivery had no object body.");
+  }
+  const payload = body;
+  const ref = typeof payload.ref === "string" ? payload.ref : "";
+  if (!ref.startsWith("refs/heads/"))
+    return null;
+  if (payload.deleted === true || payload.after === "0000000000000000000000000000000000000000")
+    return null;
+  const repository = provider === "gitlab" ? String(payload.project?.path_with_namespace ?? "") : String(payload.repository?.full_name ?? "");
+  const commit = typeof payload.after === "string" ? payload.after : typeof payload.checkout_sha === "string" ? payload.checkout_sha : "";
+  if (!repository || !commit) {
+    throw new PipelineError("MALFORMED_EVENT", "That delivery named no repository or no commit.");
+  }
+  return {
+    branch: branchOf(ref),
+    commit,
+    repository,
+    pushedBy: typeof payload.user_username === "string" ? payload.user_username : typeof payload.pusher?.name === "string" ? String(payload.pusher.name) : undefined,
+    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." };
+  if (event.repository !== config.repository) {
+    return { deploy: false, reason: `Delivery is for ${event.repository}, not ${config.repository}.` };
+  }
+  if (event.branch !== config.branch) {
+    return { deploy: false, reason: `Pushed to ${event.branch}; this pipeline follows ${config.branch}.` };
+  }
+  return { deploy: true, reason: `${event.branch} at ${event.commit.slice(0, 8)}` };
+}
+var webhookPath = (tenant, pipelineKey) => `/v1/hooks/${tenant}/${pipelineKey}`;
+export {
+  webhookPath,
+  verifyWebhook,
+  shouldDeploy,
+  planDeploy,
+  parsePush,
+  PipelineError,
+  PLAN_ACTIONS,
+  GIT_PROVIDERS
+};

package/dist/queue.d.ts

@@ -0,0 +1,243 @@
+/**
+ * A keyed work queue — parallel across keys, strictly sequential within one.
+ *
+ * The problem this solves is narrow and very common: most work can run in any
+ * order, but some of it must not. Two credits to the same wallet, two writes to
+ * the same vault entry, two deploys of the same application — each pair has to
+ * happen one after the other, while everything touching a DIFFERENT wallet,
+ * entry or application should run at full width.
+ *
+ * A global lock gives you the ordering and throws away the throughput. A plain
+ * worker pool gives you the throughput and loses the ordering. The answer is to
+ * partition by key: the queue is really thousands of tiny FIFOs, and a worker
+ * claims a KEY rather than a message.
+ *
+ * ## Why claim the key, not the message
+ *
+ * Claiming a message and processing it is the obvious design and it does not
+ * order anything: two workers can claim message 1 and message 2 of the same key
+ * at the same instant and finish in either order. Claiming the KEY makes
+ * ordering structural — while a worker holds `wallet:42`, nobody else can take
+ * ANY message for it, so its messages can only be processed in the order they
+ * were written.
+ *
+ * ## What this guarantees, and what it does not
+ *
+ * GUARANTEED   per-key FIFO order; at-least-once delivery; at most one worker
+ *              per key at a time, across the whole cluster; a message that
+ *              exhausts its attempts moves to a dead letter INSTEAD of blocking
+ *              its key forever.
+ *
+ * NOT GUARANTEED   exactly-once execution. Nothing can guarantee that: a worker
+ *              can complete the side effect and die before recording that it
+ *              did. `dedupeKey` collapses duplicate ENQUEUES, and the lease
+ *              stops concurrent delivery, but a crash between "money moved" and
+ *              "message acknowledged" will redeliver.
+ *
+ * ## So for money, read this
+ *
+ * The queue is not what makes a financial operation safe — the HANDLER is. Make
+ * the effect idempotent at the point of effect: a ledger posting keyed on the
+ * message id and refused by a unique index, or a transfer keyed on an
+ * idempotency key the payment provider also honours. Then redelivery is free
+ * and the queue only has to provide ordering and durability, which it does.
+ *
+ * Anything that relies on "the queue delivered it once" is relying on something
+ * no queue provides, including this one, including the expensive ones.
+ */
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+/** `30s` → 30000. Throws rather than guessing — a wrong window is silent. */
+export declare function durationMs(value: string | number): number;
+export type MessageStatus = 'ready' | 'leased' | 'done' | 'dead';
+export interface Message<Body = unknown> {
+    id: string;
+    /** The partition. Everything sharing it runs in order, one at a time. */
+    key: string;
+    body: Body;
+    /** Monotonic per queue. Decides order within a key. */
+    sequence: number;
+    status: MessageStatus;
+    attempts: number;
+    /** Earliest time this may be delivered. Set by a retry backoff. */
+    availableAtMs: number;
+    /** Collapses repeat enqueues within a window. See `enqueue`. */
+    dedupeKey?: string;
+    lastError?: string;
+    enqueuedAtMs: number;
+    completedAtMs?: number;
+}
+export interface KeyLease {
+    key: string;
+    /** Rises every time the key is granted. A stale holder cannot write. */
+    fence: number;
+    untilMs: number;
+    owner: string;
+}
+/**
+ * Where the queue lives. Memory for tests, a database for a cluster.
+ *
+ * `claimKey` MUST be atomic. A read-then-write implementation hands the same key
+ * to two workers under exactly the load that makes ordering matter, and the bug
+ * looks like "the queue occasionally processes out of order" — which is the
+ * hardest possible thing to reproduce.
+ */
+export interface QueueStore<Body = unknown> {
+    /** Which deployment shape this store can serve. See `MODES`. */
+    readonly mode: QueueMode;
+    append(queue: string, message: Message<Body>): Promise<void>;
+    /** Existing message with this dedupe key, if the window has not passed. */
+    findByDedupe(queue: string, dedupeKey: string, sinceMs: number): Promise<Message<Body> | null>;
+    /**
+     * Take the next key that has ready work and is not leased. Atomic.
+     * `exclude` skips keys this worker already holds.
+     */
+    claimKey(queue: string, owner: string, ttlMs: number, nowMs: number): Promise<KeyLease | null>;
+    renewKey(queue: string, lease: KeyLease, ttlMs: number, nowMs: number): Promise<boolean>;
+    releaseKey(queue: string, lease: KeyLease): Promise<void>;
+    /** Ready messages for one key, in sequence order. */
+    readKey(queue: string, key: string, nowMs: number, limit: number): Promise<Message<Body>[]>;
+    update(queue: string, id: string, patch: Partial<Message<Body>>): Promise<void>;
+    stats(queue: string): Promise<QueueStats>;
+    /** Dead-lettered messages, newest first. */
+    dead(queue: string, limit: number): Promise<Message<Body>[]>;
+}
+export interface QueueStats {
+    ready: number;
+    leased: number;
+    dead: number;
+    keys: number;
+}
+/**
+ * Standalone and cluster are the same queue with a different store.
+ *
+ *   standalone  one process, state in memory. No coordination, nothing to
+ *               install, and the ordering guarantee still holds — because a
+ *               single process claiming its own keys cannot race itself.
+ *               Everything is lost on restart, which is correct for a
+ *               development machine and wrong for anything holding money.
+ *
+ *   cluster     several processes over shared storage. The guarantee is the
+ *               same and the requirement is stricter: `claimKey` must be
+ *               ATOMIC. A read-then-write implementation hands one key to two
+ *               workers under exactly the load that makes ordering matter, and
+ *               the bug presents as "the queue occasionally processes out of
+ *               order" — the hardest possible thing to reproduce.
+ *
+ * The distinction is declared on the store rather than inferred, so a
+ * deployment can refuse to start when a durable queue was expected and a memory
+ * one was wired in. That mistake is otherwise invisible until a restart.
+ */
+export declare const MODES: readonly ["standalone", "cluster"];
+export type QueueMode = (typeof MODES)[number];
+/**
+ * Single process. Correct for tests and for one instance, and honest about
+ * being no more — nothing here coordinates across processes.
+ */
+export declare function memoryStore<Body = unknown>(clock?: Clock): QueueStore<Body>;
+export interface Handler<Body> {
+    (message: Message<Body>, context: HandlerContext): Promise<void>;
+}
+export interface HandlerContext {
+    /** Still ours? False means the lease expired and nothing further may be written. */
+    holdsKey(): Promise<boolean>;
+    log(message: string): void;
+    attempt: number;
+}
+export interface QueueOptions<Body> {
+    name: string;
+    store: QueueStore<Body>;
+    handler: Handler<Body>;
+    /** How many KEYS one worker processes at once. Not messages — see the note. */
+    concurrency?: number;
+    /** How long a key lease lasts. Renewed between messages. */
+    leaseMs?: number;
+    /** Attempts before a message is dead-lettered. */
+    maxAttempts?: number;
+    /** Backoff between attempts. Doubles, capped. */
+    backoffMs?: number;
+    maxBackoffMs?: number;
+    /** Repeat enqueues with the same `dedupeKey` inside this window collapse. */
+    dedupeWindowMs?: number;
+    /** Messages taken per key per turn, so one hot key cannot hold a slot forever. */
+    batch?: number;
+    clock?: Clock;
+    owner?: string;
+    onError?: (message: Message<Body>, error: unknown) => void;
+    /**
+     * Refuse to start unless the store is durable.
+     *
+     * Set it wherever losing queued work on a restart would be a real loss.
+     * Without it, wiring the memory store into a cluster is a mistake nothing
+     * reports until the first restart, by which point the work is gone.
+     */
+    require?: QueueMode;
+}
+export interface EnqueueResult {
+    id: string;
+    /** True when an identical `dedupeKey` was already queued and this was dropped. */
+    duplicate: boolean;
+}
+export declare function createQueue<Body = unknown>(options: QueueOptions<Body>): {
+    enqueue: (args: {
+        key: string;
+        body: Body;
+        dedupeKey?: string;
+        delayMs?: number;
+    }) => Promise<EnqueueResult>;
+    tick: () => Promise<number>;
+    /** Drain until nothing is ready. For tests and for a one-shot worker. */
+    drain(maxPasses?: number): Promise<void>;
+    /** Poll forever. `stop()` lets in-flight keys finish. */
+    start(intervalMs?: number): void;
+    stop(): void;
+    mode: "standalone" | "cluster";
+    stats: () => Promise<QueueStats>;
+    dead: (limit?: number) => Promise<Message<Body>[]>;
+    /** Put a dead message back at the front of its key. An operator decision. */
+    revive(id: string): Promise<void>;
+};
+export type Queue<Body = unknown> = ReturnType<typeof createQueue<Body>>;
+export declare const VERSION = "0.1.0";
+/**
+ * The four operations a shared database has to provide, and the one that is
+ * hard.
+ *
+ * Everything except `claimKey` is an ordinary read or write. `claimKey` has to
+ * find a key with ready work, check that nobody holds it, and take it — as ONE
+ * atomic step. Split into a read and a write, two workers pass the check
+ * together and both proceed, and the queue silently stops ordering anything.
+ *
+ * Written as a small adapter rather than a driver so the same queue runs over
+ * ArangoDB, Postgres or Redis, and so this package keeps no dependency.
+ */
+export interface ClusterAdapter<Body = unknown> {
+    insert(queue: string, message: Message<Body>): Promise<void>;
+    findDuplicate(queue: string, dedupeKey: string, sinceMs: number): Promise<Message<Body> | null>;
+    /**
+     * ATOMIC. Must return a key that has ready work and no live lease, marking it
+     * leased in the same operation. Returning null means there is nothing to do.
+     */
+    takeKey(args: {
+        queue: string;
+        owner: string;
+        untilMs: number;
+        nowMs: number;
+    }): Promise<KeyLease | null>;
+    extendKey(queue: string, key: string, fence: number, untilMs: number): Promise<boolean>;
+    dropKey(queue: string, key: string, fence: number): Promise<void>;
+    readReady(queue: string, key: string, nowMs: number, limit: number): Promise<Message<Body>[]>;
+    patch(queue: string, id: string, patch: Partial<Message<Body>>): Promise<void>;
+    counts(queue: string): Promise<QueueStats>;
+    deadLetter(queue: string, limit: number): Promise<Message<Body>[]>;
+}
+/**
+ * A durable store over any shared database.
+ *
+ * Declares `mode: 'cluster'`, which is what lets a deployment refuse to start if
+ * somebody wires the memory store into production by mistake — a mistake that
+ * is otherwise invisible until the first restart takes the queue with it.
+ */
+export declare function clusterStore<Body = unknown>(adapter: ClusterAdapter<Body>): QueueStore<Body>;