@dxos/client-services 0.10.0 → 0.11.0

package/src/packlets/worker/worker-runtime.ts

@@ -3,25 +3,26 @@
 //
 
 import * as Reactivity from '@effect/experimental/Reactivity';
+import type * as RpcClient from '@effect/rpc/RpcClient';
+import type * as RpcServer from '@effect/rpc/RpcServer';
 import type * as SqlClient from '@effect/sql/SqlClient';
+import * as Context_ from 'effect/Context';
 import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
 import * as Layer from 'effect/Layer';
 import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as Scope from 'effect/Scope';
 
 import { Trigger } from '@dxos/async';
-import { DEFAULT_WORKER_BROADCAST_CHANNEL } from '@dxos/client-protocol';
 import { type Config } from '@dxos/config';
 import { Context } from '@dxos/context';
+import { EffectEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
-import {
-  MemorySignalManager,
-  MemorySignalManagerContext,
-  WebsocketSignalManager,
-  setIdentityTags,
-} from '@dxos/messaging';
+import { MemorySignalManager, MemorySignalManagerContext, setIdentityTags } from '@dxos/messaging';
 import { RtcTransportProxyFactory } from '@dxos/network-manager';
-import { type RpcPort } from '@dxos/rpc';
+import { makeInProcessClient } from '@dxos/protocols';
+import { DevicesService, IdentityService } from '@dxos/protocols/rpc';
 import * as SqlExport from '@dxos/sql-sqlite/SqlExport';
 import * as SqliteClient from '@dxos/sql-sqlite/SqliteClient';
 import * as SqlTransaction from '@dxos/sql-sqlite/SqlTransaction';
@@ -30,16 +31,17 @@ import { type MaybePromise } from '@dxos/util';
 import { ClientServicesHost } from '../services';
 import { WorkerSession } from './worker-session';
 
-// NOTE: Keep as RpcPorts to avoid dependency on @dxos/rpc-tunnel so we don't depend on browser-specific apis.
+// Session transports are effect-rpc protocol layers handed over by the worker framework: appProtocol
+// serves the client services (+ WorkerService); systemProtocol carries the reverse-direction
+// BridgeService (worker→tab).
 export type CreateSessionProps = {
-  appPort: RpcPort;
-  systemPort: RpcPort;
-  shellPort?: RpcPort;
+  appProtocol: RpcServer.Protocol['Type'];
+  systemProtocol: RpcClient.Protocol['Type'];
+  shellPort?: MessagePort;
   onClose?: () => Promise<void>;
 };
 
 export type WorkerRuntimeOptions = {
-  channel?: string;
   configProvider: () => MaybePromise<Config>;
   acquireLock: () => Promise<void>;
   releaseLock: () => void;
@@ -57,241 +59,233 @@ export type WorkerRuntimeOptions = {
 };
 
 /**
- * Runtime for the shared and dedciated worker.
- * Manages connections from proxies (in tabs).
- * Tabs make requests to the `ClientServicesHost`, and provide a WebRTC gateway.
+ * Effect service surface for the dedicated-worker runtime.
+ *
+ * Manages connections from proxies (in tabs): tabs make requests to the `ClientServicesHost`, and
+ * provide a WebRTC gateway. Lifecycle (`start` / `stop`) is caller-driven — the worker framework
+ * builds the runtime after receiving init config, then drives sessions for their lifetime — so these
+ * are explicit programs rather than Layer finalizers.
  */
-export class WorkerRuntime {
-  private readonly _configProvider: () => MaybePromise<Config>;
-  private readonly _acquireLock: () => Promise<void>;
-  private readonly _releaseLock: () => void;
-  private readonly _onStop?: () => Promise<void>;
-  private readonly _transportFactory = new RtcTransportProxyFactory();
-  private readonly _ready = new Trigger<Error | undefined>();
-  private readonly _sessions = new Set<WorkerSession>();
-  private readonly _clientServices!: ClientServicesHost;
-  private readonly _channel: string;
-  private readonly _automaticallyConnectWebrtc: boolean;
-  private readonly _livenessLock = new WebLockWrapper(`@dxos/client-services/WorkerRuntime/${crypto.randomUUID()}`);
-  private _broadcastChannel?: BroadcastChannel;
-  private _sessionForNetworking?: WorkerSession; // TODO(burdon): Expose to client QueryStatusResponse.
-  private _config!: Config;
-  private _signalMetadataTags: any = { runtime: 'worker-runtime' };
-  private _signalTelemetryEnabled: boolean = false;
-  private _runtime!: ManagedRuntime.ManagedRuntime<
-    SqlTransaction.SqlTransaction | SqlClient.SqlClient | SqlExport.SqlExport,
-    never
-  >;
-
-  constructor({
-    channel = DEFAULT_WORKER_BROADCAST_CHANNEL,
-    configProvider,
-    acquireLock,
-    releaseLock,
-    onStop,
-    automaticallyConnectWebrtc = true,
-    sqliteLayer,
-  }: WorkerRuntimeOptions) {
-    this._configProvider = configProvider;
-    this._acquireLock = acquireLock;
-    this._releaseLock = releaseLock;
-    this._onStop = onStop;
-    this._channel = channel;
-    if (sqliteLayer) {
-      log.warn('Using testing SQLite layer');
-    }
-    this._runtime = ManagedRuntime.make(
-      SqlTransaction.layer
-        .pipe(Layer.provideMerge(sqliteLayer ?? LocalSqliteOpfsLayer), Layer.provideMerge(Reactivity.layer))
-        .pipe(Layer.orDie),
-    );
-    this._clientServices = new ClientServicesHost({
-      callbacks: {
-        onReset: async () => this.stop(),
-      },
-      runtime: this._runtime.runtimeEffect,
-      runtimeProps: {
-        // Auto-activate spaces that were previously active after leader changeover.
-        autoActivateSpaces: true,
-      },
-    });
-    this._automaticallyConnectWebrtc = automaticallyConnectWebrtc;
-  }
+export interface WorkerRuntimeService {
+  /** The client services host served to connected tabs. */
+  readonly host: ClientServicesHost;
+  /** Resolve config, open the services host, and signal readiness. Never fails: startup errors are surfaced to session callers via the readiness gate. */
+  readonly start: () => Effect.Effect<void>;
+  /** Tear down sessions' host, dispose the runtime, release the storage lock, and run `onStop`. Idempotent. */
+  readonly stop: () => Effect.Effect<void>;
+  /** Open a new tab session over the supplied effect-rpc protocols and register it for WebRTC bridging. */
+  readonly createSession: (props: CreateSessionProps) => Effect.Effect<WorkerSession>;
+  /** Route the WebRTC bridge through the given session (or disconnect when `undefined`). */
+  readonly connectWebrtcBridge: (session: WorkerSession | undefined) => Effect.Effect<void>;
+}
 
-  get host() {
-    return this._clientServices;
-  }
+/**
+ * Context tag for the dedicated-worker runtime service. Provided by {@link layerWorkerRuntime}.
+ */
+export class WorkerRuntime extends Context_.Tag('@dxos/client-services/WorkerRuntime')<
+  WorkerRuntime,
+  WorkerRuntimeService
+>() {}
 
-  get livenessLockKey(): string {
-    return this._livenessLock.key;
+/**
+ * Constructs the {@link WorkerRuntimeService}. The SQLite {@link ManagedRuntime} and
+ * {@link ClientServicesHost} are built eagerly; the async open sequence runs in {@link start}.
+ */
+export const makeWorkerRuntime = ({
+  configProvider,
+  acquireLock,
+  releaseLock,
+  onStop,
+  automaticallyConnectWebrtc = true,
+  sqliteLayer,
+}: WorkerRuntimeOptions): WorkerRuntimeService => {
+  const transportFactory = new RtcTransportProxyFactory();
+  const ready = new Trigger<Error | undefined>();
+  const sessions = new Set<WorkerSession>();
+  const signalMetadataTags: any = { runtime: 'worker-runtime' };
+
+  let stopped = false;
+  let sessionForNetworking: WorkerSession | undefined;
+  let config: Config;
+  let serviceScope: Scope.CloseableScope | undefined;
+
+  if (sqliteLayer) {
+    log.warn('Using testing SQLite layer');
   }
 
-  async start(): Promise<void> {
-    log('starting...');
-    try {
-      log('worker-runtime: acquiring liveness lock (background)');
-      void this._livenessLock.acquire();
+  const runtime = ManagedRuntime.make(
+    SqlTransaction.layer
+      .pipe(Layer.provideMerge(sqliteLayer ?? LocalSqliteOpfsLayer), Layer.provideMerge(Reactivity.layer))
+      .pipe(Layer.orDie),
+  );
 
-      // Steal the lock from the other worker.
-      log('worker-runtime: broadcasting stop to displace previous worker');
-      this._broadcastChannel = new BroadcastChannel(this._channel);
-      this._broadcastChannel.postMessage({ action: 'stop' });
-      this._broadcastChannel.onmessage = async (event) => {
-        if (event.data?.action === 'stop') {
-          log('worker-runtime: received stop broadcast');
-          await this.stop();
+  const stop = (): Effect.Effect<void> =>
+    Effect.promise(async () => {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      // Release the lock to notify remote clients that the worker is terminating.
+      releaseLock();
+      // Always dispose the SQLite runtime and run onStop, even if host / scope teardown rejects —
+      // otherwise a failed close would leak the runtime and skip the shutdown signal.
+      try {
+        await clientServices.close(Context.default());
+        if (serviceScope) {
+          await EffectEx.runPromise(Scope.close(serviceScope, Exit.void));
+          serviceScope = undefined;
         }
-      };
-
-      log('worker-runtime: acquiring storage lock');
-      await this._acquireLock();
-      log('worker-runtime: storage lock acquired, resolving config');
-      this._config = await this._configProvider();
-      log('worker-runtime: config resolved');
-      this._signalTelemetryEnabled = this._config.get('runtime.client.signalTelemetryEnabled') ?? false;
-      const observabilityGroup = this._config.get('runtime.client.observabilityGroup');
-      if (observabilityGroup) {
-        this._signalMetadataTags.group = observabilityGroup;
+      } finally {
+        await runtime.dispose();
+        await onStop?.();
       }
-      const signals = this._config.get('runtime.services.signaling');
-      log('worker-runtime: initializing client services host');
-      this._clientServices.initialize({
-        config: this._config,
-        signalManager: this._config.get('runtime.client.edgeFeatures')?.signaling
-          ? undefined
-          : signals
-            ? new WebsocketSignalManager(signals, () => (this._signalTelemetryEnabled ? this._signalMetadataTags : {}))
-            : new MemorySignalManager(new MemorySignalManagerContext()), // TODO(dmaretskyi): Inject this context.
-        transportFactory: this._transportFactory,
-      });
-      log('worker-runtime: client services host initialized, opening');
-
-      await this._clientServices.open(new Context());
-      log('worker-runtime: client services host opened, signalling ready');
-      this._ready.wake(undefined);
-      log('started');
-      setIdentityTags({
-        identityService: this._clientServices.services.IdentityService!,
-        devicesService: this._clientServices.services.DevicesService!,
-        setTag: (k: string, v: string) => {
-          this._signalMetadataTags[k] = v;
-        },
-      });
-    } catch (err: any) {
-      this._ready.wake(err);
-      log.error('starting', err);
-    }
-  }
-
-  async stop(): Promise<void> {
-    // Release the lock to notify remote clients that the worker is terminating.
-    this._releaseLock();
-    this._broadcastChannel?.close();
-    this._broadcastChannel = undefined;
-    await this._clientServices.close(Context.default());
-    await this._runtime.dispose();
-    await this._onStop?.();
-    await this._livenessLock.release();
-  }
+    });
 
-  /**
-   * Update signaling telemetry tags from a client-supplied config overlay.
-   *
-   * The worker services outlive individual client connections, so the first client seeds the
-   * worker's core config (storage, signaling, edge features). For fields that can legitimately
-   * differ per tab — `observabilityGroup` and `signalTelemetryEnabled` — this method lets later
-   * connections refresh the signal metadata the worker attaches to its signaling requests
-   * (last-writer-wins, matching the pre-DX-930 per-session RPC behaviour).
-   */
-  updateSignalMetadata(config: Config): void {
-    const observabilityGroup = config.get('runtime.client.observabilityGroup');
-    if (observabilityGroup) {
-      this._signalMetadataTags.group = observabilityGroup;
-    } else {
-      // Clear stale group so a later config that removes observabilityGroup stops attributing
-      // telemetry to the previous client's group (last-writer-wins).
-      delete this._signalMetadataTags.group;
+  const clientServices = new ClientServicesHost({
+    callbacks: {
+      onReset: async () => {
+        await EffectEx.runPromise(stop());
+      },
+    },
+    runtime: runtime.runtimeEffect,
+    runtimeProps: {
+      // Auto-activate spaces that were previously active after leader changeover.
+      autoActivateSpaces: true,
+    },
+  });
+
+  const connectBridge = (session: WorkerSession | undefined): void => {
+    sessionForNetworking = session;
+    transportFactory.setBridgeService(session?.bridgeService);
+  };
+
+  // Selects one of the existing sessions for WebRTC networking.
+  const reconnectWebrtc = Effect.sync(() => {
+    log('reconnecting webrtc...');
+    // Drop the current session if it has since closed.
+    if (sessionForNetworking && !sessions.has(sessionForNetworking)) {
+      sessionForNetworking = undefined;
     }
-    const signalTelemetryEnabled = config.get('runtime.client.signalTelemetryEnabled');
-    if (signalTelemetryEnabled !== undefined) {
-      this._signalTelemetryEnabled = signalTelemetryEnabled;
+    if (!sessionForNetworking) {
+      connectBridge(Array.from(sessions).find((session) => session.bridgeService));
     }
-  }
-
-  /**
-   * Create a new session.
-   */
-  async createSession({ appPort, systemPort, shellPort, onClose }: CreateSessionProps): Promise<WorkerSession> {
-    const session = new WorkerSession({
-      serviceHost: this._clientServices,
-      appPort,
-      systemPort,
-      shellPort,
-      readySignal: this._ready,
-    });
-
-    // When tab is closed or client is destroyed.
-    session.onClose.set(async () => {
-      this._sessions.delete(session);
-      if (this._sessions.size === 0) {
-        // Terminate the worker when all sessions are closed.
-        await this.stop();
-      } else {
-        if (this._automaticallyConnectWebrtc) {
-          this._reconnectWebrtc();
+  });
+
+  const start = (): Effect.Effect<void> =>
+    Effect.promise(async () => {
+      log('starting...');
+      try {
+        log('worker-runtime: acquiring storage lock');
+        await acquireLock();
+        log('worker-runtime: storage lock acquired, resolving config');
+        config = await configProvider();
+        log('worker-runtime: config resolved');
+        const observabilityGroup = config.get('runtime.client.observabilityGroup');
+        if (observabilityGroup) {
+          signalMetadataTags.group = observabilityGroup;
         }
+        log('worker-runtime: initializing client services host');
+        clientServices.initialize({
+          config,
+          // Edge signaling is created in the services host from the edge connection; otherwise fall
+          // back to an isolated in-memory manager (KUBE `WebsocketSignalManager` removed).
+          signalManager: config.get('runtime.client.edgeFeatures')?.signaling
+            ? undefined
+            : new MemorySignalManager(new MemorySignalManagerContext()), // TODO(dmaretskyi): Inject this context.
+          transportFactory,
+        });
+        log('worker-runtime: client services host initialized, opening');
+
+        await clientServices.open(new Context());
+        log('worker-runtime: client services host opened, signalling ready');
+        ready.wake(undefined);
+        log('started');
+        // Bridge the host identity/devices Handlers to the effect-rpc client surface in-process.
+        serviceScope = Effect.runSync(Scope.make());
+        const { IdentityService: identityHandlers, DevicesService: devicesHandlers } = clientServices.services;
+        invariant(identityHandlers, 'IdentityService handler not available');
+        invariant(devicesHandlers, 'DevicesService handler not available');
+        const [identityService, devicesService] = await EffectEx.runPromise(
+          Effect.all([
+            makeInProcessClient(IdentityService.Rpcs, identityHandlers),
+            makeInProcessClient(DevicesService.Rpcs, devicesHandlers),
+          ]).pipe(Effect.provideService(Scope.Scope, serviceScope)),
+        );
+        setIdentityTags({
+          identityService,
+          devicesService,
+          setTag: (key: string, value: string) => {
+            signalMetadataTags[key] = value;
+          },
+        });
+      } catch (err: any) {
+        ready.wake(err);
+        log.error('starting', err);
       }
-      await onClose?.();
     });
 
-    await session.open();
-    // A worker can only service one origin currently
-    invariant(
-      !this._signalMetadataTags.origin || this._signalMetadataTags.origin === session.origin,
-      `worker origin changed from ${this._signalMetadataTags.origin} to ${session.origin}?`,
-    );
-    this._signalMetadataTags.origin = session.origin;
-    this._sessions.add(session);
+  const createSession = ({
+    appProtocol,
+    systemProtocol,
+    shellPort,
+    onClose,
+  }: CreateSessionProps): Effect.Effect<WorkerSession> =>
+    Effect.gen(function* () {
+      const session = new WorkerSession({
+        serviceHost: clientServices,
+        appProtocol,
+        systemProtocol,
+        shellPort,
+        readySignal: ready,
+      });
 
-    if (this._automaticallyConnectWebrtc) {
-      this._reconnectWebrtc();
-    }
+      // When tab is closed or client is destroyed.
+      session.onClose.set(async () => {
+        await EffectEx.runPromise(
+          Effect.gen(function* () {
+            sessions.delete(session);
+            if (sessions.size === 0) {
+              // Terminate the worker when all sessions are closed.
+              yield* stop();
+            } else if (automaticallyConnectWebrtc) {
+              yield* reconnectWebrtc;
+            }
+          }),
+        );
+        await onClose?.();
+      });
 
-    return session;
-  }
+      yield* session.open();
+      // A worker can only service one origin currently.
+      invariant(
+        !signalMetadataTags.origin || signalMetadataTags.origin === session.origin,
+        `worker origin changed from ${signalMetadataTags.origin} to ${session.origin}?`,
+      );
+      signalMetadataTags.origin = session.origin;
+      sessions.add(session);
+
+      if (automaticallyConnectWebrtc) {
+        yield* reconnectWebrtc;
+      }
 
-  /**
-   * Connects the WebRTC bridge to the specified session.
-   * If no session is provided, disconnects the WebRTC bridge.
-   *
-   * Called automatically if `automaticallyConnectWebrtc` is true.
-   *
-   * @param session The session to connect the WebRTC bridge to.
-   */
-  connectWebrtcBridge(session: WorkerSession | undefined): void {
-    this._sessionForNetworking = session;
-    this._transportFactory.setBridgeService(session?.bridgeService);
-  }
+      return session;
+    });
 
-  /**
-   * Selects one of the existing session for WebRTC networking.
-   */
-  private _reconnectWebrtc(): void {
-    log('reconnecting webrtc...');
-    // Check if current session is already closed.
-    if (this._sessionForNetworking) {
-      if (!this._sessions.has(this._sessionForNetworking)) {
-        this._sessionForNetworking = undefined;
-      }
-    }
+  return {
+    host: clientServices,
+    start,
+    stop,
+    createSession,
+    connectWebrtcBridge: (session) => Effect.sync(() => connectBridge(session)),
+  };
+};
 
-    // Select existing session.
-    if (!this._sessionForNetworking) {
-      const selected = Array.from(this._sessions).find((session) => session.bridgeService);
-      this.connectWebrtcBridge(selected);
-    }
-  }
-}
+/**
+ * Layer providing the {@link WorkerRuntime} service. The service is constructed synchronously;
+ * callers drive `start` / `stop` explicitly (see {@link WorkerRuntimeService}).
+ */
+export const layerWorkerRuntime = (options: WorkerRuntimeOptions): Layer.Layer<WorkerRuntime> =>
+  Layer.sync(WorkerRuntime, () => makeWorkerRuntime(options));
 
 const DB_NAME = 'DXOS';
 
@@ -317,35 +311,3 @@ const LocalSqliteOpfsLayer = SqlExportLayer.pipe(
   Layer.provideMerge(SqliteClient.layerOpfs({ dbName: DB_NAME })),
   Layer.provideMerge(Reactivity.layer),
 );
-
-// TODO(wittjosiah): Factor out to a separate module.
-class WebLockWrapper {
-  readonly #key: string;
-  #release?: () => void;
-
-  constructor(key: string) {
-    this.#key = key;
-  }
-
-  get key(): string {
-    return this.#key;
-  }
-
-  acquire(options: LockOptions = {}) {
-    return navigator.locks.request(this.#key, options, async () => {
-      await new Promise<void>((resolve) => {
-        this.#release = resolve;
-      }); // Blocks for the duration of the worker's lifetime.
-      this.#release = undefined;
-    });
-  }
-
-  release() {
-    this.#release?.();
-    this.#release = undefined;
-  }
-
-  [Symbol.dispose]() {
-    this.release();
-  }
-}