eraspace 0.2.0 → 0.4.0

package/sdk/src/client/transport.ts

@@ -22,6 +22,8 @@ export interface SocketOptions {
   rejoinAfterMs?: (attempt: number) => number;
   /** How long a socket must stay open before reconnect backoff starts again from the first attempt. */
   stableAfterMs?: number;
+  /** Accept large payloads as deflated binary frames. Defaults to on where `DecompressionStream` inflates raw deflate. */
+  compression?: boolean;
 }
 
 interface Frame {
@@ -42,6 +44,58 @@ interface Pending {
 }
 export interface JoinReply { self?: string; now?: number; version?: number }
 
+function asFrame(value: unknown): Frame | undefined {
+  if (!value || typeof value !== "object" || !("topic" in value) || typeof value.topic !== "string"
+    || !("event" in value) || typeof value.event !== "string" || !("session" in value)
+    || !(value.session === null || typeof value.session === "string") || !("ref" in value)
+    || !(value.ref === null || typeof value.ref === "string") || !("payload" in value)) return undefined;
+  return value as Frame;
+}
+
+/**
+ * Reports an exception thrown by app code that consumes frames, as an uncaught event handler exception would be.
+ * It must not look like a transport failure, which would fail every in-flight request with an unknown outcome.
+ */
+function report(error: unknown): void {
+  if (typeof reportError === "function") reportError(error);
+  else setTimeout(() => { throw error; });
+}
+
+function inflates(): boolean {
+  try { return typeof DecompressionStream === "function" && Boolean(new DecompressionStream("deflate-raw")); }
+  catch { return false; }
+}
+
+async function bytesOf(data: unknown): Promise<Uint8Array<ArrayBuffer> | undefined> {
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer);
+  if (typeof Blob !== "undefined" && data instanceof Blob) return new Uint8Array(await data.arrayBuffer());
+  return undefined;
+}
+
+/**
+ * A binary frame is a four-byte big-endian header length, the frame's JSON header and a raw-deflated JSON
+ * object. The header's `z` places the object: `"response"` is the reply's response, `"members"` adds its
+ * members to the header payload.
+ */
+async function inflateFrame(data: unknown): Promise<Frame | undefined> {
+  const bytes = await bytesOf(data);
+  if (!bytes || bytes.length < 4) return undefined;
+  const length = new DataView(bytes.buffer, bytes.byteOffset).getUint32(0);
+  if (4 + length > bytes.length) return undefined;
+  const header: unknown = JSON.parse(new TextDecoder().decode(bytes.subarray(4, 4 + length)));
+  const frame = asFrame(header);
+  const z = header && typeof header === "object" && "z" in header ? header.z : undefined;
+  if (!frame || !frame.payload || typeof frame.payload !== "object") return undefined;
+  const inflated = new Blob([bytes.subarray(4 + length)]).stream().pipeThrough(new DecompressionStream("deflate-raw"));
+  const body: unknown = JSON.parse(await new Response(inflated).text());
+  const payload = frame.payload as Record<string, unknown>;
+  if (z === "response") payload.response = body;
+  else if (z === "members" && body && typeof body === "object") frame.payload = { ...body, ...payload };
+  else return undefined;
+  return { session: frame.session, ref: frame.ref, topic: frame.topic, event: frame.event, payload: frame.payload };
+}
+
 /** Multiplexes topics over one native WebSocket. Sent requests are never replayed on reconnect. */
 export class Socket {
   private ws: WebSocketTransport | undefined;
@@ -65,6 +119,7 @@ export class Socket {
     const url = new URL(endpoint, typeof location === "undefined" ? undefined : location.href);
     url.protocol = url.protocol === "https:" || url.protocol === "wss:" ? "wss:" : "ws:";
     url.searchParams.set("v", "1");
+    if (options.compression ?? inflates()) url.searchParams.set("z", "1");
     this.url = url.href;
     this.options = options;
   }
@@ -88,6 +143,7 @@ export class Socket {
     try { ws = new Transport(this.url); }
     catch { this.scheduleReconnect(); return; }
     this.ws = ws;
+    (ws as { binaryType?: string }).binaryType = "arraybuffer";
     this.opening = setTimeout(() => this.lost(ws), this.options.timeout ?? 15000);
     ws.onopen = () => {
       if (this.ws !== ws) return;
@@ -103,25 +159,33 @@ export class Socket {
       this.heartbeat = setInterval(() => this.sendHeartbeat(ws), 25000);
     };
     ws.onmessage = (event) => {
-      if (this.ws !== ws || typeof event.data !== "string") return;
-      let frame: Frame;
-      try {
-        const value: unknown = JSON.parse(event.data);
-        if (!value || typeof value !== "object" || !("topic" in value) || typeof value.topic !== "string"
-          || !("event" in value) || typeof value.event !== "string" || !("session" in value)
-          || !(value.session === null || typeof value.session === "string") || !("ref" in value)
-          || !(value.ref === null || typeof value.ref === "string") || !("payload" in value)) return;
-        frame = value as Frame;
-      } catch { return; }
+      if (this.ws !== ws) return;
+      if (typeof event.data !== "string") {
+        // Deflated frames inflate asynchronously, in arrival order with every other frame.
+        const data = event.data;
+        // A frame that does not inflate is a transport failure; an exception while delivering one is not.
+        this.incoming = this.incoming.then(() => inflateFrame(data)).then(
+          frame => { if (frame) this.deliver(ws, frame); },
+          () => this.lost(ws),
+        );
+        return;
+      }
+      let frame: Frame | undefined;
+      try { frame = asFrame(JSON.parse(event.data)); } catch { return; }
+      if (!frame) return;
+      const received = frame;
       // ws can deliver several frames in one task. Let reply consumers settle before the next push.
-      this.incoming = this.incoming.then(() => {
-        if (this.ws === ws) this.receive(frame);
-      }).catch(() => this.lost(ws));
+      this.incoming = this.incoming.then(() => this.deliver(ws, received));
     };
     ws.onclose = () => this.lost(ws);
     ws.onerror = () => this.lost(ws);
   }
 
+  private deliver(ws: WebSocketTransport, frame: Frame): void {
+    if (this.ws !== ws) return;
+    try { this.receive(frame); } catch (error) { report(error); }
+  }
+
   private receive(frame: Frame): void {
     if (frame.event === "reply" && frame.ref) {
       const body = frame.payload;
@@ -333,8 +397,11 @@ export class Channel {
   receive(frame: Frame): void {
     if (this.closed || frame.session !== this.session) return;
     if (frame.event === "closed") { this.leave(); return; }
-    this.onMessage?.(frame.event, frame.payload);
-    for (const cb of this.events.get(frame.event) ?? []) cb(frame.payload);
+    // One throwing handler must not keep the frame from the others.
+    try { this.onMessage?.(frame.event, frame.payload); } catch (error) { report(error); }
+    for (const cb of this.events.get(frame.event) ?? []) {
+      try { cb(frame.payload); } catch (error) { report(error); }
+    }
   }
 
   disconnected(): void {

package/sdk/src/server/index.ts

@@ -151,8 +151,24 @@ export interface TableDefinition<F extends FieldMap = FieldMap, I extends IndexM
     name: N,
     fields: Fs,
   ): TableDefinition<F, Simplify<I & { [P in N]: Fs }>>;
+  /**
+   * Upgrade rows written before this migration to the table's current fields. Versions start at any positive
+   * number and each call takes the next one; rows are written at the last version. A deploy then accepts rows of
+   * an older shape: they are upgraded when read and rewritten in the background. `upgrade` receives the stored
+   * row with `id` and `createdAt` and must return the new row synchronously, depending only on the row.
+   * Undeclared fields of the result are dropped. Keep a migration until every row has passed it.
+   */
+  migrate(version: number, upgrade: (row: StoredRow<F>) => MigratedRow<F>): TableDefinition<F, I>;
 }
 
+/**
+ * A row as an earlier deployment stored it: `id`, `createdAt` and whatever fields it had then. Their types are
+ * unknown, and fields of the current schema may be absent, so they read as `any`.
+ */
+export type StoredRow<F extends FieldMap = FieldMap> = { id: string; createdAt: number } & { [K in keyof F]: any } & { [field: string]: any };
+/** What a migration returns: the row with the table's current fields. `id` and `createdAt` keep their values. */
+export type MigratedRow<F extends FieldMap> = InferInsert<F> & { id?: string; createdAt?: number };
+
 export type AnyTable = TableDefinition<any, any>;
 export type Schema = Record<string, AnyTable>;
 /** The schema a capsule gets when it declares none. Tables and fields are untyped. */
@@ -160,6 +176,7 @@ export type DefaultSchema = Record<string, TableDefinition<Record<string, Field<
 
 export function table<const F extends FieldMap>(fields: F): TableDefinition<F, {}> {
   const indexes: Record<string, readonly string[]> = {};
+  const migrations: number[] = [];
   const def: any = {
     kind: "table",
     fields,
@@ -169,10 +186,20 @@ export function table<const F extends FieldMap>(fields: F): TableDefinition<F, {
       indexes[name] = idx;
       return def;
     },
+    migrate(version: number, upgrade: unknown) {
+      if (!Number.isInteger(version) || version < 1) throw new TypeError("migrate() expects a positive integer version");
+      if (typeof upgrade !== "function") throw new TypeError("migrate() expects a function from a stored row to the upgraded row");
+      const last = migrations.length ? migrations[migrations.length - 1]! : version - 1;
+      if (version !== last + 1) throw new Error(`migrate(${version}) must follow migrate(${last}) with the next version, ${last + 1}`);
+      migrations.push(version);
+      return def;
+    },
     toJSON() {
+      const versions = migrations.length ? { version: migrations[migrations.length - 1], migratesFrom: migrations[0]! - 1 } : {};
       return {
         fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, describeField(v)])),
         indexes,
+        ...versions,
       };
     },
   };
@@ -349,6 +376,16 @@ interface BaseContext {
 interface DbHolder<Db> extends BaseContext {
   db: Db;
 }
+export interface Scheduler {
+  /**
+   * Runs mutation `name` with `args` once, `delayMs` milliseconds after this mutation commits. The job commits with
+   * this mutation, so it exists only if this mutation does, and its run commits at most once. Returns the job's id.
+   */
+  runAfter(delayMs: number, name: string, ...args: any[]): string;
+}
+interface MutationHolder<Db> extends DbHolder<Db> {
+  scheduler: Scheduler;
+}
 interface ActionHolder<Db> extends DbHolder<Db> {
   runQuery(name: string, ...args: any[]): Promise<any>;
   runMutation(name: string, ...args: any[]): Promise<any>;
@@ -357,8 +394,8 @@ interface ActionHolder<Db> extends DbHolder<Db> {
 
 /** The `ctx` a `query()` (or a `readOnly` endpoint) receives. */
 export type QueryServerContext<S extends Schema = DefaultSchema> = DbHolder<DbContext<S>>;
-/** The `ctx` a `mutation()` or writable `endpoint()` receives. Its `db` can write. */
-export type ServerContext<S extends Schema = DefaultSchema> = DbHolder<MutationDbContext<S>>;
+/** The `ctx` a `mutation()` or writable `endpoint()` receives. Its `db` can write and its `scheduler` schedules mutations. */
+export type ServerContext<S extends Schema = DefaultSchema> = MutationHolder<MutationDbContext<S>>;
 /** The `ctx` an `action()` receives: read-only db plus `runQuery`/`runMutation`. Use global `fetch` for HTTP. */
 export type ActionServerContext<S extends Schema = DefaultSchema> = ActionHolder<DbContext<S>>;
 
@@ -477,6 +514,8 @@ export interface EndpointRequest {
   json<T = unknown>(): Promise<T>;
   /** Request body bytes as a JSON-compatible number array. */
   bytes(): Promise<number[]>;
+  /** A multipart/form-data or application/x-www-form-urlencoded body. Other content types reject with a TypeError. */
+  formData(): Promise<FormData>;
 }
 
 export interface EndpointResponseOptions {

package/templates/chat/client/index.tsx

@@ -1,7 +1,7 @@
 import { createClient, FilePreview, FileUpload, type FileRef } from "eraspace/client";
-import { useState, useEffect } from "preact/hooks";
+import { useState, useEffect, useRef } from "preact/hooks";
 import type app from "../server/index";
-const client = createClient<typeof app>({ reloadOnDeploy: true });
+const client = createClient<typeof app>();
 export default function App() {
   const [room, setRoom] = useState("general");
   const [author, setAuthor] = useState("Guest");
@@ -12,7 +12,12 @@ export default function App() {
   const [file, setFile] = useState<FileRef | null>(null);
   const messages = client.useQuery("messages", room);
   const send = client.useMutation("send");
-  const channel = client.useRoom<{ name: string }> (room, { name: author });
+  // Room messages share the app's request budget, so presence takes the name once typing pauses and the typing
+  // notice goes out at most once a second; the 1.5 s display below bridges the gap.
+  const [shownName, setShownName] = useState(author);
+  useEffect(() => { const timer = setTimeout(() => setShownName(author), 500); return () => clearTimeout(timer); }, [author]);
+  const lastTyping = useRef(0);
+  const channel = client.useRoom<{ name: string }> (room, { name: shownName });
   useEffect(() => channel.on("typing", (payload: unknown) => {
     if (typeof payload === "string") setTyping(payload);
   }), [room]);
@@ -29,7 +34,10 @@ export default function App() {
       try { await send(room, author, body, file); setBody(""); setFile(null); } catch (err) { setError(err instanceof Error ? err.message : String(err)); } finally { setSending(false); }
     }}>
       <input aria-label="Your name" value={author} maxLength={40} onInput={e => setAuthor(e.currentTarget.value)}/>
-      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => { setBody(e.currentTarget.value); channel.broadcast("typing", author); }}/>
+      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => {
+        setBody(e.currentTarget.value);
+        if (Date.now() - lastTyping.current >= 1000) { lastTyping.current = Date.now(); channel.broadcast("typing", author); }
+      }}/>
       <button disabled={sending || (!body.trim() && !file)}>Send</button>
       {file
         ? <div class="pending"><FilePreview client={client} file={file} caption={false} class="attachment"/><span>{file.name}</span><button type="button" class="subtle" disabled={sending} onClick={() => { void client.storage.delete(file.key).catch(() => {}); setFile(null); }}>Remove</button></div>

package/templates/poll/client/index.tsx

@@ -1,7 +1,7 @@
 import { createClient } from "eraspace/client";
 import { useState } from "preact/hooks";
 import type app from "../server/index";
-const client = createClient<typeof app>({ reloadOnDeploy: true });
+const client = createClient<typeof app>();
 export default function App() {
   const options = client.useQuery("results");
   const add = client.useMutation("addOption");

package/templates/todo/client/index.tsx

@@ -1,7 +1,7 @@
 import { createClient } from "eraspace/client";
 import { useState } from "preact/hooks";
 import type app from "../server/index";
-const client = createClient<typeof app>({ reloadOnDeploy: true });
+const client = createClient<typeof app>();
 export default function App() {
   const todos = client.useQuery("list");
   const [title, setTitle] = useState("");