@zeyolabs/kit 0.0.0-stage → 2026.11.5

package/cloudflare/r2/client.ts

@@ -0,0 +1,154 @@
+import { AwsClient } from 'aws4fetch';
+
+export type PresignedUpload = {
+	/** Headers the browser MUST replay verbatim on the PUT (they're signed). */
+	headers: Record<string, string>;
+	/** Fully-signed PUT URL (auth in query string). */
+	url: string;
+};
+
+/** Keyed by the actual env/secret binding names — the caller reads them off `EnvStore`
+ *  (`string()`/`secret()`), no separate camelCase shape to keep in sync. */
+export type R2Config = {
+	CF_ACCOUNT_ID: string;
+	R2_ACCESS_KEY_ID: string;
+	R2_SECRET_ACCESS_KEY: string;
+	R2_UPLOADS_BUCKET: string;
+};
+
+export interface IR2Client {
+	deleteObject(key: string): Promise<void>;
+	getObject(key: string): Promise<ArrayBuffer>;
+	getObjectWithHeaders(
+		key: string
+	): Promise<null | { body: ArrayBuffer; contentEncoding: null | string }>;
+	presignDownload(key: string, fileName?: string, expiresSeconds?: number): Promise<string>;
+	presignUpload(data: {
+		contentType?: string;
+		key: string;
+		size: number;
+	}): Promise<PresignedUpload>;
+	putObject(key: string, body: BodyInit, contentType?: string): Promise<void>;
+}
+
+/**
+ * Presigned direct-to-R2 access over the S3 API. Large CSVs go browser → R2 (and back) without
+ * streaming through the worker. No ambient context, no app-specific knowledge — the credentials
+ * are passed in.
+ */
+export class R2Client implements IR2Client {
+	private awsClient: AwsClient | null = null;
+
+	/** `AwsClient` construction memoized on first access — every call after the first reuses it. */
+	private get client(): { base: string; client: AwsClient } {
+		this.awsClient ??= new AwsClient({
+			accessKeyId: this.config.R2_ACCESS_KEY_ID,
+			region: 'auto',
+			secretAccessKey: this.config.R2_SECRET_ACCESS_KEY,
+			service: 's3',
+		});
+		return {
+			base: `https://${this.config.CF_ACCOUNT_ID}.r2.cloudflarestorage.com/${this.config.R2_UPLOADS_BUCKET}`,
+			client: this.awsClient,
+		};
+	}
+
+	constructor(private readonly config: R2Config) {}
+
+	/** Delete an object outright (authenticated S3 DELETE) — e.g. a user removing a stored export
+	 *  before its R2 lifecycle rule would otherwise expire it. */
+	async deleteObject(key: string): Promise<void> {
+		const { base, client } = this.client;
+		const res = await client.fetch(`${base}/${key}`, { method: 'DELETE' });
+		if (!res.ok && res.status !== 404) throw new Error(`R2 delete ${key} failed (${res.status})`);
+	}
+
+	/**
+	 * Read an object's full bytes straight from R2 (authenticated S3 GET, not presigned) — e.g.
+	 * pulling a stored attachment back out at send time to embed as base64 in an outgoing email.
+	 */
+	async getObject(key: string): Promise<ArrayBuffer> {
+		const { base, client } = this.client;
+		const res = await client.fetch(`${base}/${key}`);
+		if (!res.ok) throw new Error(`R2 get ${key} failed (${res.status})`);
+		return res.arrayBuffer();
+	}
+
+	/**
+	 * Read an object's bytes plus its `Content-Encoding`, treating a 404 as "not there" rather
+	 * than throwing — e.g. reading a stored raw email that may predate whatever compression a
+	 * caller now requires. Any other non-2xx still throws (an unexpected failure, not a missing
+	 * object).
+	 */
+	async getObjectWithHeaders(
+		key: string
+	): Promise<null | { body: ArrayBuffer; contentEncoding: null | string }> {
+		const { base, client } = this.client;
+		const res = await client.fetch(`${base}/${key}`);
+		if (res.status === 404) return null;
+		if (!res.ok) throw new Error(`R2 get ${key} failed (${res.status})`);
+		return { body: await res.arrayBuffer(), contentEncoding: res.headers.get('content-encoding') };
+	}
+
+	/**
+	 * Presign a one-shot GET for an export object so the browser downloads it straight from R2. The
+	 * object lives ~3 days (R2 lifecycle); each link is presigned fresh with a short validity.
+	 * `response-content-disposition` forces a download with a friendly filename (signed, so it can't
+	 * be tampered with after signing).
+	 */
+	async presignDownload(key: string, fileName?: string, expiresSeconds = 3600): Promise<string> {
+		const { base, client } = this.client;
+		const disposition = fileName
+			? `&response-content-disposition=${encodeURIComponent(`attachment; filename="${fileName}"`)}`
+			: '';
+		const endpoint = `${base}/${key}?X-Amz-Expires=${expiresSeconds}${disposition}`;
+		const signed = await client.sign(endpoint, { aws: { signQuery: true }, method: 'GET' });
+		return signed.url;
+	}
+
+	/**
+	 * Presign a one-shot PUT straight to R2 so a large file goes browser → R2 directly and never
+	 * streams through the worker. The object carries NO metadata — the mapping/listId/userId live in
+	 * the `jobs.list_upload` row (keyed by this object key). Content-Length pins the exact body size; a
+	 * PUT of any other length fails R2's signature check. `contentType` defaults to the original
+	 * CSV-only caller's assumption so existing call sites are unaffected.
+	 */
+	async presignUpload(data: {
+		contentType?: string;
+		key: string;
+		size: number;
+	}): Promise<PresignedUpload> {
+		const { base, client } = this.client;
+		// aws4fetch reads validity from the X-Amz-Expires query param — 300s.
+		const endpoint = `${base}/${data.key}?X-Amz-Expires=300`;
+		const signHeaders: Record<string, string> = {
+			'content-length': String(data.size),
+			'content-type': data.contentType ?? 'text/csv',
+		};
+		const signed = await client.sign(endpoint, {
+			aws: { signQuery: true },
+			headers: signHeaders,
+			method: 'PUT',
+		});
+		// The browser sets Content-Length automatically from the body (forbidden to set manually) —
+		// return only the headers the client must replay verbatim.
+		const { 'content-length': _contentLength, ...replay } = signHeaders;
+		return { headers: replay, url: signed.url };
+	}
+
+	/**
+	 * Write an object straight to R2 (authenticated S3 PUT, not presigned) — a small trigger file
+	 * (drops into a notification-watched folder so the existing R2 → queue → processor pipeline
+	 * picks it up, since the app has no queue producer binding) or a reply's own file attachment,
+	 * whose bytes now arrive in the same request as the send rather than a presigned browser PUT.
+	 */
+	async putObject(key: string, body: BodyInit, contentType = 'application/json'): Promise<void> {
+		const { base, client } = this.client;
+		const res = await client.fetch(`${base}/${key}`, {
+			body,
+			headers: { 'content-type': contentType },
+			method: 'PUT',
+		});
+		if (!res.ok) throw new Error(`R2 put ${key} failed (${res.status})`);
+	}
+}

package/cloudflare/r2/testing.ts

@@ -0,0 +1,43 @@
+import type { IR2Client, PresignedUpload } from './client';
+
+export class FakeR2Client implements IR2Client {
+	private readonly objects = new Map<
+		string,
+		{ body: ArrayBuffer; contentEncoding: null | string }
+	>();
+
+	async deleteObject(key: string): Promise<void> {
+		this.objects.delete(key);
+	}
+
+	async getObject(key: string): Promise<ArrayBuffer> {
+		const obj = this.objects.get(key);
+		if (!obj) throw new Error(`R2 get ${key} failed (404)`);
+		return obj.body;
+	}
+
+	async getObjectWithHeaders(
+		key: string
+	): Promise<null | { body: ArrayBuffer; contentEncoding: null | string }> {
+		return this.objects.get(key) ?? null;
+	}
+
+	async presignDownload(key: string): Promise<string> {
+		return `https://fake-r2.test/${key}`;
+	}
+
+	async presignUpload(data: { key: string }): Promise<PresignedUpload> {
+		return { headers: {}, url: `https://fake-r2.test/${data.key}` };
+	}
+
+	async putObject(key: string, body: BodyInit, contentType = 'application/json'): Promise<void> {
+		const arrayBuffer =
+			body instanceof ArrayBuffer ? body : await new Response(body as BodyInit).arrayBuffer();
+		this.objects.set(key, { body: arrayBuffer, contentEncoding: null });
+		void contentType;
+	}
+
+	seed(key: string, body: ArrayBuffer, contentEncoding: null | string = null): void {
+		this.objects.set(key, { body, contentEncoding });
+	}
+}

package/cloudflare/rate-limiter.ts

@@ -0,0 +1,65 @@
+// RateLimiter Durable Object.
+// Sliding-window limiter over DO storage. Handles both the single-window form (rate-limit
+// categories: {limit, window}) and the multi-window form ({windows: [[limit, secs]...]}).
+// Allowed only when every window has budget; one timestamp is recorded against all of them.
+// Host it in a standalone worker (see workers/rate-limiter) and bind it with `script_name`.
+import { DurableObject } from 'cloudflare:workers';
+
+type RateLimitRequest = {
+	category: string;
+	limit?: number;
+	userId: string;
+	window?: number;
+	windows?: [number, number][];
+};
+
+export class RateLimiter extends DurableObject {
+	async fetch(req: Request): Promise<Response> {
+		const body = await req.json<RateLimitRequest>();
+
+		// Normalise both request forms to a list of [limit, windowSeconds].
+		const windows: [number, number][] =
+			body.windows && body.windows.length > 0
+				? body.windows
+				: [[body.limit ?? 0, body.window ?? 0]];
+
+		const key = `${body.userId}:${body.category}`;
+		const stored = (await this.ctx.storage.get<number[]>(key)) ?? [];
+
+		const now = Date.now();
+		// Drop timestamps older than the largest window: they can't count toward any window.
+		const maxWindow = Math.max(...windows.map(([, secs]) => secs));
+		const cutoff = now - maxWindow * 1000;
+		const valid = stored.filter((ts) => ts > cutoff);
+
+		// Deny, recording nothing, if any single window is already at its limit.
+		for (const [limit, secs] of windows) {
+			const start = now - secs * 1000;
+			const inWindow = valid.filter((ts) => ts > start);
+			if (inWindow.length >= limit) {
+				const oldest = Math.min(...inWindow);
+				const resetAt = oldest + secs * 1000;
+				const retryAfter = Math.ceil((resetAt - now) / 1000);
+				return Response.json(
+					{ allowed: false, remaining: 0, resetAt, retryAfter },
+					{ status: 429 }
+				);
+			}
+		}
+
+		valid.push(now);
+		await this.ctx.storage.put(key, valid);
+
+		// Report remaining/reset for the tightest window.
+		const remaining = Math.max(
+			0,
+			Math.min(
+				...windows.map(
+					([limit, secs]) => limit - valid.filter((ts) => ts > now - secs * 1000).length
+				)
+			)
+		);
+		const soonest = Math.min(...windows.map(([, secs]) => secs));
+		return Response.json({ allowed: true, remaining, resetAt: now + soonest * 1000 });
+	}
+}

package/cloudflare/wait-until.ts

@@ -0,0 +1,12 @@
+/** `cloudflare:workers`'s `waitUntil` only exists in the real Workers runtime — a plain Node
+ *  process (local SvelteKit dev, route analysis during `vite build`, most test runs) has no such
+ *  module, so it's imported dynamically here and swallowed if that fails: there's nothing to do to
+ *  extend a promise's lifetime outside the Workers runtime anyway. */
+export async function waitUntil(promise: Promise<unknown>): Promise<void> {
+	try {
+		const workers = await import('cloudflare:workers');
+		workers.waitUntil(promise);
+	} catch {
+		// Not in the Workers runtime — no way to keep this alive past the caller's response.
+	}
+}

package/cloudflare/workers/index.ts

@@ -0,0 +1,311 @@
+// Minimal hand-rolled router + middleware chain for a plain Worker's fetch/queue/cron — no
+// dependency, and queue/cron registration gets the same chaining shape fetch does.
+//
+// Two classes, not one: a Cloudflare Service Binding entrypoint (`WorkerEntrypoint`) is only ever
+// reachable via RPC methods like `fetch()` — queues and Cron Triggers both bind to a worker's
+// top-level default export, never to a named entrypoint class, so a binding can be neither a queue
+// consumer nor scheduled. `WorkerBindingRouter` has no `.queue()`/`.cron()` at all, so that
+// mismatch is a compile error instead of a handler that's registered but silently unreachable.
+import type { CloudflareOptions } from '@sentry/cloudflare';
+import type { DurableObject } from 'cloudflare:workers';
+
+import * as Sentry from '@sentry/cloudflare';
+import { WorkerEntrypoint } from 'cloudflare:workers';
+
+import { runWithContext } from '../context';
+
+type WorkerSentryEnv = { SENTRY_DSN: string; SENTRY_RELEASE?: string };
+function sentryOptionsFor(env: WorkerSentryEnv): CloudflareOptions {
+	return {
+		dsn: env.SENTRY_DSN,
+		environment: 'production',
+		release: env.SENTRY_RELEASE,
+		tracesSampleRate: 0,
+	};
+}
+
+export type WorkerContext<Env> = {
+	env: Env;
+	executionCtx: ExecutionContext;
+	json(data: unknown, status?: number): Response;
+	req: Request;
+	/** The matched route pattern (e.g. `/health`), or `"unmatched"` — for a metrics middleware's
+	 *  label, so nothing needs its own path-collapsing allowlist. */
+	route: string;
+	/** Pre-parsed once per request — handlers that need query params/pathname read this instead of
+	 *  re-parsing `req.url`. */
+	url: URL;
+};
+
+export type CronMiddleware<Env> = (
+	cronExpression: string,
+	env: Env,
+	executionCtx: ExecutionContext,
+	next: () => Promise<void>
+) => Promise<void>;
+export type HttpHandler<Env> = (c: WorkerContext<Env>) => Promise<Response> | Response;
+export type HttpMiddleware<Env> = (
+	c: WorkerContext<Env>,
+	next: () => Promise<Response>
+) => Promise<Response>;
+export type QueueHandler<Env> = (
+	batch: MessageBatch<unknown>,
+	env: Env,
+	executionCtx: ExecutionContext
+) => Promise<void>;
+export type QueueMiddleware<Env> = (
+	queueName: string,
+	env: Env,
+	executionCtx: ExecutionContext,
+	next: () => Promise<void>
+) => Promise<void>;
+/** Return type is `unknown`, not `void` — the runtime ignores it either way (Cloudflare never
+ *  reads a `scheduled()` return value), but this lets a handler double as a directly-testable
+ *  function that returns something (a tally, a summary) without a separate void-returning wrapper
+ *  just to satisfy this type. */
+export type ScheduledHandler<Env> = (
+	controller: ScheduledController,
+	env: Env,
+	executionCtx: ExecutionContext
+) => Promise<unknown>;
+/** What `.use()` takes on both router classes — one bundle instead of a separate call per surface
+ *  (`.use(Metrics.WorkerMiddleware('inbox'))` wires HTTP, queue, and cron in one go). Each field is
+ *  optional: `WorkerBindingRouter` only ever applies `http` (it has no queue/cron to wrap), and a
+ *  bundle that only cares about one surface just omits the others. */
+export type WorkerMiddleware<Env> = {
+	cron?: CronMiddleware<Env>;
+	http?: HttpMiddleware<Env>;
+	queue?: QueueMiddleware<Env>;
+};
+
+type RawFetch<Env> = (
+	request: Request,
+	env: Env,
+	executionCtx: ExecutionContext
+) => Promise<Response>;
+
+/** The route-match + middleware-chain dispatcher shared by both router classes below. Neither
+ *  class exposes this directly — each wraps the result in Sentry differently (fetch alone for
+ *  `WorkerBindingRouter`, fetch+queue together for `WorkerRouter`). */
+function buildFetch<Env extends object>(
+	routes: Map<string, HttpHandler<Env>>,
+	middlewares: HttpMiddleware<Env>[],
+	secretNames: ReadonlySet<string>
+): RawFetch<Env> {
+	return (request, env, executionCtx) =>
+		runWithContext(env, secretNames, () => {
+			const url = new URL(request.url);
+			const handler = routes.get(`${request.method} ${url.pathname}`);
+			const c: WorkerContext<Env> = {
+				env,
+				executionCtx,
+				json: (data, status = 200) => Response.json(data, { status }),
+				req: request,
+				route: handler ? url.pathname : 'unmatched',
+				url,
+			};
+			const run = () => Promise.resolve(handler ? handler(c) : new Response(null, { status: 404 }));
+			const dispatch = (i: number): Promise<Response> =>
+				i < middlewares.length ? middlewares[i](c, () => dispatch(i + 1)) : run();
+			return dispatch(0);
+		});
+}
+
+/** Fetch-only router for a Service Binding entrypoint — never public, only reachable by another
+ *  worker holding a binding to it. No `.queue()`: see the file header for why. */
+export class WorkerBindingRouter<Env extends object> {
+	readonly fetch: RawFetch<Env>;
+	private readonly middlewares: HttpMiddleware<Env>[] = [];
+	private readonly routes = new Map<string, HttpHandler<Env>>();
+
+	/** Prefer `WorkerBindingRouter.withSentry()` — this bare constructor skips Sentry
+	 *  instrumentation entirely, which no real worker should ship without. */
+	constructor(
+		secretNames: ReadonlySet<string>,
+		sentryOptions?: (env: Env) => CloudflareOptions | undefined
+	) {
+		const rawFetch = buildFetch(this.routes, this.middlewares, secretNames);
+		this.fetch = sentryOptions
+			? Sentry.withSentry(sentryOptions, { fetch: rawFetch }).fetch!
+			: rawFetch;
+	}
+
+	/** `secretNames`: the app's secret-store binding names. */
+	static withSentry<Env extends WorkerSentryEnv>(
+		secretNames: ReadonlySet<string>
+	): WorkerBindingRouter<Env> {
+		return new WorkerBindingRouter<Env>(secretNames, sentryOptionsFor);
+	}
+
+	/** Terminal call — builds the `WorkerEntrypoint` class a `wrangler.jsonc` binding names via
+	 *  `entrypoint: "..."`. */
+	build(): new (ctx: ExecutionContext, env: Env) => WorkerEntrypoint<Env> {
+		const fetch = this.fetch;
+		return class extends WorkerEntrypoint<Env> {
+			fetch(request: Request): Promise<Response> {
+				return fetch(request, this.env, this.ctx);
+			}
+		};
+	}
+
+	get(path: string, handler: HttpHandler<Env>): this {
+		this.routes.set(`GET ${path}`, handler);
+		return this;
+	}
+
+	post(path: string, handler: HttpHandler<Env>): this {
+		this.routes.set(`POST ${path}`, handler);
+		return this;
+	}
+
+	/** Only `middleware.http` applies here — see `WorkerMiddleware`'s doc comment. */
+	use(middleware: WorkerMiddleware<Env>): this {
+		if (middleware.http) this.middlewares.push(middleware.http);
+		return this;
+	}
+}
+
+/** Router for a worker's top-level default export — fetch, queue, or both. Terminal `.build()`
+ *  returns an `ExportedHandler`. For a Service Binding entrypoint, use `WorkerBindingRouter`
+ *  instead — its `.build()` returns a `WorkerEntrypoint` class, not an `ExportedHandler`. */
+export class WorkerRouter<Env extends object> {
+	readonly fetch: RawFetch<Env>;
+	readonly handleQueue: (
+		batch: MessageBatch<unknown>,
+		env: Env,
+		executionCtx: ExecutionContext
+	) => Promise<void>;
+	readonly handleScheduled: (
+		controller: ScheduledController,
+		env: Env,
+		executionCtx: ExecutionContext
+	) => Promise<void>;
+	private readonly cronHandlers = new Map<string, ScheduledHandler<Env>>();
+	private readonly cronMiddlewares: CronMiddleware<Env>[] = [];
+	private readonly middlewares: HttpMiddleware<Env>[] = [];
+	private readonly queueHandlers = new Map<string, QueueHandler<Env>>();
+	private readonly queueMiddlewares: QueueMiddleware<Env>[] = [];
+	private readonly routes = new Map<string, HttpHandler<Env>>();
+
+	/** Prefer `WorkerRouter.withSentry()` — this bare constructor skips Sentry instrumentation
+	 *  entirely, which no real worker should ship without. */
+	constructor(
+		secretNames: ReadonlySet<string>,
+		sentryOptions?: (env: Env) => CloudflareOptions | undefined
+	) {
+		const rawFetch = buildFetch(this.routes, this.middlewares, secretNames);
+		const rawHandleQueue = (
+			batch: MessageBatch<unknown>,
+			env: Env,
+			executionCtx: ExecutionContext
+		): Promise<void> =>
+			runWithContext(env, secretNames, () => {
+				const handler = this.queueHandlers.get(batch.queue);
+				if (!handler)
+					throw new Error(`WorkerRouter: no queue handler registered for "${batch.queue}"`);
+				const run = () => handler(batch, env, executionCtx);
+				const dispatch = (i: number): Promise<void> =>
+					i < this.queueMiddlewares.length
+						? this.queueMiddlewares[i](batch.queue, env, executionCtx, () => dispatch(i + 1))
+						: run();
+				return dispatch(0);
+			});
+		const rawHandleScheduled = (
+			controller: ScheduledController,
+			env: Env,
+			executionCtx: ExecutionContext
+		): Promise<void> =>
+			runWithContext(env, secretNames, () => {
+				const handler = this.cronHandlers.get(controller.cron);
+				if (!handler)
+					throw new Error(`WorkerRouter: no cron handler registered for "${controller.cron}"`);
+				// Discard the handler's return value here — Cloudflare's own `scheduled()` contract is
+				// `Promise<void>`, but `ScheduledHandler` itself returns `unknown` so a handler can double
+				// as a directly-testable function (see that type's doc comment).
+				const run = async () => {
+					await handler(controller, env, executionCtx);
+				};
+				const dispatch = (i: number): Promise<void> =>
+					i < this.cronMiddlewares.length
+						? this.cronMiddlewares[i](controller.cron, env, executionCtx, () => dispatch(i + 1))
+						: run();
+				return dispatch(0);
+			});
+
+		if (sentryOptions) {
+			const wrapped = Sentry.withSentry(sentryOptions, {
+				fetch: rawFetch,
+				queue: rawHandleQueue,
+				scheduled: rawHandleScheduled,
+			});
+			this.fetch = wrapped.fetch!;
+			this.handleQueue = wrapped.queue!;
+			this.handleScheduled = wrapped.scheduled!;
+		} else {
+			this.fetch = rawFetch;
+			this.handleQueue = rawHandleQueue;
+			this.handleScheduled = rawHandleScheduled;
+		}
+	}
+
+	/** The one real entry point — every route/queue registration still chains off the returned
+	 *  instance (`.use(...).post(...).queue(...)`), but `fetch`/`handleQueue` come out the other
+	 *  end already Sentry-instrumented, same as every worker's export today, just without a
+	 *  separate `Sentry.withSentry(...)` wrap at the bottom of the file. `secretNames`:
+	 *  the app's secret-store binding names. */
+	static withSentry<Env extends WorkerSentryEnv>(
+		secretNames: ReadonlySet<string>
+	): WorkerRouter<Env> {
+		return new WorkerRouter<Env>(secretNames, sentryOptionsFor);
+	}
+
+	/** Terminal call for a worker's default export — fetch, queue, scheduled, or any mix. */
+	build(): ExportedHandler<Env> {
+		return { fetch: this.fetch, queue: this.handleQueue, scheduled: this.handleScheduled };
+	}
+
+	/** Registers a handler for one of `wrangler.jsonc`'s `triggers.crons` entries — dispatched by
+	 *  `ScheduledController.cron` at runtime, same shape as `.queue(name, handler)`. `expression`
+	 *  must match that config exactly, or this cron silently has no handler to run. */
+	cron(expression: string, handler: ScheduledHandler<Env>): this {
+		this.cronHandlers.set(expression, handler);
+		return this;
+	}
+
+	get(path: string, handler: HttpHandler<Env>): this {
+		this.routes.set(`GET ${path}`, handler);
+		return this;
+	}
+
+	post(path: string, handler: HttpHandler<Env>): this {
+		this.routes.set(`POST ${path}`, handler);
+		return this;
+	}
+
+	queue(name: string, handler: QueueHandler<Env>): this {
+		this.queueHandlers.set(name, handler);
+		return this;
+	}
+
+	/** Applies whichever of `middleware.http`/`.queue`/`.cron` are present — see `WorkerMiddleware`'s
+	 *  doc comment. One call wires every surface this router has at once. */
+	use(middleware: WorkerMiddleware<Env>): this {
+		if (middleware.http) this.middlewares.push(middleware.http);
+		if (middleware.queue) this.queueMiddlewares.push(middleware.queue);
+		if (middleware.cron) this.cronMiddlewares.push(middleware.cron);
+		return this;
+	}
+}
+
+export const WorkerDOBinding = {
+	/** Same `.withSentry()` instrumentation as the router classes, for a Durable Object class. */
+	withSentry<Env extends WorkerSentryEnv, T extends DurableObject<Env>>(
+		DurableObjectClass: new (state: DurableObjectState, env: Env) => T
+	): new (state: DurableObjectState, env: Env) => T {
+		return Sentry.instrumentDurableObjectWithSentry<
+			Env,
+			T,
+			new (state: DurableObjectState, env: Env) => T
+		>(sentryOptionsFor, DurableObjectClass);
+	},
+};

package/cloudflare/workers/testing.ts

@@ -0,0 +1,94 @@
+import type { WorkerContext } from '.';
+
+/** Builds a `WorkerContext` for calling an `HttpHandler` directly in a test, same shape
+ *  `WorkerRouter.fetch` would build for a real request. */
+export function fakeContext<Env>(request: Request, url: URL, env: Env): WorkerContext<Env> {
+	return {
+		env,
+		executionCtx: { waitUntil: () => {} } as unknown as ExecutionContext,
+		json: (data, status = 200) => Response.json(data, { status }),
+		req: request,
+		route: url.pathname,
+		url,
+	};
+}
+
+/** In-memory `DurableObjectStorage` stand-in for tests: `get`/`put`/`list` (single-key and
+ *  bulk forms) and a single-slot alarm (`getAlarm`/`setAlarm`/`deleteAlarm`) round-trip for
+ *  real, no real DO runtime needed. `list`'s `prefix`/`reverse` match real key-ordering
+ *  semantics (lexicographic). The returned client also carries a `reset()`.
+ *
+ *  `DurableObjectStorage` is a large interface (`sql`, `kv`, `transaction`, bookmarks) — only
+ *  `get`/`put`/`list`/the alarm methods are implemented, since that's the entire surface any
+ *  current caller uses. Everything else throws instead of silently no-op'ing, so a caller that
+ *  reaches past these gets a loud failure at the call site, not a silent gap — same stance as
+ *  `mockRedis()` (`packages/kit/storage/redis/testing.ts`). Add a case if a test needs one. */
+export function mockDurableObjectStorage(): DurableObjectStorage & { reset: () => void } {
+	const rows = new Map<string, unknown>();
+	let alarm: null | number = null;
+
+	function get<T>(key: string): Promise<T | undefined>;
+	function get<T>(keys: string[]): Promise<Map<string, T>>;
+	function get<T>(keyOrKeys: string | string[]): Promise<Map<string, T> | T | undefined> {
+		if (Array.isArray(keyOrKeys)) {
+			const out = new Map<string, T>();
+			for (const k of keyOrKeys) {
+				if (rows.has(k)) out.set(k, rows.get(k) as T);
+			}
+			return Promise.resolve(out);
+		}
+		return Promise.resolve(rows.get(keyOrKeys) as T | undefined);
+	}
+
+	function put<T>(key: string, value: T): Promise<void>;
+	function put<T>(entries: Record<string, T>): Promise<void>;
+	function put<T>(keyOrEntries: Record<string, T> | string, value?: T): Promise<void> {
+		if (typeof keyOrEntries === 'string') {
+			rows.set(keyOrEntries, value);
+		} else {
+			for (const [k, v] of Object.entries(keyOrEntries)) rows.set(k, v);
+		}
+		return Promise.resolve();
+	}
+
+	function list<T>(options?: DurableObjectListOptions): Promise<Map<string, T>> {
+		const prefix = options?.prefix ?? '';
+		let keys = [...rows.keys()].filter((k) => k.startsWith(prefix)).sort();
+		if (options?.reverse) keys = keys.reverse();
+		if (options?.limit !== undefined) keys = keys.slice(0, options.limit);
+		const out = new Map<T extends never ? never : string, T>();
+		for (const k of keys) out.set(k as never, rows.get(k) as T);
+		return Promise.resolve(out as Map<string, T>);
+	}
+
+	const notImplemented = (method: string) => () => {
+		throw new Error(`mockDurableObjectStorage(): "${method}" is not implemented`);
+	};
+
+	return {
+		delete: notImplemented('delete'),
+		deleteAlarm: () => {
+			alarm = null;
+			return Promise.resolve();
+		},
+		deleteAll: notImplemented('deleteAll'),
+		get,
+		getAlarm: () => Promise.resolve(alarm),
+		getBookmarkForTime: notImplemented('getBookmarkForTime'),
+		getCurrentBookmark: notImplemented('getCurrentBookmark'),
+		list,
+		onNextSessionRestoreBookmark: notImplemented('onNextSessionRestoreBookmark'),
+		put,
+		reset: () => {
+			rows.clear();
+			alarm = null;
+		},
+		setAlarm: (time: Date | number) => {
+			alarm = time instanceof Date ? time.getTime() : time;
+			return Promise.resolve();
+		},
+		sync: notImplemented('sync'),
+		transaction: notImplemented('transaction'),
+		transactionSync: notImplemented('transactionSync'),
+	} as unknown as DurableObjectStorage & { reset: () => void };
+}