eraspace 0.0.0-stage → 0.2.0

package/sdk/src/client/room.ts

@@ -0,0 +1,110 @@
+import type { Socket, Channel } from "./transport.ts";
+import { signal, type Signal } from "@preact/signals";
+import type { PresenceEntry } from "./types.ts";
+import { EraspaceError } from "./errors.ts";
+import { stableStringify } from "./sub-key.ts";
+
+export class RoomConn {
+  channel: Channel;
+  readonly members: Signal<PresenceEntry<Record<string, unknown>>[]> = signal([]);
+  readonly state: Signal<Record<string, unknown>> = signal({});
+  readonly self: Signal<string>;
+  readonly error = signal<EraspaceError | undefined>(undefined);
+  private serverState: Record<string, unknown> = {};
+  private pending = new Map<number, { key: string; value: unknown }>();
+  private revisions = new Map<string, number>();
+  private nextChange = 0;
+  private closed = false;
+  refs = 0;
+  meta: Record<string, unknown> = {};
+  listeners = new Map<string, Set<(payload: any, from: string | undefined) => void>>();
+  timer: ReturnType<typeof setTimeout> | undefined;
+  readonly topic: string;
+
+  constructor(socket: Socket, topic: string, clientSelf: Signal<string>) {
+    this.topic = topic;
+    // The join reply carries the server-derived id; until then this is the id from the app channel, if known.
+    this.self = signal(clientSelf.value);
+    this.channel = socket.channel(topic, () => ({ meta: this.meta }));
+    this.channel.on<Record<string, Record<string, unknown>[]>>("presence", (members) => {
+      this.members.value = Object.entries(members).map(([id, metas]) => ({ id, meta: metas[0] ?? {}, metas }));
+    });
+    this.channel.on("msg", (m: { event: string; payload: unknown; from?: string }) => {
+      const set = this.listeners.get(m.event);
+      if (set) for (const cb of [...set]) cb(m.payload, m.from);
+      const all = this.listeners.get("*");
+      if (all) for (const cb of [...all]) cb(m, m.from);
+    });
+    this.channel.on("state:full", (m: { state?: Record<string, unknown> }) => {
+      this.serverState = { ...(m.state ?? {}) };
+      this.revisions.clear();
+      // Writes buffered while joining still need their replies to settle or report an error.
+      this.recompute();
+    });
+    this.channel.on("state", (m: { key: string; value: unknown }) => {
+      this.serverState = { ...this.serverState, [m.key]: m.value };
+      this.revisions.set(m.key, (this.revisions.get(m.key) ?? 0) + 1);
+      this.recompute();
+    });
+    const failed = (payload: unknown) => {
+      this.pending.clear();
+      this.recompute();
+      this.error.value = EraspaceError.from(payload, "Room channel disconnected");
+      if (payload && typeof payload === "object" && "name" in payload && payload.name === "AppGone") this.close();
+    };
+    this.channel.on("gone", () => failed({ name: "AppGone", message: "This app is no longer serving", reason: "gone" }));
+    this.channel.onError(failed);
+    this.channel.onClose(() => { if (!this.closed) failed({ name: "UnavailableError", message: "Room channel closed" }); });
+    this.channel.onJoin((resp) => {
+      this.error.value = undefined;
+      if (resp && typeof resp.self === "string") this.self.value = clientSelf.value = resp.self;
+    });
+    this.channel.join();
+  }
+
+  setMeta(meta: Record<string, unknown>): void {
+    if (stableStringify(meta) === stableStringify(this.meta)) return;
+    const previous = this.meta;
+    this.meta = meta;
+    const failed = (payload: unknown) => {
+      if (this.meta === meta) this.meta = previous;
+      this.error.value = EraspaceError.from(payload, "Room metadata update failed");
+    };
+    void this.channel.push("meta", { meta }).catch(failed);
+  }
+
+  private recompute(): void {
+    const state = { ...this.serverState };
+    for (const { key, value } of this.pending.values()) state[key] = value;
+    this.state.value = state;
+  }
+
+  setState(key: string, value: unknown): void {
+    if (this.closed) return;
+    const id = ++this.nextChange;
+    const revision = this.revisions.get(key) ?? 0;
+    this.pending.set(id, { key, value: value ?? null });
+    this.recompute();
+    const failed = (payload: unknown) => {
+      if (!this.pending.delete(id)) return;
+      this.recompute();
+      this.error.value = EraspaceError.from(payload, "Room state update failed");
+    };
+    void this.channel.push("state:set", { key, value: value ?? null })
+      .then(() => {
+        if (!this.pending.delete(id)) return;
+        if ((this.revisions.get(key) ?? 0) === revision) this.serverState = { ...this.serverState, [key]: value ?? null };
+        this.error.value = undefined;
+        this.recompute();
+      }, failed);
+  }
+
+  close(): void {
+    this.closed = true;
+    clearTimeout(this.timer);
+    this.pending.clear();
+    this.recompute();
+    this.channel.leave();
+  }
+
+}

package/sdk/src/client/router.ts

@@ -0,0 +1,177 @@
+// Client routing. preact-iso's <Router> does the matching; our <LocationProvider> feeds it app-relative paths, so
+// `<Route path="/todos/:id">` matches `/<app>/todos/123`. Links and navigation add the base back.
+import { h, isValidElement, toChildArray, type ComponentChildren, type ComponentType, type Context, type JSX, type VNode } from "preact";
+import { useContext, useLayoutEffect, useMemo, useState } from "preact/hooks";
+import { LocationProvider as IsoLocationProvider, Router as IsoRouter, useLocation as isoUseLocation, useRoute } from "preact-iso/router";
+import { readConfig } from "./client.ts";
+
+export interface LocationValue {
+  /** App-relative URL including the query string, e.g. `/todos/1?x=2`. */
+  url: string;
+  /** App-relative path, e.g. `/todos/1`. */
+  path: string;
+  query: Record<string, string>;
+  /** Navigate to an app-relative URL. */
+  route(url: string, replace?: boolean): void;
+  back(): void;
+  forward(): void;
+}
+
+const ctx = (IsoLocationProvider as unknown as { ctx: Context<any> }).ctx;
+
+function normalizeBase(base: string | undefined): string {
+  let b = base ?? readConfig().base ?? "/";
+  if (!b.startsWith("/")) b = "/" + b;
+  if (!b.endsWith("/")) b += "/";
+  return b;
+}
+
+/** Strip the app base from an absolute path: `/chat/rooms/1` → `/rooms/1`. */
+export function stripBase(base: string, url: string): string {
+  if (url.startsWith(base)) return "/" + url.slice(base.length);
+  const bare = base.slice(0, -1);
+  if (url === bare || url.startsWith(bare + "?") || url.startsWith(bare + "#")) return "/" + url.slice(bare.length);
+  return url;
+}
+
+/** Turn an app-relative URL into an absolute one: `/rooms/1` → `/chat/rooms/1`. */
+export function withBase(base: string, to: string): string {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(to) || to.startsWith("//")) return to;
+  if (to.startsWith(base)) return to;
+  return base + (to.startsWith("/") ? to.slice(1) : to);
+}
+
+function currentUrl(base: string): string {
+  if (typeof location === "undefined") return "/";
+  return stripBase(base, location.pathname + location.search);
+}
+
+let globalBase = "/";
+
+/** Provides the app-relative location. `mount()` adds one around your App unless `router: false`. */
+export function LocationProvider(props: { base?: string; url?: string; children?: ComponentChildren }) {
+  const base = normalizeBase(props.base);
+  globalBase = base;
+  const [state, setState] = useState(() => ({ url: props.url ?? currentUrl(base), wasPush: false }));
+
+  const value = useMemo(() => {
+    const u = new URL(state.url, "http://x");
+    const path = u.pathname.replace(/\/+$/g, "") || "/";
+    const route = (to: string, replace?: boolean) => {
+      const abs = withBase(base, to);
+      if (typeof history !== "undefined") {
+        if (replace) history.replaceState(null, "", abs);
+        else history.pushState(null, "", abs);
+      }
+      setState({ url: stripBase(base, abs), wasPush: !replace });
+    };
+    return {
+      url: state.url,
+      path,
+      query: Object.fromEntries(u.searchParams),
+      route,
+      back: () => history.back(),
+      forward: () => history.forward(),
+      wasPush: state.wasPush,
+    };
+  }, [state, base]);
+
+  useLayoutEffect(() => {
+    const onPop = () => setState({ url: currentUrl(base), wasPush: false });
+    const onClick = (e: MouseEvent) => {
+      if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const a = (e.composedPath() as Element[]).find((el) => el.nodeName === "A") as HTMLAnchorElement | undefined;
+      if (!a || !a.href || a.origin !== location.origin || a.download) return;
+      if (a.target && !/^_?self$/i.test(a.target)) return;
+      const href = a.getAttribute("href") ?? "";
+      if (href.startsWith("#")) return;
+      const abs = a.pathname + a.search;
+      if (!(abs + "/").startsWith(base) && !abs.startsWith(base)) return;
+      e.preventDefault();
+      value.route(stripBase(base, abs + a.hash));
+    };
+    addEventListener("popstate", onPop);
+    addEventListener("click", onClick);
+    return () => {
+      removeEventListener("popstate", onPop);
+      removeEventListener("click", onClick);
+    };
+  }, [base, value]);
+
+  return h(ctx.Provider, { value }, props.children);
+}
+
+function isRouteChild(v: unknown): boolean {
+  const p = (v as VNode<any> | null)?.props;
+  return !!p && (p.path !== undefined || p.default);
+}
+
+/**
+ * Renders the first child `<Route>` whose `path` matches. Without route children it only provides the location,
+ * so both `<Router><Route .../></Router>` and Lakebed's `<Router><Routes>...</Routes></Router>` work.
+ */
+export function Router(props: {
+  children?: ComponentChildren;
+  onRouteChange?: (url: string) => void;
+  onLoadStart?: (url: string) => void;
+  onLoadEnd?: (url: string) => void;
+}) {
+  const hasProvider = !!useContext(ctx)?.url;
+  const routes = toChildArray(props.children).some(isRouteChild);
+  // preact-iso serializes route props, and rendered VNodes contain circular parent links, so elements travel in
+  // a function. It re-renders a matched route only when the URL or those serialized props change, and functions
+  // do not serialize: the revision marks every new element as a change. ElementRoute stays the same component,
+  // so the route updates in place instead of remounting.
+  const children = useMemo(() => toChildArray(props.children).filter(isValidElement).map((child) => {
+    if (child.type !== Route) return child;
+    const { element, ...rest } = (child as VNode<RouteProps>).props;
+    if (element === undefined) return child;
+    return h(Route, { ...rest, key: child.key, component: ElementRoute, render: () => element, revision: ++elementRevision });
+  }), [props.children]);
+  const content = routes ? h(IsoRouter as ComponentType<typeof props>, { ...props, children }) : props.children;
+  return hasProvider ? (content as any) : h(LocationProvider, null, content);
+}
+
+let elementRevision = 0;
+
+function ElementRoute(props: { render: () => JSX.Element | null }) {
+  return props.render();
+}
+
+/** Alias of `<Router>` (react-router style naming). */
+export const Routes = Router;
+
+export type RouteProps<P = {}> = {
+  path?: string;
+  default?: boolean;
+} & ({ component: ComponentType<any>; element?: undefined } | { element: JSX.Element | null; component?: undefined }) &
+  P;
+
+/** A route. Use `component={Page}` (gets `params` as props) or `element={<Page />}` (read `useParams()`). */
+export function Route(props: RouteProps<Record<string, unknown>>) {
+  const { component, element, ...rest } = props as any;
+  return element !== undefined ? element : h(component, rest);
+}
+
+/** `<a>` with an app-relative `to`. */
+export function Link(props: JSX.IntrinsicElements["a"] & { to?: string; href?: string }) {
+  const { to, href, ...rest } = props as any;
+  return h("a", { ...rest, href: withBase(globalBase, to ?? href ?? "/") });
+}
+
+export function useLocation(): LocationValue {
+  return isoUseLocation() as unknown as LocationValue;
+}
+
+/** Returns `navigate(to, { replace })` for app-relative paths. */
+export function useNavigate(): (to: string, options?: { replace?: boolean }) => void {
+  const loc = useLocation();
+  return (to, options) => loc.route(to, options?.replace);
+}
+
+/** Route params of the matched `<Route path="/x/:id">`. */
+export function useParams<P extends Record<string, string> = Record<string, string>>(): P {
+  return ((useRoute() as any)?.params ?? {}) as P;
+}
+
+export { useRoute };

package/sdk/src/client/storage.ts

@@ -0,0 +1,132 @@
+import { EraspaceError } from "./errors.ts";
+
+export interface UploadedObject {
+  key: string;
+  url: string;
+  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 bucket. Apps and their files are public. */
+  upload(body: Blob, options?: StorageUploadOptions): Promise<UploadedObject>;
+  url(key: string): string;
+  /** 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)}`;
+  }
+  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 (status < 200 || status > 299 || result.ok !== true) throw EraspaceError.from(result.error, `Storage request failed: HTTP ${status}`);
+    return result;
+  }
+  return {
+    url,
+    async upload(body, options = {}) {
+      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 { 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");
+      }
+      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 = {}) {
+      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/sub-key.ts

@@ -0,0 +1,12 @@
+/** Stable key for `(fn, args)`. Object keys are sorted so `{a,b}` and `{b,a}` dedupe. */
+export function subKey(fn: string, args: unknown[]): string {
+  return fn + ":" + stableStringify(args);
+}
+export function stableStringify(v: unknown): string {
+  if (v === undefined) return "null";
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(stableStringify).join(",") + "]";
+  const o = v as Record<string, unknown>;
+  const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(o[k])).join(",") + "}";
+}

package/sdk/src/client/subscription.ts

@@ -0,0 +1,55 @@
+import { signal, type Signal } from "@preact/signals";
+import { EraspaceError } from "./errors.ts";
+import type { Patch } from "./result-diff.ts";
+
+export interface FullResult {
+  value: unknown;
+  commitSeq: number;
+  revision: number;
+}
+export type DataMessage = { id: string } & (FullResult | {
+  patch: Patch[];
+  base: number;
+  revision: number;
+  commitSeq: number;
+});
+
+interface Layer {
+  mid: number;
+  apply: (prev: any) => any;
+  commitSeq?: number;
+}
+
+export class Subscription {
+  readonly value: Signal<any> = signal(undefined);
+  readonly error: Signal<EraspaceError | undefined> = signal(undefined);
+  server: any = undefined;
+  hasServer = false;
+  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;
+  readonly args: unknown[];
+  readonly key: string;
+  constructor(id: string, fn: string, args: unknown[], key: string) {
+    this.id = id;
+    this.fn = fn;
+    this.args = args;
+    this.key = key;
+  }
+
+  recompute(): void {
+    let v = this.server;
+    if (this.hasServer) for (const l of this.layers) v = l.apply(v);
+    this.value.value = v;
+  }
+}