appflare 0.0.28 → 0.1.0

package/cli/templates/handlers/registration.ts

@@ -0,0 +1,1114 @@
+import type { DiscoveredHandlerOperation } from "../../utils/handler-discovery";
+
+function toSafeIdentifier(value: string): string {
+	const sanitized = value.replace(/[^A-Za-z0-9_]/g, "_");
+	if (/^[0-9]/.test(sanitized)) {
+		return `_${sanitized}`;
+	}
+	return sanitized;
+}
+
+function buildImportAlias(
+	operation: DiscoveredHandlerOperation,
+	index: number,
+): string {
+	const routeName = operation.routePath.replace(/^\//, "").replace(/\//g, "_");
+	return toSafeIdentifier(`op_${index}_${routeName}`);
+}
+
+export function generateRegistration(
+	operations: DiscoveredHandlerOperation[],
+): string {
+	const httpOperations = operations.filter(
+		(operation) => operation.kind === "query" || operation.kind === "mutation",
+	);
+	const schedulerOperations = operations.filter(
+		(operation) => operation.kind === "scheduler",
+	);
+	const cronOperations = operations.filter(
+		(operation) => operation.kind === "cron",
+	);
+	const storageOperations = operations.filter(
+		(operation) => operation.kind === "storage",
+	);
+
+	const imports = operations
+		.map((operation, index) => {
+			const alias = buildImportAlias(operation, index);
+			return `import { ${operation.exportName} as ${alias} } from "${operation.importPath}";`;
+		})
+		.join("\n");
+
+	const operationSchemas = httpOperations
+		.map((operation, index) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const schemaName = `${alias}Schema`;
+			return `const ${schemaName} = z.object(${alias}.definition.args);`;
+		})
+		.join("\n");
+
+	const schedulerSchemas = schedulerOperations
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const schemaName = `${alias}SchedulerSchema`;
+			return `const ${schemaName} = ${alias}.definition.args ? z.object(${alias}.definition.args) : z.undefined();`;
+		})
+		.join("\n");
+
+	const queryRoutes = httpOperations
+		.filter((operation) => operation.kind === "query")
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const schemaName = `${alias}Schema`;
+			return `
+	app.get(
+		"${operation.routePath}",
+		sValidator("query", ${schemaName}),
+		async (c) => {
+			const ctx = await createExecutionContext(c, options);
+			try {
+				return await executeOperation(c, ${alias}, c.req.valid("query"), ctx);
+			} catch (error) {
+				return handleOperationError(c, error, "Invalid query arguments");
+			}
+		},
+	);`;
+		})
+		.join("\n");
+
+	const mutationRoutes = httpOperations
+		.filter((operation) => operation.kind === "mutation")
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const schemaName = `${alias}Schema`;
+			return `
+	app.post(
+		"${operation.routePath}",
+		sValidator("json", ${schemaName}),
+		async (c) => {
+			const ctx = await createExecutionContext(c, options);
+			try {
+				const response = await executeOperation(c, ${alias}, c.req.valid("json"), ctx);
+				await publishMutationEvents(c, options, ctx.mutationEvents);
+				return response;
+			} catch (error) {
+				return handleOperationError(c, error, "Invalid mutation arguments");
+			}
+		},
+	);`;
+		})
+		.join("\n");
+
+	const queryRegistryEntries = httpOperations
+		.filter((operation) => operation.kind === "query")
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const schemaName = `${alias}Schema`;
+			const queryName = operation.handlerName ?? operation.routePath;
+			return `
+	${JSON.stringify(queryName)}: {
+		definition: ${alias}.definition,
+		schema: ${schemaName},
+	},`;
+		})
+		.join("\n");
+
+	const schedulerEntries = schedulerOperations
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const schemaName = `${alias}SchedulerSchema`;
+			const taskName = operation.taskName ?? `${operation.routePath}`;
+			return `
+	${JSON.stringify(taskName)}: {
+		definition: ${alias}.definition,
+		schema: ${schemaName},
+	},`;
+		})
+		.join("\n");
+
+	const schedulerPayloadMapEntries = schedulerOperations
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const taskName = operation.taskName ?? `${operation.routePath}`;
+			return `\t${JSON.stringify(taskName)}: Parameters<typeof ${alias}.definition.handler>[1];`;
+		})
+		.join("\n");
+
+	const cronEntries = cronOperations
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			const taskName = operation.taskName ?? `${operation.routePath}`;
+			const cronTriggers = operation.cronTriggers ?? [];
+			return `
+	{
+		taskName: ${JSON.stringify(taskName)},
+		cronTriggers: ${JSON.stringify(cronTriggers)},
+		definition: ${alias}.definition,
+	},`;
+		})
+		.join("\n");
+
+	const storageHandlersEntries = storageOperations
+		.map((operation) => {
+			const operationIndex = operations.indexOf(operation);
+			const alias = buildImportAlias(operation, operationIndex);
+			return `\n\t${alias}.definition.handler,`;
+		})
+		.join("\n");
+
+	return `import { sValidator } from "@hono/standard-validator";
+import type { Hono } from "hono";
+import type { D1Database, IncomingRequestCfProperties, KVNamespace } from "@cloudflare/workers-types";
+import { ZodError, z } from "zod";
+	import {
+		AppflareHandledError,
+		type AppflareContext,
+		type DbMutationEvent,
+		createDb,
+		createQueryDb,
+		setStorageHandlers,
+		type RegisterHandlersOptions,
+		type StorageMethod,
+		type WorkerEnv,
+	} from "./handlers";
+import { createExecutionContext, createSchedulerExecutionContext, resolveSession } from "./handlers.context";
+import { executeOperation, handleOperationError } from "./handlers.execution";
+${imports ? `\n${imports}` : ""}
+
+${operationSchemas}
+${schedulerSchemas}
+
+const realtimeQueryHandlers = {${queryRegistryEntries || "\n"}
+} as const;
+
+const schedulerHandlers = {${schedulerEntries || "\n"}
+} as const;
+
+type GeneratedSchedulerPayloadMap = {${
+		schedulerPayloadMapEntries ? `\n${schedulerPayloadMapEntries}\n` : ""
+	}};
+
+declare global {
+	interface AppflareSchedulerHandlerMap extends GeneratedSchedulerPayloadMap {}
+}
+
+const cronHandlers = [${cronEntries || "\n"}
+] as const;
+
+const storageHandlers = [${storageHandlersEntries || "\n"}
+] as const;
+
+setStorageHandlers([...storageHandlers]);
+
+type SchedulerTaskName = keyof typeof schedulerHandlers extends never
+	? string
+	: keyof typeof schedulerHandlers;
+
+type QueueMessageBody = {
+	task?: string;
+	payload?: unknown;
+};
+
+type RealtimeSubscription = {
+	token: string;
+	signature: string;
+	queryName: string;
+	args: Record<string, unknown>;
+	authToken: string;
+	userId: string;
+	createdAt: number;
+};
+
+type RealtimeEmitPayload = {
+	token: string;
+	event: string;
+	payload: unknown;
+};
+
+type RealtimeStub = {
+	fetch: (request: Request) => Promise<Response>;
+};
+
+type RealtimeDurableObjectNamespace = {
+	idFromName: (name: string) => unknown;
+	get: (id: unknown) => RealtimeStub;
+};
+
+type RealtimeQueryName = keyof typeof realtimeQueryHandlers extends never
+	? string
+	: Extract<keyof typeof realtimeQueryHandlers, string>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function stableStringify(value: unknown): string {
+	if (Array.isArray(value)) {
+		return "[" + value.map((entry) => stableStringify(entry)).join(",") + "]";
+	}
+
+	if (value instanceof Date) {
+		return JSON.stringify(value.toISOString());
+	}
+
+	if (isRecord(value)) {
+		const keys = Object.keys(value).sort((a, b) => a.localeCompare(b));
+		return (
+			"{" +
+			keys
+				.map((key) => JSON.stringify(key) + ":" + stableStringify(value[key]))
+				.join(",") +
+			"}"
+		);
+	}
+
+	return JSON.stringify(value ?? null);
+}
+
+function normalizeComparableValue(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map((entry) => normalizeComparableValue(entry));
+	}
+
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+
+	if (isRecord(value)) {
+		return Object.entries(value)
+			.sort(([a], [b]) => a.localeCompare(b))
+			.reduce<Record<string, unknown>>((accumulator, [key, entry]) => {
+				accumulator[key] = normalizeComparableValue(entry);
+				return accumulator;
+			}, {});
+	}
+
+	return value;
+}
+
+function createSubscriptionSignature(
+	queryName: string,
+	args: Record<string, unknown>,
+): string {
+	const normalizedArgs = normalizeComparableValue(args);
+	return queryName + "::" + stableStringify(normalizedArgs);
+}
+
+function normalizeSubscriptionFilter(args: Record<string, unknown>): unknown {
+	const where = args.where;
+	if (isRecord(where)) {
+		return where;
+	}
+
+	return args;
+}
+
+function hasPartialOverlap(left: unknown, right: unknown): boolean {
+	if (left === null || left === undefined || right === null || right === undefined) {
+		return false;
+	}
+
+	if (Array.isArray(left) && Array.isArray(right)) {
+		return left.some((leftValue) => {
+			return right.some((rightValue) => hasPartialOverlap(leftValue, rightValue));
+		});
+	}
+
+	if (Array.isArray(left)) {
+		return left.some((leftValue) => hasPartialOverlap(leftValue, right));
+	}
+
+	if (Array.isArray(right)) {
+		return right.some((rightValue) => hasPartialOverlap(left, rightValue));
+	}
+
+	if (isRecord(left) && isRecord(right)) {
+		const keys = Object.keys(left);
+		for (const key of keys) {
+			if (!(key in right)) {
+				continue;
+			}
+
+			if (hasPartialOverlap(left[key], right[key])) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	return left === right;
+}
+
+function doesSubscriptionMatchMutation(
+	subscriptionArgs: Record<string, unknown>,
+	event: DbMutationEvent,
+): boolean {
+	const filter = normalizeSubscriptionFilter(subscriptionArgs);
+	if (!filter) {
+		return true;
+	}
+
+	if (hasPartialOverlap(filter, event.args)) {
+		return true;
+	}
+
+	return event.rows.some((row) => hasPartialOverlap(filter, row));
+}
+
+function getRealtimeStub(
+	env: Record<string, unknown>,
+	options: RegisterHandlersOptions,
+): RealtimeStub | null {
+	const binding = options.realtimeBinding ?? "APPFLARE_REALTIME";
+	const namespace = env[binding] as RealtimeDurableObjectNamespace | undefined;
+	if (!namespace) {
+		return null;
+	}
+
+	const objectName = options.realtimeObjectName ?? "global";
+	const objectId = namespace.idFromName(objectName);
+	return namespace.get(objectId);
+}
+
+async function validateAuthToken(
+	request: Request,
+	env: Record<string, unknown>,
+	options: RegisterHandlersOptions,
+	authToken: string,
+): Promise<{ user: unknown; session: unknown } | null> {
+	const database = env[options.databaseBinding] as D1Database | undefined;
+	if (!database) {
+		return null;
+	}
+
+	const kvNamespace = options.kvBinding
+		? (env[options.kvBinding] as KVNamespace | undefined)
+		: undefined;
+	const headers = new Headers(request.headers);
+	headers.set("authorization", "Bearer " + authToken);
+	const tokenRequest = new Request(request.url, {
+		method: request.method,
+		headers,
+	});
+
+	const session = await resolveSession(
+		tokenRequest,
+		database,
+		kvNamespace,
+		request.cf as IncomingRequestCfProperties | undefined,
+	);
+
+	if (!session?.user) {
+		return null;
+	}
+
+	return session;
+}
+
+function extractUserId(user: unknown): string {
+	if (!isRecord(user)) {
+		return "unknown";
+	}
+
+	const id = user.id;
+	return typeof id === "string" && id.length > 0 ? id : "unknown";
+}
+
+function buildRealtimeWsUrl(requestUrl: string, websocketPath: string): string {
+	const url = new URL(requestUrl);
+	url.pathname = websocketPath;
+	url.search = "";
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	return url.toString();
+}
+
+async function publishMutationEvents(
+	c: { req: { raw: Request }; env: Record<string, unknown> },
+	options: RegisterHandlersOptions,
+	mutationEvents: DbMutationEvent[],
+): Promise<void> {
+	if (mutationEvents.length === 0) {
+		return;
+	}
+
+	const stub = getRealtimeStub(c.env, options);
+	if (!stub) {
+		return;
+	}
+
+	const subscriptionsResponse = await stub.fetch(
+		new Request("https://realtime.internal/subscriptions", {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+			},
+		}),
+	);
+	if (!subscriptionsResponse.ok) {
+		return;
+	}
+
+	const payload = (await subscriptionsResponse.json()) as {
+		subscriptions?: RealtimeSubscription[];
+	};
+	const subscriptions = Array.isArray(payload.subscriptions)
+		? payload.subscriptions
+		: [];
+
+	for (const subscription of subscriptions) {
+		const operation = (realtimeQueryHandlers as Record<
+			string,
+			{
+				definition: {
+					handler: (ctx: AppflareContext, args: unknown) => Promise<unknown> | unknown;
+				};
+				schema: z.ZodTypeAny;
+			}
+		>)[subscription.queryName];
+		if (!operation) {
+			continue;
+		}
+
+		const shouldPublish = mutationEvents.some((event) => {
+			return doesSubscriptionMatchMutation(subscription.args, event);
+		});
+		if (!shouldPublish) {
+			continue;
+		}
+
+		const authSession = await validateAuthToken(
+			c.req.raw,
+			c.env,
+			options,
+			subscription.authToken,
+		);
+		if (!authSession) {
+			continue;
+		}
+
+		const subscriberCtx = await createExecutionContext(c as never, options);
+		subscriberCtx.user = authSession.user as never;
+		subscriberCtx.session = authSession.session as never;
+
+		try {
+			const parsedArgs = operation.schema.parse(subscription.args);
+			const result = await operation.definition.handler(subscriberCtx, parsedArgs);
+			const emitPayload: RealtimeEmitPayload = {
+				token: subscription.token,
+				event: "query:update",
+				payload: {
+					queryName: subscription.queryName,
+					signature: subscription.signature,
+					data: result,
+				},
+			};
+
+			await stub.fetch(
+				new Request("https://realtime.internal/emit", {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+					},
+					body: JSON.stringify(emitPayload),
+				}),
+			);
+		} catch (error) {
+			console.warn("Failed to publish realtime update", subscription.queryName, error);
+		}
+	}
+}
+
+function registerRealtimeRoutes(
+	app: Hono<WorkerEnv>,
+	options: RegisterHandlersOptions,
+): void {
+	const subscribePath = options.realtimeSubscribePath ?? "/realtime/subscribe";
+	const unsubscribePath = "/realtime/unsubscribe";
+	const websocketPath = options.realtimeWebsocketPath ?? "/realtime/ws";
+	const protocol = options.realtimeProtocol ?? "appflare.realtime.v1";
+
+	app.post(subscribePath, async (c) => {
+		const body = await c.req.json().catch(() => ({} as Record<string, unknown>));
+		const queryName = typeof body.queryName === "string" ? body.queryName : "";
+		const authToken = typeof body.authToken === "string" ? body.authToken : "";
+		const rawArgs = isRecord(body.args) ? body.args : {};
+
+		if (!queryName || !authToken) {
+			return c.json({ message: "queryName and authToken are required" }, 400);
+		}
+
+		const operation = (realtimeQueryHandlers as Record<
+			string,
+			{
+				definition: unknown;
+				schema: z.ZodTypeAny;
+			}
+		>)[queryName as RealtimeQueryName];
+		if (!operation) {
+			return c.json({ message: "Unknown queryName" }, 404);
+		}
+
+		const authSession = await validateAuthToken(
+			c.req.raw,
+			c.env,
+			options,
+			authToken,
+		);
+		if (!authSession) {
+			return c.json({ message: "Invalid auth token" }, 401);
+		}
+
+		let args: Record<string, unknown>;
+		try {
+			args = operation.schema.parse(rawArgs) as Record<string, unknown>;
+		} catch (error) {
+			if (error instanceof ZodError) {
+				return c.json({ message: "Invalid query args", issues: error.issues }, 400);
+			}
+			return c.json({ message: "Invalid query args" }, 400);
+		}
+
+		const token = crypto.randomUUID();
+		const signature = createSubscriptionSignature(queryName, args);
+		const stub = getRealtimeStub(c.env, options);
+		if (!stub) {
+			return c.json({ message: "Realtime binding is not configured" }, 500);
+		}
+
+		await stub.fetch(
+			new Request("https://realtime.internal/subscribe", {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+				},
+				body: JSON.stringify({
+					token,
+					signature,
+					queryName,
+					args,
+					authToken,
+					userId: extractUserId(authSession.user),
+					createdAt: Date.now(),
+				}),
+			}),
+		);
+
+		const websocketUrl = buildRealtimeWsUrl(c.req.raw.url, websocketPath);
+		return c.json(
+			{
+				token,
+				signature,
+				websocket: {
+					url: websocketUrl,
+					protocol,
+					params: {
+						tokenParam: "token",
+						authTokenParam: "authToken",
+					},
+				},
+			},
+			200,
+		);
+	});
+
+	app.post(unsubscribePath, async (c) => {
+		const body = await c.req.json().catch(() => ({} as Record<string, unknown>));
+		const token = typeof body.token === "string" ? body.token : "";
+		const authToken = typeof body.authToken === "string" ? body.authToken : "";
+
+		if (!token || !authToken) {
+			return c.json({ message: "token and authToken are required" }, 400);
+		}
+
+		const authSession = await validateAuthToken(
+			c.req.raw,
+			c.env,
+			options,
+			authToken,
+		);
+		if (!authSession) {
+			return c.json({ message: "Invalid auth token" }, 401);
+		}
+
+		const stub = getRealtimeStub(c.env, options);
+		if (!stub) {
+			return c.json({ message: "Realtime binding is not configured" }, 500);
+		}
+
+		const response = await stub.fetch(
+			new Request("https://realtime.internal/unsubscribe", {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+				},
+				body: JSON.stringify({
+					token,
+					authToken,
+				}),
+			}),
+		);
+
+		if (!response.ok) {
+			const payload = (await response.json().catch(() => null)) as {
+				message?: string;
+			} | null;
+			return c.json(
+				{ message: payload?.message ?? "Unable to remove subscription" },
+				response.status,
+			);
+		}
+
+		return c.json({ ok: true }, 200);
+	});
+
+	app.get(websocketPath, async (c) => {
+		const token = c.req.query("token") ?? "";
+		const authToken = c.req.query("authToken") ?? "";
+
+		if (!token || !authToken) {
+			return c.json({ message: "token and authToken are required" }, 400);
+		}
+
+		const authSession = await validateAuthToken(
+			c.req.raw,
+			c.env,
+			options,
+			authToken,
+		);
+		if (!authSession) {
+			return c.json({ message: "Invalid auth token" }, 401);
+		}
+
+		const stub = getRealtimeStub(c.env, options);
+		if (!stub) {
+			return c.json({ message: "Realtime binding is not configured" }, 500);
+		}
+
+		const wsUrl = new URL("https://realtime.internal/ws");
+		wsUrl.searchParams.set("token", token);
+		wsUrl.searchParams.set("authToken", authToken);
+		return stub.fetch(new Request(wsUrl.toString(), c.req.raw));
+	});
+}
+
+export class AppflareRealtimeDurableObject {
+	private readonly subscriptions = new Map<string, RealtimeSubscription>();
+	private readonly sockets = new Map<string, WebSocket>();
+
+	public constructor(_state: unknown) {}
+
+	public async fetch(request: Request): Promise<Response> {
+		const url = new URL(request.url);
+
+		if (request.method === "POST" && url.pathname === "/subscribe") {
+			const payload = (await request.json().catch(() => null)) as RealtimeSubscription | null;
+			if (!payload?.token || !payload.queryName || !payload.authToken) {
+				return new Response(JSON.stringify({ message: "Invalid subscription payload" }), {
+					status: 400,
+					headers: { "content-type": "application/json" },
+				});
+			}
+
+			this.subscriptions.set(payload.token, payload);
+			return new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			});
+		}
+
+		if (request.method === "POST" && url.pathname === "/subscriptions") {
+			return new Response(
+				JSON.stringify({ subscriptions: Array.from(this.subscriptions.values()) }),
+				{
+					status: 200,
+					headers: { "content-type": "application/json" },
+				},
+			);
+		}
+
+		if (request.method === "POST" && url.pathname === "/unsubscribe") {
+			const payload = (await request.json().catch(() => null)) as {
+				token?: unknown;
+				authToken?: unknown;
+			} | null;
+			const token = typeof payload?.token === "string" ? payload.token : "";
+			const authToken =
+				typeof payload?.authToken === "string" ? payload.authToken : "";
+
+			if (!token || !authToken) {
+				return new Response(
+					JSON.stringify({ message: "token and authToken are required" }),
+					{
+						status: 400,
+						headers: { "content-type": "application/json" },
+					},
+				);
+			}
+
+			const existing = this.subscriptions.get(token);
+			if (!existing || existing.authToken !== authToken) {
+				return new Response(JSON.stringify({ message: "Subscription not found" }), {
+					status: 404,
+					headers: { "content-type": "application/json" },
+				});
+			}
+
+			const socket = this.sockets.get(token);
+			if (socket && socket.readyState === 1) {
+				socket.close();
+			}
+
+			this.sockets.delete(token);
+			this.subscriptions.delete(token);
+
+			return new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			});
+		}
+
+		if (request.method === "POST" && url.pathname === "/emit") {
+			const payload = (await request.json().catch(() => null)) as RealtimeEmitPayload | null;
+			if (!payload?.token || !payload.event) {
+				return new Response(JSON.stringify({ message: "Invalid emit payload" }), {
+					status: 400,
+					headers: { "content-type": "application/json" },
+				});
+			}
+
+			const socket = this.sockets.get(payload.token);
+			if (socket && socket.readyState === 1) {
+				socket.send(
+					JSON.stringify({
+						event: payload.event,
+						payload: payload.payload,
+					}),
+				);
+			}
+
+			return new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			});
+		}
+
+		if (request.method === "GET" && url.pathname === "/ws") {
+			const token = url.searchParams.get("token") ?? "";
+			const authToken = url.searchParams.get("authToken") ?? "";
+			const subscription = this.subscriptions.get(token);
+			if (!subscription || !authToken || subscription.authToken !== authToken) {
+				return new Response("Unauthorized", { status: 401 });
+			}
+
+			const pair = new WebSocketPair();
+			const [clientSocket, serverSocket] = Object.values(pair);
+			serverSocket.accept();
+			this.sockets.set(token, serverSocket);
+
+			const release = () => {
+				this.sockets.delete(token);
+			};
+
+			serverSocket.addEventListener("close", release);
+			serverSocket.addEventListener("error", release);
+			serverSocket.addEventListener("message", (event) => {
+				if (String(event.data ?? "").trim() === "ping") {
+					serverSocket.send(JSON.stringify({ event: "pong" }));
+				}
+			});
+
+			return new Response(null, {
+				status: 101,
+				webSocket: clientSocket,
+			} as ResponseInit & { webSocket: WebSocket });
+		}
+
+		return new Response("Not found", { status: 404 });
+	}
+}
+
+export function registerGeneratedHandlers(
+	app: Hono<WorkerEnv>,
+	options: RegisterHandlersOptions,
+): void {
+	registerRealtimeRoutes(app, options);${queryRoutes || "\n\t// No query handlers discovered under scanDir/queries.\n"}${mutationRoutes || "\n\t// No mutation handlers discovered under scanDir/mutations.\n"}
+}
+
+function parseExpiresIn(value: string | undefined): number | undefined {
+	if (!value) {
+		return undefined;
+	}
+
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		return undefined;
+	}
+
+	return Math.floor(parsed);
+}
+
+function toStoragePath(path: string): string {
+	const trimmed = path.trim();
+	if (!trimmed) {
+		throw new Error("Storage path is required");
+	}
+
+	return trimmed.startsWith("/") ? trimmed : "/" + trimmed;
+}
+
+function readStoragePath(c: { req: { query: (name: string) => string | undefined } }): string {
+	const path = c.req.query("path") ?? "";
+	return toStoragePath(path);
+}
+
+export function registerGeneratedStorageRoutes(
+	app: Hono<WorkerEnv>,
+	options: RegisterHandlersOptions,
+): void {
+	app.post("/storage/upload", async (c) => {
+		const ctx = await createExecutionContext(c, options);
+		try {
+			const body = await c.req.json().catch(() => ({} as Record<string, unknown>));
+			const path = toStoragePath(String(body.path ?? ""));
+			const contentType =
+				typeof body.contentType === "string" ? body.contentType : undefined;
+			const expiresIn =
+				typeof body.expiresIn === "number" && body.expiresIn > 0
+					? Math.floor(body.expiresIn)
+					: undefined;
+
+			const url = await ctx.storage.signedUrl({
+				path,
+				method: "PUT",
+				expiresIn,
+				contentType,
+			});
+
+			return c.json({
+				url,
+				method: "PUT",
+				path,
+				expiresIn: expiresIn ?? 300,
+			}, 200);
+		} catch (error) {
+			if (error instanceof AppflareHandledError) {
+				return c.json(error.payload, error.status);
+			}
+
+			return c.json(
+				{ message: (error as Error).message ?? "Unable to create upload URL" },
+				400,
+			);
+		}
+	});
+
+	app.get("/storage/download", async (c) => {
+		const ctx = await createExecutionContext(c, options);
+		try {
+			const path = readStoragePath(c);
+			const fileName = c.req.query("fileName") ?? undefined;
+			const expiresIn = parseExpiresIn(c.req.query("expiresIn"));
+			const url = await ctx.storage.signedUrl({
+				path,
+				method: "GET",
+				expiresIn,
+				downloadAsAttachment: true,
+				fileName,
+			});
+
+			return c.json({
+				url,
+				method: "GET",
+				path,
+				disposition: "attachment",
+			}, 200);
+		} catch (error) {
+			if (error instanceof AppflareHandledError) {
+				return c.json(error.payload, error.status);
+			}
+
+			return c.json(
+				{ message: (error as Error).message ?? "Unable to create download URL" },
+				400,
+			);
+		}
+	});
+
+	app.get("/storage/preview", async (c) => {
+		const ctx = await createExecutionContext(c, options);
+		try {
+			const path = readStoragePath(c);
+			const expiresIn = parseExpiresIn(c.req.query("expiresIn"));
+			const url = await ctx.storage.signedUrl({
+				path,
+				method: "GET",
+				expiresIn,
+				downloadAsAttachment: false,
+			});
+
+			return c.json({
+				url,
+				method: "GET",
+				path,
+				disposition: "inline",
+			}, 200);
+		} catch (error) {
+			if (error instanceof AppflareHandledError) {
+				return c.json(error.payload, error.status);
+			}
+
+			return c.json(
+				{ message: (error as Error).message ?? "Unable to create preview URL" },
+				400,
+			);
+		}
+	});
+
+	app.delete("/storage/object", async (c) => {
+		const ctx = await createExecutionContext(c, options);
+		try {
+			const path = readStoragePath(c);
+			await ctx.storage.delete({ path });
+			return c.json({ ok: true, path }, 200);
+		} catch (error) {
+			if (error instanceof AppflareHandledError) {
+				return c.json(error.payload, error.status);
+			}
+
+			return c.json(
+				{ message: (error as Error).message ?? "Unable to delete object" },
+				400,
+			);
+		}
+	});
+
+	app.get("/storage/list", async (c) => {
+		const ctx = await createExecutionContext(c, options);
+		try {
+			const prefix = c.req.query("prefix") ?? undefined;
+			const cursor = c.req.query("cursor") ?? undefined;
+			const delimiter = c.req.query("delimiter") ?? undefined;
+			const limitValue = c.req.query("limit");
+			const parsedLimit = limitValue ? Number(limitValue) : undefined;
+			const limit =
+				typeof parsedLimit === "number" && Number.isFinite(parsedLimit) && parsedLimit > 0
+					? Math.floor(parsedLimit)
+					: undefined;
+			const methodValue = c.req.query("method");
+			const method: StorageMethod | undefined =
+				methodValue === "download" ||
+				methodValue === "get" ||
+				methodValue === "delete" ||
+				methodValue === "list" ||
+				methodValue === "put" ||
+				methodValue === "preview"
+					? methodValue
+					: undefined;
+
+			const result = await ctx.storage.list({
+				prefix,
+				cursor,
+				delimiter,
+				limit,
+				method,
+			});
+
+			return c.json(result, 200);
+		} catch (error) {
+			if (error instanceof AppflareHandledError) {
+				return c.json(error.payload, error.status);
+			}
+
+			return c.json(
+				{ message: (error as Error).message ?? "Unable to list storage objects" },
+				400,
+			);
+		}
+	});
+}
+
+export async function executeScheduledBatch(
+	batch: { messages?: Array<{ body?: unknown }> },
+	env: Record<string, unknown>,
+	options: RegisterHandlersOptions,
+): Promise<void> {
+	if (!batch?.messages || batch.messages.length === 0) {
+		return;
+	}
+
+	const ctx = createSchedulerExecutionContext(env, options);
+
+	for (const message of batch.messages) {
+		const body = (message?.body ?? {}) as QueueMessageBody;
+		const task = body.task;
+		if (!task) {
+			console.warn("Scheduler message missing task field");
+			continue;
+		}
+
+		const operation = (schedulerHandlers as Record<string, {
+			definition: {
+				handler: (ctx: typeof ctx, args: unknown) => Promise<void> | void;
+			};
+			schema: z.ZodTypeAny;
+		}>)[task];
+
+		if (!operation) {
+			console.warn("Unknown scheduler task", task);
+			continue;
+		}
+
+		try {
+			const payloadValue = body.payload === null ? undefined : body.payload;
+			const parsed = operation.schema.parse(payloadValue);
+			await operation.definition.handler(ctx, parsed);
+		} catch (error) {
+			if (error instanceof ZodError) {
+				console.error("Invalid scheduler payload", task, error.issues);
+				continue;
+			}
+
+			console.error("Scheduler task failed", task, error);
+		}
+	}
+}
+
+export async function executeCronTriggers(
+	controller: { cron: string },
+	env: Record<string, unknown>,
+	options: RegisterHandlersOptions,
+): Promise<void> {
+	const cronValue = controller?.cron;
+	if (!cronValue) {
+		return;
+	}
+
+	if (cronHandlers.length === 0) {
+		return;
+	}
+
+	const ctx = createSchedulerExecutionContext(env, options);
+
+	for (const cronEntry of cronHandlers) {
+		if (!cronEntry.cronTriggers.includes(cronValue)) {
+			continue;
+		}
+
+		try {
+			await cronEntry.definition.handler(ctx);
+		} catch (error) {
+			console.error("Cron task failed", cronEntry.taskName, error);
+		}
+	}
+}
+`;
+}