@loro-dev/flock-sqlite 0.8.0 → 0.9.1

package/src/write-coordinator.ts

@@ -0,0 +1,468 @@
+import { LruMap } from "./lru";
+import {
+  isFlockChannelMessage,
+  serializeError,
+  type FlockCommit,
+  type FlockRpcRequest,
+  type FlockRpcResponse,
+  type FlockWriteRequest,
+  type RequestId,
+  type TabId,
+} from "./multi-tab";
+import type {
+  FlockRoleProvider,
+  FlockRuntime,
+  FlockTransport,
+  TimeoutHandle,
+} from "./multi-tab-env";
+import type { FlockSQLiteRole, RoleChangeListener } from "./types";
+
+const DEFAULT_RPC_TIMEOUT_MS = 3000;
+const MAX_REQUEST_CACHE = 1024;
+
+export type WriteCoordinator = {
+  getRole(): FlockSQLiteRole;
+  isHost(): boolean;
+  subscribeRoleChange(listener: RoleChangeListener): () => void;
+  dispatchWriteRequest<T>(
+    payload: FlockWriteRequest,
+  ): Promise<{ commit: FlockCommit; result: T }>;
+  close(): void;
+};
+
+type CoordinatorOptions = {
+  runtime: FlockRuntime;
+  tabId: TabId;
+  transport: FlockTransport | undefined;
+  roleProvider: FlockRoleProvider;
+  ingestCommit: (commit: FlockCommit, bufferable: boolean) => void;
+  executeWriteRequest: (
+    payload: FlockWriteRequest,
+    origin: TabId,
+    requestId: RequestId,
+  ) => Promise<{ commit: FlockCommit; result: unknown }>;
+};
+
+function isRetryableForwardError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  if (error.name === "HostLost") {
+    return true;
+  }
+  if (error.message.includes("Timed out waiting for host response")) {
+    return true;
+  }
+  return false;
+}
+
+function retryDelayMs(attempt: number): number {
+  const base = 25;
+  const max = 500;
+  if (attempt <= 0) {
+    return base;
+  }
+  const exp = Math.min(max, base * 2 ** (attempt - 1));
+  return exp;
+}
+
+function bufferableCommit(commit: FlockCommit, tabId: TabId): boolean {
+  return commit.origin === tabId && commit.source === "local";
+}
+
+function requestCacheKey(from: TabId, requestId: RequestId): string {
+  return `${from}|${requestId}`;
+}
+
+function deserializeRemoteError(serialized: {
+  name: string;
+  message: string;
+  stack?: string;
+}): Error {
+  const error = new Error(serialized.message);
+  error.name = serialized.name;
+  if (serialized.stack) {
+    error.stack = serialized.stack;
+  }
+  return error;
+}
+
+class BaseCoordinator {
+  protected readonly runtime: FlockRuntime;
+  protected readonly tabId: TabId;
+  protected roleValue: FlockSQLiteRole;
+  protected readonly roleListeners: Set<RoleChangeListener>;
+  protected roleUnsubscribe: (() => void) | undefined;
+  protected closed: boolean;
+
+  constructor(runtime: FlockRuntime, tabId: TabId, roleProvider: FlockRoleProvider) {
+    this.runtime = runtime;
+    this.tabId = tabId;
+    this.roleValue = roleProvider.getRole();
+    this.roleListeners = new Set();
+    this.roleUnsubscribe = roleProvider.subscribeRoleChange?.((role) => {
+      this.setRole(role);
+    });
+    this.closed = false;
+  }
+
+  getRole(): FlockSQLiteRole {
+    return this.roleValue;
+  }
+
+  isHost(): boolean {
+    return this.roleValue === "host";
+  }
+
+  subscribeRoleChange(listener: RoleChangeListener): () => void {
+    this.roleListeners.add(listener);
+    try {
+      listener(this.roleValue);
+    } catch {
+      // Swallow listener errors to avoid breaking the CRDT/sync pipeline.
+    }
+    return () => {
+      this.roleListeners.delete(listener);
+    };
+  }
+
+  protected setRole(role: FlockSQLiteRole): void {
+    if (role === this.roleValue) {
+      return;
+    }
+    this.roleValue = role;
+    for (const listener of this.roleListeners) {
+      try {
+        listener(role);
+      } catch {
+        // Swallow listener errors to avoid breaking the CRDT/sync pipeline.
+      }
+    }
+  }
+
+  protected closeRole(): void {
+    this.roleUnsubscribe?.();
+    this.roleUnsubscribe = undefined;
+    this.setRole("unknown");
+  }
+}
+
+class DirectWriteCoordinator extends BaseCoordinator implements WriteCoordinator {
+  private writeQueue: Promise<void>;
+  private readonly ingestCommit: (commit: FlockCommit, bufferable: boolean) => void;
+  private readonly executeWriteRequest: (
+    payload: FlockWriteRequest,
+    origin: TabId,
+    requestId: RequestId,
+  ) => Promise<{ commit: FlockCommit; result: unknown }>;
+
+  constructor(options: CoordinatorOptions) {
+    super(options.runtime, options.tabId, options.roleProvider);
+    this.ingestCommit = options.ingestCommit;
+    this.executeWriteRequest = options.executeWriteRequest;
+    this.writeQueue = Promise.resolve();
+  }
+
+  private enqueueWrite<T>(task: () => Promise<T>): Promise<T> {
+    const scheduled = this.writeQueue.then(task, task);
+    this.writeQueue = scheduled.then(
+      () => undefined,
+      () => undefined,
+    );
+    return scheduled;
+  }
+
+  async dispatchWriteRequest<T>(
+    payload: FlockWriteRequest,
+  ): Promise<{ commit: FlockCommit; result: T }> {
+    if (this.closed) {
+      throw new Error("FlockSQLite is closed");
+    }
+    const requestId = this.runtime.randomUUID();
+    const { commit, result } = await this.enqueueWrite(() =>
+      this.executeWriteRequest(payload, this.tabId, requestId),
+    );
+    this.ingestCommit(commit, bufferableCommit(commit, this.tabId));
+    return { commit, result: result as T };
+  }
+
+  close(): void {
+    this.closed = true;
+    this.closeRole();
+  }
+}
+
+class MultiTabWriteCoordinator extends BaseCoordinator implements WriteCoordinator {
+  private readonly transport: FlockTransport;
+  private transportUnsubscribe: (() => void) | undefined;
+  private readonly pendingRequests: Map<
+    RequestId,
+    {
+      resolve: (response: FlockRpcResponse) => void;
+      reject: (error: unknown) => void;
+      timeoutId: TimeoutHandle;
+    }
+  >;
+  private readonly hostResponseCache: LruMap<string, FlockRpcResponse>;
+  private readonly hostInFlight: Map<string, Promise<FlockRpcResponse>>;
+  private writeQueue: Promise<void>;
+  private readonly ingestCommit: (commit: FlockCommit, bufferable: boolean) => void;
+  private readonly executeWriteRequest: (
+    payload: FlockWriteRequest,
+    origin: TabId,
+    requestId: RequestId,
+  ) => Promise<{ commit: FlockCommit; result: unknown }>;
+
+  constructor(options: CoordinatorOptions & { transport: FlockTransport }) {
+    super(options.runtime, options.tabId, options.roleProvider);
+    this.transport = options.transport;
+    this.transportUnsubscribe = this.transport.subscribe((message) => {
+      try {
+        this.handleTransportMessage(message);
+      } catch {
+        // ignore
+      }
+    });
+    this.pendingRequests = new Map();
+    this.hostResponseCache = new LruMap<string, FlockRpcResponse>(MAX_REQUEST_CACHE);
+    this.hostInFlight = new Map();
+    this.writeQueue = Promise.resolve();
+    this.ingestCommit = options.ingestCommit;
+    this.executeWriteRequest = options.executeWriteRequest;
+  }
+
+  private enqueueWrite<T>(task: () => Promise<T>): Promise<T> {
+    const scheduled = this.writeQueue.then(task, task);
+    this.writeQueue = scheduled.then(
+      () => undefined,
+      () => undefined,
+    );
+    return scheduled;
+  }
+
+  private shouldForwardWrites(): boolean {
+    return this.roleValue !== "host";
+  }
+
+  private handleTransportMessage(message: unknown): void {
+    if (!isFlockChannelMessage(message)) {
+      return;
+    }
+    if (message.t === "res") {
+      if (message.to !== this.tabId) {
+        return;
+      }
+      const pending = this.pendingRequests.get(message.id);
+      if (!pending) {
+        return;
+      }
+      this.runtime.clearTimeout(pending.timeoutId);
+      this.pendingRequests.delete(message.id);
+      pending.resolve(message);
+      return;
+    }
+
+    if (message.t === "commit") {
+      const commit = message.commit;
+      this.ingestCommit(commit, bufferableCommit(commit, this.tabId));
+      return;
+    }
+
+    if (message.t === "req") {
+      if (message.from === this.tabId) {
+        return;
+      }
+      if (this.roleValue !== "host" || this.closed) {
+        return;
+      }
+      void this.processHostRequest(message);
+    }
+  }
+
+  private broadcastCommit(commit: FlockCommit): void {
+    if (this.closed) {
+      return;
+    }
+    if (this.roleValue !== "host") {
+      return;
+    }
+    this.transport.postMessage({ t: "commit", commit });
+  }
+
+  private async forwardWriteRequest<T>(
+    payload: FlockWriteRequest,
+    requestId: RequestId,
+    timeoutMs = DEFAULT_RPC_TIMEOUT_MS,
+  ): Promise<{ commit: FlockCommit | undefined; result: T }> {
+    if (this.closed) {
+      throw new Error("FlockSQLite is closed");
+    }
+
+    const request: FlockRpcRequest = {
+      t: "req",
+      from: this.tabId,
+      id: requestId,
+      payload,
+    };
+
+    const response = await new Promise<FlockRpcResponse>((resolve, reject) => {
+      const timeoutId = this.runtime.setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Timed out waiting for host response"));
+      }, timeoutMs);
+
+      this.pendingRequests.set(requestId, { resolve, reject, timeoutId });
+      this.transport.postMessage(request);
+    });
+
+    if (!response.ok) {
+      if (response.error) {
+        throw deserializeRemoteError(response.error);
+      }
+      throw new Error("Host rejected request");
+    }
+
+    const commit = response.commit;
+    if (commit) {
+      this.ingestCommit(commit, bufferableCommit(commit, this.tabId));
+    }
+    return { commit, result: response.result as T };
+  }
+
+  async dispatchWriteRequest<T>(
+    payload: FlockWriteRequest,
+  ): Promise<{ commit: FlockCommit; result: T }> {
+    if (this.closed) {
+      throw new Error("FlockSQLite is closed");
+    }
+
+    const requestId = this.runtime.randomUUID();
+    const maxAttempts = 5;
+    let lastError: unknown;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      if (!this.shouldForwardWrites()) {
+        const { commit, result } = await this.enqueueWrite(() =>
+          this.executeWriteRequest(payload, this.tabId, requestId),
+        );
+        this.ingestCommit(commit, bufferableCommit(commit, this.tabId));
+        this.broadcastCommit(commit);
+        return { commit, result: result as T };
+      }
+
+      try {
+        const forwarded = await this.forwardWriteRequest<T>(
+          payload,
+          requestId,
+        );
+        if (!forwarded.commit) {
+          throw new Error("Host did not return commit");
+        }
+        return { commit: forwarded.commit, result: forwarded.result };
+      } catch (error) {
+        lastError = error;
+        if (attempt >= maxAttempts || !isRetryableForwardError(error)) {
+          throw error;
+        }
+        await new Promise<void>((resolve) => {
+          this.runtime.setTimeout(() => resolve(), retryDelayMs(attempt));
+        });
+      }
+    }
+
+    throw lastError ?? new Error("Failed to dispatch write request");
+  }
+
+  private async processHostRequest(request: FlockRpcRequest): Promise<void> {
+    const cacheKey = requestCacheKey(request.from, request.id);
+    const cached = this.hostResponseCache.get(cacheKey);
+    if (cached) {
+      if (cached.ok && cached.commit) {
+        this.broadcastCommit(cached.commit);
+      }
+      this.transport.postMessage(cached);
+      return;
+    }
+
+    let inFlight = this.hostInFlight.get(cacheKey);
+    if (!inFlight) {
+      inFlight = this.enqueueWrite(async () => {
+        if (this.roleValue !== "host" || this.closed) {
+          return {
+            t: "res",
+            to: request.from,
+            id: request.id,
+            ok: false,
+            error: { name: "HostLost", message: "Host role was lost" },
+          } satisfies FlockRpcResponse;
+        }
+
+        try {
+          const { commit, result } = await this.executeWriteRequest(
+            request.payload,
+            request.from,
+            request.id,
+          );
+          this.ingestCommit(commit, bufferableCommit(commit, this.tabId));
+          this.broadcastCommit(commit);
+
+          return {
+            t: "res",
+            to: request.from,
+            id: request.id,
+            ok: true,
+            commit,
+            result,
+          } satisfies FlockRpcResponse;
+        } catch (error) {
+          return {
+            t: "res",
+            to: request.from,
+            id: request.id,
+            ok: false,
+            error: serializeError(error),
+          } satisfies FlockRpcResponse;
+        }
+      });
+
+      this.hostInFlight.set(cacheKey, inFlight);
+      void inFlight.finally(() => {
+        this.hostInFlight.delete(cacheKey);
+      });
+    }
+
+    const response = await inFlight;
+    this.hostResponseCache.set(cacheKey, response);
+    this.transport.postMessage(response);
+  }
+
+  close(): void {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.transportUnsubscribe?.();
+    this.transportUnsubscribe = undefined;
+    this.transport.close?.();
+
+    for (const { reject, timeoutId } of this.pendingRequests.values()) {
+      this.runtime.clearTimeout(timeoutId);
+      try {
+        reject(new Error("FlockSQLite closed"));
+      } catch {
+        // ignore
+      }
+    }
+    this.pendingRequests.clear();
+
+    this.closeRole();
+  }
+}
+
+export function createWriteCoordinator(options: CoordinatorOptions): WriteCoordinator {
+  if (!options.transport) {
+    return new DirectWriteCoordinator(options);
+  }
+  return new MultiTabWriteCoordinator({ ...options, transport: options.transport });
+}
+