@rxferrix/client 0.0.0-stage → 0.1.0

package/src/request_manager.ts

@@ -0,0 +1,199 @@
+import { CONNECTION_LOST, RxFerrixError } from "./errors.js";
+import type {
+  ActionMessage,
+  ActionResponseMessage,
+  MutationMessage,
+  MutationResponseMessage,
+  RequestId,
+} from "./protocol.js";
+
+type Settle = { resolve: (value: unknown) => void; reject: (error: unknown) => void };
+
+type MutationRequest = Settle & {
+  kind: "mutation";
+  message: MutationMessage;
+  /** Sent on the current socket. */
+  sent: boolean;
+  /** Set once a successful MutationResponse arrived: waiting for a Transition with ts >= this. */
+  completed: { ts: number; result: unknown } | null;
+  startedAt: number;
+};
+
+type ActionRequest = Settle & {
+  kind: "action";
+  message: ActionMessage;
+  sent: boolean;
+  startedAt: number;
+};
+
+type Request = MutationRequest | ActionRequest;
+
+export interface SettledMutation {
+  requestId: RequestId;
+  settle: () => void;
+}
+
+/**
+ * Tracks in-flight mutations and actions.
+ *
+ * A mutation's promise resolves only once BOTH its successful `MutationResponse { ts: M }` has arrived AND the client
+ * has applied a Transition with `endVersion.ts >= M` (read-your-writes). Failures reject immediately.
+ *
+ * Settling is split in two (`settle` callbacks are returned rather than invoked) so the client can update its query
+ * view (dropping optimistic updates) before promise continuations run.
+ */
+export class RequestManager {
+  private nextRequestId = 0;
+  private readonly requests = new Map<RequestId, Request>();
+
+  allocateRequestId(): RequestId {
+    return this.nextRequestId++;
+  }
+
+  trackMutation(message: MutationMessage): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      this.requests.set(message.requestId, {
+        kind: "mutation",
+        message,
+        sent: false,
+        completed: null,
+        startedAt: Date.now(),
+        resolve,
+        reject,
+      });
+    });
+  }
+
+  trackAction(message: ActionMessage): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      this.requests.set(message.requestId, {
+        kind: "action",
+        message,
+        sent: false,
+        startedAt: Date.now(),
+        resolve,
+        reject,
+      });
+    });
+  }
+
+  /** Messages that still have to go out on the current socket, in request order. */
+  unsent(): (MutationMessage | ActionMessage)[] {
+    const out: (MutationMessage | ActionMessage)[] = [];
+    for (const request of this.requests.values()) {
+      if (request.sent) continue;
+      if (request.kind === "mutation" && request.completed) continue;
+      out.push(request.message);
+    }
+    return out;
+  }
+
+  /** The message went out on the current socket. */
+  markSent(requestId: RequestId): void {
+    const request = this.requests.get(requestId);
+    if (request) request.sent = true;
+  }
+
+  /**
+   * Handles a MutationResponse. `observedTs` is the ts of the last applied Transition, or null when the client's view
+   * is not currently consistent with the server (right after a reconnect).
+   *
+   * Returns the settled mutation (whose optimistic update must be dropped), or null if it is still waiting for its
+   * ts to be observed (or the requestId is unknown).
+   */
+  onMutationResponse(response: MutationResponseMessage, observedTs: number | null): SettledMutation | null {
+    const request = this.requests.get(response.requestId);
+    if (!request || request.kind !== "mutation" || request.completed) return null;
+    if (!response.success) {
+      this.requests.delete(response.requestId);
+      const error = RxFerrixError.fromServer(response.errorMessage, response.errorData);
+      return { requestId: response.requestId, settle: () => request.reject(error) };
+    }
+    request.completed = { ts: response.ts, result: response.result };
+    if (observedTs !== null && observedTs >= response.ts) {
+      this.requests.delete(response.requestId);
+      const result = response.result;
+      return { requestId: response.requestId, settle: () => request.resolve(result) };
+    }
+    return null;
+  }
+
+  /** Handles an ActionResponse. Returns the settle callback, or null for an unknown request. */
+  onActionResponse(response: ActionResponseMessage): (() => void) | null {
+    const request = this.requests.get(response.requestId);
+    if (!request || request.kind !== "action") return null;
+    this.requests.delete(response.requestId);
+    if (response.success) {
+      const result = response.result;
+      return () => request.resolve(result);
+    }
+    const error = RxFerrixError.fromServer(response.errorMessage, response.errorData);
+    return () => request.reject(error);
+  }
+
+  /** A Transition with `endVersion.ts = ts` was applied: completes every mutation with a commit ts <= ts. */
+  removeCompleted(ts: number): SettledMutation[] {
+    const settled: SettledMutation[] = [];
+    for (const [requestId, request] of this.requests) {
+      if (request.kind !== "mutation" || !request.completed || request.completed.ts > ts) continue;
+      this.requests.delete(requestId);
+      const result = request.completed.result;
+      settled.push({ requestId, settle: () => request.resolve(result) });
+    }
+    return settled;
+  }
+
+  /**
+   * The socket dropped. Mutations without a response will be re-sent on the next socket. Actions that were already
+   * sent are rejected because they are not idempotent; actions that never left the client stay queued.
+   */
+  onSocketClosed(): { settle: () => void; requestId: RequestId }[] {
+    const rejected: { settle: () => void; requestId: RequestId }[] = [];
+    for (const [requestId, request] of this.requests) {
+      if (request.kind === "mutation") {
+        if (!request.completed) request.sent = false;
+        continue;
+      }
+      if (!request.sent) continue;
+      this.requests.delete(requestId);
+      const error = new RxFerrixError(
+        `Connection lost while action "${request.message.udfPath}" was in flight`,
+        { code: CONNECTION_LOST },
+      );
+      rejected.push({ requestId, settle: () => request.reject(error) });
+    }
+    return rejected;
+  }
+
+  /** Rejects everything (client closed). */
+  rejectAll(error: RxFerrixError): void {
+    const all = [...this.requests.values()];
+    this.requests.clear();
+    for (const request of all) request.reject(error);
+  }
+
+  hasInflight(): boolean {
+    return this.requests.size > 0;
+  }
+
+  hasInflightMutations(): boolean {
+    for (const request of this.requests.values()) if (request.kind === "mutation") return true;
+    return false;
+  }
+
+  counts(): { mutations: number; actions: number; oldestStartedAt: number | null } {
+    let mutations = 0;
+    let actions = 0;
+    let oldest: number | null = null;
+    for (const request of this.requests.values()) {
+      if (request.kind === "mutation") mutations++;
+      else actions++;
+      if (oldest === null || request.startedAt < oldest) oldest = request.startedAt;
+    }
+    return { mutations, actions, oldestStartedAt: oldest };
+  }
+
+  udfPathOf(requestId: RequestId): string | undefined {
+    return this.requests.get(requestId)?.message.udfPath;
+  }
+}

package/src/storage.ts

@@ -0,0 +1,171 @@
+/**
+ * File uploads to a RxFerrix server.
+ *
+ * The flow: a mutation returns `ctx.storage.generate_upload_url()`, the client `POST`s the file to it
+ * with {@link uploadFile}, and a second mutation stores the returned `Id<"_storage">` in a document. Serve it with
+ * the URL from `ctx.storage.get_url(id)` (`/api/storage/<id>`).
+ *
+ * ```ts
+ * const url = await client.mutation(api.files.generateUploadUrl, {});
+ * const storageId = await uploadFile(url, file, { onProgress: ({ loaded, total }) => (pct = loaded / total) });
+ * await client.mutation(api.files.attach, { storageId });
+ * ```
+ */
+import type { Id } from "./api.js";
+import { RxFerrixError } from "./errors.js";
+import type { ErrorData } from "./protocol.js";
+
+export interface UploadProgress {
+  /** Bytes sent so far. */
+  loaded: number;
+  /** Total bytes to send. */
+  total: number;
+}
+
+export interface UploadFileOptions {
+  /** Called as the upload progresses (with `XMLHttpRequest`; with `fetch`, only at the start and the end). */
+  onProgress?: (progress: UploadProgress) => void;
+  /** Aborts the upload; the promise rejects with an `AbortError`. */
+  signal?: AbortSignal;
+  /** The `Content-Type` to store. Default: the Blob's `type` (none if empty). */
+  contentType?: string;
+  /** The original file name to store. Default: `File.name` for a `File`; `null` sends none. */
+  filename?: string | null;
+  /** Base for a root-relative upload URL (`/api/storage/upload?…`). Default: the page's `location`. */
+  baseUrl?: string;
+  /** `fetch` to use when `XMLHttpRequest` is unavailable (or `transport: "fetch"`). Default: `globalThis.fetch`. */
+  fetch?: typeof globalThis.fetch;
+  /** Force a transport. Default: `XMLHttpRequest` when available (browsers, for progress events), else `fetch`. */
+  transport?: "xhr" | "fetch";
+}
+
+/** A successful upload's response body. */
+interface UploadResponse {
+  storageId: string;
+}
+
+/** The final URL: `uploadUrl` resolved against `baseUrl`, with `filename` appended. */
+export function uploadRequestUrl(uploadUrl: string, filename: string | null | undefined, baseUrl?: string): string {
+  const base = baseUrl ?? (typeof location !== "undefined" ? location.href : undefined);
+  let url: URL;
+  try {
+    url = base === undefined ? new URL(uploadUrl) : new URL(uploadUrl, base);
+  } catch {
+    throw new RxFerrixError(`Invalid upload URL ${JSON.stringify(uploadUrl)} (pass options.baseUrl for relative URLs)`, {
+      code: "invalid_upload_url",
+    });
+  }
+  if (filename) url.searchParams.set("filename", filename);
+  return url.toString();
+}
+
+function parseResult(status: number, text: string): Id<"_storage"> {
+  let body: unknown = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    // Not JSON (e.g. a proxy's error page).
+  }
+  if (status >= 200 && status < 300) {
+    const id = (body as UploadResponse | null)?.storageId;
+    if (typeof id !== "string") throw new RxFerrixError(`Unexpected upload response: ${text.slice(0, 200)}`);
+    return id as Id<"_storage">;
+  }
+  const err = body as { errorMessage?: string; errorData?: ErrorData | null } | null;
+  if (err && typeof err === "object" && (err.errorMessage || err.errorData)) {
+    throw RxFerrixError.fromServer(err.errorMessage, err.errorData ?? null);
+  }
+  throw new RxFerrixError(`Upload failed with HTTP ${status}`, { code: status === 413 ? "file_too_large" : "http_error" });
+}
+
+function abortError(signal: AbortSignal | undefined): unknown {
+  return signal?.reason ?? new DOMException("The upload was aborted", "AbortError");
+}
+
+/**
+ * Upload `file` to an upload URL from `ctx.storage.generate_upload_url()` and return the new file's
+ * `Id<"_storage">`. Rejects with a {@link RxFerrixError} whose `code` is the server's (`file_too_large`,
+ * `upload_url_expired`, `upload_url_used`, `invalid_upload_url`, `rate_limited`, ...), or `network_error`.
+ */
+export async function uploadFile(uploadUrl: string, file: Blob, options: UploadFileOptions = {}): Promise<Id<"_storage">> {
+  const filename =
+    options.filename !== undefined
+      ? options.filename
+      : typeof File !== "undefined" && file instanceof File && file.name
+        ? file.name
+        : null;
+  const url = uploadRequestUrl(uploadUrl, filename, options.baseUrl);
+  const contentType = options.contentType ?? (file.type || undefined);
+  if (options.signal?.aborted) throw abortError(options.signal);
+  const useXhr = options.transport ? options.transport === "xhr" : typeof XMLHttpRequest === "function";
+  return useXhr ? uploadWithXhr(url, file, contentType, options) : uploadWithFetch(url, file, contentType, options);
+}
+
+function uploadWithXhr(
+  url: string,
+  file: Blob,
+  contentType: string | undefined,
+  options: UploadFileOptions,
+): Promise<Id<"_storage">> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const { signal, onProgress } = options;
+    const onAbort = () => xhr.abort();
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    xhr.open("POST", url);
+    if (contentType) xhr.setRequestHeader("Content-Type", contentType);
+    if (onProgress) {
+      xhr.upload.onprogress = (e: ProgressEvent) => {
+        onProgress({ loaded: e.loaded, total: e.lengthComputable ? e.total : file.size });
+      };
+    }
+    xhr.onload = () => {
+      cleanup();
+      try {
+        const id = parseResult(xhr.status, xhr.responseText);
+        onProgress?.({ loaded: file.size, total: file.size });
+        resolve(id);
+      } catch (e) {
+        reject(e);
+      }
+    };
+    xhr.onerror = () => {
+      cleanup();
+      reject(new RxFerrixError("The upload failed: network error", { code: "network_error" }));
+    };
+    xhr.onabort = () => {
+      cleanup();
+      reject(abortError(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    xhr.send(file);
+  });
+}
+
+async function uploadWithFetch(
+  url: string,
+  file: Blob,
+  contentType: string | undefined,
+  options: UploadFileOptions,
+): Promise<Id<"_storage">> {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  options.onProgress?.({ loaded: 0, total: file.size });
+  let res: Response;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      body: file,
+      headers: contentType ? { "Content-Type": contentType } : {},
+      signal: options.signal,
+    });
+  } catch (e) {
+    if (options.signal?.aborted) throw abortError(options.signal);
+    throw new RxFerrixError(`The upload failed: ${e instanceof Error ? e.message : String(e)}`, {
+      code: "network_error",
+      cause: e,
+    });
+  }
+  const id = parseResult(res.status, await res.text());
+  options.onProgress?.({ loaded: file.size, total: file.size });
+  return id;
+}

package/src/testing.ts

@@ -0,0 +1,120 @@
+/**
+ * Test utilities: a scriptable fake of the RxFerrix sync endpoint (`@rxferrix/client/testing`).
+ *
+ * ```ts
+ * const server = new FakeServer();
+ * const client = new RxFerrixClient("http://localhost", { webSocketConstructor: server.WebSocket });
+ * server.open();                       // the socket connects
+ * await flushMicrotasks();             // batched ModifyQuerySet goes out
+ * server.sent;                         // what the client sent on this socket
+ * server.transition({ querySet: 1, ts: 1 }, [{ type: "QueryUpdated", queryId: 0, value: [] }]);
+ * ```
+ */
+import type { ClientMessage, ServerMessage, StateVersion } from "./protocol.js";
+
+type Modification = Extract<ServerMessage, { type: "Transition" }>["modifications"][number];
+
+export class FakeSocket {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+
+  readyState = FakeSocket.CONNECTING;
+  readonly sent: ClientMessage[] = [];
+  closedByClient = false;
+  /** The server-side StateVersion of this socket, advanced by `transition`. */
+  version: StateVersion = { querySet: 0, identity: 0, ts: 0 };
+
+  onopen: ((ev: unknown) => void) | null = null;
+  onmessage: ((ev: { data: string }) => void) | null = null;
+  onclose: ((ev: { code: number; reason: string }) => void) | null = null;
+  onerror: ((ev: unknown) => void) | null = null;
+
+  constructor(readonly url: string) {}
+
+  send(data: string): void {
+    if (this.readyState !== FakeSocket.OPEN) throw new Error("send on a socket that is not open");
+    this.sent.push(JSON.parse(data) as ClientMessage);
+  }
+
+  close(): void {
+    if (this.readyState === FakeSocket.CLOSED) return;
+    this.closedByClient = true;
+    this.readyState = FakeSocket.CLOSED;
+  }
+}
+
+export class FakeServer {
+  readonly sockets: FakeSocket[] = [];
+  readonly WebSocket: typeof WebSocket;
+
+  constructor() {
+    const sockets = this.sockets;
+    class BoundFakeSocket extends FakeSocket {
+      constructor(url: string) {
+        super(url);
+        sockets.push(this);
+      }
+    }
+    this.WebSocket = BoundFakeSocket as unknown as typeof WebSocket;
+  }
+
+  /** The most recently created socket. */
+  get socket(): FakeSocket {
+    const s = this.sockets[this.sockets.length - 1];
+    if (!s) throw new Error("no socket created yet");
+    return s;
+  }
+
+  /** Everything the client sent on the current socket. */
+  get sent(): ClientMessage[] {
+    return this.socket.sent;
+  }
+
+  /** Messages of one type sent on the current socket. */
+  sentOfType<T extends ClientMessage["type"]>(type: T): Extract<ClientMessage, { type: T }>[] {
+    return this.sent.filter((m): m is Extract<ClientMessage, { type: T }> => m.type === type);
+  }
+
+  /** Returns and forgets what the client sent on the current socket so far. */
+  drain(): ClientMessage[] {
+    return this.socket.sent.splice(0);
+  }
+
+  open(): void {
+    const s = this.socket;
+    s.readyState = FakeSocket.OPEN;
+    s.onopen?.({});
+  }
+
+  push(message: ServerMessage | Record<string, unknown>): void {
+    const s = this.socket;
+    if (s.readyState !== FakeSocket.OPEN) throw new Error("push on a socket that is not open");
+    s.onmessage?.({ data: JSON.stringify(message) });
+  }
+
+  /**
+   * Pushes a Transition from the socket's current version. `end` overrides fields of the end version; unspecified
+   * fields keep their current value.
+   */
+  transition(end: Partial<StateVersion>, modifications: Modification[] = []): void {
+    const s = this.socket;
+    const startVersion = { ...s.version };
+    const endVersion = { ...s.version, ...end };
+    s.version = endVersion;
+    this.push({ type: "Transition", startVersion, endVersion, modifications });
+  }
+
+  /** The server closes the current socket. */
+  close(code = 1011, reason = "server closed"): void {
+    const s = this.socket;
+    s.readyState = FakeSocket.CLOSED;
+    s.onclose?.({ code, reason });
+  }
+}
+
+/** Lets queued microtasks (query-set flush, promise continuations) run. */
+export async function flushMicrotasks(): Promise<void> {
+  for (let i = 0; i < 5; i++) await Promise.resolve();
+}