appflare 0.1.0 → 0.1.11

package/cli/templates/core/client-modules/handlers/index.ts

@@ -230,11 +230,14 @@ function renderRouteFactory(operation: HttpOperation): string {
 				}
 
 				if (!resolvedAuthToken) {
-					onError?.(
-						new Error(
-							"authToken is required for realtime subscribe (pass options.authToken or Authorization Bearer header)",
-						),
+					const authError = new Error(
+						"authToken is required for realtime subscribe (pass options.authToken or Authorization Bearer header)",
 					);
+					if (onError) {
+						onError(authError);
+					} else {
+						console.warn("[appflare:subscribe]", authError.message);
+					}
 					return;
 				}
 
@@ -295,7 +298,11 @@ function renderRouteFactory(operation: HttpOperation): string {
 					onError?.(new Error("Realtime websocket error"));
 				});
 			} catch (error) {
-				onError?.(error);
+				if (onError) {
+					onError(error);
+				} else {
+					console.warn("[appflare:subscribe] Subscription failed:", error);
+				}
 			}
 		})();
 

package/cli/templates/handlers/README.md

@@ -191,6 +191,94 @@ Execution contexts store these as `ctx.mutationEvents`, and mutation routes call
 
 ---
 
+## DB aggregate helpers
+
+Generated `ctx.db.<table>` wrappers now include aggregate helpers:
+
+- `count(args?)`
+  - `where?: WhereInput<TModel>`
+  - `field?: keyof TModel | string` (supports relation paths, e.g. `comments.id`)
+  - `distinct?: boolean`
+  - `with?: QueryWithInput<...>`
+  - returns `Promise<number>`
+- `avg(args)`
+  - `where?: WhereInput<TModel>`
+  - `field: NumericFieldKey<TModel> | string` (supports relation paths, e.g. `comments.id`)
+  - `distinct?: boolean`
+  - `with?: QueryWithInput<...>`
+  - returns `Promise<number | null>`
+
+Aggregate behavior with `with`:
+
+- Relation `with.where` and nested `with` filters are treated as parent-row constraints for aggregates (EXISTS-style).
+- For `count` with `with`, `distinct` defaults to `true` when `field` is provided.
+- Nested relation paths are supported recursively for both `count` and `avg`.
+
+Relation `with` aggregates on `findMany`/`findFirst`:
+
+- You can request per-parent relation aggregates directly inside `with` using `_count` and `_avg`.
+- Result rows include a sibling `<relationName>Aggregate` object.
+- `_avg` returns `0` for parents with no related rows.
+
+Example:
+
+```ts
+const total = await ctx.db.posts.count({
+	where: { ownerId: user.id },
+});
+
+const uniqueOwners = await ctx.db.posts.count({
+	field: "ownerId",
+	distinct: true,
+});
+
+const averageId = await ctx.db.posts.avg({
+	field: "id",
+	where: { ownerId: user.id },
+});
+
+const postsWithMatchingComments = await ctx.db.posts.count({
+	with: {
+		comments: {
+			where: {
+				id: { gte: 10000 },
+			},
+		},
+	},
+});
+
+const averageCommentId = await ctx.db.posts.avg({
+	field: "comments.id",
+	with: {
+		comments: {
+			where: {
+				id: { gte: 10000 },
+			},
+		},
+	},
+});
+
+const postsWithCommentStats = await ctx.db.posts.findMany({
+	with: {
+		comments: {
+			_count: true,
+			_avg: {
+				id: true,
+			},
+		},
+	},
+});
+
+const firstPostCommentCount =
+	postsWithCommentStats[0]?.commentsAggregate.count ?? 0;
+const firstPostAverageCommentId =
+	postsWithCommentStats[0]?.commentsAggregate.avg.id ?? 0;
+```
+
+`geoWithin.latitudeField` and `geoWithin.longitudeField` are now typed to table keys (instead of free-form strings). Invalid field names still no-op the geo filter at runtime, but now emit a warning.
+
+---
+
 ## Durable Object responsibilities
 
 `AppflareRealtimeDurableObject` keeps in-memory maps for:

package/cli/templates/handlers/auth.ts

@@ -1,6 +1,7 @@
 export function generateAuth(): string {
 	return `
 
+import { getHeaders } from "./server";
 export async function resolveSession(
 \trequest: Request,
 \tdatabase: D1Database,
@@ -17,7 +18,7 @@ export async function resolveSession(
 
 \ttry {
 \t\tconst session = await auth.api.getSession({
-\t\t\theaders: request.headers,
+\t\t\theaders: getHeaders(request.headers),
 \t\t});
 
 \t\treturn {

package/cli/templates/handlers/generators/registration/modules/cron.ts

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

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);
+	});
+}
+`;