@brass-build/client 0.4.1 → 0.5.0

package/src/sha256.ts

@@ -0,0 +1,65 @@
+// SHA-256 over a string's UTF-8 bytes, synchronous and dependency-free, so
+// the browser, the SDK and the Lambdas compute the same digest without
+// `node:crypto` or an async `crypto.subtle` call on a path that must be
+// synchronous (a status keyed by a reference set is computed inside a
+// subscription callback).
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+/** Lower-case hex SHA-256 of `input`'s UTF-8 encoding. */
+export function sha256Hex(input: string): string {
+  const bytes = new TextEncoder().encode(input);
+  const bitLen = bytes.length * 8;
+  const padded = new Uint8Array((((bytes.length + 9 + 63) >> 6) << 6));
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  // Messages here are far below 2^32 bits, so the high word stays zero.
+  view.setUint32(padded.length - 4, bitLen >>> 0);
+  view.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000));
+
+  const h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const a = w[i - 15]!;
+      const b = w[i - 2]!;
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
+    }
+    let a = h[0]!, b = h[1]!, c = h[2]!, d = h[3]!;
+    let e = h[4]!, f = h[5]!, g = h[6]!, hh = h[7]!;
+    for (let i = 0; i < 64; i++) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + s1 + ch + K[i]! + w[i]!) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (s0 + maj) >>> 0;
+      hh = g; g = f; f = e; e = (d + t1) >>> 0;
+      d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0]! + a) >>> 0; h[1] = (h[1]! + b) >>> 0;
+    h[2] = (h[2]! + c) >>> 0; h[3] = (h[3]! + d) >>> 0;
+    h[4] = (h[4]! + e) >>> 0; h[5] = (h[5]! + f) >>> 0;
+    h[6] = (h[6]! + g) >>> 0; h[7] = (h[7]! + hh) >>> 0;
+  }
+  let out = '';
+  for (const word of h) out += word.toString(16).padStart(8, '0');
+  return out;
+}

package/src/stable-handles.ts

@@ -0,0 +1,235 @@
+// The handles a Document hands an app.
+//
+// A document's storage can change under an open copy, from frozen content to
+// a CRDT when it is edited and back when a frozen copy reloads onto a reseal.
+// Each handle here passes every call to the handle the current storage
+// provides for the same container, and owns its subscriptions, so a swap
+// moves them in one place and the handles behind it never learn of it.
+
+import type {
+  HandleUnsubscribe,
+  ListHandle,
+  ListSubscriber,
+  MapHandle,
+  MapSubscriber,
+  OrderedMapHandle,
+  TextHandle,
+} from './handle-types.js';
+import { hideOwnFields } from './handles.js';
+
+type Call = (...args: unknown[]) => unknown;
+type Backing = Record<string, Call>;
+type Kind = 'map' | 'list' | 'text';
+
+interface Scope {
+  generation: number;
+  // Every handle holding a subscription, which a swap has to move.
+  readonly subscribed: Set<StableHandle>;
+  readonly report: (err: unknown) => void;
+}
+
+interface Subscription {
+  cb: Call;
+  settled: boolean;
+  off: HandleUnsubscribe;
+}
+
+/** A map subscriber whose first fire also reports the keys it was handed
+ *  before and the new container no longer holds, which is what a swap owes
+ *  a subscriber that moves with it. */
+function reportingLeftKeys<T>(cb: MapSubscriber<T>, before: readonly string[]): MapSubscriber<T> {
+  let first = true;
+  return (change, origin) => {
+    if (first) {
+      first = false;
+      const left = before.filter((key) => !change.set.has(key));
+      if (left.length > 0) change = { ...change, deleted: [...change.deleted, ...left] };
+    }
+    cb(change, origin);
+  };
+}
+
+/** The list counterpart: the first fire also removes the items handed before. */
+function replacingHeldItems<T>(cb: ListSubscriber<T>, held: number): ListSubscriber<T> {
+  let first = true;
+  return (change) => {
+    if (first) {
+      first = false;
+      if (held > 0) {
+        const [head, ...rest] = change.splices;
+        change =
+          head !== undefined && head.at === 0
+            ? { splices: [{ ...head, removed: head.removed + held }, ...rest] }
+            : { splices: [{ at: 0, removed: held, inserted: [] }, ...change.splices] };
+      }
+    }
+    cb(change);
+  };
+}
+
+class StableHandle {
+  private _backing: Backing;
+  private _at: number;
+  private readonly _subs = new Set<Subscription>();
+  // Keyed by the scoped handle the backing hands out, so whether two calls
+  // return the same one is the backing's decision.
+  private readonly _children = new WeakMap<object, StableHandle>();
+
+  constructor(
+    private readonly _scope: Scope,
+    private readonly _kind: Kind,
+    private readonly _resolve: () => unknown,
+    backing: unknown = _resolve(),
+  ) {
+    this._backing = backing as Backing;
+    this._at = _scope.generation;
+    hideOwnFields(this);
+  }
+
+  private get _h(): Backing {
+    if (this._at !== this._scope.generation) {
+      this._backing = this._resolve() as Backing;
+      this._at = this._scope.generation;
+    }
+    return this._backing;
+  }
+
+  _call(method: string, args: unknown[]): unknown {
+    return this._h[method]!(...args);
+  }
+
+  map(key: string): StableHandle {
+    return this._child('map', key);
+  }
+
+  list(key: string): StableHandle {
+    return this._child('list', key);
+  }
+
+  private _child(kind: Kind, key: string): StableHandle {
+    const backing = this._call(kind, [key]) as object;
+    let child = this._children.get(backing);
+    if (child === undefined) {
+      child = new StableHandle(this._scope, kind, () => this._call(kind, [key]), backing);
+      this._children.set(backing, child);
+    }
+    return child;
+  }
+
+  subscribe(cb: Call): HandleUnsubscribe {
+    return this._add(cb, false);
+  }
+
+  onSettled(cb: Call): HandleUnsubscribe {
+    return this._add(cb, true);
+  }
+
+  private _add(cb: Call, settled: boolean): HandleUnsubscribe {
+    const sub: Subscription = { cb, settled, off: () => {} };
+    sub.off = this._call(settled ? 'onSettled' : 'subscribe', [cb]) as HandleUnsubscribe;
+    this._subs.add(sub);
+    this._scope.subscribed.add(this);
+    return () => {
+      sub.off();
+      this._subs.delete(sub);
+      if (this._subs.size === 0) this._scope.subscribed.delete(this);
+    };
+  }
+
+  // Take every subscription off the current handle, noting what its
+  // subscribers were handed; the returned call registers them with the handle
+  // the storage provides by then, as a whole-container delivery.
+  _detach(): () => void {
+    const held = this._kind === 'text' ? null : this._call(this._kind === 'map' ? 'keys' : 'length', []);
+    const moved = (cb: Call): Call =>
+      this._kind === 'map'
+        ? (reportingLeftKeys(cb as MapSubscriber<unknown>, held as string[]) as Call)
+        : this._kind === 'list'
+          ? (replacingHeldItems(cb as ListSubscriber<unknown>, held as number) as Call)
+          : cb;
+    for (const sub of this._subs) sub.off();
+    return () => {
+      // Subscribers first, so each `onSettled` fires after the delivery it
+      // reports.
+      for (const settled of [false, true]) {
+        for (const sub of this._subs) {
+          if (sub.settled !== settled) continue;
+          const cb = settled ? sub.cb : moved(sub.cb);
+          try {
+            sub.off = this._call(settled ? 'onSettled' : 'subscribe', [cb]) as HandleUnsubscribe;
+          } catch (err) {
+            sub.off = () => {};
+            this._scope.report(err);
+          }
+        }
+      }
+    };
+  }
+}
+
+type Passed = Exclude<
+  keyof MapHandle | keyof ListHandle | keyof OrderedMapHandle | keyof TextHandle,
+  'subscribe' | 'onSettled' | 'map' | 'list'
+>;
+
+// Every other call passes straight through. A record, so a method the handle
+// interfaces gain does not compile until it is listed here.
+const PASSED: Record<Passed | 'read' | '_pageIndexRebuilds', true> = {
+  get: true,
+  has: true,
+  keys: true,
+  entries: true,
+  values: true,
+  length: true,
+  read: true,
+  ordered: true,
+  mutate: true,
+  insert: true,
+  move: true,
+  update: true,
+  _pageIndexRebuilds: true,
+};
+for (const method of Object.keys(PASSED)) {
+  Object.defineProperty(StableHandle.prototype, method, {
+    value(this: StableHandle, ...args: unknown[]): unknown {
+      return this._call(method, args);
+    },
+  });
+}
+
+/** The handles one Document has handed out, one per root. */
+export class StableHandles {
+  private _scope: Scope;
+  private readonly _roots = new Map<string, StableHandle>();
+
+  constructor(private readonly _report: (err: unknown) => void) {
+    this._scope = { generation: 0, subscribed: new Set(), report: _report };
+  }
+
+  /** The handle under `cacheKey`, made over what `resolve` returns. `resolve`
+   *  is asked again after every `swap`. */
+  root<H>(cacheKey: string, kind: Kind, resolve: () => H): H {
+    let handle = this._roots.get(cacheKey);
+    if (handle === undefined) {
+      handle = new StableHandle(this._scope, kind, resolve);
+      this._roots.set(cacheKey, handle);
+    }
+    return handle as unknown as H;
+  }
+
+  /** Change the storage behind every handle: `change` runs while nothing is
+   *  subscribed to the old storage, and every subscription then moves to the
+   *  new one. */
+  swap(change: () => void): void {
+    const moves = Array.from(this._scope.subscribed, (handle) => handle._detach());
+    change();
+    this._scope.generation++;
+    for (const move of moves) move();
+  }
+
+  /** Forget every handle. One an app still holds stays on the storage it had. */
+  clear(): void {
+    this._roots.clear();
+    this._scope = { generation: 0, subscribed: new Set(), report: this._report };
+  }
+}

package/src/staged-seal.ts

@@ -0,0 +1,90 @@
+// Waiting on a staged upload's seal. The platform answers `202 { seal_id }`
+// once the upload is queued and seals it afterwards; the caller resolves or
+// rejects on the outcome, exactly as it did on the synchronous answer.
+
+import { brassErrorFromBody } from './api-fetch.js';
+import { BrassError } from './errors.js';
+
+/** @internal */
+export type SealStatus =
+  | { state: 'pending' }
+  | { state: 'stored'; body: unknown }
+  | {
+      state: 'refused';
+      status: number;
+      error: string;
+      code?: string;
+      import_failed?: { message: string };
+    };
+
+/** @internal A seal the platform refused. `importFailed` is the failure it
+ *  recorded on the document when the seal completed an import. */
+export class SealRefusedError extends BrassError {
+  readonly importFailed?: string;
+
+  constructor(refused: Extract<SealStatus, { state: 'refused' }>) {
+    const base = brassErrorFromBody(refused.status, {
+      error: refused.error,
+      ...(refused.code !== undefined ? { code: refused.code } : {}),
+    });
+    super(base.message, {
+      ...(base.status !== undefined ? { status: base.status } : {}),
+      ...(base.code !== undefined ? { code: base.code } : {}),
+    });
+    if (refused.import_failed !== undefined) {
+      this.importFailed = refused.import_failed.message;
+    }
+  }
+}
+
+// The worker may take both of the queue's deliveries before the DLQ drain
+// records a refusal, so the wait outlasts them.
+const SEAL_WAIT_MS = 40 * 60 * 1000;
+const SEAL_POLL_MS = [250, 500, 1000, 1000, 2000];
+const MAX_FAILED_READS = 10;
+
+function retryable(status: number | undefined): boolean {
+  return status === undefined || status === 429 || status >= 500;
+}
+
+function sealIdOf(accepted: unknown): string | null {
+  if (typeof accepted !== 'object' || accepted === null) return null;
+  const id = (accepted as { seal_id?: unknown }).seal_id;
+  return typeof id === 'string' && id !== '' ? id : null;
+}
+
+/** @internal Resolve with the stored outcome's body once the seal `accepted`
+ *  names has landed, or throw its refusal. A body naming no seal is a server
+ *  that sealed synchronously, and is the answer itself. */
+export async function awaitSeal<T>(
+  accepted: unknown,
+  read: (sealId: string) => Promise<SealStatus>,
+): Promise<T> {
+  const sealId = sealIdOf(accepted);
+  if (sealId === null) return accepted as T;
+  const deadline = Date.now() + SEAL_WAIT_MS;
+  let failedReads = 0;
+  for (let attempt = 0; ; attempt += 1) {
+    let status: SealStatus | null = null;
+    try {
+      status = await read(sealId);
+      failedReads = 0;
+    } catch (err) {
+      // A read that failed in transit says nothing about the seal, which goes
+      // on regardless; a refusal of the read itself, or a run of failures,
+      // ends the wait.
+      failedReads += 1;
+      if (err instanceof BrassError && !retryable(err.status)) throw err;
+      if (failedReads >= MAX_FAILED_READS) throw err;
+    }
+    if (status?.state === 'stored') return status.body as T;
+    if (status?.state === 'refused') throw new SealRefusedError(status);
+    if (Date.now() >= deadline) {
+      throw new BrassError('The upload is taking too long to store. Try again.', {
+        status: 504,
+      });
+    }
+    const delay = SEAL_POLL_MS[Math.min(attempt, SEAL_POLL_MS.length - 1)]!;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+}

package/src/subscriber-delivery.ts

@@ -0,0 +1,37 @@
+// What every handle kind shares about handing data to an app's callback.
+
+import type { Splice } from './handle-types.js';
+
+// The natural apply is `rows.splice(at, removed, ...inserted)`, and a spread
+// passes every item as a call argument, which overflows the engine's stack
+// somewhere past tens of thousands of items. A large insert is therefore
+// delivered as consecutive splices, which applied in order make the same edit.
+const SPLICE_MAX_INSERTED = 10_000;
+
+export function pushBoundedSplice<E>(out: Splice<E>[], splice: Splice<E>): void {
+  const { at, removed, inserted } = splice;
+  if (inserted.length <= SPLICE_MAX_INSERTED) {
+    out.push(splice);
+    return;
+  }
+  for (let i = 0; i < inserted.length; i += SPLICE_MAX_INSERTED) {
+    out.push({
+      at: at + i,
+      removed: i === 0 ? removed : 0,
+      inserted: inserted.slice(i, i + SPLICE_MAX_INSERTED),
+    });
+  }
+}
+
+/** The error `Brass.onError` receives when an app's own callback threw while
+ *  being handed a document or a change to one. The app usually shows an empty
+ *  or stale view after that, so the sentence is one it can show the reader;
+ *  the throw rides as `cause`. */
+export function appCallbackError(err: unknown): Error {
+  const detail = err instanceof Error ? err.message : String(err);
+  const report: Error & { cause?: unknown } = new Error(
+    `The app could not display a change: ${detail}`,
+  );
+  report.cause = err;
+  return report;
+}

package/src/tail-op-import.ts

@@ -0,0 +1,30 @@
+import { LoroDoc } from './wasm-runtime.js';
+
+// An op whose dependencies are missing still imports here (as pending), so a
+// refusal means the bytes are not an update anything could apply.
+function importsIntoEmptyDoc(blob: Uint8Array): boolean {
+  const probe = new LoroDoc();
+  try {
+    probe.import(blob);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    probe.free();
+  }
+}
+
+/**
+ * Import one op from a join's tail or a live delivery. Bytes that do not decode
+ * even into an empty document can never be applied by any peer, and compaction
+ * seals past them, so they are skipped: one such op in a tail must not fail
+ * every open until that seal. An op that fails only against `engine`'s state
+ * throws.
+ */
+export function importTailOp(engine: LoroDoc, blob: Uint8Array): void {
+  try {
+    engine.import(blob);
+  } catch (err) {
+    if (importsIntoEmptyDoc(blob)) throw err;
+  }
+}

package/src/topic-lifecycle.ts

@@ -21,6 +21,14 @@
 // that: it describes the frame the server could not process, not the
 // subscription it arrived on, so every live phase keeps its state and hands
 // the error to the topic's callbacks, which hold the frame that drew it.
+// While the subscribe is unacked the subscribe may be the frame that drew it,
+// so the client also sends that again after a backoff (a duplicate subscribe
+// is idempotent on the server).
+//
+// A `server_ended` event (the server evicted every subscriber on the topic
+// and deleted their rows) returns any phase to `idle` and detaches the
+// topic's callbacks, so whoever subscribes next sends a subscribe of its own
+// rather than attaching to a subscription the server no longer holds.
 //
 // Invariant: every transition into `tornDown` emits `send_unsubscribe`,
 // so no server-side subscription row can outlive the client-side state
@@ -49,10 +57,17 @@ export type TopicEvent =
   | { type: 'socket_open' }
   | { type: 'socket_closed' }
   | { type: 'subscribed_ack' }
+  | { type: 'server_ended' }
+  // The server reports it holds no subscription row for an established topic
+  // while the socket stays up (a presence row reaped as stale).
+  | { type: 'server_dropped' }
   | { type: 'error'; reason: string };
 
 export type TopicEffect =
   | { kind: 'send_subscribe' }
+  // Send the subscribe again after the client's backoff: the server could
+  // not finish the one in flight.
+  | { kind: 'resend_subscribe_later' }
   | { kind: 'send_unsubscribe' }
   // Flush the frames held for the unacked subscribe, in order.
   | { kind: 'flush_held' }
@@ -87,6 +102,7 @@ export function isFrameScopedReason(reason: string): boolean {
 }
 
 const SEND_SUBSCRIBE: TopicEffect = { kind: 'send_subscribe' };
+const RESEND_SUBSCRIBE_LATER: TopicEffect = { kind: 'resend_subscribe_later' };
 const FLUSH_HELD: TopicEffect = { kind: 'flush_held' };
 const DROP_HELD: TopicEffect = { kind: 'drop_held' };
 
@@ -126,6 +142,10 @@ function unsubscribed(): StepResult {
 }
 
 export function step(state: TopicState, event: TopicEvent): StepResult {
+  if (event.type === 'server_ended') {
+    if (state.phase === 'idle') return { state, effects: [] };
+    return { state: IDLE_TOPIC, effects: [DROP_HELD, { kind: 'drop_listeners' }] };
+  }
   switch (state.phase) {
     case 'idle':
       if (event.type === 'user_subscribe') {
@@ -145,7 +165,13 @@ export function step(state: TopicState, event: TopicEvent): StepResult {
           };
         case 'error':
           if (isFrameScopedReason(event.reason)) {
-            return deliverError(state, event.reason);
+            return {
+              state,
+              effects: [
+                { kind: 'deliver_error', reason: event.reason },
+                RESEND_SUBSCRIBE_LATER,
+              ],
+            };
           }
           // Never established on this connection: the rejection is final.
           return tearDown(state, event.reason);
@@ -182,6 +208,10 @@ export function step(state: TopicState, event: TopicEvent): StepResult {
           return tearDown(state, event.reason);
         case 'subscribed_ack':
           return { state, effects: [FLUSH_HELD] };
+        // Subscribe again, holding frames until it is acked. It spends no
+        // retry: the report arrives once per heartbeat, so it cannot loop.
+        case 'server_dropped':
+          return { state: { ...state, phase: 'subscribing' }, effects: [SEND_SUBSCRIBE] };
         case 'socket_open':
           return reopened();
         case 'socket_closed':
@@ -197,7 +227,13 @@ export function step(state: TopicState, event: TopicEvent): StepResult {
       switch (event.type) {
         case 'error':
           if (isFrameScopedReason(event.reason)) {
-            return deliverError(state, event.reason);
+            return {
+              state,
+              effects: [
+                { kind: 'deliver_error', reason: event.reason },
+                RESEND_SUBSCRIBE_LATER,
+              ],
+            };
           }
           // An eviction draws errors for EVERY frame in flight against the
           // reaped row; the trailing ones land while the retry's subscribe