eraspace 0.1.0 → 0.2.0

package/sdk/src/client/storage.ts

@@ -6,25 +6,87 @@ export interface UploadedObject {
   size: number;
   contentType: string;
   name: string | null;
+  /** Private upload capability. Keep it out of public rows and file references. */
+  deleteToken?: string;
+}
+
+export interface StorageUploadOptions {
+  name?: string;
+  signal?: AbortSignal;
+  /** Called with the uploaded fraction, from 0 to 1, as the bytes leave the browser. */
+  onProgress?: (fraction: number) => void;
 }
 
 export interface StorageClient {
-  /** Store a file in this app's Postgres schema. v1 apps and their files are public. */
-  upload(body: Blob, options?: { name?: string; signal?: AbortSignal }): Promise<UploadedObject>;
+  /** Store a file in this app's bucket. Apps and their files are public. */
+  upload(body: Blob, options?: StorageUploadOptions): Promise<UploadedObject>;
   url(key: string): string;
-  delete(key: string, options?: { signal?: AbortSignal }): Promise<void>;
+  /** A stored file's metadata, or null when there is no such file. */
+  info(key: string, options?: { signal?: AbortSignal }): Promise<UploadedObject | null>;
+  delete(key: string, options?: { signal?: AbortSignal; deleteToken?: string }): Promise<void>;
+}
+
+/** Storage keys are UUIDs. */
+export function isStorageKey(key: unknown): key is string {
+  return typeof key === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key);
+}
+
+/** The filename in a `filename*=UTF-8''...` Content-Disposition. */
+function dispositionName(value: string | null): string | null {
+  const encoded = value?.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+  if (!encoded) return null;
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+}
+
+/** POST `body` with XMLHttpRequest, which reports upload progress where fetch cannot. */
+function sendWithProgress(target: string, headers: Headers, body: Blob, signal: AbortSignal | undefined, onProgress: (fraction: number) => void) {
+  return new Promise<{ status: number; text: string }>((resolve, reject) => {
+    const abortError = () => signal?.reason ?? new DOMException("The upload was aborted", "AbortError");
+    if (signal?.aborted) return reject(abortError());
+    const xhr = new XMLHttpRequest();
+    const abort = () => xhr.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    const done = () => signal?.removeEventListener("abort", abort);
+    xhr.open("POST", target);
+    headers.forEach((value, name) => xhr.setRequestHeader(name, value));
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && e.total > 0) onProgress(e.loaded / e.total);
+    };
+    xhr.onload = () => {
+      done();
+      if (xhr.status >= 200 && xhr.status < 300) onProgress(1);
+      resolve({ status: xhr.status, text: xhr.responseText });
+    };
+    xhr.onerror = () => {
+      done();
+      reject(new EraspaceError("StorageError", "The upload failed. Check your connection and try again."));
+    };
+    xhr.onabort = () => {
+      done();
+      reject(abortError());
+    };
+    xhr.send(body);
+  });
 }
 
 export function createStorageClient(base: () => string): StorageClient {
+  const deleteTokens = new Map<string, string>();
   function url(key?: string): string {
     const path = `${base().replace(/\/+$/, "")}/_sb/storage`;
     return key === undefined ? path : `${path}/${encodeURIComponent(key)}`;
   }
-  async function check(response: Response): Promise<Record<string, unknown>> {
-    const payload = await response.json() as unknown;
-    if (!payload || typeof payload !== "object") throw new EraspaceError("StorageError", `HTTP ${response.status}`);
+  function check(status: number, text: string): Record<string, unknown> {
+    let payload: unknown;
+    try {
+      payload = JSON.parse(text);
+    } catch {}
+    if (!payload || typeof payload !== "object") throw new EraspaceError("StorageError", `HTTP ${status}`);
     const result = payload as Record<string, unknown>;
-    if (!response.ok || result.ok !== true) throw EraspaceError.from(result.error, `Storage request failed: HTTP ${response.status}`);
+    if (status < 200 || status > 299 || result.ok !== true) throw EraspaceError.from(result.error, `Storage request failed: HTTP ${status}`);
     return result;
   }
   return {
@@ -33,14 +95,38 @@ export function createStorageClient(base: () => string): StorageClient {
       const headers = new Headers({ "content-type": body.type || "application/octet-stream" });
       const name = options.name ?? (typeof File !== "undefined" && body instanceof File ? body.name : undefined);
       if (name) headers.set("x-filename", encodeURIComponent(name));
-      const result = await check(await fetch(url(), { method: "POST", headers, body, signal: options.signal }));
+      const { onProgress, signal } = options;
+      const response = onProgress && typeof XMLHttpRequest !== "undefined"
+        ? await sendWithProgress(url(), headers, body, signal, onProgress)
+        : await fetch(url(), { method: "POST", headers, body, signal }).then(async (r) => ({ status: r.status, text: await r.text() }));
+      const result = check(response.status, response.text);
       if (typeof result.key !== "string" || typeof result.url !== "string" || typeof result.size !== "number" || typeof result.contentType !== "string" || (result.name !== null && typeof result.name !== "string")) {
         throw new EraspaceError("StorageError", "Invalid upload response");
       }
-      return { key: result.key, url: result.url, size: result.size, contentType: result.contentType, name: result.name };
+      const deleteToken = typeof result.deleteToken === "string" ? result.deleteToken : undefined;
+      if (deleteToken) deleteTokens.set(result.key, deleteToken);
+      return { key: result.key, url: result.url, size: result.size, contentType: result.contentType, name: result.name, ...(deleteToken ? { deleteToken } : {}) };
+    },
+    async info(key, options = {}) {
+      if (!isStorageKey(key)) return null;
+      const response = await fetch(url(key), { method: "HEAD", signal: options.signal });
+      if (response.status === 404) return null;
+      if (!response.ok) throw new EraspaceError("StorageError", `Storage request failed: HTTP ${response.status}`);
+      return {
+        key,
+        url: url(key),
+        size: Number(response.headers.get("content-length") ?? 0),
+        contentType: response.headers.get("content-type") ?? "application/octet-stream",
+        name: dispositionName(response.headers.get("content-disposition")),
+      };
     },
     async delete(key, options = {}) {
-      await check(await fetch(url(key), { method: "DELETE", signal: options.signal }));
+      const deleteToken = options.deleteToken ?? deleteTokens.get(key);
+      const headers = new Headers();
+      if (deleteToken) headers.set("x-eraspace-file-token", deleteToken);
+      const response = await fetch(url(key), { method: "DELETE", headers, signal: options.signal });
+      check(response.status, await response.text());
+      deleteTokens.delete(key);
     },
   };
 }

package/sdk/src/client/subscription.ts

@@ -28,9 +28,13 @@ export class Subscription {
   commitSeq = -1;
   revision: number | undefined;
   request = 0;
+  retries = 0;
+  retryTimer: ReturnType<typeof setTimeout> | undefined;
   refs = 0;
   layers: Layer[] = [];
   timer: ReturnType<typeof setTimeout> | undefined;
+  /** The id last sent to the server, and the app channel join it was sent on. */
+  sent: { id: string; join: number } | undefined;
   // Resubscriptions take a new id so messages for the previous one are ignored.
   id: string;
   readonly fn: string;

package/sdk/src/client/transport.ts

@@ -0,0 +1,356 @@
+import { EraspaceError } from "./errors.ts";
+import { retryDelay } from "./retry.ts";
+
+// Event classes differ across runtimes. Handlers only read message data.
+type TransportHandler<T> = { handle(event: T): void }["handle"];
+
+/** The browser WebSocket API subset also implemented by Node and ws. */
+export interface WebSocketTransport {
+  readonly readyState: number;
+  onopen: TransportHandler<unknown> | null;
+  onclose: TransportHandler<unknown> | null;
+  onerror: TransportHandler<unknown> | null;
+  onmessage: TransportHandler<{ data: unknown }> | null;
+  send(data: string): void;
+  close(): void;
+}
+export type WebSocketConstructor = new (url: string) => WebSocketTransport;
+export interface SocketOptions {
+  timeout?: number;
+  transport?: WebSocketConstructor;
+  reconnectAfterMs?: (attempt: number) => number;
+  rejoinAfterMs?: (attempt: number) => number;
+  /** How long a socket must stay open before reconnect backoff starts again from the first attempt. */
+  stableAfterMs?: number;
+}
+
+interface Frame {
+  session: string | null;
+  ref: string | null;
+  topic: string;
+  event: string;
+  payload: unknown;
+}
+interface Pending {
+  /** The frame to send: undefined while not ready, null to withdraw a request that was never sent. */
+  frame: () => Frame | undefined | null;
+  sent?: Frame;
+  resolve: (value: unknown) => void;
+  reject: (error: EraspaceError) => void;
+  timer: ReturnType<typeof setTimeout>;
+  topic: string;
+}
+export interface JoinReply { self?: string; now?: number; version?: number }
+
+/** Multiplexes topics over one native WebSocket. Sent requests are never replayed on reconnect. */
+export class Socket {
+  private ws: WebSocketTransport | undefined;
+  private channels = new Map<string, Channel>();
+  private pending = new Map<string, Pending>();
+  private nextRef = 0;
+  private incoming = Promise.resolve();
+  private stopped = true;
+  private attempts = 0;
+  private reconnect: ReturnType<typeof setTimeout> | undefined;
+  private opening: ReturnType<typeof setTimeout> | undefined;
+  private stable: ReturnType<typeof setTimeout> | undefined;
+  private heartbeat: ReturnType<typeof setInterval> | undefined;
+  private awaitingHeartbeat: { ref: string; timer: ReturnType<typeof setTimeout> } | undefined;
+  private opens = new Set<() => void>();
+  private closes = new Set<() => void>();
+  readonly options: SocketOptions;
+  private url: string;
+
+  constructor(endpoint: string, options: SocketOptions = {}) {
+    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");
+    this.url = url.href;
+    this.options = options;
+  }
+
+  onOpen(cb: () => void): void { this.opens.add(cb); }
+  onClose(cb: () => void): void { this.closes.add(cb); }
+  ref(): string { return String(++this.nextRef); }
+  get connected(): boolean { return this.ws?.readyState === 1; }
+
+  connect(): void {
+    if (!this.stopped) return;
+    this.stopped = false;
+    this.attempts = 0;
+    this.open();
+  }
+
+  private open(): void {
+    if (this.stopped) return;
+    const Transport = this.options.transport ?? WebSocket;
+    let ws: WebSocketTransport;
+    try { ws = new Transport(this.url); }
+    catch { this.scheduleReconnect(); return; }
+    this.ws = ws;
+    this.opening = setTimeout(() => this.lost(ws), this.options.timeout ?? 15000);
+    ws.onopen = () => {
+      if (this.ws !== ws) return;
+      clearTimeout(this.opening);
+      // A server that accepts sockets and then drops them must not reset every client's backoff at once, so
+      // backoff restarts only after the connection has proved stable.
+      this.stable = setTimeout(() => {
+        if (this.ws === ws) this.attempts = 0;
+      }, this.options.stableAfterMs ?? 10000);
+      for (const cb of this.opens) cb();
+      for (const channel of this.channels.values()) channel.rejoin();
+      this.flush();
+      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; }
+      // 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));
+    };
+    ws.onclose = () => this.lost(ws);
+    ws.onerror = () => this.lost(ws);
+  }
+
+  private receive(frame: Frame): void {
+    if (frame.event === "reply" && frame.ref) {
+      const body = frame.payload;
+      if (!body || typeof body !== "object" || !("status" in body) || !("response" in body)) return;
+      if (body.status !== "ok" && body.status !== "error") return;
+      if (frame.ref === this.awaitingHeartbeat?.ref && frame.topic === "" && frame.session === null && body.status === "ok") {
+        clearTimeout(this.awaitingHeartbeat.timer);
+        this.awaitingHeartbeat = undefined;
+        return;
+      }
+      const pending = this.pending.get(frame.ref);
+      if (!pending?.sent || pending.sent.topic !== frame.topic || pending.sent.session !== frame.session) return;
+      this.pending.delete(frame.ref);
+      clearTimeout(pending.timer);
+      if (body.status === "ok") pending.resolve(body.response);
+      else {
+        const error = EraspaceError.from(body.response);
+        pending.reject(new EraspaceError(error.name, error.message, body.response));
+      }
+      this.flush();
+    } else {
+      this.channels.get(frame.topic)?.receive(frame);
+    }
+  }
+
+  private sendHeartbeat(ws: WebSocketTransport): void {
+    if (this.ws !== ws || ws.readyState !== 1 || this.awaitingHeartbeat) return;
+    const ref = this.ref();
+    // Liveness checks bypass the application window and start their deadline only after send succeeds.
+    try {
+      ws.send(JSON.stringify({ session: null, ref, topic: "", event: "ping", payload: {} }));
+      this.awaitingHeartbeat = { ref, timer: setTimeout(() => this.lost(ws), 10000) };
+    } catch { this.lost(ws); }
+  }
+
+  private lost(ws: WebSocketTransport): void {
+    if (this.ws !== ws) return;
+    this.ws = undefined;
+    clearTimeout(this.opening);
+    clearTimeout(this.stable);
+    ws.onopen = ws.onclose = ws.onmessage = null;
+    ws.onerror = () => {};
+    ws.close();
+    clearInterval(this.heartbeat);
+    clearTimeout(this.awaitingHeartbeat?.timer);
+    this.awaitingHeartbeat = undefined;
+    for (const [ref, pending] of this.pending) {
+      if (pending.sent) this.fail(ref, new EraspaceError("OutcomeUnknownError", "Connection lost before the reply arrived"));
+    }
+    for (const channel of this.channels.values()) channel.disconnected();
+    for (const cb of this.closes) cb();
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped) return;
+    clearTimeout(this.reconnect);
+    this.reconnect = setTimeout(() => this.open(), (this.options.reconnectAfterMs ?? retryDelay)(++this.attempts));
+  }
+
+  disconnect(): void {
+    this.stopped = true;
+    clearTimeout(this.reconnect);
+    clearInterval(this.heartbeat);
+    for (const channel of [...this.channels.values()]) channel.leave();
+    if (this.ws) this.lost(this.ws);
+    for (const ref of this.pending.keys()) this.fail(ref, new EraspaceError("UnavailableError", "Socket closed"));
+  }
+
+  channel(topic: string, payload: object | (() => object) = {}): Channel {
+    const previous = this.channels.get(topic);
+    if (previous) return previous;
+    const channel = new Channel(this, topic, payload);
+    this.channels.set(topic, channel);
+    return channel;
+  }
+
+  remove(channel: Channel, session: string | null): void {
+    if (this.channels.get(channel.topic) !== channel) return;
+    const ws = this.ws;
+    if (session !== null && !this.stopped && ws?.readyState === 1) {
+      // Cleanup must also work while the request window is full or a join reply is still pending.
+      try { ws.send(JSON.stringify({ session, ref: this.ref(), topic: channel.topic, event: "leave", payload: {} })); }
+      catch { this.lost(ws); }
+    }
+    this.channels.delete(channel.topic);
+    for (const [ref, pending] of this.pending) {
+      if (pending.topic === channel.topic) this.fail(ref, new EraspaceError("UnavailableError", "Channel closed"));
+    }
+  }
+
+  request<T>(frame: () => Frame | undefined | null, topic: string, timeout = this.options.timeout ?? 15000): Promise<T> {
+    if (this.pending.size >= 256) return Promise.reject(new EraspaceError("ResourceError", "Too many pending socket requests"));
+    const ref = this.ref();
+    return new Promise<T>((resolve, reject) => {
+      // Work that never left this client has no unknown outcome, so it does not time out like a sent request.
+      const timer = setTimeout(() => this.fail(ref, this.pending.get(ref)?.sent
+        ? new EraspaceError("TimeoutError", "Socket request timed out")
+        : new EraspaceError("UnavailableError", "Not connected; the request was not sent")), timeout);
+      this.pending.set(ref, { frame, topic, timer, resolve: value => resolve(value as T), reject });
+      this.flush();
+    });
+  }
+
+  private fail(ref: string, error: EraspaceError): void {
+    const pending = this.pending.get(ref);
+    if (!pending) return;
+    this.pending.delete(ref);
+    clearTimeout(pending.timer);
+    pending.reject(error);
+    this.flush();
+  }
+
+  flush(): void {
+    const ws = this.ws;
+    if (!ws || ws.readyState !== 1) return;
+    // A join can produce a reply plus presence and state pushes. Bound bursts below the desk's mailboxes.
+    let inFlight = [...this.pending.values()].filter(pending => pending.sent).length;
+    for (const [ref, pending] of this.pending) {
+      if (inFlight >= 16) break;
+      if (pending.sent) continue;
+      const frame = pending.frame();
+      if (frame === null) {
+        this.pending.delete(ref);
+        clearTimeout(pending.timer);
+        pending.reject(new EraspaceError("UnavailableError", "Request withdrawn before it was sent"));
+        continue;
+      }
+      if (!frame) continue;
+      frame.ref = ref;
+      try { ws.send(JSON.stringify(frame)); pending.sent = frame; inFlight++; }
+      catch { this.lost(ws); break; }
+    }
+  }
+}
+
+/** A join generation prevents late replies and pushes from a replaced channel being delivered. */
+export class Channel {
+  readonly topic: string;
+  private socket: Socket;
+  private payload: object | (() => object);
+  private session: string | null = null;
+  private joined = false;
+  private started = false;
+  private closed = false;
+  private joining = false;
+  private attempts = 0;
+  private retry: ReturnType<typeof setTimeout> | undefined;
+  private events = new Map<string, Set<(payload: unknown) => void>>();
+  private joins = new Set<(reply: JoinReply) => void>();
+  private errors = new Set<(error: unknown, rejected: boolean) => void>();
+  private closes = new Set<() => void>();
+  onMessage: ((event: string, payload: unknown) => void) | undefined;
+
+  constructor(socket: Socket, topic: string, payload: object | (() => object)) {
+    this.socket = socket;
+    this.topic = topic;
+    this.payload = payload;
+  }
+  on<T = unknown>(event: string, cb: (payload: T) => void): () => void {
+    const handler = (value: unknown) => cb(value as T);
+    let handlers = this.events.get(event);
+    if (!handlers) this.events.set(event, handlers = new Set());
+    handlers.add(handler);
+    return () => handlers.delete(handler);
+  }
+  onJoin(cb: (reply: JoinReply) => void): void { this.joins.add(cb); }
+  onError(cb: (error: unknown, rejected: boolean) => void): void { this.errors.add(cb); }
+  onClose(cb: () => void): void { this.closes.add(cb); }
+
+  join(): void {
+    if (this.started || this.closed) return;
+    this.started = true;
+    this.rejoin();
+  }
+
+  rejoin(): void {
+    if (!this.started || this.closed || this.joined || this.joining || !this.socket.connected) return;
+    clearTimeout(this.retry);
+    const session = this.socket.ref();
+    this.session = session;
+    this.joining = true;
+    void this.socket.request<JoinReply>(() => ({ session, ref: null, topic: this.topic, event: "join", payload: typeof this.payload === "function" ? this.payload() : this.payload }), this.topic)
+      .then(reply => {
+        if (this.closed || this.session !== session) return;
+        this.joining = false;
+        this.joined = true;
+        this.attempts = 0;
+        for (const cb of this.joins) cb(reply);
+        this.socket.flush();
+      }, error => {
+        if (this.closed || this.session !== session) return;
+        this.joining = false;
+        for (const cb of this.errors) cb(error, error instanceof EraspaceError && error.data !== undefined);
+        if (!this.closed) this.retry = setTimeout(() => this.rejoin(), (this.socket.options.rejoinAfterMs ?? retryDelay)(++this.attempts));
+      });
+  }
+
+  /** A function payload is read when the request is sent; returning null withdraws the request unsent. */
+  push<T = unknown>(event: string, payload: object | (() => object | null), timeout?: number): Promise<T> {
+    if (this.closed) return Promise.reject(new EraspaceError("UnavailableError", "Channel closed"));
+    return this.socket.request<T>(() => {
+      if (!this.joined) return undefined;
+      const body = typeof payload === "function" ? payload() : payload;
+      return body === null ? null : { session: this.session, ref: null, topic: this.topic, event, payload: body };
+    }, this.topic, timeout);
+  }
+
+  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);
+  }
+
+  disconnected(): void {
+    this.joined = this.joining = false;
+    this.session = null;
+    clearTimeout(this.retry);
+    for (const cb of this.errors) cb(new EraspaceError("UnavailableError", "Connection lost"), false);
+  }
+
+  leave(): void {
+    if (this.closed) return;
+    const session = this.session;
+    this.closed = true;
+    this.joined = false;
+    clearTimeout(this.retry);
+    this.socket.remove(this, session);
+    for (const cb of this.closes) cb();
+  }
+}

package/sdk/src/client/types.ts

@@ -1,6 +1,7 @@
 import type { ReadonlySignal } from "@preact/signals";
 import type { EraspaceError } from "./errors.ts";
 import type { StorageClient } from "./storage.ts";
+import type { Upload, UseUploadOptions } from "./files.ts";
 
 import type {
   ActionArgs,
@@ -72,11 +73,15 @@ export interface Room<M = Record<string, unknown>, S extends Record<string, unkn
   on(event: string, cb: (payload: any, from: string | undefined) => void): () => void;
   /** Ephemeral shared state (kept by the room process, never stored). */
   state: Partial<S>;
+  /** Last room join or write error. Cleared by a successful join or state update. */
+  error: EraspaceError | undefined;
   setState<K extends keyof S & string>(key: K, value: S[K]): void;
 }
 
 export interface EraspaceClient<C> {
   readonly storage: StorageClient;
+  /** Upload files to app storage with progress and errors as component state. `<FileUpload>` wraps this. */
+  useUpload(options?: UseUploadOptions): Upload;
   /** Subscribe to a query. Returns `undefined` until the first result arrives, then live values. */
   useQuery<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): QueryResult<C, N> | undefined;
   /** Pass computed signals directly to JSX text nodes for updates without a component render. */
@@ -102,6 +107,8 @@ export interface EraspaceClient<C> {
 
   query<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): Promise<QueryResult<C, N>>;
   mutation<N extends MutationName<C>>(name: N, ...args: MutationArgs<C, N>): Promise<MutationResult<C, N>>;
+  /** Recover an unknown mutation outcome with its original name, arguments and request key, within 24 hours. */
+  retryMutation<N extends MutationName<C>>(name: N, args: MutationArgs<C, N>, requestKey: string): Promise<MutationResult<C, N>>;
   action<N extends ActionName<C>>(name: N, ...args: ActionArgs<C, N>): Promise<ActionResult<C, N>>;
   /** Imperative live subscription. Returns an unsubscribe function. */
   subscribe<N extends QueryName<C>>(

package/sdk/src/server/index.ts

@@ -1,9 +1,8 @@
 // Generated by scripts/generate-server-api.ts. Edit api/server-api.ts or api/server.ts.in.
 // eraspace/server: capsule definition API.
 //
-// On the platform this module is never executed. The compiler maps `eraspace/server` to the Erlang module
-// `sbrt_sdk`, which implements the same constructors. The implementations below are thin descriptors so that the
-// module also works in Bun (tests, tooling) and, mainly, so the types drive inference.
+// V8 supplies this module from the engine bootstrap. These descriptors also run in Node for tooling and tests;
+// their types drive client and server inference.
 //
 // Type design. `ctx.db` must be typed from `schema` even though both live in the same object literal:
 //
@@ -476,7 +475,7 @@ export interface EndpointRequest {
   query: EndpointQuery;
   text(): Promise<string>;
   json<T = unknown>(): Promise<T>;
-  /** Request body bytes. Typed arrays are not supported by the runtime. */
+  /** Request body bytes as a JSON-compatible number array. */
   bytes(): Promise<number[]>;
 }
 

package/templates/chat/client/index.tsx

@@ -1,4 +1,4 @@
-import { createClient } from "eraspace/client";
+import { createClient, FilePreview, FileUpload, type FileRef } from "eraspace/client";
 import { useState, useEffect } from "preact/hooks";
 import type app from "../server/index";
 const client = createClient<typeof app>({ reloadOnDeploy: true });
@@ -9,6 +9,7 @@ export default function App() {
   const [error, setError] = useState("");
   const [sending, setSending] = useState(false);
   const [typing, setTyping] = useState("");
+  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 });
@@ -22,14 +23,17 @@ export default function App() {
       <input name="room" aria-label="Room" defaultValue={room} maxLength={40}/><button class="subtle">Join room</button>
     </form>
     <div class="presence">{channel.presence.length} online · {channel.presence.map(member => member.meta.name || "Guest").join(", ")}</div>
-    {messages === undefined ? <p>Loading messages…</p> : messages.length === 0 ? <p>Send the first message.</p> : <ul>{[...messages].reverse().map(message => <li key={message.id}><strong>{message.author}</strong><span>{message.body}</span><time>{new Date(message.createdAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time></li>)}</ul>}
+    {messages === undefined ? <p>Loading messages…</p> : messages.length === 0 ? <p>Send the first message.</p> : <ul>{[...messages].reverse().map(message => <li key={message.id}><strong>{message.author}</strong><span>{message.body}{message.file && <FilePreview client={client} file={message.file} class="attachment"/>}</span><time>{new Date(message.createdAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time></li>)}</ul>}
     <form onSubmit={async e => {
       e.preventDefault(); setSending(true); setError("");
-      try { await send(room, author, body); setBody(""); } catch (err) { setError(err instanceof Error ? err.message : String(err)); } finally { setSending(false); }
+      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 onInput={e => { setBody(e.currentTarget.value); channel.broadcast("typing", author); }}/>
-      <button disabled={sending || !body.trim()}>Send</button>
+      <input aria-label="Message" placeholder="Message" value={body} maxLength={2000} required={!file} onInput={e => { setBody(e.currentTarget.value); 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>
+        : <FileUpload client={client} class="attach" onUpload={setFile}>Attach a file (up to 5 MB)</FileUpload>}
     </form>
     {typing && <small>{typing} is typing</small>}
     {error && <p role="alert">{error}</p>}

package/templates/chat/client/styles.css

@@ -24,5 +24,20 @@
   meter::-moz-meter-bar { background: #fff; }
   .done { text-decoration: line-through; }
   .presence { padding: 12px 0; font-size: 13px; }
+  .attach { flex-basis: 100%; padding: 10px; border: 1px dashed #666; color: #aaa; font-size: 13px; text-align: center; cursor: pointer; position: relative; }
+  .attach[data-dragging], .attach:hover, .attach:focus-within { border-color: #fff; color: #fff; }
+  .attach progress { display: block; width: 100%; margin-top: 6px; accent-color: #fff; }
+  .pending { flex-basis: 100%; display: flex; align-items: center; gap: 12px; font-size: 13px; }
+  .pending > span { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  li:has(.attachment) { align-items: flex-start; }
+  .attachment { margin: 8px 0 0; }
+  li > span > .attachment:first-child { margin-top: 0; }
+  .attachment img, .attachment video { display: block; max-width: 100%; max-height: 280px; border: 1px solid #333; }
+  .pending .attachment { margin: 0; }
+  .pending .attachment img { max-height: 48px; }
+  .attachment audio { display: block; width: 100%; }
+  .attachment iframe { display: block; width: 100%; height: 160px; border: 1px solid #333; background: #fff; }
+  .attachment a { color: #ccc; display: inline-flex; gap: 8px; }
+  .attachment figcaption { display: flex; gap: 8px; margin-top: 4px; font-size: 12px; color: #888; }
   @media (max-width: 480px) { main { padding: 20px 12px; } li { flex-wrap: wrap; } }
 }

package/templates/chat/server/index.ts

@@ -1,17 +1,27 @@
-import { capsule, table, query, mutation, endpoint, string, text } from "eraspace/server";
+import { capsule, table, query, mutation, endpoint, string, number, object, text } from "eraspace/server";
+type Attachment = { key: string; name: string; contentType: string; size: number };
+const KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 export default capsule({
-  schema: { messages: table({ room: string(), author: string(), body: string() }).index("by_room", ["room"]) },
+  schema: {
+    messages: table({
+      room: string(), author: string(), body: string(),
+      // A file in app storage, saved from the client's FileUpload.
+      file: object({ key: string(), name: string(), contentType: string(), size: number() }).optional(),
+    }).index("by_room", ["room"]),
+  },
   queries: {
     messages: query(async (ctx, room: string) => ctx.db.messages.withIndex("by_room", q => q.eq("room", room)).order("desc").take(100)),
   },
   mutations: {
-    send: mutation(async (ctx, room: string, author: string, body: string) => {
+    send: mutation(async (ctx, room: string, author: string, body: string, file?: Attachment | null) => {
       const trimmed = body.trim();
-      if (!trimmed || trimmed.length > 2000) throw new Error("Write a message of 1 to 2000 characters.");
+      if (trimmed.length > 2000 || (!trimmed && !file)) throw new Error("Write a message of 1 to 2000 characters.");
+      if (file && (!KEY.test(String(file.key)) || typeof file.name !== "string" || typeof file.contentType !== "string" || !Number.isInteger(file.size) || file.size < 0)) throw new Error("That attachment is not a stored file.");
       const name = author.trim().slice(0, 40) || "Guest";
       ctx.log.info("message sent", { room });
-      return ctx.db.messages.insert({ room, author: name, body: trimmed });
+      const attachment = file ? { key: file.key, name: file.name.slice(0, 255) || "file", contentType: file.contentType.slice(0, 256), size: file.size } : undefined;
+      return ctx.db.messages.insert({ room, author: name, body: trimmed, file: attachment });
     }),
   },
-  endpoints: { hi: endpoint({ method: "GET", path: "/hi", readOnly: true }, () => text("hello from BEAM")) },
+  endpoints: { hi: endpoint({ method: "GET", path: "/hi", readOnly: true }, () => text("hello from eraspace")) },
 });