@brass-build/client 0.4.0 → 0.5.0

package/src/internal.ts

@@ -23,8 +23,15 @@ export {
 export { decodeIdToken } from './jwt.js';
 export {
   readDocumentContents,
+  readJoinContents,
   type DocumentContents,
 } from './document-contents.js';
+export { decodeJoinContent, type JoinContent } from './join-content.js';
+export { SEALED_ACCEPT } from './sealed-store.js';
+export { decodeRecordValue } from './record-paging.js';
+// `Brass.documents.list` is internal, so what it takes and returns is too.
+export type { DocumentListing, ListDocumentsQuery } from './documents-namespace.js';
+export type { DocumentList } from './document-set-subscription.js';
 export {
   fetchWithRetry,
   RETRY_READ,

package/src/join-content.ts

@@ -0,0 +1,135 @@
+// The one path from a join's `snapshot` field to the content it carries.
+//
+// The open, the reload, a line's resync, a guest's pull and a version checkout
+// all read the same envelope, and each is handed back a content source in the
+// encoding the server stated. The SDK never infers the encoding from bytes the
+// wire already named, and a kind this build does not read is an upgrade error
+// rather than a guess: treating unreadable content as empty would let a reader
+// edit over content that is there.
+
+import { BrassError } from './errors.js';
+import { fetchSealedBytes, forgetSealedBytes } from './sealed-cache.js';
+import {
+  type SealedContent,
+  SealedStoreError,
+  decodeSealedContent,
+  frameVersion,
+  loadSealedCodec,
+  needsSealedCodec,
+  NEWEST_VERSION,
+} from './sealed-store.js';
+
+/** What a join's snapshot field holds, decoded as far as the wire says. */
+export type JoinContent =
+  /** No snapshot: the branch's state is its tail alone. */
+  | { kind: 'none' }
+  /** CRDT snapshot bytes, for the engine to import. */
+  | { kind: 'crdt'; bytes: Uint8Array }
+  /** Frozen content, read with no CRDT engine. */
+  | { kind: 'frozen'; content: SealedContent };
+
+/** Fetches a signed URL's body. The open passes one that reports progress. */
+export type ContentFetch = (url: string) => Promise<Uint8Array>;
+
+/** The error a snapshot this build cannot read is reported as. */
+function contentTooNewError(): BrassError {
+  return new BrassError(
+    'Opening this needs a newer version of this app. Update to the latest @brass-build/client to open it.',
+    { status: 426 },
+  );
+}
+
+/** The encoding a join's snapshot field states, read off the wire without
+ *  fetching anything. Throws the 426 upgrade error for a kind this build does
+ *  not read. */
+export function joinEncoding(snapshot: unknown): JoinContent['kind'] {
+  if (snapshot === null || snapshot === undefined) return 'none';
+  if (typeof snapshot !== 'object') throw contentTooNewError();
+  switch ((snapshot as { kind?: unknown }).kind) {
+    case 'inline':
+    case 'presigned':
+      return 'crdt';
+    case 'sealed':
+      return 'frozen';
+    default:
+      throw contentTooNewError();
+  }
+}
+
+/**
+ * Decode a join's snapshot field.
+ *
+ * `inline` and `presigned` are CRDT snapshots; `sealed` is sealed content in
+ * any frame this build reads. A frame newer than that, or a kind this build
+ * does not know, throws the 426 upgrade error.
+ */
+export async function decodeJoinContent(
+  snapshot: unknown,
+  fetchBody: ContentFetch,
+): Promise<JoinContent> {
+  if (joinEncoding(snapshot) === 'none') return { kind: 'none' };
+  const snap = snapshot as { kind?: unknown; data_b64?: unknown; url?: unknown };
+  switch (snap.kind) {
+    case 'inline':
+      if (typeof snap.data_b64 !== 'string') throw malformed();
+      return { kind: 'crdt', bytes: base64ToBytes(snap.data_b64) };
+    case 'presigned':
+      if (typeof snap.url !== 'string') throw malformed();
+      return { kind: 'crdt', bytes: await fetchBody(snap.url) };
+    default: {
+      if (typeof snap.url !== 'string') throw malformed();
+      const url = snap.url;
+      const raw = (snapshot as { content_id?: unknown }).content_id;
+      const contentId = typeof raw === 'string' && raw !== '' ? raw : undefined;
+      const bytes = await fetchSealedBytes(contentId, url, fetchBody);
+      if (needsSealedCodec(bytes)) await loadSealedCodec();
+      try {
+        return { kind: 'frozen', content: await decodeFrozen(bytes) };
+      } catch (err) {
+        // A kept copy that will not decode is dropped and fetched again, so a
+        // damaged entry costs one download rather than the document.
+        if (contentId === undefined || isUpgradeError(err)) throw err;
+        await forgetSealedBytes(contentId);
+        const fresh = await fetchSealedBytes(contentId, url, fetchBody);
+        if (needsSealedCodec(fresh)) await loadSealedCodec();
+        return { kind: 'frozen', content: await decodeFrozen(fresh) };
+      }
+    }
+  }
+}
+
+/** Frozen bytes as content, with a frame newer than this build reported as
+ *  the upgrade error rather than as corrupt content. */
+async function decodeFrozen(bytes: Uint8Array): Promise<SealedContent> {
+  const version = frameVersion(bytes);
+  if (version !== null && version > NEWEST_VERSION) throw contentTooNewError();
+  try {
+    return await decodeSealedContent(bytes);
+  } catch (err) {
+    if (err instanceof SealedStoreError) {
+      throw new BrassError('This document could not be read: its stored content is damaged.', {
+        status: 500,
+      });
+    }
+    throw err;
+  }
+}
+
+function isUpgradeError(err: unknown): boolean {
+  return err instanceof BrassError && err.status === 426;
+}
+
+function malformed(): BrassError {
+  return new BrassError('Malformed document snapshot', { status: 500 });
+}
+
+// Uses `atob` (present in modern browsers, Node 20+, and jsdom) rather than
+// Node-only `Buffer`, which would force a browser-bundle polyfill.
+export function base64ToBytes(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) {
+    bytes[i] = bin.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/join-stamp.ts

@@ -0,0 +1,12 @@
+// The document's `updated_at` as the join that produced a copy read it. The
+// join reads the document's row before its content, so this stamp is never
+// later than what the copy holds.
+const stamps = new WeakMap<object, string>();
+
+export function setJoinStamp(doc: object, updatedAt: unknown): void {
+  if (typeof updatedAt === 'string') stamps.set(doc, updatedAt);
+}
+
+export function joinStampOf(doc: object): string | undefined {
+  return stamps.get(doc);
+}

package/src/manifest-drift.ts

@@ -0,0 +1,54 @@
+import type { ApiFetch } from './api-fetch.js';
+import { inDevelopment } from './in-development.js';
+
+const LOCAL_MANIFEST_PATH = '/.well-known/brass-app.json';
+
+let checked = false;
+
+export interface ManifestDriftDeps {
+  appId: string;
+  origin: string;
+  apiFetch: ApiFetch;
+  fetchImpl?: typeof fetch;
+}
+
+// Development builds only. Brass enforces the manifest it read from the
+// app's published origin, so a local edit has no effect until publish.
+// Runs once per page load and never holds up its caller.
+export function checkManifestDrift(deps: ManifestDriftDeps): void {
+  if (checked || !inDevelopment()) return;
+  checked = true;
+  void compare(deps).catch(() => undefined);
+}
+
+async function compare(deps: ManifestDriftDeps): Promise<void> {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const response = await fetchImpl(`${deps.origin}${LOCAL_MANIFEST_PATH}`, {
+    cache: 'no-store',
+  });
+  if (!response.ok) return;
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(await response.text());
+  } catch {
+    return;
+  }
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) return;
+  const { differing } = await deps.apiFetch<{ differing?: unknown }>({
+    method: 'POST',
+    path: `/apps/${encodeURIComponent(deps.appId)}/manifest-drift`,
+    body: { manifest },
+    idempotent: true,
+  });
+  if (!Array.isArray(differing) || differing.length === 0) return;
+  const fields = differing.filter((f): f is string => typeof f === 'string');
+  if (fields.length === 0) return;
+  console.warn(
+    `[brass] This page's ${LOCAL_MANIFEST_PATH} differs from the manifest Brass is enforcing for this app in: ${fields.join(', ')}. Brass reads the manifest from the published app, so the change applies once the app is published.`,
+  );
+}
+
+/** @internal Test seam: forget that this page load already checked. */
+export function _resetManifestDriftCheck(): void {
+  checked = false;
+}