@pithy-sh/cloudflare 0.1.2 → 0.1.3

package/dist/test-utils/harness.d.ts

@@ -0,0 +1,192 @@
+import { R2Credentials } from "../r2/r2Credentials";
+/**
+ * The live-suite credentials: this package's own `.dev.vars`, then `process.env` per key for anything it
+ * did not set. The `.dev.vars` half is why this is here rather than in `../env/devVars` — nothing outside
+ * a live test reads a `.dev.vars` for credentials now, and a shared function that still did would be an
+ * invitation to point a command back at the checkout.
+ *
+ * Exported for `fixtures.ts`, which resolves the whole fixture estate against the same pair. Two readers
+ * of two files is how a suite and its own report come to disagree about what this run has.
+ */
+export declare function loadIntegrationEnv(): Record<string, string>;
+/** Cloudflare credentials for a live run, plus whether enough of them are present to run at all. */
+export interface IntegrationCreds {
+    /** The target account id (`CLOUDFLARE_ACCOUNT_ID`). Empty string when unset. */
+    accountId: string;
+    /** The scoped API token (`CLOUDFLARE_API_TOKEN`). Empty string when unset. */
+    apiToken: string;
+    /** The Secrets Store id (`SECRETS_STORE_ID`), for the secrets-store live test. Empty string when unset. */
+    secretsStoreId: string;
+    /** R2 S3 keys (from `R2_CREDENTIALS` JSON), for the R2 presigned-URL test. Null when unset. */
+    r2: R2Credentials | null;
+    /** True only when both an account id and a token are present — the gate for `describe.skipIf`. */
+    hasCreds: boolean;
+}
+/**
+ * Parse the `R2_CREDENTIALS` JSON blob through the canonical {@link R2Credentials} schema — the same
+ * object the R2 storage feature manages as a JSON payload, so the harness and the feature validate it
+ * identically. Returns null when unset (the R2 suite then skips); a set-but-malformed/invalid blob
+ * fails `.parse()` and throws, surfacing the misconfiguration loudly rather than silently skipping.
+ */
+export declare function parseR2Creds(raw: string | undefined): R2Credentials | null;
+/**
+ * Load the live-CF credentials a `*.integration.test.ts` needs, reading the package `.dev.vars` and
+ * overlaying `process.env` (the loader's own fallback, so CI passes them as plain env vars). Gate the
+ * suite with `describe.skipIf(!loadIntegrationCreds().hasCreds)` so it skips cleanly with no creds.
+ */
+export declare function loadIntegrationCreds(): IntegrationCreds;
+/**
+ * The project name a live test provisions under, so that names composed by the *product's* provisioners —
+ * `<project>-<env>-<thing>`, where the project segment is verbatim and first — land inside the reservation
+ * too. A live test of `pithy provision --feature` cannot route through {@link uniqueName}: the names are the
+ * thing under test. Giving it a reserved project puts them in the namespace anyway.
+ *
+ * The reservation itself is {@link RESERVED_TEST_PREFIX}, in `@pithy-sh/core`. It lives beside the name
+ * composer because both sides of it are naming facts: this harness mints inside it, and `scaffoldProject`
+ * refuses to mint a project that would land in it. One literal, or the two drift apart.
+ */
+export declare const RESERVED_TEST_PROJECT = "pithy-int-test";
+/**
+ * The compatibility date every throwaway Worker a live suite uploads runs on.
+ *
+ * `createWorker` has no default any more (#396): a compatibility date is a behavior contract in
+ * somebody's account, so the caller names it. That makes every live suite a caller, and one place for
+ * them to read it from is the difference between one date and six.
+ *
+ * **It is stated rather than imported, and the reason is a wall rather than a preference.** The floor
+ * lives in `compatibility.ts` at the repository root, and this package's `rootDir` is `src` — a static
+ * import of a file above it is TS6059, the same wall `compatibilityDates.test.ts` records for
+ * `packages/cli`. So this is a fixture stating a date, which is the one shape that gate excludes on
+ * purpose. Keep it level with the floor when the floor moves.
+ */
+export declare const INTEGRATION_COMPATIBILITY_DATE = "2026-06-01";
+/**
+ * Mint a collision-proof name for a throwaway live resource:
+ * `pithy-int-<label>-<timestamp>-<counter>-<rand>`.
+ *
+ * The caller supplies only the distinguishing part — {@link RESERVED_TEST_PREFIX} is composed on, never
+ * passed in. That is the point: when the prefix was a *default* a caller could override, a suite could
+ * silently create resources under a name the reaper does not recognize, which is exactly how orphans
+ * came to sit on a real account. A label that already carries the prefix is refused rather than doubled.
+ *
+ * The 6-char random suffix guarantees uniqueness across separate test files (Vitest isolates each file, so
+ * the counter only deduplicates within one); the timestamp is what {@link testResourceAge} reads, so every
+ * name this mints is reapable by construction. The label is kebabbed and fitted, so the result always
+ * stays inside R2's {@link MAX_RESOURCE_NAME} cap and the lowercase `a-z0-9-` charset every CF namespace
+ * accepts, whatever the caller passed.
+ */
+export declare function uniqueName(label: string): string;
+/**
+ * Create a live resource, exercise it, and guarantee teardown — even if `exercise` throws. This is the
+ * spine of every live integration test: a failed assertion must never orphan a real Cloudflare resource.
+ * `create` runs outside the `try`, so a creation failure does not call `teardown` on something that was
+ * never created; once `create` resolves, `teardown` always runs in the `finally`. The exercise result is
+ * returned for the rare caller that wants it.
+ */
+export declare function withThrowawayResource<R, T>(create: () => Promise<R>, exercise: (resource: R) => Promise<T>, teardown: (resource: R) => Promise<void>): Promise<T>;
+/**
+ * Create a live resource **at a name the caller already chose**, exercise it, and guarantee teardown —
+ * including when `create` itself rejects.
+ *
+ * {@link withThrowawayResource} runs `create` outside the `try` on purpose: for a kind whose id only
+ * exists once creation succeeds, tearing down a failed create would be tearing down nothing. But a whole
+ * family of Cloudflare calls are **named writes** — `putSecret(name, …)`, `createBucket(name)`,
+ * `createDatabase(name)`, `createWorker(name)` — where the address is the caller's own argument. There a
+ * rejection is ambiguous: the server may have accepted the write and failed on the way back, and the
+ * resource now exists under a name the test is still holding. `withThrowawayResource` walks away from it.
+ *
+ * This variant tears down on the **name**, and arms the teardown before `create` is ever called, so the
+ * ambiguous case cleans up. `teardown` must therefore tolerate a resource that was never created — every
+ * caller here passes an idempotent delete, and the reaper is the backstop if one is not.
+ */
+export declare function withNamedResource<T>(name: string, create: (name: string) => Promise<unknown>, exercise: (name: string) => Promise<T>, teardown: (name: string) => Promise<void>): Promise<T>;
+/**
+ * How old a resource must be before a reaper will remove it.
+ *
+ * **Twelve hours, and the size is the safety argument.** Reaping is a race with any suite that is still
+ * running: a resource deleted mid-flight surfaces as an unexplained 404 in a test that was passing, which
+ * is a far worse failure than debris. Cloudflare offers no way to mark a D1, KV namespace, bucket, or
+ * index as owned by a live process — no lease, no tag our client can set on every kind — so the only
+ * defense available is a window nothing plausible can cross.
+ *
+ * A single live test is capped at 120s and a hook at 120s (`vitest.integration.config.ts`); a whole
+ * package's suite is minutes, and every package's suites together are well under an hour even when
+ * Vectorize is settling. Twelve hours is two orders of magnitude past that, and still short enough that
+ * debris never survives a day. The cost of the wider window is a handful of orphans lingering longer;
+ * the cost of the narrower one is a green suite turned red by its own housekeeping.
+ */
+export declare const DEFAULT_STALE_AFTER_MS: number;
+/**
+ * The ms-epoch {@link uniqueName} embedded, or `null` if this is not one of our names.
+ *
+ * `uniqueName` composes `pithy-int-<label>-<epoch>-<counter>-<rand>`, so the timestamp is the third
+ * segment from the end. Anything that does not match that shape returns `null` and is therefore never
+ * reaped — including a name inside the reservation that some *other* generator produced, such as a
+ * feature resource provisioned under {@link RESERVED_TEST_PROJECT}. Conservative on purpose: failing to
+ * clean up costs pennies, deleting someone's data does not.
+ */
+export declare function testResourceAge(name: string, now: number): number | null;
+/**
+ * Which of these names are stale test debris — ours, and old enough that no running suite owns them.
+ *
+ * Pure, so the age arithmetic is unit-tested without touching Cloudflare.
+ */
+export declare function staleTestResourceNames(names: readonly string[], options?: {
+    now?: number;
+    staleAfterMs?: number;
+}): string[];
+/** One reapable resource kind: what it is called, how to list it, and how to remove one. */
+export interface ReapableKind {
+    /** Human label for the reap log, e.g. "Vectorize index". */
+    label: string;
+    /** Every resource name of this kind currently in the account. */
+    list: () => Promise<string[]>;
+    /** Remove one by name. Must be idempotent — another runner may have reaped it first. */
+    remove: (name: string) => Promise<void>;
+}
+/**
+ * Remove stale throwaway resources of one kind, and report what went.
+ *
+ * `withThrowawayResource` guarantees teardown only while the process lives. A run killed by a test
+ * timeout, a Ctrl-C, or a crash orphans whatever it had created — which is exactly how two Vectorize
+ * indexes came to sit on a real account for a month. Calling this in a suite's `beforeAll` makes each
+ * run clean up after the last one, so the failure mode self-heals instead of accumulating.
+ *
+ * Never throws: a reaper that fails must not fail the suite it is trying to help. Failures are reported
+ * in the returned list of what could not be removed.
+ */
+export declare function reapStaleTestResources(kind: ReapableKind, options?: {
+    now?: number;
+    staleAfterMs?: number;
+}): Promise<{
+    reaped: string[];
+    failed: string[];
+}>;
+/**
+ * Empty a throwaway bucket so R2 will delete it.
+ *
+ * Two things hold a bucket against deletion: stored objects, and the parts of a multipart upload that was
+ * never completed or aborted — precisely what a test that failed mid-upload leaves behind. Both are
+ * cleared, dangling uploads first. Every page is drained, so a bucket with more than a thousand keys is
+ * emptied rather than half-emptied.
+ *
+ * Throws when the S3 key pair is absent: a bucket that cannot be emptied cannot be deleted, and silence
+ * there is how debris becomes permanent.
+ */
+export declare function emptyTestBucket(creds: IntegrationCreds, bucketName: string): Promise<void>;
+/**
+ * Reclaim stale throwaway R2 buckets — the one kind that needs more than an API token, so it lives here
+ * once instead of being re-derived by every suite that makes a bucket.
+ *
+ * Without `R2_CREDENTIALS` this reaps nothing and says so loudly rather than failing quietly: the buckets
+ * are still there, still cost money, and the only fix is the key pair. Never throws — a reaper must not
+ * fail the suite it is trying to help.
+ */
+export declare function reapStaleTestBuckets(creds: IntegrationCreds, options?: {
+    now?: number;
+    staleAfterMs?: number;
+}): Promise<{
+    reaped: string[];
+    failed: string[];
+}>;
+//# sourceMappingURL=harness.d.ts.map

package/dist/test-utils/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/test-utils/harness.ts"],"names":[],"mappings":"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"}

package/dist/test-utils/harness.js

@@ -0,0 +1,351 @@
+import { R2Credentials } from "../r2/r2Credentials.js";
+import { CloudflareClients } from "../client/clients.js";
+import { CLOUDFLARE_ENV_KEYS, parseDevVars } from "../env/devVars.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { AbortMultipartUploadCommand, DeleteObjectCommand, ListMultipartUploadsCommand, ListObjectsV2Command, S3Client } from "@aws-sdk/client-s3";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_RESOURCE_NAME, RESERVED_TEST_PREFIX, fitSegment, kebab } from "@pithy-sh/core/src/naming/resource";
+//#region src/test-utils/harness.ts
+/**
+* Shared scaffolding for the package's `*.integration.test.ts` live suites. Every live test does the
+* same three things — find credentials, create a throwaway resource, and guarantee it is torn down —
+* so that logic lives here once instead of being re-derived per manager. Generalized from the D1
+* provisioner's first live test; see `README.md` § "Live integration tests" for the template.
+*/
+/**
+* **This** package's root, whichever package's live suite is running — `@pithy-sh/storage` imports this
+* harness, so its credentials come from `packages/cloudflare/.dev.vars` too, and a `.dev.vars` beside the
+* importing package is read by nothing. See `README.md` § "Live integration tests".
+*
+* Nothing creates that file, and nothing in the CLI reads one any more — adopter credentials moved to
+* the account-scoped `<config>/cloudflare.json` (#182), and this package cannot resolve that directory
+* without a second implementation of where Pithy's config lives. So this stays a **maintainer-authored
+* file for the live suites and nothing else**: no command writes it, no adopter has one, and it holds
+* whatever account the person running `test:integration` wants the throwaway resources created in.
+* Write it by hand, or export the keys — {@link loadIntegrationEnv} overlays `process.env` per key for
+* anything the file does not set, which is how CI runs with no file at all.
+*/
+const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "../..");
+/**
+* The live-suite credentials: this package's own `.dev.vars`, then `process.env` per key for anything it
+* did not set. The `.dev.vars` half is why this is here rather than in `../env/devVars` — nothing outside
+* a live test reads a `.dev.vars` for credentials now, and a shared function that still did would be an
+* invitation to point a command back at the checkout.
+*
+* Exported for `fixtures.ts`, which resolves the whole fixture estate against the same pair. Two readers
+* of two files is how a suite and its own report come to disagree about what this run has.
+*/
+function loadIntegrationEnv() {
+	let vars = {};
+	try {
+		vars = parseDevVars(readFileSync(path.join(PACKAGE_ROOT, ".dev.vars"), "utf8"));
+	} catch {}
+	for (const key of CLOUDFLARE_ENV_KEYS) {
+		const fromEnv = process.env[key];
+		if (!vars[key] && fromEnv) vars[key] = fromEnv;
+	}
+	return vars;
+}
+/**
+* Parse the `R2_CREDENTIALS` JSON blob through the canonical {@link R2Credentials} schema — the same
+* object the R2 storage feature manages as a JSON payload, so the harness and the feature validate it
+* identically. Returns null when unset (the R2 suite then skips); a set-but-malformed/invalid blob
+* fails `.parse()` and throws, surfacing the misconfiguration loudly rather than silently skipping.
+*/
+function parseR2Creds(raw) {
+	if (!raw) return null;
+	return R2Credentials.parse(JSON.parse(raw));
+}
+/**
+* Load the live-CF credentials a `*.integration.test.ts` needs, reading the package `.dev.vars` and
+* overlaying `process.env` (the loader's own fallback, so CI passes them as plain env vars). Gate the
+* suite with `describe.skipIf(!loadIntegrationCreds().hasCreds)` so it skips cleanly with no creds.
+*/
+function loadIntegrationCreds() {
+	const vars = loadIntegrationEnv();
+	const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+	const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+	return {
+		accountId,
+		apiToken,
+		secretsStoreId: vars.SECRETS_STORE_ID ?? "",
+		r2: parseR2Creds(vars.R2_CREDENTIALS),
+		hasCreds: Boolean(accountId && apiToken)
+	};
+}
+/**
+* The project name a live test provisions under, so that names composed by the *product's* provisioners —
+* `<project>-<env>-<thing>`, where the project segment is verbatim and first — land inside the reservation
+* too. A live test of `pithy provision --feature` cannot route through {@link uniqueName}: the names are the
+* thing under test. Giving it a reserved project puts them in the namespace anyway.
+*
+* The reservation itself is {@link RESERVED_TEST_PREFIX}, in `@pithy-sh/core`. It lives beside the name
+* composer because both sides of it are naming facts: this harness mints inside it, and `scaffoldProject`
+* refuses to mint a project that would land in it. One literal, or the two drift apart.
+*/
+const RESERVED_TEST_PROJECT = `${RESERVED_TEST_PREFIX}test`;
+/**
+* The compatibility date every throwaway Worker a live suite uploads runs on.
+*
+* `createWorker` has no default any more (#396): a compatibility date is a behavior contract in
+* somebody's account, so the caller names it. That makes every live suite a caller, and one place for
+* them to read it from is the difference between one date and six.
+*
+* **It is stated rather than imported, and the reason is a wall rather than a preference.** The floor
+* lives in `compatibility.ts` at the repository root, and this package's `rootDir` is `src` — a static
+* import of a file above it is TS6059, the same wall `compatibilityDates.test.ts` records for
+* `packages/cli`. So this is a fixture stating a date, which is the one shape that gate excludes on
+* purpose. Keep it level with the floor when the floor moves.
+*/
+const INTEGRATION_COMPATIBILITY_DATE = "2026-06-01";
+/** Deduplicates names minted within one test file; the random suffix covers the cross-file case. */
+let nameCounter = 0;
+/**
+* Mint a collision-proof name for a throwaway live resource:
+* `pithy-int-<label>-<timestamp>-<counter>-<rand>`.
+*
+* The caller supplies only the distinguishing part — {@link RESERVED_TEST_PREFIX} is composed on, never
+* passed in. That is the point: when the prefix was a *default* a caller could override, a suite could
+* silently create resources under a name the reaper does not recognize, which is exactly how orphans
+* came to sit on a real account. A label that already carries the prefix is refused rather than doubled.
+*
+* The 6-char random suffix guarantees uniqueness across separate test files (Vitest isolates each file, so
+* the counter only deduplicates within one); the timestamp is what {@link testResourceAge} reads, so every
+* name this mints is reapable by construction. The label is kebabbed and fitted, so the result always
+* stays inside R2's {@link MAX_RESOURCE_NAME} cap and the lowercase `a-z0-9-` charset every CF namespace
+* accepts, whatever the caller passed.
+*/
+function uniqueName(label) {
+	const segment = kebab(label);
+	if (!segment) throw new ValidationError({
+		message: "A throwaway resource needs a label.",
+		action: "Pass a short label, e.g. uniqueName('kv').",
+		detail: `uniqueName received ${JSON.stringify(label)}, which kebabs to nothing.`
+	});
+	if (segment.startsWith(RESERVED_TEST_PREFIX)) throw new ValidationError({
+		message: `A throwaway label must not repeat the reserved "${RESERVED_TEST_PREFIX}" prefix.`,
+		action: `Pass only the distinguishing part, e.g. uniqueName('${segment.slice(RESERVED_TEST_PREFIX.length) || "kv"}').`,
+		detail: `uniqueName composes ${RESERVED_TEST_PREFIX} itself; ${JSON.stringify(label)} would double it.`
+	});
+	nameCounter += 1;
+	const rand = Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+	const suffix = `-${Date.now()}-${nameCounter}-${rand}`;
+	const budget = MAX_RESOURCE_NAME - RESERVED_TEST_PREFIX.length - suffix.length;
+	return `${RESERVED_TEST_PREFIX}${fitSegment(segment, budget)}${suffix}`;
+}
+/**
+* Create a live resource, exercise it, and guarantee teardown — even if `exercise` throws. This is the
+* spine of every live integration test: a failed assertion must never orphan a real Cloudflare resource.
+* `create` runs outside the `try`, so a creation failure does not call `teardown` on something that was
+* never created; once `create` resolves, `teardown` always runs in the `finally`. The exercise result is
+* returned for the rare caller that wants it.
+*/
+async function withThrowawayResource(create, exercise, teardown) {
+	const resource = await create();
+	try {
+		return await exercise(resource);
+	} finally {
+		await teardown(resource);
+	}
+}
+/**
+* Create a live resource **at a name the caller already chose**, exercise it, and guarantee teardown —
+* including when `create` itself rejects.
+*
+* {@link withThrowawayResource} runs `create` outside the `try` on purpose: for a kind whose id only
+* exists once creation succeeds, tearing down a failed create would be tearing down nothing. But a whole
+* family of Cloudflare calls are **named writes** — `putSecret(name, …)`, `createBucket(name)`,
+* `createDatabase(name)`, `createWorker(name)` — where the address is the caller's own argument. There a
+* rejection is ambiguous: the server may have accepted the write and failed on the way back, and the
+* resource now exists under a name the test is still holding. `withThrowawayResource` walks away from it.
+*
+* This variant tears down on the **name**, and arms the teardown before `create` is ever called, so the
+* ambiguous case cleans up. `teardown` must therefore tolerate a resource that was never created — every
+* caller here passes an idempotent delete, and the reaper is the backstop if one is not.
+*/
+async function withNamedResource(name, create, exercise, teardown) {
+	try {
+		await create(name);
+		return await exercise(name);
+	} finally {
+		await teardown(name);
+	}
+}
+/**
+* How old a resource must be before a reaper will remove it.
+*
+* **Twelve hours, and the size is the safety argument.** Reaping is a race with any suite that is still
+* running: a resource deleted mid-flight surfaces as an unexplained 404 in a test that was passing, which
+* is a far worse failure than debris. Cloudflare offers no way to mark a D1, KV namespace, bucket, or
+* index as owned by a live process — no lease, no tag our client can set on every kind — so the only
+* defense available is a window nothing plausible can cross.
+*
+* A single live test is capped at 120s and a hook at 120s (`vitest.integration.config.ts`); a whole
+* package's suite is minutes, and every package's suites together are well under an hour even when
+* Vectorize is settling. Twelve hours is two orders of magnitude past that, and still short enough that
+* debris never survives a day. The cost of the wider window is a handful of orphans lingering longer;
+* the cost of the narrower one is a green suite turned red by its own housekeeping.
+*/
+const DEFAULT_STALE_AFTER_MS = 432e5;
+/**
+* The ms-epoch {@link uniqueName} embedded, or `null` if this is not one of our names.
+*
+* `uniqueName` composes `pithy-int-<label>-<epoch>-<counter>-<rand>`, so the timestamp is the third
+* segment from the end. Anything that does not match that shape returns `null` and is therefore never
+* reaped — including a name inside the reservation that some *other* generator produced, such as a
+* feature resource provisioned under {@link RESERVED_TEST_PROJECT}. Conservative on purpose: failing to
+* clean up costs pennies, deleting someone's data does not.
+*/
+function testResourceAge(name, now) {
+	if (!name.startsWith(RESERVED_TEST_PREFIX)) return null;
+	const segments = name.split("-");
+	if (segments.length < 3) return null;
+	const stamp = Number(segments[segments.length - 3]);
+	if (!Number.isInteger(stamp) || stamp <= 0 || stamp > now) return null;
+	return now - stamp;
+}
+/**
+* Which of these names are stale test debris — ours, and old enough that no running suite owns them.
+*
+* Pure, so the age arithmetic is unit-tested without touching Cloudflare.
+*/
+function staleTestResourceNames(names, options = {}) {
+	const now = options.now ?? Date.now();
+	const staleAfterMs = options.staleAfterMs ?? 432e5;
+	return names.filter((name) => {
+		const age = testResourceAge(name, now);
+		return age !== null && age >= staleAfterMs;
+	});
+}
+/**
+* Remove stale throwaway resources of one kind, and report what went.
+*
+* `withThrowawayResource` guarantees teardown only while the process lives. A run killed by a test
+* timeout, a Ctrl-C, or a crash orphans whatever it had created — which is exactly how two Vectorize
+* indexes came to sit on a real account for a month. Calling this in a suite's `beforeAll` makes each
+* run clean up after the last one, so the failure mode self-heals instead of accumulating.
+*
+* Never throws: a reaper that fails must not fail the suite it is trying to help. Failures are reported
+* in the returned list of what could not be removed.
+*/
+async function reapStaleTestResources(kind, options = {}) {
+	const reaped = [];
+	const failed = [];
+	let names;
+	try {
+		names = await kind.list();
+	} catch {
+		return {
+			reaped,
+			failed
+		};
+	}
+	for (const name of staleTestResourceNames(names, options)) try {
+		await kind.remove(name);
+		reaped.push(name);
+	} catch {
+		failed.push(name);
+	}
+	if (reaped.length > 0) console.warn(`reaped ${reaped.length} stale ${kind.label}(s): ${reaped.join(", ")}`);
+	if (failed.length > 0) console.warn(`could not reap ${failed.length} stale ${kind.label}(s): ${failed.join(", ")}`);
+	return {
+		reaped,
+		failed
+	};
+}
+/**
+* An S3 client for the account's R2, built from the harness's own key pair.
+*
+* **R2 is the one kind the API token cannot reap.** Cloudflare refuses to delete a non-empty bucket, and
+* emptying one is an S3-protocol operation — `ListObjectsV2`, `DeleteObject`, `AbortMultipartUpload` —
+* that the REST API does not offer and a scoped API token cannot authenticate. So the harness holds the
+* S3 credentials itself: {@link IntegrationCreds.r2}, parsed from `R2_CREDENTIALS`, is what makes a
+* throwaway bucket reclaimable at all.
+*
+* Raw S3 rather than `CloudflareR2Manager` on purpose. This is teardown, and teardown must not depend on
+* the code under test: if `emptyBucket` is the thing that broke, the bucket still has to come back empty
+* or a failing test leaks a real resource instead of reporting a bug.
+*/
+function testS3(creds) {
+	if (!creds.r2) throw new ValidationError({
+		message: "Emptying an R2 bucket needs the S3 key pair.",
+		action: "Set R2_CREDENTIALS in .dev.vars, or gate the suite on `creds.r2`.",
+		detail: "R2 refuses to delete a non-empty bucket, and draining one is an S3 operation, not a REST one."
+	});
+	return new S3Client({
+		region: "auto",
+		endpoint: `https://${creds.accountId}.r2.cloudflarestorage.com`,
+		credentials: {
+			accessKeyId: creds.r2.accessKeyId,
+			secretAccessKey: creds.r2.secretAccessKey
+		}
+	});
+}
+/**
+* Empty a throwaway bucket so R2 will delete it.
+*
+* Two things hold a bucket against deletion: stored objects, and the parts of a multipart upload that was
+* never completed or aborted — precisely what a test that failed mid-upload leaves behind. Both are
+* cleared, dangling uploads first. Every page is drained, so a bucket with more than a thousand keys is
+* emptied rather than half-emptied.
+*
+* Throws when the S3 key pair is absent: a bucket that cannot be emptied cannot be deleted, and silence
+* there is how debris becomes permanent.
+*/
+async function emptyTestBucket(creds, bucketName) {
+	const s3 = testS3(creds);
+	const uploads = await s3.send(new ListMultipartUploadsCommand({ Bucket: bucketName }));
+	for (const upload of uploads.Uploads ?? []) {
+		if (!upload.Key || !upload.UploadId) continue;
+		await s3.send(new AbortMultipartUploadCommand({
+			Bucket: bucketName,
+			Key: upload.Key,
+			UploadId: upload.UploadId
+		}));
+	}
+	let token;
+	do {
+		const page = await s3.send(new ListObjectsV2Command({
+			Bucket: bucketName,
+			ContinuationToken: token
+		}));
+		for (const entry of page.Contents ?? []) if (entry.Key) await s3.send(new DeleteObjectCommand({
+			Bucket: bucketName,
+			Key: entry.Key
+		}));
+		token = page.IsTruncated ? page.NextContinuationToken : void 0;
+	} while (token);
+}
+/**
+* Reclaim stale throwaway R2 buckets — the one kind that needs more than an API token, so it lives here
+* once instead of being re-derived by every suite that makes a bucket.
+*
+* Without `R2_CREDENTIALS` this reaps nothing and says so loudly rather than failing quietly: the buckets
+* are still there, still cost money, and the only fix is the key pair. Never throws — a reaper must not
+* fail the suite it is trying to help.
+*/
+async function reapStaleTestBuckets(creds, options = {}) {
+	if (!creds.r2) {
+		console.warn("no R2_CREDENTIALS: stale pithy-int- buckets cannot be emptied, so none were reaped.");
+		return {
+			reaped: [],
+			failed: []
+		};
+	}
+	const provisioner = new CloudflareClients({
+		accountId: creds.accountId,
+		apiToken: creds.apiToken
+	}).r2Provisioner();
+	return reapStaleTestResources({
+		label: "R2 bucket",
+		list: async () => (await provisioner.listBuckets()).map((bucket) => bucket.name),
+		remove: async (name) => {
+			await emptyTestBucket(creds, name);
+			await provisioner.deleteBucket(name);
+		}
+	}, options);
+}
+//#endregion
+export { DEFAULT_STALE_AFTER_MS, INTEGRATION_COMPATIBILITY_DATE, RESERVED_TEST_PROJECT, emptyTestBucket, loadIntegrationCreds, loadIntegrationEnv, parseR2Creds, reapStaleTestBuckets, reapStaleTestResources, staleTestResourceNames, testResourceAge, uniqueName, withNamedResource, withThrowawayResource };

package/dist/test-utils/inboundRecorder.d.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import type { CloudflareWorkersManager } from "../workers/workersManager";
+import type { IntegrationCreds } from "./harness";
+/**
+ * A throwaway Worker that records what its `email()` handler was handed, and the reader that fetches
+ * the record back out.
+ *
+ * ## Why a Worker has to exist at all
+ *
+ * An Email Routing rule cannot point at a Worker that is not there. Cloudflare rejects the rule with
+ * `2016 Workers Script Info not found` at creation time, so a live test of `ensureWorkerRoute` has to
+ * deploy a real script before it can create a real rule. That fact alone forces this file; everything
+ * else here is what the script may as well do once it is running.
+ *
+ * ## Why the record goes through KV
+ *
+ * There is no inbox. The fixture zone's catch-all drops and it has zero verified destination
+ * addresses, so nothing this suite sends can be read from a mailbox — and a test that waits for one
+ * waits forever. The Worker is the destination, so the Worker has to be the witness: it writes what it
+ * received to a KV namespace the test created, and the test reads it back over the REST API.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not classify, suppress, or parse MIME. Everything `@pithy-sh/email` actually does with an
+ * inbound message is unit-tested against real D1 in the Workers pool, where a hostile message can be
+ * constructed exactly rather than mailed and hoped for. What only a live delivery can answer is what
+ * Cloudflare *hands* the handler — which headers survive, which Cloudflare adds, and whether a
+ * sender's own headers arrive intact. So the recorder records, and asserts nothing.
+ */
+/** The KV binding the recorder writes through. */
+export declare const INBOUND_RECORDER_BINDING = "OBSERVED";
+/** The header a sender stamps to address its record. One send, one key, so parallel runs cannot collide. */
+export declare const INBOUND_NONCE_HEADER = "X-Pithy-Probe";
+/**
+ * The recorder's source, as a module string.
+ *
+ * Kept verbatim here rather than built from a template because it is uploaded as-is and read by whoever
+ * is debugging a delivery that did not arrive. It writes **once**, under the nonce it finds in the raw
+ * message, and it must never throw: a throw inside `email()` is a delivery failure Cloudflare retries,
+ * which turns one test message into several.
+ */
+export declare const INBOUND_RECORDER_MODULE = "\nconst NONCE = /^X-Pithy-Probe:[ \\t]*(\\S+)[ \\t]*$/im;\nconst AUTH_RESULTS = /^Authentication-Results:[ \\t]*([\\s\\S]*?)(?=\\r?\\n[^ \\t])/gim;\n\n/** Header names in the raw block, in order, lowercased. Duplicates kept \u2014 two DKIM signatures are two facts. */\nfunction rawHeaderNames(raw) {\n  const block = raw.split(/\\r?\\n\\r?\\n/)[0] ?? \"\";\n  return block\n    .split(/\\r?\\n/)\n    .filter((line) => /^[A-Za-z0-9-]+:/.test(line))\n    .map((line) => line.slice(0, line.indexOf(\":\")).toLowerCase());\n}\n\nexport default {\n  async email(message, env) {\n    let record;\n    let nonce = \"unkeyed\";\n    try {\n      const raw = await new Response(message.raw).text();\n      nonce = NONCE.exec(raw)?.[1] ?? \"unkeyed\";\n      record = {\n        envelopeFrom: message.from,\n        envelopeTo: message.to,\n        rawSize: message.rawSize,\n        seen: [...message.headers.keys()].map((name) => name.toLowerCase()).sort(),\n        rawHeaderNames: rawHeaderNames(raw),\n        authenticationResults: [...raw.matchAll(AUTH_RESULTS)].map((match) => match[1].trim()),\n        raw: raw.slice(0, 16384),\n      };\n    } catch (error) {\n      record = { failure: String(error) };\n    }\n    await env.OBSERVED.put(nonce, JSON.stringify(record), { expirationTtl: 3600 });\n  },\n};\n";
+/**
+ * What the recorder saw — validated on the way back in, because a KV read is a boundary like any other.
+ *
+ * The Worker that wrote it is ours, which is exactly the argument that has let every unvalidated
+ * internal read through. A truncated write or a stale record from an older recorder deserves a Zod
+ * failure naming the field, not a `TypeError` three assertions later.
+ */
+export declare const ObservedInbound: z.ZodObject<{
+    envelopeFrom: z.ZodString;
+    envelopeTo: z.ZodString;
+    rawSize: z.ZodNumber;
+    seen: z.ZodArray<z.ZodString>;
+    rawHeaderNames: z.ZodArray<z.ZodString>;
+    authenticationResults: z.ZodArray<z.ZodString>;
+    raw: z.ZodString;
+}, z.core.$strip>;
+/** What the recorder saw. */
+export type ObservedInbound = z.output<typeof ObservedInbound>;
+/** A trivial module Worker: enough for an Email Routing rule to be allowed to point at it. */
+export declare const PLACEHOLDER_INBOUND_MODULE = "export default { async email() {} };\n";
+/** The module filename every throwaway Worker here is uploaded under. */
+export declare const INBOUND_MODULE_NAME = "worker.mjs";
+/**
+ * Deploy the recorder at `scriptName`, bound to the KV namespace records are written to.
+ *
+ * Uploaded through `CloudflareWorkersManager.createWorker` like anything else. It briefly was not:
+ * #373 was a manager that could not upload a module to the live API at all, and this file carried a
+ * hand-rolled `fetch` around it. The manager is the path again — a helper that exists because the
+ * product is broken is the thing people copy.
+ */
+export declare function deployInboundRecorder(options: {
+    workers: CloudflareWorkersManager;
+    scriptName: string;
+    namespaceId: string;
+    /** The date this throwaway Worker runs on. Named by the suite, because #396 left no default to inherit. */
+    compatibilityDate: string;
+}): Promise<void>;
+/**
+ * The record for one nonce, or null while nothing has arrived.
+ *
+ * Null rather than a throw for the missing case, because "not yet" is the normal state of a mail
+ * delivery: the caller polls. A 404 from KV is that state; anything else is a real failure and throws.
+ */
+export declare function readObservedInbound(options: {
+    creds: IntegrationCreds;
+    namespaceId: string;
+    nonce: string;
+}): Promise<ObservedInbound | null>;
+//# sourceMappingURL=inboundRecorder.d.ts.map

package/dist/test-utils/inboundRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inboundRecorder.d.ts","sourceRoot":"","sources":["../../src/test-utils/inboundRecorder.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAapD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,myCAmCnC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;iBAgBqD,CAAC;AAElF,6BAA6B;AAC7B,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B,2CAA2C,CAAC;AAEnF,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE;IACnD,OAAO,EAAE,wBAAwB,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,2GAA2G;IAC3G,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuBlC"}