@edgehero/pi-dispatch-receiver 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Webhook receiver for pi-dispatch: the always-on edge that verifies GitHub, GitLab, Forgejo and Azure DevOps deliveries and enqueues (at most) one job per event for the worker.",
   "keywords": [

package/src/filter-azure.mjs

@@ -116,6 +116,10 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
 		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level and conditional for the
+		// reasons filter.mjs states in full: receiver.mjs reads this to decide how many times to enqueue, and an
+		// unflagged job's data must stay byte-identical to today's.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
 		trigger: {
 			event,
 			action: resolved.action,
@@ -179,6 +183,7 @@ function matchLabelRules(subset, triggers, labels, action) {
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.target?.number, title: subset.target?.title, body: subset.target?.body },
 	};
@@ -219,6 +224,7 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 		skillsDir: triggers.comment.skillsDir,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// No author_association: Azure has none, and the authority that admitted this comment was resolved
 		// from the graph, not read off the body.
@@ -248,6 +254,7 @@ function routePullRequest(subset, triggers, action) {
 			skillsDir: rule.skillsDir,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {
 				type: "pull_request",

package/src/filter-forgejo.mjs

@@ -118,6 +118,10 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
 		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level and conditional for the
+		// reasons filter.mjs states in full: receiver.mjs reads this to decide how many times to enqueue, and an
+		// unflagged job's data must stay byte-identical to today's.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
 		trigger: {
 			event: eventName,
 			// Forgejo's OWN word, not our translation of it. The run record should say what the forge said.
@@ -147,6 +151,7 @@ function routeIssueLabel(subset, triggers) {
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
 	};
@@ -192,6 +197,7 @@ function routeComment(subset, triggers, knownFlows) {
 		skillsDir: triggers.comment.skillsDir,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// The invoking comment rides on the trigger. No author_association: Forgejo has none, and the
 		// authority that admitted this comment was resolved from the API, not read off the body.
@@ -219,6 +225,7 @@ function routePullRequest(subset, triggers, action) {
 			skillsDir: rule.skillsDir,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {
 				type: "pull_request",

package/src/filter-gitlab.mjs

@@ -111,6 +111,10 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
 		// byte-identical to today's, so the key is absent rather than present-and-undefined.
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level and conditional for the
+		// reasons filter.mjs states in full: receiver.mjs reads this to decide how many times to enqueue, and an
+		// unflagged job's data must stay byte-identical to today's.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
 		trigger: {
 			event: kind,
 			action: subset.action,
@@ -145,6 +149,7 @@ function routeLabel(subset, triggers, targetType) {
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) },
 		target: buildTarget(subset, targetType),
 	};
@@ -205,6 +210,7 @@ function mrResult(subset, rule, matched) {
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched,
 		target: buildTarget(subset, "pull_request"),
 	};
@@ -251,6 +257,7 @@ function routeNote(subset, triggers, knownFlows) {
 		skillsDir: triggers.comment.skillsDir,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		target: buildTarget(subset, targetType),
 		// The invoking comment rides the job as DATA (CONST-ISSUE-TEXT-IS-DATA). No author_association

package/src/poller.mjs

@@ -804,7 +804,10 @@ function makeAppInstallationTokenFn(github, { fetchFn, readFile, now }) {
 	let cached = null; // { token, expiresAtMs }
 	return async () => {
 		if (cached !== null && cached.expiresAtMs - now() > 5 * 60_000) return cached.token;
-		const pem = await readFile(github.privateKeyPath, "utf8");
+		// Inline key (GITHUB_APP_PRIVATE_KEY) when the operator supplied one, the file otherwise. The shared
+		// loadGitHubAuth normalised and shape-checked it at load and refuses both-set, so there is nothing to
+		// decide here (issue #208).
+		const pem = github.privateKey ?? (await readFile(github.privateKeyPath, "utf8"));
 		const jwt = appJwt(github.appId, pem, now());
 		const res = await fetchFn(`${API_URL}/app/installations/${github.installationId}/access_tokens`, {
 			method: "POST",

package/src/receiver.mjs

@@ -1,7 +1,8 @@
 /**
- * The webhook receiver: a thin producer that turns a verified GitHub webhook into (at most) one queued
+ * The webhook receiver: a thin producer that turns a verified forge webhook into (at most) one queued
  * job -- or, when the matched trigger opted into `run.replicas`, into exactly that many independent ones
- * (REQ-REPLICA-RUNS). It composes the three pieces that own the hard parts -- `makeVerifiedHandler` (the
+ * (REQ-REPLICA-RUNS, on every forge since #187; the poller stays github-only, so replicas on the other
+ * three arrive by webhook alone). It composes the three pieces that own the hard parts -- `makeVerifiedHandler` (the
  * HMAC trust boundary), `filter` (the trigger/author gate), and the SHARED `enqueueGitHubJob` -- and adds
  * only the glue: parse the verified body, project the payload subset, route on the filter's verdict, and
  * map the outcome to a status code.
@@ -169,6 +170,36 @@ function pathOf(url) {
 	return raw.length > 1 && raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
 
+/**
+ * REPLICA FANOUT (REQ-REPLICA-RUNS). The one place a single delivery becomes more than one job, shared by
+ * all four forge arms since #187 widened `run.replicas` past github.
+ *
+ * ONE body rather than four, for the reason `enqueueForgeJob` gives for collapsing its own wrappers
+ * (queue.mjs): four copies is four places for one of them to be quietly weakened while every test stays
+ * green. What would be weakened here is the `replicas > 1` conditional, whose whole job is byte-identity
+ * for an unflagged delivery -- spread `replica: i` unconditionally in one arm and that forge's `data`, its
+ * jobId and its dedup id all change for every ordinary job, with no test outside that forge to notice.
+ *
+ * Absent `replicas` is `1` and the call below is byte-identical to the single enqueue it replaced: no
+ * `replica` key on the job, so the jobId, the dedup id and `data` are exactly what they were.
+ *
+ * PARTIAL FAILURE IS IDEMPOTENT BY CONSTRUCTION, which is why there is no compensating logic here: if
+ * replica k throws, the caller's catch answers 503, the forge redelivers, replicas 1..k-1 dedup on their
+ * own now-taken jobIds and k..n enqueue. The retry converges on exactly n jobs rather than n + (k-1).
+ *
+ * `enqueue` is a callback because the four arms spell their enqueue differently (a named github/gitlab
+ * wrapper, or `enqueueForgeJob` with an explicit kind); the fanout itself is forge-blind.
+ *
+ * @returns {Promise<number>} how many jobs were enqueued, for the caller's `enqueued` log line.
+ */
+async function fanout(job, enqueue) {
+	const replicas = job.replicas ?? 1;
+	for (let i = 1; i <= replicas; i++) {
+		await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+	}
+	return replicas;
+}
+
 /**
  * The GitHub arm. Returns `makeVerifiedHandler`'s handler directly, so it only ever sees an already-verified
  * request. `onVerified` owns parse, filter, enqueue, and response; a good signature is the sole
@@ -189,19 +220,10 @@ function makeGitHubHandler({ queue, selfId, cfg, log }) {
 			return respond(res, 204);
 		}
 
-		// REPLICA FANOUT (REQ-REPLICA-RUNS). The one place a single delivery becomes more than one job, and it
-		// belongs here because this is where the 202/503 decision already lives. Absent `replicas` is `1` and
-		// the call below is byte-identical to the single enqueue it replaced -- no `replica` key on the job,
-		// so the jobId, the dedup id and `data` are all exactly what they were.
-		//
-		// PARTIAL FAILURE IS IDEMPOTENT BY CONSTRUCTION, which is why there is no compensating logic here: if
-		// replica k throws, the catch below answers 503, GitHub redelivers, replicas 1..k-1 dedup on their own
-		// now-taken jobIds and k..n enqueue. The retry converges on exactly n jobs rather than n + (k-1).
-		const replicas = result.job.replicas ?? 1;
+		// Fanout (REQ-REPLICA-RUNS) lives in `fanout` above; the 202/503 decision stays here, where it always was.
+		let replicas;
 		try {
-			for (let i = 1; i <= replicas; i++) {
-				await enqueueGitHubJob(queue, replicas > 1 ? { ...result.job, replica: i } : result.job);
-			}
+			replicas = await fanout(result.job, (j) => enqueueGitHubJob(queue, j));
 		} catch (err) {
 			// Own try/catch so a Valkey-down enqueue is a 503 (retryable), not verify's outer 500.
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
@@ -249,8 +271,9 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
 			return respond(res, 204);
 		}
 
+		let replicas;
 		try {
-			await enqueueGitLabJob(queue, result.job);
+			replicas = await fanout(result.job, (j) => enqueueGitLabJob(queue, j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // GitLab redelivers; dedup by webhook-id coalesces
@@ -259,7 +282,7 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
 		// `!` for a merge request, `#` for an issue -- GitLab's own notation, and the same discrimination
 		// the semantic dedup key makes, because the two are separate number sequences.
 		const sep = result.job.target.type === "pull_request" ? "!" : "#";
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow });
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, replicas });
 		return respond(res, 202, { status: "queued" });
 	});
 }
@@ -300,14 +323,15 @@ function makeForgejoHandler({ queue, cfg, log, secret, selfId, resolveAuthority
 			return respond(res, 204);
 		}
 
+		let replicas;
 		try {
-			await enqueueForgeJob(queue, "forgejo", result.job);
+			replicas = await fanout(result.job, (j) => enqueueForgeJob(queue, "forgejo", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // Forgejo redelivers; dedup by GUID coalesces
 		}
 
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow });
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
 		return respond(res, 202, { status: "queued" });
 	});
 }
@@ -357,8 +381,9 @@ function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, r
 			return respond(res, 204);
 		}
 
+		let replicas;
 		try {
-			await enqueueForgeJob(queue, "azure", result.job);
+			replicas = await fanout(result.job, (j) => enqueueForgeJob(queue, "azure", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" });
@@ -367,7 +392,7 @@ function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, r
 		// `!` for a pull request, `#` for a work item -- Azure numbers them separately, and this is the same
 		// discrimination the semantic dedup key makes.
 		const sep = result.job.target.type === "pull_request" ? "!" : "#";
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow });
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, replicas });
 		return respond(res, 202, { status: "queued" });
 	});
 }

package/src/start.mjs

@@ -28,6 +28,7 @@ import { watch } from "node:fs";
 import { dirname, basename } from "node:path";
 import { loadReceiverConfig, triggersFilePath, reloadTriggers } from "./config.mjs";
 import { makeReceiver } from "./receiver.mjs";
+import { entryExitCode } from "./cli.mjs";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { resolveGitLabSelfId } from "@edgehero/pi-dispatch/gitlab-identity";
 import { resolveForgejoSelfId } from "@edgehero/pi-dispatch/forgejo-identity";
@@ -192,6 +193,12 @@ function watchTriggers(env, cfg, log) {
 if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("start.mjs")) {
 	startReceiver(process.env).catch((err) => {
 		process.stderr.write(`${JSON.stringify({ event: "receiver_start_failed", reason: err?.message })}\n`);
-		process.exitCode = 1;
+		// entryExitCode, NOT a bare 1. This file is what `receiver.service` execs -- cli.mjs is not on that
+		// path -- so the mapping cli.mjs documents ("a supervisor restarting on exit 2 would loop on a config
+		// that can never parse") only reaches a real deployment from here. A tagged config refusal exits 2
+		// and `RestartPreventExitStatus=2` stops the unit; anything else is infra and stays retryable at 1.
+		// IMPORTED rather than restated: two copies of an exit-code rule is one place for it to drift, and
+		// the copy that drifts is the one nobody is looking at.
+		process.exitCode = entryExitCode(err);
 	});
 }