appflare 0.1.1 → 0.1.12

package/cli/templates/core/wrangler.ts

@@ -91,7 +91,7 @@ export function generateWranglerJson(
 					migrations: [
 						{
 							tag: "appflare-realtime-v1",
-							new_classes: [config.config.realtime.className],
+							new_sqlite_classes: [config.config.realtime.className],
 						},
 					],
 				}

package/cli/templates/handlers/generators/registration/modules/realtime/auth.ts

@@ -0,0 +1,75 @@
+export const realtimeAuthModule = `
+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);
+	headers.delete("upgrade");
+	headers.delete("connection");
+	for (const key of [...headers.keys()]) {
+		if (key.toLowerCase().startsWith("sec-websocket")) {
+			headers.delete(key);
+		}
+	}
+	const tokenRequest = new Request(request.url, {
+		method: "GET",
+		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();
+}
+`;

package/cli/templates/handlers/generators/registration/modules/realtime/durable-object.ts

@@ -0,0 +1,144 @@
+export const realtimeDurableObjectModule = `
+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" || url.pathname.endsWith("/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" }));
+				}
+			});
+
+			const requestedProtocol = request.headers.get("Sec-WebSocket-Protocol");
+			const headers = new Headers();
+			if (requestedProtocol) {
+				headers.set("Sec-WebSocket-Protocol", requestedProtocol);
+			}
+
+			return new Response(null, {
+				status: 101,
+				webSocket: clientSocket,
+				headers,
+			} as ResponseInit & { webSocket: WebSocket });
+		}
+
+		return new Response("Not found", { status: 404 });
+	}
+}
+`;

package/cli/templates/handlers/generators/registration/modules/realtime/index.ts

@@ -0,0 +1,15 @@
+import { realtimeAuthModule } from "./auth";
+import { realtimeDurableObjectModule } from "./durable-object";
+import { realtimePublisherModule } from "./publisher";
+import { realtimeRoutesModule } from "./routes";
+import { realtimeTypesModule } from "./types";
+import { realtimeUtilsModule } from "./utils";
+
+export const realtimeModule = [
+	realtimeTypesModule,
+	realtimeUtilsModule,
+	realtimeAuthModule,
+	realtimePublisherModule,
+	realtimeRoutesModule,
+	realtimeDurableObjectModule,
+].join("\n\n");

package/cli/templates/handlers/generators/registration/modules/realtime/publisher.ts

@@ -0,0 +1,105 @@
+export const realtimePublisherModule = `
+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 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 matchPlan = await buildRealtimeQueryMatchPlan(
+				operation.definition.handler,
+				parsedArgs,
+				{
+					user: subscriberCtx.user,
+					session: subscriberCtx.session,
+				},
+			);
+			const shouldPublish = mutationEvents.some((event) => {
+				return doesSubscriptionMatchMutation(matchPlan, event);
+			});
+			if (!shouldPublish) {
+				continue;
+			}
+
+			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);
+		}
+	}
+}
+`;

package/cli/templates/handlers/generators/registration/modules/realtime/routes.ts

@@ -0,0 +1,171 @@
+export const realtimeRoutesModule = `
+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);
+		}
+
+		return stub.fetch(c.req.raw);
+	});
+}
+`;

package/cli/templates/handlers/generators/registration/modules/realtime/types.ts

@@ -0,0 +1,30 @@
+export const realtimeTypesModule = `
+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>;
+`;