@edgehero/pi-dispatch-receiver 1.5.0 → 2.0.0

package/src/poller.mjs

@@ -108,13 +108,14 @@
 import { createSign } from "node:crypto";
 import { readFile as fsReadFile } from "node:fs/promises";
 import { configError } from "@edgehero/pi-dispatch/config";
-import { parseConnection } from "@edgehero/pi-dispatch/connection";
+import { judgeValkeyAtStart, makeRedisClient, parseConnection, valkeyClientContext } from "@edgehero/pi-dispatch/connection";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { enqueueGitHubJob, makeQueue } from "@edgehero/pi-dispatch/queue";
 import { filter, hasCloseTriggers, wantsCloserAuthority } from "./filter.mjs";
 import { makeResolveGitHubAuthority } from "./github-members.mjs";
 import { parseSubset } from "./receiver.mjs";
 import { loadPollerConfig } from "./poller-config.mjs";
+import { retryIdentity } from "./boot-retry.mjs";
 
 const API_URL = "https://api.github.com";
 // 35 days: strictly outlives the 31-day gh-* job retention -- see the header's cursor/TTL section.
@@ -153,9 +154,10 @@ class RateLimited extends Error {
  * Boot the poller: config, HARD-FAIL identity, repo set, then the cycle loop. Collaborators are
  * injected with real defaults (start.mjs's convention), so the whole producer is testable offline
  * with no GitHub, no Valkey, and no timers:
- *   { fetchFn, redis, queueFn, out, now, random, sleep, selfIdFn, tokenFn, fsDeps }
+ *   { fetchFn, redis, queueFn, out, now, random, sleep, signals, selfIdFn, tokenFn, fsDeps }
  * Returns `{ stop, done }`: `stop()` ends the loop after the in-flight work; `done` resolves once
- * owned connections are closed.
+ * owned connections are closed, with the inter-cycle default-sleep timer cleared by then (issue
+ * #325) -- after `done`, no timer armed by the poller remains.
  */
 export async function startPoller(env = process.env, deps = {}) {
 	const {
@@ -164,6 +166,12 @@ export async function startPoller(env = process.env, deps = {}) {
 		now = Date.now,
 		random = Math.random,
 		sleep,
+		// The signal gate, decoupled from the sleep default (issue #325): `sleep === undefined` used to
+		// double as the "real run" flag, which made the REAL default timer unarmable under test without
+		// also registering process-wide SIGTERM/SIGINT handlers -- the exact leak the gate exists to
+		// prevent. A test that arms the real sleep passes `signals: false`; the one production caller
+		// (cli.mjs, no deps) keeps handlers exactly as before through this default.
+		signals = sleep === undefined,
 		redis,
 		queueFn,
 		selfIdFn,
@@ -172,7 +180,11 @@ export async function startPoller(env = process.env, deps = {}) {
 		fsDeps = {},
 		makeAuth = makeGitHubAuth,
 		makeQueueFn = makeQueue,
+		// Issue #464 (gate round 3): how the poller builds its own Valkey client; a seam, so a test sees none built.
+		makeRedisFn = makeRedisClient,
 		makeResolveGitHubAuthority: makeResolveGitHubAuthorityFn = makeResolveGitHubAuthority,
+		// Issue #464 (gate round 3): the start-time judgement of VALKEY_URL, as the receiver's (start.mjs).
+		judgeValkey = (url, opts) => judgeValkeyAtStart(url, valkeyClientContext({ env: opts.env }), { now: opts.now, ...(opts.sleep ? { sleep: opts.sleep } : {}) }),
 	} = deps;
 
 	const cfg = loadPollerConfig(env, fsDeps);
@@ -181,9 +193,21 @@ export async function startPoller(env = process.env, deps = {}) {
 	// the bot-loop guard's sole input, and a poller running without it would read the harness's own
 	// completion comment next cycle and enqueue it -- an unbounded paid recursion, only slower than the
 	// webhook version. No try/catch: an unresolvable identity must prevent the loop from ever starting.
+	// A TRANSIENT failure retries in-process under the same window serve uses (issue #318): a
+	// pure-polling deployment loses work to a stopped process just as surely as a webhook one.
+	//
+	// The default sleep sits above the gate because the gate sleeps too (issue #318); the boot retry
+	// simply awaits its cancellable promise to completion, so `cancel` is the LOOP's concern alone.
+	const sleepFn = sleep ?? cancellableSleep;
 	let auth = null;
+	// `auth ??= await ...` assigns only when the mint RESOLVES, so a retried getAuth re-invokes
+	// makeAuth. Caching the PROMISE instead would memoize the first failure and turn the retry loop
+	// into a rethrow spinner -- pinned by the poller's retry test.
 	const getAuth = async () => (auth ??= await makeAuth(cfg.github));
-	const selfId = selfIdFn ? await selfIdFn(cfg.github) : (await getAuth()).selfId;
+	const selfId = await retryIdentity(
+		() => (selfIdFn ? selfIdFn(cfg.github) : getAuth().then((a) => a.selfId)),
+		{ forge: "github", windowMs: cfg.identityRetryWindowMs, log: out, now, sleep: sleepFn },
+	);
 	out({ event: "self_identity", id: selfId, source: cfg.github.source });
 
 	// The polling credential comes from the same auth config the worker validates. pat/gh hand back
@@ -210,9 +234,12 @@ export async function startPoller(env = process.env, deps = {}) {
 	// queue connection: a long-running producer should survive a Valkey restart.
 	let redisClient = redis ?? null;
 	let ownRedis = false;
+	// Issue #464 (gate round 3): judged before this process builds its own Valkey clients: a refusal exits 2, nothing
+	// answering for 20 s exits 1, never a poller running on a queue that cannot connect.
+	if (redisClient === null || queueFn === undefined || queueFn === null) await judgeValkey(cfg.valkeyUrl, { env, now, sleep });
 	if (redisClient === null) {
-		const { default: Redis } = await import("ioredis");
-		redisClient = new Redis(cfg.valkeyUrl);
+		// Through connection.mjs, as every Valkey client of this project (issue #464): it judges and pins the address.
+		redisClient = makeRedisFn(cfg.valkeyUrl);
 		ownRedis = true;
 	}
 
@@ -263,7 +290,6 @@ export async function startPoller(env = process.env, deps = {}) {
 		stopped = true;
 		wake();
 	};
-	const sleepFn = sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
 
 	const done = (async () => {
 		let cycleNo = 0;
@@ -328,14 +354,27 @@ export async function startPoller(env = process.env, deps = {}) {
 			// in one synchronized stampede).
 			let delayMs = Math.max(cfg.intervalSeconds, stats.minDelaySeconds) * 1000;
 			if (rateResetMs !== null) delayMs = Math.max(delayMs, rateResetMs - now() + jitterMs(random));
-			await Promise.race([sleepFn(delayMs), stopWaker]);
+			// Hold the sleep so the LOSER can be cleared: when stop() wins this race, an uncancelled
+			// default timer stays armed for up to a full poll interval after `done` resolves (issue
+			// #325) -- masked in production by the signal handler's process.exit(0) below, and real for
+			// every caller that stops the poller without exiting. Optional-chained because injected
+			// test sleeps are plain promises carrying no cancel; their call count and arguments are
+			// untouched, and a rejecting one still propagates through the finally.
+			const nap = sleepFn(delayMs);
+			try {
+				await Promise.race([nap, stopWaker]);
+			} finally {
+				nap.cancel?.();
+			}
 		}
 		await closeOwned();
 	})();
 
-	// Signal handlers only on a real run (no injected sleep) -- start.mjs's rule, same reason: under
-	// test injection the fakes are per-test, and a process-wide handler would leak across tests.
-	if (sleep === undefined) {
+	// Signal handlers only on a real run (`signals`, defaulting from the sleep seam) -- start.mjs's
+	// rule, same reason: under test injection the fakes are per-test, and a process-wide handler would
+	// leak across tests. Its own seam since issue #325, so a test can arm the REAL default sleep
+	// without inheriting the handlers.
+	if (signals) {
 		const shutdown = async (signal) => {
 			out({ event: "poller_stopping", signal });
 			stop();
@@ -358,6 +397,27 @@ function jitterMs(random) {
 	return 1_000 + Math.floor(random() * 29_000);
 }
 
+/**
+ * The default inter-cycle sleep: a REF'D setTimeout whose promise carries its own `cancel` (issue
+ * #325). Ref'd deliberately -- the poller IS its process's main loop and holding the loop through the
+ * delay is the point (`DES-RETENTION-SWEEPS-ON-A-TIMER`'s rejected list records the contrast; between
+ * cycles this timer is the only thing keeping a pure-poll process alive, cli.mjs's "awaiting done").
+ * The defect was never the ref, only survival past stop(): "unref'd is not cleaned up" has a ref'd
+ * twin, a cleared-nothing timer that holds the loop for up to a full interval after `done` resolved.
+ * A cancelled sleep never resolves, which is safe here because its only awaiter is a race `stopWaker`
+ * has already settled, and cancel on an already-fired timer is a no-op, so the winning side's clear
+ * costs nothing. EXPORTED for `settleWithin`'s reason (worker/src/start.mjs): the cleared-timer
+ * guarantee deserves a deterministic async_hooks pin on the helper, not a census of a full boot.
+ */
+export function cancellableSleep(ms) {
+	let timer;
+	const p = new Promise((resolve) => {
+		timer = setTimeout(resolve, ms);
+	});
+	p.cancel = () => clearTimeout(timer);
+	return p;
+}
+
 /** The redis key family for one repo -- see the schema table in the module header. */
 function keyNames(repo) {
 	const p = `poll:${repo}`;
@@ -916,11 +976,20 @@ async function gate(ctx, eventName, payload, deliveryId, stats) {
 		return;
 	}
 	const replicas = result.job.replicas ?? 1;
+	let created = 0;
 	for (let i = 1; i <= replicas; i++) {
-		await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		const r = await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		// Issue #289, the receiver arms' honesty rule at the poller's own seam: a semantic-window swallow
+		// gets its own line with the surviving id, `enqueued` counts only what was CREATED, and a bare-id
+		// return from an enqueue seam predating the shape counts as created -- the old behaviour exactly.
+		if (r && typeof r === "object" && r.deduplicated === true) {
+			ctx.out({ event: "deduplicated", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, jobId: r.jobId, survivingJobId: r.survivingJobId });
+		} else {
+			created += 1;
+		}
 	}
-	stats.enqueued += replicas;
-	ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
+	stats.enqueued += created;
+	if (created > 0) ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas: created });
 }
 
 /**

package/src/receiver.mjs

@@ -205,14 +205,43 @@ function pathOf(url) {
  * `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.
+ * @returns {Promise<{replicas: number, created: number, deduplicated: Array<{jobId, survivingJobId}>}>}
+ *   what actually happened, per replica (issue #289): `created` counts jobs that now EXIST because of
+ *   this delivery, and `deduplicated` carries each swallow the semantic window made, with the id that
+ *   survived. A bare-id return from an enqueue that predates the shape counts as created -- the old
+ *   behaviour exactly.
  */
 async function fanout(job, enqueue) {
 	const replicas = job.replicas ?? 1;
+	let created = 0;
+	const deduplicated = [];
 	for (let i = 1; i <= replicas; i++) {
-		await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+		const r = await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+		if (r && typeof r === "object" && r.deduplicated === true) deduplicated.push({ jobId: r.jobId, survivingJobId: r.survivingJobId });
+		else created += 1;
 	}
-	return replicas;
+	return { replicas, created, deduplicated };
+}
+
+/**
+ * One log-and-answer for a fanout outcome, shared by all four arms so a weakened copy cannot hide (the
+ * four-copies doctrine above). Issue #289's honesty rule: `enqueued` is logged only when something was
+ * CREATED, with `replicas` meaning jobs that now exist; every semantic-window swallow gets its own
+ * `deduplicated` line naming the surviving job's id (every field forge- or worker-minted, no payload
+ * text); and a delivery that created NOTHING answers `202 {status:"deduplicated"}` -- still a 2xx,
+ * because a non-2xx would trigger a redelivery storm for a delivery that was handled, but no longer
+ * "queued", because a receiver that logs the swallow while answering success on the wire would be the
+ * honest-log/lying-wire split this project refuses. Each arm passes its own target grammar.
+ */
+function respondEnqueueOutcome({ log, res, delivery, repo, target, flow, outcome }) {
+	for (const d of outcome.deduplicated) {
+		log?.({ event: "deduplicated", delivery, repo, target, flow, jobId: d.jobId, survivingJobId: d.survivingJobId });
+	}
+	if (outcome.created > 0) {
+		log?.({ event: "enqueued", delivery, repo, target, flow, replicas: outcome.created });
+		return respond(res, 202, { status: "queued" });
+	}
+	return respond(res, 202, { status: "deduplicated" });
 }
 
 /**
@@ -266,17 +295,16 @@ function makeGitHubHandler({ queue, routeTo, selfId, cfg, log, resolveAuthority
 		}
 
 		// Fanout (REQ-REPLICA-RUNS) lives in `fanout` above; the 202/503 decision stays here, where it always was.
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueGitHubJob(await routeTo("github", j), j));
+			outcome = await fanout(result.job, async (j) => await enqueueGitHubJob(await routeTo("github", j), 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 });
 			return respond(res, 503, { error: "enqueue-failed" }); // GitHub 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, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -316,9 +344,9 @@ function makeGitLabHandler({ routeTo, queue, cfg, log, mode, secret, selfId, res
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueGitLabJob(await routeTo("gitlab", j), j));
+			outcome = await fanout(result.job, async (j) => await enqueueGitLabJob(await routeTo("gitlab", j), 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
@@ -327,8 +355,7 @@ function makeGitLabHandler({ routeTo, queue, cfg, log, mode, secret, selfId, res
 		// `!` 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, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -368,16 +395,15 @@ function makeForgejoHandler({ routeTo, queue, cfg, log, secret, selfId, resolveA
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("forgejo", j), "forgejo", j));
+			outcome = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("forgejo", j), "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, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -426,9 +452,9 @@ function makeAzureHandler({ routeTo, queue, cfg, log, mode, secret, headerName,
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("azure", j), "azure", j));
+			outcome = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("azure", j), "azure", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" });
@@ -437,7 +463,6 @@ function makeAzureHandler({ routeTo, queue, cfg, log, mode, secret, headerName,
 		// `!` 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, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }