appflare 0.0.28 → 0.1.1

package/cli/templates/handlers/README.md

@@ -0,0 +1,353 @@
+# Handlers Template System (with Realtime Durable Objects)
+
+This directory contains code-generation templates used by the Appflare CLI to build runtime handler files in `_generated/`.
+
+The generated runtime now supports **realtime updates** using a **single global Cloudflare Durable Object** and websocket fanout.
+
+---
+
+## What this template set generates
+
+From this directory, the CLI generates:
+
+- `handlers.ts`
+- `handlers.context.ts`
+- `handlers.execution.ts`
+- `handlers.routes.ts`
+
+Key behavior added for realtime:
+
+1. Endpoint-first subscriptions (`POST /realtime/subscribe`)
+2. WebSocket connect endpoint (`GET /realtime/ws`)
+3. Per-subscription `token` + `signature`
+4. Query identity contract: `[dirName]/[fileName]/[functionName]`
+5. Args validation against discovered query schema (args-derived keys only)
+6. Mutation-to-query invalidation with **partial filter overlap** matching
+7. Push updated query result to matching subscribers only
+
+---
+
+## Realtime architecture
+
+### Components
+
+- **Generated query routes** (`GET /queries/...`)
+- **Generated mutation routes** (`POST /mutations/...`)
+- **Realtime subscription endpoint** (`POST /realtime/subscribe`)
+- **Realtime websocket endpoint** (`GET /realtime/ws?token=...&authToken=...`)
+- **Global Durable Object class**: `AppflareRealtimeDurableObject`
+
+### Data flow
+
+1. Client calls `POST /realtime/subscribe` with:
+   - `queryName`: `[dir]/[file]/[function]`
+   - `args`: query arguments
+   - `authToken`: bearer token
+2. Server validates:
+   - query exists
+   - args parse against that query Zod schema
+   - auth token resolves to a user session
+3. Server stores subscription inside the global DO and returns:
+   - `token`
+   - `signature`
+   - websocket URL/protocol metadata
+4. Client opens websocket at `GET /realtime/ws?token=...&authToken=...`.
+5. On any mutation (`insert`, `update`, `delete`, `upsert`), generated `db` wrappers collect mutation events.
+6. Matching subscriptions are re-executed (same query + same validated args) and pushed over websocket as `query:update`.
+
+---
+
+## Identity and signatures
+
+### Query identity
+
+Query names are generated from discovered source layout:
+
+`[dirName]/[fileName]/[functionName]`
+
+Examples:
+
+- `users/profile/getProfile`
+- `root/test/getTest`
+
+### Signature
+
+Signature is generated from:
+
+- `queryName`
+- normalized `args`
+
+The generated runtime normalizes/sorts object keys before stringifying, so logically equivalent payloads produce a stable signature.
+
+---
+
+## Partial filter overlap matching
+
+When mutations run, subscribers are selected using overlap logic (not strict equality).
+
+High-level rules:
+
+- Scalars: equal values overlap
+- Arrays: overlap if any element overlaps
+- Objects: overlap if any shared key overlaps recursively
+- Matching checks both:
+  - mutation input args (`set`, `where`, `values`, etc.)
+  - returned mutation rows
+
+This means subscriptions react when filters intersect mutation impact, without requiring exact filter identity.
+
+---
+
+## Authentication model
+
+### Subscribe
+
+`POST /realtime/subscribe` requires `authToken` in body.
+
+The runtime creates a request with `Authorization: Bearer <authToken>` and calls `resolveSession(...)`.
+
+If no user resolves, response is `401`.
+
+### WebSocket connect
+
+`GET /realtime/ws` requires both query params:
+
+- `token`
+- `authToken`
+
+Server validates token ownership and auth token before websocket upgrade.
+
+---
+
+## Endpoint contracts
+
+### 1) Subscribe
+
+`POST /realtime/subscribe`
+
+Request:
+
+```json
+{
+	"queryName": "users/profile/getProfile",
+	"args": { "userId": "u_123" },
+	"authToken": "<token>"
+}
+```
+
+Success response:
+
+```json
+{
+	"token": "<subscription-token>",
+	"signature": "users/profile/getProfile::{\"userId\":\"u_123\"}",
+	"websocket": {
+		"url": "wss://api.example.com/realtime/ws",
+		"protocol": "appflare.realtime.v1",
+		"params": {
+			"tokenParam": "token",
+			"authTokenParam": "authToken"
+		}
+	}
+}
+```
+
+### 2) WebSocket connect
+
+`GET /realtime/ws?token=<token>&authToken=<authToken>`
+
+Server pushes messages like:
+
+```json
+{
+	"event": "query:update",
+	"payload": {
+		"queryName": "users/profile/getProfile",
+		"signature": "...",
+		"data": { "id": "u_123", "name": "Ada" }
+	}
+}
+```
+
+Heartbeat support:
+
+- client sends: `ping`
+- server replies: `{"event":"pong"}`
+
+---
+
+## Mutation event capture
+
+`createQueryDb(...)` now accepts options with `onMutation`.
+
+The generated wrappers for `insert`, `update`, `upsert`, and `delete` emit:
+
+- operation kind
+- table name
+- mutation args
+- returned rows
+
+Execution contexts store these as `ctx.mutationEvents`, and mutation routes call `publishMutationEvents(...)` after successful execution.
+
+---
+
+## 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:
+
+- `subscriptions` (`token -> metadata`)
+- `sockets` (`token -> websocket`)
+
+Supported internal routes:
+
+- `POST /subscribe`
+- `POST /subscriptions`
+- `POST /emit`
+- `GET /ws`
+
+This design centralizes fanout in one global app DO instance.
+
+---
+
+## Generated client support
+
+The client generator exposes realtime helper APIs:
+
+- `appflare.realtime.subscribe(...)`
+
+Types include:
+
+- `RealtimeSubscriptionRequest`
+- `RealtimeSubscriptionResponse`
+
+The client performs endpoint-first subscription; websocket connection is then established using returned metadata.
+
+---
+
+## Configuration knobs (from app config)
+
+Realtime defaults are normalized from `realtime` config:
+
+- `enabled` (default `true`)
+- `binding` (default `APPFLARE_REALTIME`)
+- `className` (default `AppflareRealtimeDurableObject`)
+- `objectName` (default `global`)
+- `subscribePath` (default `/realtime/subscribe`)
+- `websocketPath` (default `/realtime/ws`)
+- `protocol` (default `appflare.realtime.v1`)
+
+Wrangler generation automatically emits:
+
+- `durable_objects.bindings`
+- `migrations` with DO class
+
+---
+
+## Notes and limitations
+
+1. Current DO storage is in-memory; restarts drop live subscriptions.
+2. Matching is overlap-based and intentionally permissive for realtime invalidation.
+3. Query re-execution occurs on matching mutation events and can be tuned later for batching/debouncing.
+
+---
+
+## Safe extension points
+
+- `registration.ts`:
+  - realtime routes, token/session policy, protocol envelopes
+- `types.ts`:
+  - mutation event payload contracts
+- `generators/context/context-creation.ts`:
+  - context-level mutation event tracking
+- `utils/handler-discovery.ts`:
+  - query identity strategy
+
+After template changes, regenerate and validate `_generated` output.

package/cli/templates/handlers/auth.ts

@@ -0,0 +1,37 @@
+export function generateAuth(): string {
+	return `
+
+import { getHeaders } from "./server";
+export async function resolveSession(
+\trequest: Request,
+\tdatabase: D1Database,
+\tkvNamespace?: KVNamespace,
+\tcf?: IncomingRequestCfProperties,
+): Promise<{ user: unknown; session: unknown }> {
+\tconst auth = createAuth(
+\t\t{
+\t\t\tDATABASE: database,
+\t\t\tKV: kvNamespace,
+\t\t},
+\t\tcf,
+\t);
+
+\ttry {
+\t\tconst session = await auth.api.getSession({
+\t\t\theaders: getHeaders(request.headers),
+\t\t});
+
+\t\treturn {
+\t\t\tuser: (session as any)?.user ?? null,
+\t\t\tsession: (session as any)?.session ?? null,
+\t\t};
+\t} catch {
+\t\treturn {
+\t\t\tuser: null,
+\t\t\tsession: null,
+\t\t};
+\t}
+}
+
+`;
+}

package/cli/templates/handlers/execution.ts

@@ -0,0 +1,39 @@
+export function generateExecution(): string {
+	return `
+export async function executeOperation(
+	c: Context<WorkerEnv>,
+\toperation: RegisteredOperation<ZodRawShape, unknown>,
+	args: unknown,
+\tctx: AppflareContext,
+): Promise<Response> {
+	if (operation.definition.authRequired && !ctx.user) {
+		ctx.error(401, "Unauthorized");
+	}
+
+	if (operation.definition.middleware) {
+		await operation.definition.middleware(ctx, args as never, c.req.raw);
+	}
+
+	const result = await operation.definition.handler(ctx, args as never);
+
+\treturn c.json(result, 200);
+}
+
+export function handleOperationError(
+	c: Context<WorkerEnv>,
+	error: unknown,
+	validationMessage: string,
+): Response {
+	if (error instanceof AppflareHandledError) {
+		return c.json(error.payload, error.status);
+	}
+
+	if (error instanceof ZodError) {
+		return c.json({ message: validationMessage, issues: error.issues }, 400);
+	}
+
+	return c.json({ message: (error as Error).message ?? "Unknown error" }, 500);
+}
+
+`;
+}

package/cli/templates/handlers/generators/context/context-creation.ts

@@ -0,0 +1,80 @@
+export function generateContextCreation(defaultR2Binding?: string): string {
+	return `
+export function createSchedulerExecutionContext(
+	env: Record<string, unknown>,
+	options: RegisterHandlersOptions,
+): AppflareContext {
+	const database = env[options.databaseBinding] as D1Database;
+	const r2Binding = options.r2Binding ?? ${JSON.stringify(defaultR2Binding ?? "")};
+	const storageBucket = r2Binding
+		? (env[r2Binding] as R2BucketBinding | undefined)
+		: undefined;
+	const db = createDb(database);
+	const mutationEvents = [] as AppflareContext["mutationEvents"];
+	const schedulerBinding = options.schedulerBinding ?? "APPFLARE_SCHEDULER_QUEUE";
+	const schedulerQueue = env[schedulerBinding] as SchedulerQueueBinding | undefined;
+	const helpers = createContextErrorHelpers();
+	const ctx = {
+		$db: db,
+		db: createQueryDb(db, {
+			onMutation: (event) => {
+				mutationEvents.push(event);
+			},
+		}),
+		mutationEvents,
+		user: null as never,
+		session: null as never,
+		context: null as never,
+		scheduler: createScheduler(schedulerQueue),
+		storage: null as never,
+		...helpers,
+	} as AppflareContext;
+
+	ctx.storage = createStorageApi(ctx, storageBucket);
+	return ctx;
+}
+
+export async function createExecutionContext(
+	c: Context<WorkerEnv>,
+	options: RegisterHandlersOptions,
+): Promise<AppflareContext> {
+	const database = c.env[options.databaseBinding] as D1Database;
+	const r2Binding = options.r2Binding ?? ${JSON.stringify(defaultR2Binding ?? "")};
+	const storageBucket = r2Binding
+		? (c.env[r2Binding] as R2BucketBinding | undefined)
+		: undefined;
+	const kvNamespace = options.kvBinding
+		? (c.env[options.kvBinding] as KVNamespace)
+		: undefined;
+	const db = createDb(database);
+	const mutationEvents = [] as AppflareContext["mutationEvents"];
+	const { user, session } = await resolveSession(
+		c.req.raw,
+		database,
+		kvNamespace,
+		c.req.raw.cf as IncomingRequestCfProperties | undefined,
+	);
+	const schedulerBinding = options.schedulerBinding ?? "APPFLARE_SCHEDULER_QUEUE";
+	const schedulerQueue = c.env[schedulerBinding] as SchedulerQueueBinding | undefined;
+	const helpers = createContextErrorHelpers();
+	const ctx = {
+		$db: db,
+		db: createQueryDb(db, {
+			onMutation: (event) => {
+				mutationEvents.push(event);
+			},
+		}),
+		mutationEvents,
+		user,
+		session,
+		context: c,
+		scheduler: createScheduler(schedulerQueue),
+		storage: null as never,
+		...helpers,
+	} as AppflareContext;
+
+	ctx.storage = createStorageApi(ctx, storageBucket);
+	return ctx;
+}
+`;
+}

package/cli/templates/handlers/generators/context/error-helpers.ts

@@ -0,0 +1,11 @@
+export function generateErrorHelpers(): string {
+	return `
+function createContextErrorHelpers() {
+	return {
+		error: (status: number, message: string, details?: unknown) => {
+			throw new AppflareHandledError(status, { message, details });
+		},
+	};
+}
+`;
+}

package/cli/templates/handlers/generators/context/scheduler.ts

@@ -0,0 +1,24 @@
+export function generateSchedulerFunctions(): string {
+	return `
+export function createScheduler(
+	queue?: SchedulerQueueBinding,
+): Scheduler {
+	return {
+		enqueue: async (task, ...args) => {
+			const [payload, options] = args as [unknown, SchedulerEnqueueOptions | undefined];
+			if (!queue) {
+				throw new Error("Scheduler queue binding is not configured");
+			}
+
+			await queue.send(
+				{
+					task,
+					payload,
+				},
+				options,
+			);
+		},
+	};
+}
+`;
+}

package/cli/templates/handlers/generators/context/storage-api.ts

@@ -0,0 +1,112 @@
+export function generateStorageApi(): string {
+	return `
+function createStorageApi(
+	ctx: AppflareContext,
+	bucket: R2BucketBinding | undefined,
+): AppflareStorage {
+	const assertAuthorized = async (args: StorageAuthorizationArgs): Promise<void> => {
+		const allowed = await isStorageAllowed(ctx, args);
+		if (!allowed) {
+			ctx.error(403, "Storage access denied", {
+				path: args.path,
+				method: args.method,
+			});
+		}
+	};
+
+	const requireBucket = (): R2BucketBinding => {
+		if (!bucket) {
+			throw new Error(
+				"R2 binding is not configured. Set r2 in appflare.config.ts and regenerate artifacts.",
+			);
+		}
+		return bucket;
+	};
+
+	return {
+		put: async (args) => {
+			const path = normalizeStoragePath(args.path);
+			await assertAuthorized({
+				path: "/" + path,
+				method: "put",
+				contentType: args.contentType,
+			});
+
+			return requireBucket().put(path, args.body, {
+				httpMetadata: {
+					...(args.httpMetadata ?? {}),
+					...(args.contentType ? { contentType: args.contentType } : {}),
+				},
+				customMetadata: args.customMetadata,
+			});
+		},
+		get: async (args) => {
+			const path = normalizeStoragePath(args.path);
+			const method = normalizeStorageMethod(args.method);
+			await assertAuthorized({
+				path: "/" + path,
+				method,
+			});
+
+			return requireBucket().get(path, {
+				onlyIf: args.onlyIf,
+				range: args.range,
+			});
+		},
+		delete: async (args) => {
+			const path = normalizeStoragePath(args.path);
+			await assertAuthorized({
+				path: "/" + path,
+				method: "delete",
+			});
+
+			await requireBucket().delete(path);
+		},
+		list: async (args = {}) => {
+			await assertAuthorized({
+				path: "/" + (args.prefix ?? ""),
+				method: args.method ?? "list",
+			});
+
+			return requireBucket().list({
+				prefix: args.prefix,
+				cursor: args.cursor,
+				limit: args.limit,
+				delimiter: args.delimiter,
+				include: args.include,
+			});
+		},
+		signedUrl: async (args) => {
+			const path = normalizeStoragePath(args.path);
+			const requestMethod = args.method ?? "GET";
+			const method: StorageMethod =
+				requestMethod === "PUT"
+					? "put"
+					: requestMethod === "DELETE"
+						? "delete"
+						: args.downloadAsAttachment === false
+							? "preview"
+							: "download";
+
+			await assertAuthorized({
+				path: "/" + path,
+				method,
+				contentType: args.contentType,
+			});
+
+			const currentBucket = requireBucket();
+			if (typeof currentBucket.createPresignedUrl !== "function") {
+				throw new Error("R2 createPresignedUrl is unavailable for this runtime binding");
+			}
+
+			const signedRequest = buildSignedRequest(args, path);
+			const signedUrl = await currentBucket.createPresignedUrl(signedRequest, {
+				expiresIn: args.expiresIn ?? 60 * 5,
+			});
+
+			return signedUrl.toString();
+		},
+	};
+}
+`;
+}