@frockbot/cloudflare 0.0.0 → 0.7.291

package/src/push.ts

@@ -0,0 +1,498 @@
+import { BRAND_V1 } from "#brand";
+import { isPublicIdentifier } from "@frockbot/core/configuration";
+import { withDeadlineV1 } from "@frockbot/core/deadline";
+
+/**
+ * Which app holds an FCM token. An iPhone's token reaches APNs, which draws
+ * the alert itself and needs an `apns` block to say what to draw; an Android
+ * app draws its own from the data alone.
+ */
+export type PushPlatformV1 = "android" | "ios";
+const PUSH_PLATFORMS_V1: readonly PushPlatformV1[] = ["android", "ios"];
+
+export interface PushDevice {
+  deviceId: string;
+  token?: string;
+  /** Set with the token it describes. */
+  platform?: PushPlatformV1;
+  activeBotId?: string;
+  updatedAt: number;
+}
+export interface PushUpdate {
+  botId: string;
+  /**
+   * A Group Chat message: `botId` is its author, and the group is what the
+   * alert opens, what a device reading it defers to, and whose cursor it is.
+   */
+  groupId?: string;
+  cursor: string;
+  kind: "message" | "read";
+  title?: string;
+  body?: string;
+  notify?: boolean;
+}
+export interface PushRegistration {
+  deviceId: string;
+  token?: string;
+  platform?: PushPlatformV1;
+  activeBotId?: string;
+  remove?: boolean;
+}
+const DEVICE_PREFIX = "push:device:";
+const DELIVERY_PREFIX = "push:delivery:";
+const PRESENCE_MS = 15_000;
+
+export function decodePushRegistration(input: unknown): PushRegistration {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Invalid push registration");
+  const value = input as Record<string, unknown>;
+  if (
+    Object.keys(value).some(
+      (key) =>
+        !["deviceId", "token", "platform", "activeBotId", "remove"].includes(
+          key,
+        ),
+    ) ||
+    !isPublicIdentifier(value.deviceId)
+  )
+    throw new Error("Invalid device id");
+  if (
+    value.token !== undefined &&
+    (typeof value.token !== "string" ||
+      value.token.length < 20 ||
+      value.token.length > 4096)
+  )
+    throw new Error("Invalid push token");
+  // A platform describes a token, so it never arrives without one.
+  if (
+    value.platform !== undefined &&
+    (value.token === undefined ||
+      !PUSH_PLATFORMS_V1.includes(value.platform as PushPlatformV1))
+  )
+    throw new Error("Invalid push platform");
+  if (value.activeBotId !== undefined && !isPublicIdentifier(value.activeBotId))
+    throw new Error("Invalid active Bot");
+  if (value.remove !== undefined && typeof value.remove !== "boolean")
+    throw new Error("Invalid remove flag");
+  return value as unknown as PushRegistration;
+}
+
+export async function registerPushDevice(
+  storage: DurableObjectStorage,
+  value: PushRegistration,
+  now = Date.now(),
+): Promise<void> {
+  const key = DEVICE_PREFIX + value.deviceId;
+  if (value.remove) {
+    await forgetDevice(storage, key, value.deviceId);
+    return;
+  }
+  const devices = await storage.list<PushDevice>({ prefix: DEVICE_PREFIX });
+  for (const [oldKey, device] of devices)
+    if (
+      now - device.updatedAt >
+      (device.token ? 30 * 86400_000 : PRESENCE_MS * 4)
+    ) {
+      await forgetDevice(storage, oldKey, device.deviceId);
+      devices.delete(oldKey);
+    }
+  if (!devices.has(key) && devices.size >= 32)
+    throw new Error("Too many registered devices");
+  // A refreshed token replaces the installation's old token, never adds
+  // another recipient. A registration that carries no token is a presence
+  // update — the device says which Bot it is reading, from the first frame,
+  // before the FCM token has been fetched — so it keeps the token already
+  // registered rather than erasing the only address the Bot can reach. Every
+  // other field is stated afresh: an omitted `activeBotId` means this device
+  // is no longer reading anything, and merging it would suppress its alerts.
+  // The platform is the token's, so it is kept or replaced with it.
+  const previous = devices.get(key);
+  const token = value.token ?? previous?.token;
+  const platform =
+    value.token === undefined ? previous?.platform : value.platform;
+  await storage.put(key, {
+    deviceId: value.deviceId,
+    ...(token === undefined ? {} : { token }),
+    ...(platform === undefined ? {} : { platform }),
+    ...(value.activeBotId === undefined
+      ? {}
+      : { activeBotId: value.activeBotId }),
+    updatedAt: now,
+  } satisfies PushDevice);
+}
+
+/**
+ * A device and everything written about it. The delivery receipts are keyed by
+ * the device id, so they have to go with it: an install that is replaced or
+ * expires would otherwise leave one row per Bot and kind behind for ever.
+ */
+async function forgetDevice(
+  storage: DurableObjectStorage,
+  key: string,
+  deviceId: string,
+): Promise<void> {
+  await storage.delete(key);
+  await forgetDeliveries(storage, deviceId);
+}
+
+async function forgetDeliveries(
+  storage: DurableObjectStorage,
+  deviceId: string,
+): Promise<void> {
+  const receipts = await storage.list<unknown>({ prefix: DELIVERY_PREFIX });
+  for (const receiptKey of receipts.keys())
+    if (receiptKey.endsWith(`:${deviceId}`)) await storage.delete(receiptKey);
+}
+
+export class RetryablePushError extends Error {}
+
+interface ServiceAccount {
+  project_id: string;
+  client_email: string;
+  private_key: string;
+}
+const encoder = new TextEncoder();
+function base64url(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/=/g, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+}
+
+/**
+ * The minted access token, reused until it is nearly expired.
+ *
+ * The assertion buys an hour; signing and exchanging one per device per message
+ * turned a burst into a run of RSA signings and round trips to Google for no
+ * gain. A token that stops being accepted is dropped and re-minted rather than
+ * cached into a permanent failure.
+ */
+const accessTokens = new Map<string, { token: string; expiresAt: number }>();
+const ACCESS_TOKEN_MARGIN_MS = 300_000;
+
+async function accessToken(
+  account: ServiceAccount,
+  request: typeof fetch,
+): Promise<string> {
+  const cached = accessTokens.get(account.client_email);
+  if (cached && cached.expiresAt > Date.now()) return cached.token;
+  const now = Math.floor(Date.now() / 1000);
+  const header = base64url(
+    encoder.encode(JSON.stringify({ alg: "RS256", typ: "JWT" })),
+  );
+  const claims = base64url(
+    encoder.encode(
+      JSON.stringify({
+        iss: account.client_email,
+        scope: "https://www.googleapis.com/auth/firebase.messaging",
+        aud: "https://oauth2.googleapis.com/token",
+        iat: now,
+        exp: now + 3600,
+      }),
+    ),
+  );
+  const pem = account.private_key
+    .replace(/-----[^-]+-----/g, "")
+    .replace(/\s/g, "");
+  const key = await crypto.subtle.importKey(
+    "pkcs8",
+    Uint8Array.from(atob(pem), (c) => c.charCodeAt(0)),
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "RSASSA-PKCS1-v1_5",
+    key,
+    encoder.encode(`${header}.${claims}`),
+  );
+  const deadline = withDeadlineV1(10_000);
+  let access: { access_token: string; expires_in?: number };
+  try {
+    const auth = await request("https://oauth2.googleapis.com/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: `${header}.${claims}.${base64url(new Uint8Array(signature))}`,
+      }),
+      signal: deadline.signal,
+    }).catch(() => {
+      throw new RetryablePushError("Push authorization is unavailable");
+    });
+    if (!auth.ok)
+      throw new RetryablePushError(
+        `Push authorization failed (${auth.status})`,
+      );
+    access = (await auth.json()) as {
+      access_token: string;
+      expires_in?: number;
+    };
+  } finally {
+    deadline.clear();
+  }
+  accessTokens.set(account.client_email, {
+    token: access.access_token,
+    expiresAt:
+      Date.now() +
+      Math.max(
+        60_000,
+        (access.expires_in ?? 3600) * 1000 - ACCESS_TOKEN_MARGIN_MS,
+      ),
+  });
+  return access.access_token;
+}
+
+/** Read signals, like the Android `ttl`, stop being worth delivering after a day. */
+const DELIVERY_LIFETIME_S = 86_400;
+
+/**
+ * What APNs draws on an iPhone. A suspended app cannot draw an alert from
+ * data, so a message to be told arrives as the alert itself, threaded per
+ * conversation the way Android keeps one notification per Bot. Everything
+ * else — a read on another device, a message not to be told — is a background
+ * push that wakes the app if iOS allows it, and that iOS may hold back.
+ */
+function apnsMessage(
+  data: Record<string, string>,
+  notify: boolean,
+): Record<string, unknown> {
+  const expiration = String(
+    Math.floor(Date.now() / 1000) + DELIVERY_LIFETIME_S,
+  );
+  if (!notify)
+    return {
+      headers: {
+        "apns-priority": "5",
+        "apns-push-type": "background",
+        "apns-expiration": expiration,
+      },
+      payload: { aps: { "content-available": 1 } },
+    };
+  return {
+    headers: {
+      "apns-priority": "10",
+      "apns-push-type": "alert",
+      "apns-expiration": expiration,
+    },
+    payload: {
+      aps: {
+        alert: {
+          title: data.title || BRAND_V1.productName,
+          body: data.body || "New message",
+        },
+        sound: "default",
+        "thread-id": data.groupId ? `group:${data.groupId}` : data.botId,
+      },
+    },
+  };
+}
+
+export async function sendFcm(
+  secret: string,
+  target: { token: string; platform?: PushPlatformV1 },
+  data: Record<string, string>,
+  notify: boolean,
+  request: typeof fetch = fetch,
+): Promise<"sent" | "unregistered"> {
+  const account = JSON.parse(secret) as ServiceAccount;
+  const bearer = await accessToken(account, request);
+  const deadline = withDeadlineV1(10_000);
+  let result: Response;
+  try {
+    result = await request(
+      `https://fcm.googleapis.com/v1/projects/${encodeURIComponent(account.project_id)}/messages:send`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${bearer}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          message: {
+            token: target.token,
+            data,
+            android: {
+              priority: notify ? "HIGH" : "NORMAL",
+              ttl: `${DELIVERY_LIFETIME_S}s`,
+            },
+            ...(target.platform === "ios"
+              ? { apns: apnsMessage(data, notify) }
+              : {}),
+          },
+        }),
+        signal: deadline.signal,
+      },
+    );
+  } finally {
+    deadline.clear();
+  }
+  if (result.status === 404) {
+    const error = (await result.json()) as {
+      error?: { details?: { errorCode?: string }[] };
+    };
+    if (
+      error.error?.details?.some(
+        (detail) => detail.errorCode === "UNREGISTERED",
+      )
+    )
+      return "unregistered";
+  }
+  if (result.status === 401 || result.status === 403) {
+    accessTokens.delete(account.client_email);
+    throw new RetryablePushError(
+      `Push authorization was rejected (${result.status})`,
+    );
+  }
+  if (result.status === 429 || result.status >= 500)
+    throw new RetryablePushError(
+      `Push service rejected the attempt (${result.status})`,
+    );
+  if (!result.ok) throw new Error(`Push delivery failed (${result.status})`);
+  await result.body?.cancel();
+  return "sent";
+}
+
+/** One external attempt per message/device; an uncertain send is explicit, never blindly replayed. */
+export async function deliverPush(
+  storage: DurableObjectStorage,
+  userId: string,
+  update: PushUpdate,
+  secret: string | undefined,
+  sender = sendFcm,
+): Promise<void> {
+  const devices = await storage.list<PushDevice>({ prefix: DEVICE_PREFIX });
+  const now = Date.now();
+  for (const [key, device] of devices) {
+    if (
+      now - device.updatedAt >
+      (device.token ? 30 * 86400_000 : PRESENCE_MS * 4)
+    ) {
+      await forgetDevice(storage, key, device.deviceId);
+      devices.delete(key);
+    }
+  }
+  if (![...devices.values()].some((device) => device.token)) return;
+  if (!secret) throw new Error("Firebase push is not configured");
+  const target = update.groupId ?? update.botId;
+  const beingRead = [...devices.values()].some(
+    (device) =>
+      device.activeBotId === target && now - device.updatedAt < PRESENCE_MS,
+  );
+  // Presence delays delivery; only a durable read receipt can discard an alert.
+  // A stale focus lease must never silently lose a message.
+  if (beingRead && update.kind === "message" && update.notify === true)
+    throw new RetryablePushError(
+      "Waiting for the visible message's read receipt",
+    );
+  for (const [deviceKey, device] of devices) {
+    if (!device.token) continue;
+    const key = update.groupId
+      ? `${DELIVERY_PREFIX}group:${update.groupId}:${update.kind}:${device.deviceId}`
+      : `${DELIVERY_PREFIX}${update.botId}:${update.kind}:${device.deviceId}`;
+    const claimed = await storage.transaction(async (tx) => {
+      const previous = await tx.get<{
+        cursor: string;
+        status: string;
+        at: number;
+        retryAt?: number;
+      }>(key);
+      if (
+        previous &&
+        previous.cursor >= update.cursor &&
+        previous.status === "retry"
+      ) {
+        if (previous.cursor > update.cursor || (previous.retryAt ?? 0) > now)
+          throw new RetryablePushError("Push retry is scheduled");
+      } else if (previous && previous.cursor >= update.cursor) {
+        if (previous.status === "attempting") {
+          await tx.put(key, { ...previous, status: "uncertain" });
+          console.error(
+            JSON.stringify({
+              event: "push-delivery-uncertain",
+              botId: update.botId,
+              cursor: update.cursor,
+            }),
+          );
+        }
+        return false;
+      }
+      await tx.put(key, {
+        cursor: update.cursor,
+        status: "attempting",
+        at: now,
+      });
+      return true;
+    });
+    if (!claimed) continue;
+    const notify =
+      update.kind === "message" && update.notify === true && !beingRead;
+    try {
+      const result = await sender(
+        secret,
+        {
+          token: device.token,
+          ...(device.platform ? { platform: device.platform } : {}),
+        },
+        {
+          userId,
+          botId: update.botId,
+          ...(update.groupId ? { groupId: update.groupId } : {}),
+          cursor: update.cursor,
+          kind: update.kind,
+          title: update.title ?? "",
+          body: update.body ?? "",
+          notify: String(notify),
+        },
+        notify,
+      );
+      if (result === "unregistered") {
+        const removed = await storage.transaction(async (tx) => {
+          if ((await tx.get<PushDevice>(deviceKey))?.token !== device.token)
+            return false;
+          await tx.delete(deviceKey);
+          return true;
+        });
+        if (removed) {
+          await forgetDeliveries(storage, device.deviceId);
+          continue;
+        }
+      }
+      await finishDelivery(storage, key, update.cursor, result, now);
+    } catch (error) {
+      if (error instanceof RetryablePushError) {
+        await storage.transaction(async (tx) => {
+          if ((await tx.get<{ cursor: string }>(key))?.cursor === update.cursor)
+            await tx.put(key, {
+              cursor: update.cursor,
+              status: "retry",
+              at: now,
+              retryAt: now + 60_000,
+            });
+        });
+        throw error;
+      }
+      await finishDelivery(storage, key, update.cursor, "uncertain", now);
+      console.error(
+        JSON.stringify({
+          event: "push-delivery-uncertain",
+          botId: update.botId,
+          cursor: update.cursor,
+        }),
+      );
+    }
+  }
+}
+
+async function finishDelivery(
+  storage: DurableObjectStorage,
+  key: string,
+  cursor: string,
+  status: string,
+  at: number,
+): Promise<void> {
+  await storage.transaction(async (tx) => {
+    if ((await tx.get<{ cursor: string }>(key))?.cursor === cursor)
+      await tx.put(key, { cursor, status, at });
+  });
+}

package/src/request-body.ts

@@ -0,0 +1,165 @@
+/**
+ * Answering a request without reading it.
+ *
+ * workerd tears the whole isolate down — "Can't read from request stream after
+ * response has been sent" — when a handler answers a request whose body it
+ * never touched. Every early return is such a handler: a body refused for its
+ * size before it was parsed, a bad origin, a 404 on a POST. A 111 KB message
+ * took the dev stack down twice this way, because the size refusal that
+ * answered it 400 was the one path guaranteed never to read the body.
+ *
+ * So the drain is not per-route diligence. It is one helper on the outermost
+ * wrapper of each Worker in the request path — the gateway and the loaded User
+ * application are separate isolates with separate `Request` objects, and both
+ * have to drain their own.
+ */
+
+/** The longest message a Turn will carry. */
+export const TURN_TEXT_MAX_CHARACTERS_V1 = 32_000;
+
+/**
+ * The largest body the send route will read.
+ *
+ * Generous over the text limit because the same JSON also carries a command
+ * id, Skill refs and the retry target; a body past it cannot contain an
+ * acceptable `text` no matter how it is shaped.
+ */
+export const TURN_BODY_MAX_BYTES_V1 = TURN_TEXT_MAX_CHARACTERS_V1 * 2;
+
+export const TURN_SEND_PATH_V1 = /^\/api\/bots\/[^/]+\/turns$/;
+
+/**
+ * What the composer shows when a send is refused for size.
+ *
+ * A person wrote too much. That is not a fault and not a server error, so the
+ * answer is 413 with a sentence that says what to do about it, rather than a
+ * 400 naming a byte budget nobody chose.
+ */
+export const TURN_TOO_LONG_MESSAGE_V1 = `Your message is too long. Keep it under ${TURN_TEXT_MAX_CHARACTERS_V1.toLocaleString("en-US")} characters.`;
+
+/** A size refusal, told apart from an unreadable body. */
+export class RequestTooLargeError extends Error {
+  override readonly name = "RequestTooLargeError";
+  constructor(message = TURN_TOO_LONG_MESSAGE_V1) {
+    super(message);
+  }
+}
+
+export function isRequestTooLargeV1(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    error.name === "RequestTooLargeError"
+  );
+}
+
+/**
+ * Requests whose body has been handed to a subrequest.
+ *
+ * `new Request(request, init)` and `fetch(request)` pipe the incoming body
+ * onward without ever setting `bodyUsed` on the request we were handed, so
+ * `bodyUsed` cannot tell a forwarded body from an unread one. It has to be
+ * recorded where the handoff happens.
+ *
+ * A `WeakSet` because the entry is worth exactly as long as the request is.
+ */
+const forwardedBodies = new WeakSet<Request>();
+
+/**
+ * Record that this request's body now belongs to a subrequest.
+ *
+ * Call it at every handoff, before awaiting the subrequest. Once the
+ * subrequest has answered, the pipe is closed from the far end and touching
+ * the near end — a cancel included — raises "Can't read from request stream
+ * after response has been sent". That error surfaces on the isolate rather
+ * than on the promise, so no `try`/`catch` around the cancel can contain it:
+ * it took workerd down mid-suite, every run, on the one POST whose body no
+ * route reads.
+ */
+export function forwardingBodyV1<T>(request: Request, forwarded: T): T {
+  forwardedBodies.add(request);
+  return forwarded;
+}
+
+/** Whether this request's body was handed on rather than read here. */
+export function bodyWasForwardedV1(request: Request): boolean {
+  return forwardedBodies.has(request);
+}
+
+/**
+ * How many bytes a drain will read before it gives up and cancels.
+ *
+ * Generous: every route that admits a body of its own is bounded far below
+ * this, so reaching it means a client is sending something no route wanted.
+ * Past it the connection is worth less than the time spent reading it.
+ */
+const DRAIN_BUDGET_BYTES_V1 = 8 * 1024 * 1024;
+
+/**
+ * Read the body out and throw it away, a chunk at a time.
+ *
+ * Cancelling is not enough, and this is the whole lesson of the incident.
+ * `cancel()` tears the stream down from the reading end; the writing end — the
+ * gateway pumping the browser's bytes into the loaded application's isolate —
+ * is still holding bytes it has not delivered when the response goes out, and
+ * that is what workerd reports as "Can't read from request stream after
+ * response has been sent". Reading to `done` is what actually retires the
+ * pipe. Verified against the dev stack: with a cancel the error is on every
+ * `POST /conversations`; with a read there is none.
+ *
+ * A reader loop rather than `arrayBuffer()`, so the bytes are dropped as they
+ * arrive and a large body is never held whole.
+ */
+async function consumeBodyV1(body: ReadableStream<Uint8Array>): Promise<void> {
+  const reader = body.getReader();
+  let seen = 0;
+  for (;;) {
+    const chunk = await reader.read();
+    if (chunk.done) return;
+    seen += chunk.value?.byteLength ?? 0;
+    if (seen > DRAIN_BUDGET_BYTES_V1) {
+      await reader.cancel();
+      return;
+    }
+  }
+}
+
+/**
+ * Answer, having consumed the request's body.
+ *
+ * A body already read is left alone by `bodyUsed`; a body handed to a
+ * subrequest is left alone by `forwardingBodyV1`, because that subrequest's
+ * own wrapper is the one that owes it a read and the stream is no longer this
+ * isolate's to touch. Anything else is drained here, and a drain that throws
+ * anyway must never become the answer the client sees.
+ */
+export async function drainedAnswerV1(
+  request: Request,
+  response: Response,
+): Promise<Response> {
+  const body = request.body;
+  if (body && !request.bodyUsed && !bodyWasForwardedV1(request)) {
+    try {
+      await consumeBodyV1(body);
+    } catch {
+      // The stream was already gone. The answer stands either way.
+    }
+  }
+  return response;
+}
+
+/**
+ * A declared body too large to be worth reading.
+ *
+ * Content-Length is what a browser's `fetch` always sends for a string body,
+ * which is every send the composer makes. A chunked request declaring no
+ * length falls through to the route's own decoder, which is bounded too — this
+ * guard exists so the common oversized send is never parsed at all.
+ */
+export function turnBodyIsOversizedV1(request: Request, url: URL): boolean {
+  if (request.method !== "POST") return false;
+  if (!TURN_SEND_PATH_V1.test(url.pathname)) return false;
+  const declared = Number(request.headers.get("content-length") ?? "");
+  return Number.isFinite(declared) && declared > TURN_BODY_MAX_BYTES_V1;
+}