@powerhousedao/connect-core 6.2.3-dev.82 → 6.2.3-dev.83

package/src/runtime/drive-placements.ts

@@ -0,0 +1,361 @@
+import type { RoutingReactorClient } from "@powerhousedao/reactor-router";
+import { driveDocumentType } from "@powerhousedao/shared/document-drive";
+import { logger } from "document-model";
+import {
+  applyPlacementEntries,
+  servesSlug,
+  LOCAL_BACKEND_NAME,
+  placementKeys,
+  removeLocalCopies,
+  servedUrl,
+  type PlacementEntry,
+  type ResolvedSwitchboardDrive,
+  type SwitchboardDrive,
+  type SyncRemotes,
+} from "./drive-placement.js";
+
+/** A collection by its declared slug among its switchboard's drives, e.g. one served hashed. */
+export async function findServedDrive(
+  router: Pick<RoutingReactorClient, "backends">,
+  drive: SwitchboardDrive,
+): Promise<{ id: string; slug: string } | undefined> {
+  const backend = router.backends.find((b) => b.name === drive.remote);
+  if (!backend) return undefined;
+  const { results } = await backend.api.find({ type: driveDocumentType });
+  const served = results.find(
+    (doc) => doc.header.slug && servesSlug(drive.slug, doc.header.slug),
+  );
+  return served && { id: served.header.id, slug: served.header.slug };
+}
+
+/** Where a drive opens given its stored move, if any: the move, else the host config. */
+export function effectiveBackend(
+  drive: SwitchboardDrive,
+  entry: PlacementEntry | undefined,
+): string {
+  return entry?.backend ?? drive.configured;
+}
+
+/** A drive opening on `backend` reads its copy here, which must arrive first. */
+export function needsCopy(backend: string): boolean {
+  return backend === LOCAL_BACKEND_NAME;
+}
+
+/** A copy has caught up once every scope is at least at the source's revision. */
+export function caughtUp(
+  local: Readonly<Record<string, number>>,
+  source: Readonly<Record<string, number>>,
+): boolean {
+  return Object.entries(source).every(
+    ([scope, revision]) => (local[scope] ?? -1) >= revision,
+  );
+}
+
+/** Where this browser keeps its moves; per origin, so every tab shares it. */
+export interface PlacementStore {
+  list(): Promise<PlacementEntry[]>;
+  put(entry: PlacementEntry): Promise<void>;
+  delete(slug: string): Promise<void>;
+}
+
+/** The router's two placement layers. */
+export type PlacementRouter = {
+  setPlacement(key: string, backend: string | undefined): void;
+  setConfiguredPlacement(key: string, backend: string | undefined): void;
+};
+
+export type PlacementSync = SyncRemotes & {
+  /** Adds a sync remote for the drive. */
+  add(url: string, driveId: string): Promise<void>;
+  /** Bounded wait until the local copy holds what `remote` holds; rejects when it does not. */
+  untilCopied(driveId: string, remote: string): Promise<void>;
+};
+
+export type DrivePlacement = {
+  drive: ResolvedSwitchboardDrive;
+  /** Where the drive opens in this browser now. */
+  backend: string;
+  /** This browser moved it away from the host config. */
+  moved: boolean;
+  /** A move is running. */
+  busy: boolean;
+  /** Where a running move takes the drive. */
+  movingTo?: string;
+};
+
+/** Config placement plus this browser's moves: store, then sync remote, then router. */
+export class DrivePlacements {
+  private applied = new Map<string, PlacementEntry>();
+  private resolved: ResolvedSwitchboardDrive[] = [];
+  private router: PlacementRouter | undefined;
+  private readonly busy = new Map<string, string>();
+  private attached = false;
+  private readonly listeners = new Set<() => void>();
+  private snapshot = new Map<string, DrivePlacement>();
+
+  constructor(
+    readonly drives: readonly SwitchboardDrive[],
+    applied: readonly PlacementEntry[],
+    private readonly store: PlacementStore,
+    private readonly sync: PlacementSync,
+  ) {
+    for (const entry of applied) this.applied.set(entry.slug, entry);
+  }
+
+  /** Reads the store and drops the entries the config has overtaken (O2). */
+  static async load(
+    drives: readonly SwitchboardDrive[],
+    store: PlacementStore,
+    sync: PlacementSync,
+  ): Promise<DrivePlacements> {
+    let entries: PlacementEntry[] = [];
+    try {
+      entries = await store.list();
+    } catch (error) {
+      logger.warn("Could not read this browser's drive moves: @error", error);
+    }
+    const { applied, stale } = applyPlacementEntries(drives, entries);
+    for (const entry of stale) {
+      store.delete(entry.slug).catch((error: unknown) => {
+        logger.warn(
+          "Could not drop drive move @slug: @error",
+          entry.slug,
+          error,
+        );
+      });
+    }
+    return new DrivePlacements(drives, applied, store, sync);
+  }
+
+  /** Where `drive` opens in this browser: a move, else the config. */
+  backendOf(drive: SwitchboardDrive): string {
+    return effectiveBackend(drive, this.applied.get(drive.slug));
+  }
+
+  /** Whether a remote default drive at `url` keeps a copy here. */
+  keepsCopy(url: string): boolean {
+    const drive = this.drives.find((d) => d.url === url);
+    return !drive || this.backendOf(drive) === LOCAL_BACKEND_NAME;
+  }
+
+  /** Drives that open on their switchboard with no copy here. */
+  placed(): SwitchboardDrive[] {
+    return this.drives.filter(
+      (drive) => this.backendOf(drive) !== LOCAL_BACKEND_NAME,
+    );
+  }
+
+  /** Collections this browser keeps a copy of; default drives are added with the others. */
+  keptCollections(): ResolvedSwitchboardDrive[] {
+    return this.resolved.filter(
+      (drive) =>
+        drive.collection &&
+        drive.id !== undefined &&
+        this.backendOf(drive) === LOCAL_BACKEND_NAME,
+    );
+  }
+
+  /** Installs both layers for every drive the router can be told about. */
+  attach(
+    router: PlacementRouter | undefined,
+    resolved: readonly ResolvedSwitchboardDrive[],
+  ): void {
+    this.router = router;
+    this.resolved = [...resolved];
+    this.attached = true;
+    for (const drive of this.resolved) this.install(drive);
+    this.notify();
+  }
+
+  /**
+   * Attaches, follows the moves other tabs made since `load`, then brings
+   * the sync remotes in line; returns the collections to keep a copy of.
+   */
+  async start(
+    router: PlacementRouter | undefined,
+    resolved: readonly ResolvedSwitchboardDrive[],
+    syncsDrives: boolean,
+  ): Promise<ResolvedSwitchboardDrive[]> {
+    this.attach(router, resolved);
+    await this.reload();
+    if (!syncsDrives) return [];
+    const placed = new Set(this.placed().map((drive) => drive.slug));
+    await removeLocalCopies(
+      this.sync,
+      this.resolved.filter(
+        (drive) => placed.has(drive.slug) && !this.busy.has(drive.slug),
+      ),
+    );
+    return this.keptCollections();
+  }
+
+  /** The drive's placement in this browser; undefined for a drive the host does not place on a switchboard. */
+  placementOf(driveId: string): DrivePlacement | undefined {
+    return this.snapshot.get(driveId);
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Opens the drive on `backend` in this browser: its switchboard, or a copy here. */
+  async move(driveId: string, backend: string): Promise<void> {
+    const drive = this.resolved.find((d) => d.id === driveId);
+    if (!drive?.id) {
+      throw new Error(
+        `Drive ${driveId} is not on a switchboard this app links`,
+      );
+    }
+    if (backend !== drive.remote && backend !== LOCAL_BACKEND_NAME) {
+      throw new Error(`Drive ${drive.slug} can't open on ${backend}`);
+    }
+    if (this.busy.has(drive.slug) || this.backendOf(drive) === backend) return;
+    const previous = this.applied.get(drive.slug);
+    const entry: PlacementEntry | undefined =
+      backend === drive.configured
+        ? undefined
+        : { slug: drive.slug, backend, configWas: drive.configured };
+    const id = drive.id;
+    this.busy.set(drive.slug, backend);
+    this.notify();
+    try {
+      await this.record(drive.slug, entry);
+      if (needsCopy(backend)) {
+        try {
+          await this.sync.add(servedUrl(drive), id);
+          await this.sync.untilCopied(id, drive.remote);
+        } catch (error) {
+          // Store first: the removal's broadcast makes other tabs re-read it.
+          await this.record(drive.slug, previous);
+          await removeLocalCopies(this.sync, [drive]);
+          throw error;
+        }
+      } else {
+        try {
+          await removeLocalCopies(this.sync, [drive]);
+        } catch (error) {
+          await this.record(drive.slug, previous);
+          throw error;
+        }
+      }
+      this.install(drive);
+    } finally {
+      this.busy.delete(drive.slug);
+      this.notify();
+    }
+  }
+
+  /** Back to where the host config opens the drive. */
+  reset(driveId: string): Promise<void> {
+    const drive = this.resolved.find((d) => d.id === driveId);
+    return drive ? this.move(driveId, drive.configured) : Promise.resolve();
+  }
+
+  /** Re-reads the store after another tab moved a drive; true when something changed. */
+  async reload(): Promise<boolean> {
+    if (!this.attached) return false;
+    const next = await this.readMoves();
+    if (!next) return false;
+    const changed = this.drives.filter(
+      (drive) =>
+        !this.busy.has(drive.slug) &&
+        effectiveBackend(drive, next.get(drive.slug)) !== this.backendOf(drive),
+    );
+    if (changed.length === 0) return false;
+    await Promise.all(
+      changed.map((drive) => this.follow(drive, next.get(drive.slug))),
+    );
+    this.notify();
+    return true;
+  }
+
+  /** A copy kept by another tab is routed here only once it has arrived. */
+  private async follow(
+    drive: SwitchboardDrive,
+    entry: PlacementEntry | undefined,
+  ): Promise<void> {
+    const resolved = this.resolved.find((d) => d.slug === drive.slug);
+    if (needsCopy(effectiveBackend(drive, entry)) && resolved?.id) {
+      this.busy.set(drive.slug, LOCAL_BACKEND_NAME);
+      this.notify();
+      try {
+        await this.sync.untilCopied(resolved.id, resolved.remote);
+      } catch (error) {
+        logger.warn(
+          "Drive @slug was not copied into this browser; leaving it where it opens: @error",
+          drive.slug,
+          error,
+        );
+        return;
+      } finally {
+        this.busy.delete(drive.slug);
+      }
+      // The mover may have rolled back while this tab waited.
+      const latest = await this.readMoves();
+      if (!latest) return;
+      entry = latest.get(drive.slug);
+    }
+    if (entry) this.applied.set(drive.slug, entry);
+    else this.applied.delete(drive.slug);
+    if (resolved) this.install(resolved);
+  }
+
+  private async readMoves(): Promise<Map<string, PlacementEntry> | undefined> {
+    let entries: PlacementEntry[];
+    try {
+      entries = await this.store.list();
+    } catch (error) {
+      logger.warn("Could not read this browser's drive moves: @error", error);
+      return undefined;
+    }
+    const { applied } = applyPlacementEntries(this.drives, entries);
+    return new Map(applied.map((entry) => [entry.slug, entry]));
+  }
+
+  private async record(
+    slug: string,
+    entry: PlacementEntry | undefined,
+  ): Promise<void> {
+    if (entry) {
+      await this.store.put(entry);
+      this.applied.set(slug, entry);
+    } else {
+      await this.store.delete(slug);
+      this.applied.delete(slug);
+    }
+  }
+
+  private install(drive: ResolvedSwitchboardDrive): void {
+    const router = this.router;
+    if (!router) return;
+    const configured =
+      drive.configured === drive.remote ? drive.remote : undefined;
+    const runtime = this.applied.get(drive.slug)?.backend;
+    for (const key of placementKeys(drive)) {
+      router.setConfiguredPlacement(key, configured);
+      router.setPlacement(key, runtime);
+    }
+  }
+
+  private notify(): void {
+    const snapshot = new Map<string, DrivePlacement>();
+    for (const drive of this.resolved) {
+      if (!drive.id) continue;
+      const backend = this.backendOf(drive);
+      snapshot.set(drive.id, {
+        drive,
+        backend,
+        moved: backend !== drive.configured,
+        busy: this.busy.has(drive.slug),
+        ...(this.busy.has(drive.slug)
+          ? { movingTo: this.busy.get(drive.slug) }
+          : {}),
+      });
+    }
+    this.snapshot = snapshot;
+    for (const listener of [...this.listeners]) listener();
+  }
+}

package/src/runtime/index.ts

@@ -28,6 +28,36 @@ export {
   relistAppDrives,
   selectAppReactorClient,
 } from "./app-reactor-client.js";
+export {
+  applyPlacementEntries,
+  keepsLocalCopy,
+  LOCAL_BACKEND_NAME,
+  placementKeys,
+  removeLocalCopies,
+  resolveSwitchboardDrives,
+  servedUrl,
+  servesSlug,
+  switchboardDrives,
+} from "./drive-placement.js";
+export type {
+  PlacementEntry,
+  ResolvedSwitchboardDrive,
+  ResolveSwitchboardDrivesOptions,
+  SwitchboardDrive,
+} from "./drive-placement.js";
+export {
+  caughtUp,
+  DrivePlacements,
+  effectiveBackend,
+  findServedDrive,
+  needsCopy,
+} from "./drive-placements.js";
+export type {
+  DrivePlacement,
+  PlacementRouter,
+  PlacementStore,
+  PlacementSync,
+} from "./drive-placements.js";
 export { useBackendAuthGate } from "./backend-auth-gate.js";
 export type { BackendAuthGateMode } from "./backend-auth-gate.js";
 export type {

package/src/runtime/multi-reactor.ts

@@ -24,9 +24,11 @@ import type {
   DocumentModelModule,
   ISigner,
 } from "@powerhousedao/shared/document-model";
+import { switchboardOfDrive } from "@powerhousedao/shared/host-tokens";
 import { logger } from "document-model";
+import { LOCAL_BACKEND_NAME } from "./drive-placement.js";
 
-export const LOCAL_BACKEND_NAME = "connect-local";
+export { LOCAL_BACKEND_NAME } from "./drive-placement.js";
 export const REMOTE_BACKEND_NAME = "switchboard-remote";
 
 export type LocalReactorModule =
@@ -64,16 +66,12 @@ export function localFacts(
 export function deriveSwitchboardGraphqlUrl(
   remoteDriveUrl: string,
 ): string | undefined {
-  let parsed: URL;
-  try {
-    parsed = new URL(remoteDriveUrl);
-  } catch {
-    return undefined;
-  }
-  const prefix = /^(.*)\/d\/[^/]+\/?$/.exec(parsed.pathname)?.[1];
-  return prefix === undefined ? undefined : `${parsed.origin}${prefix}/graphql`;
+  return switchboardOfDrive(remoteDriveUrl)?.graphql;
 }
 
+/** A switchboard the router reaches, by its router backend name. */
+export type SwitchboardRemote = { name: string; graphqlUrl: string };
+
 /** The loaded document models, or a getter that reads the current ones. */
 export type LoadedDocumentModels =
   | readonly DocumentModelModule[]
@@ -83,7 +81,11 @@ export type MultiReactorParams = {
   /** The local module, built and ready. Undefined builds a REMOTE-ONLY router
    * (no local backend → no local reactor, no PGlite): the `remote` client. */
   module: LocalReactorModule | undefined;
-  remoteGraphqlUrl: string;
+  /** One per switchboard; `remoteGraphqlUrl` alone is one named `switchboard-remote`. */
+  remotes?: readonly SwitchboardRemote[];
+  remoteGraphqlUrl?: string;
+  /** Collection key or drive id -> backend; names no backend here are dropped. */
+  collections?: Readonly<Record<string, string>>;
   /** Signs routed writes; unsigned (anonymous) without one. */
   signer?: ISigner;
   /** Signing models when the local module exposes no registry; the router asks the local reactor (or, remote-only, the loaded set). */
@@ -105,8 +107,9 @@ export const PLACE_ON_REMOTE: CollectionRequirementsInput = Object.freeze({});
 function localIdCheckAnswer(
   documentId: string,
   error: unknown,
+  remoteNames: ReadonlySet<string>,
 ): boolean | undefined {
-  if (!failedOnlyOnRemote(error)) {
+  if (!failedOnlyOnRemote(error, remoteNames)) {
     return undefined;
   }
   logger.warn(
@@ -119,36 +122,61 @@ function localIdCheckAnswer(
 
 /** The router Connect installs, with Connect's handling of credentials and id checks. */
 export class ConnectRoutingClient extends RoutingReactorClient {
-  private readonly remote: SwitchboardBackend;
+  private readonly remotes: readonly SwitchboardBackend[];
 
   constructor(
     backends: readonly RoutableBackendConfig[],
     options: RoutingClientOptions,
-    remote: SwitchboardBackend,
+    remotes: readonly SwitchboardBackend[],
     hasLocal: boolean,
   ) {
+    const remoteNames = new Set(remotes.map((remote) => remote.config.name));
     super(backends, {
       ...options,
       answerFailedIdCheck: hasLocal
-        ? localIdCheckAnswer
+        ? (id, error) => localIdCheckAnswer(id, error, remoteNames)
         : options.answerFailedIdCheck,
     });
-    this.remote = remote;
+    this.remotes = remotes;
   }
 
   /** Renown's sign-in and sign-out call this on whatever client is installed. */
   notifyCredentialsChanged(): void {
-    this.remote.notifyCredentialsChanged();
+    for (const remote of this.remotes) remote.notifyCredentialsChanged();
   }
 }
 
-function failedOnlyOnRemote(error: unknown): boolean {
+function failedOnlyOnRemote(
+  error: unknown,
+  remoteNames: ReadonlySet<string>,
+): boolean {
   return (
     error instanceof FanInPartialFailureError &&
-    error.failures.every((failure) => failure.backend === REMOTE_BACKEND_NAME)
+    error.failures.every((failure) => remoteNames.has(failure.backend))
   );
 }
 
+/** The remotes to build, one per switchboard: the first link to a base wins. */
+function remotesOf(params: MultiReactorParams): SwitchboardRemote[] {
+  const listed: readonly SwitchboardRemote[] = params.remotes?.length
+    ? params.remotes
+    : params.remoteGraphqlUrl
+      ? [{ name: REMOTE_BACKEND_NAME, graphqlUrl: params.remoteGraphqlUrl }]
+      : [];
+  const seen = new Set<string>();
+  return listed.filter((remote) => {
+    if (seen.has(remote.graphqlUrl)) {
+      logger.warn(
+        "@name opens the same switchboard as an earlier backend; skipping it",
+        remote.name,
+      );
+      return false;
+    }
+    seen.add(remote.graphqlUrl);
+    return true;
+  });
+}
+
 /**
  * Build the Connect routing client. With a local `module` it is the router
  * over the tab's reactor (primary) and the Switchboard; WITHOUT one it is the
@@ -163,16 +191,22 @@ export async function buildMultiReactorClient(
   const registry = module?.reactorModule?.documentModelRegistry;
   const loaded = params.documentModelModules;
   const loadedModules = typeof loaded === "function" ? loaded : () => loaded;
+  const listed = remotesOf(params);
+  if (listed.length === 0) {
+    throw new Error("A routing client needs at least one switchboard");
+  }
   // The logged-in Renown user's token and signer, read per request as before.
-  const remote = createSwitchboardBackend({
-    name: REMOTE_BACKEND_NAME,
-    url: params.remoteGraphqlUrl,
-    tokenProvider: ambientRenownTokenProvider,
-    signer: ambientRenownSigner,
-    documentModels: () => registry?.getAllModules() ?? loadedModules(),
-    inspection: "none",
-  });
-  const remoteBackend = remote.config;
+  const remotes = listed.map((remote) =>
+    createSwitchboardBackend({
+      name: remote.name,
+      url: remote.graphqlUrl,
+      tokenProvider: ambientRenownTokenProvider,
+      signer: ambientRenownSigner,
+      documentModels: () => registry?.getAllModules() ?? loadedModules(),
+      inspection: "none",
+    }),
+  );
+  const remoteBackends = remotes.map((remote) => remote.config);
   const backends: RoutableBackendConfig[] = module
     ? [
         {
@@ -182,22 +216,29 @@ export async function buildMultiReactorClient(
           reach: localReach(module.kind),
           refusesMisroutes: false,
         },
-        remoteBackend,
+        ...remoteBackends,
       ]
-    : [remoteBackend];
+    : remoteBackends;
+  const names = new Set(backends.map((backend) => backend.name));
+  const collections = Object.fromEntries(
+    Object.entries(params.collections ?? {}).filter(([, backend]) =>
+      names.has(backend),
+    ),
+  );
   const router = new ConnectRoutingClient(
     backends,
     {
-      // Remote-only: the Switchboard is primary and serves every collection;
-      // with a local reactor, new collections land on it (inspectable).
-      primaryBackend: module ? LOCAL_BACKEND_NAME : REMOTE_BACKEND_NAME,
+      // Remote-only: the first Switchboard is primary; with a local reactor,
+      // new collections land on it (inspectable).
+      primaryBackend: module ? LOCAL_BACKEND_NAME : remoteBackends[0].name,
       defaultRequirements: module ? PLACE_ON_LOCAL : PLACE_ON_REMOTE,
+      collections,
       signer: params.signer,
       onDiagnostic: params.onDiagnostic,
       // The Switchboard serves no models over GraphQL; remote-only uses the loaded set.
       documentModelModules: module ? undefined : loadedModules,
     },
-    remote,
+    remotes,
     Boolean(module),
   );
   await router.refreshFacts();