eraspace 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,132 @@
+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,
+  ActionName,
+  ActionResult,
+  MutationArgs,
+  MutationName,
+  MutationResult,
+  PaginationOptions,
+  PaginationResult,
+  QueryArgs,
+  QueryName,
+  QueryResult,
+} from "../server/index.ts";
+
+export type Status = "connecting" | "open" | "closed";
+
+export interface PresenceEntry<M = Record<string, unknown>> {
+  id: string;
+  meta: M;
+  /** All metas for this id (one per open connection). */
+  metas: M[];
+}
+
+/** Query names whose last argument is `PaginationOptions` and whose result is a `PaginationResult`. */
+export type PaginatedQueryName<C> = {
+  [N in QueryName<C>]: QueryArgs<C, N> extends [...any[], PaginationOptions]
+    ? QueryResult<C, N> extends PaginationResult<any>
+      ? N
+      : never
+    : never;
+}[QueryName<C>];
+type PaginatedArgs<C, N extends QueryName<C>> = QueryArgs<C, N> extends [...infer P, PaginationOptions] ? P : never;
+type PaginatedItem<C, N extends QueryName<C>> = QueryResult<C, N> extends PaginationResult<infer T> ? T : never;
+
+export interface PaginatedQueryResult<T> {
+  /** Every loaded row, in page order. */
+  results: T[];
+  status: "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted";
+  isLoading: boolean;
+  loadMore(numItems?: number): void;
+  reset(): void;
+}
+
+/** The local cache handed to optimistic updaters. */
+export interface OptimisticStore<C> {
+  get<N extends QueryName<C>>(name: N, args: QueryArgs<C, N>): QueryResult<C, N> | undefined;
+  set<N extends QueryName<C>>(name: N, args: QueryArgs<C, N>, value: QueryResult<C, N>): void;
+  /** Apply `updater` to the cached result of `name(...args)` if it is loaded. */
+  update<N extends QueryName<C>>(
+    name: N,
+    args: QueryArgs<C, N>,
+    updater: (prev: QueryResult<C, N>) => QueryResult<C, N>,
+  ): void;
+}
+
+export interface MutationOptions<C, A extends any[]> {
+  optimistic?: (store: OptimisticStore<C>, ...args: A) => void;
+}
+
+export interface Room<M = Record<string, unknown>, S extends Record<string, unknown> = Record<string, unknown>> {
+  /** Members currently in the room. */
+  presence: PresenceEntry<M>[];
+  /** This connection's public guest id. Changes on reconnect. Empty until the room join completes. */
+  self: string;
+  /** Send `event` to every other member. */
+  broadcast(event: string, payload?: unknown): void;
+  /** Listen for `event` broadcasts. Returns an unsubscribe function. Call it in an effect. */
+  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. */
+  useQuerySignal<N extends QueryName<C>>(name: N, ...args: QueryArgs<C, N>): ReadonlySignal<QueryResult<C, N> | undefined>;
+  /** Re-render only when the selected result changes. */
+  useQuerySelector<N extends QueryName<C>, T>(name: N, args: QueryArgs<C, N>, select: (value: QueryResult<C, N> | undefined) => T): T;
+  useMutation<N extends MutationName<C>>(
+    name: N,
+    options?: MutationOptions<C, MutationArgs<C, N>>,
+  ): (...args: MutationArgs<C, N>) => Promise<MutationResult<C, N>>;
+  useAction<N extends ActionName<C>>(name: N): (...args: ActionArgs<C, N>) => Promise<ActionResult<C, N>>;
+  usePaginatedQuery<N extends PaginatedQueryName<C>>(
+    name: N,
+    args: PaginatedArgs<C, N>,
+    options?: { initialNumItems?: number },
+  ): PaginatedQueryResult<PaginatedItem<C, N>>;
+  /** Join `room` and return its members. `meta` is this tab's presence metadata (cursor, typing, name...). */
+  usePresence<M extends Record<string, unknown> = Record<string, unknown>>(room: string, meta?: M): PresenceEntry<M>[];
+  useRoom<M extends Record<string, unknown> = Record<string, unknown>, S extends Record<string, unknown> = Record<string, unknown>>(
+    room: string,
+    meta?: M,
+  ): Room<M, S>;
+
+  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>>(
+    name: N,
+    args: QueryArgs<C, N>,
+    onValue: (value: QueryResult<C, N>) => void,
+    onError?: (error: EraspaceError) => void,
+  ): () => void;
+
+  readonly app: string;
+  readonly base: string;
+  /** This connection's public guest id. Changes on reconnect. Empty until the socket has joined. */
+  readonly guestId: string;
+  /** Socket status: `connecting`, `open` or `closed`. */
+  readonly status: ReadonlySignal<Status>;
+  /** Latest deployed version seen by this client. */
+  readonly version: ReadonlySignal<number>;
+  /** Called after each redeploy (after subscriptions are re-sent). */
+  onDeployed(cb: (version: number) => void): () => void;
+  close(): void;
+}