@dxos/client-protocol 0.9.1-staging.ee54ba693a → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/client-protocol",
-  "version": "0.9.1-staging.ee54ba693a",
+  "version": "0.11.0",
   "description": "Core DXOS Client API.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,14 +16,12 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./types": {
       "source": "./src/types/index.ts",
       "types": "./dist/types/src/types/index.d.ts",
-      "browser": "./dist/lib/browser/types/index.mjs",
-      "node": "./dist/lib/node-esm/types/index.mjs"
+      "import": "./dist/lib/types.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -32,17 +30,24 @@
     "src"
   ],
   "dependencies": {
+    "@effect/platform": "0.96.2",
+    "@effect/platform-browser": "0.76.0",
+    "@effect/rpc": "0.75.1",
     "base-x": "~3.0.11",
     "effect": "3.21.4",
-    "@dxos/credentials": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo-client": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo": "0.9.1-staging.ee54ba693a",
-    "@dxos/async": "0.9.1-staging.ee54ba693a",
-    "@dxos/node-std": "0.9.1-staging.ee54ba693a",
-    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
-    "@dxos/keys": "0.9.1-staging.ee54ba693a",
-    "@dxos/protocols": "0.9.1-staging.ee54ba693a",
-    "@dxos/rpc": "0.9.1-staging.ee54ba693a"
+    "@dxos/async": "0.11.0",
+    "@dxos/codec-protobuf": "0.11.0",
+    "@dxos/credentials": "0.11.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/echo-client": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/node-std": "0.11.0",
+    "@dxos/protocols": "0.11.0",
+    "@dxos/rpc": "0.11.0",
+    "@dxos/rpc-tunnel": "0.11.0",
+    "@dxos/worker-framework": "0.11.0"
   },
   "peerDependencies": {
     "effect": "3.21.4"

package/src/Rpc.ts

@@ -0,0 +1,200 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as BrowserWorker from '@effect/platform-browser/BrowserWorker';
+import * as BrowserWorkerRunner from '@effect/platform-browser/BrowserWorkerRunner';
+import * as RpcClient from '@effect/rpc/RpcClient';
+import * as RpcServer from '@effect/rpc/RpcServer';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import type * as Scope from 'effect/Scope';
+
+import { RpcTiming } from '@dxos/worker-framework';
+
+export type ServeOptions = {
+  disableTracing?: boolean;
+  concurrency?: number | 'unbounded';
+  /**
+   * When enabled, stamps each outbound RPC with a `Date.now()` send time and logs queue-wait /
+   * service durations on the worker above {@link RpcTiming.Options.minLogMs} (default 100 ms).
+   */
+  timing?: boolean | RpcTiming.Options;
+};
+
+// A worker RPC client runs over a single MessagePort that multiplexes every request by id, so there
+// is no real per-connection concurrency limit. The `@effect/rpc` worker protocol backs the client
+// with a `Pool` that holds one worker for a request's whole lifetime — including long-lived streams.
+// The pool's default concurrency of 1 therefore lets a single open stream (e.g. a subscription) block
+// every other call. Allow effectively-unbounded concurrent requests over the one worker instead.
+const WORKER_CLIENT_CONCURRENCY = Number.MAX_SAFE_INTEGER;
+
+// Merged rpc groups (e.g. ClientServicesRpcs) do not structurally satisfy RpcGroup<Rpc.Any>
+// in @effect/rpc's type parameter; runtime dispatch accepts any RpcGroup instance.
+const asRpcGroup = <G>(group: G): Parameters<typeof RpcClient.make>[0] => group as Parameters<typeof RpcClient.make>[0];
+
+/**
+ * Builds an effect-native RPC client over a caller-supplied {@link RpcClient.Protocol} layer.
+ * Transport-agnostic: consumers provide the Worker-platform protocol (see {@link makeClient}) or a
+ * byte protocol over a legacy transport (e.g. `@dxos/rpc`'s RpcPort layer for iframe/devtools bridges).
+ */
+export const makeClientOverProtocol = <G, ProtocolError, ProtocolRequirements>(
+  protocol: Layer.Layer<RpcClient.Protocol, ProtocolError, ProtocolRequirements>,
+  group: G,
+  options?: Pick<ServeOptions, 'disableTracing' | 'timing'>,
+): Effect.Effect<unknown, never, Scope.Scope | ProtocolRequirements> =>
+  Effect.gen(function* () {
+    const timingEnabled = RpcTiming.isEnabled(options?.timing);
+    const rpcGroup = timingEnabled ? RpcTiming.applyMiddleware(asRpcGroup(group)) : asRpcGroup(group);
+    const protocolLayer = timingEnabled ? protocol.pipe(Layer.provideMerge(RpcTiming.clientLayer())) : protocol;
+
+    // Build the transport into the caller's scope (extended via `Scope.extend`) rather than
+    // `Effect.provide`-ing the layer directly: that would bind the transport's lifetime to this
+    // construction effect, tearing the worker connection down the instant the client is returned
+    // (the client is used later by the caller). `Layer.build` keeps it alive for the caller's scope.
+    const context = yield* Layer.build(protocolLayer);
+    return yield* RpcClient.make(asRpcGroup(rpcGroup), { disableTracing: options?.disableTracing ?? true }).pipe(
+      Effect.provide(context),
+    );
+  }).pipe(Effect.orDie);
+
+/**
+ * Builds an effect-native RPC client over a {@link MessagePort} using the native Worker platform
+ * protocol (structured-clone frames, transferables supported).
+ */
+export const makeClient = <G>(
+  port: MessagePort,
+  group: G,
+  options?: Pick<ServeOptions, 'disableTracing' | 'timing'>,
+): Effect.Effect<unknown, never, Scope.Scope> =>
+  makeClientOverProtocol(
+    RpcClient.layerProtocolWorker({ size: 1, concurrency: WORKER_CLIENT_CONCURRENCY }).pipe(
+      Layer.provide(BrowserWorker.layerPlatform(() => port)),
+    ),
+    group,
+    options,
+  );
+
+export type GroupServer = {
+  open(): Promise<void>;
+  close(): Promise<void>;
+};
+
+/**
+ * Serves an {@link RpcGroup} on a {@link MessagePort} via the native Worker runner protocol.
+ */
+export const serve = <G, H extends Layer.Layer<never, never, never>>(
+  port: MessagePort,
+  group: G,
+  handlers: H,
+  options?: ServeOptions,
+): GroupServer => {
+  let runtime: ManagedRuntime.ManagedRuntime<never, never> | undefined;
+
+  return {
+    async open(): Promise<void> {
+      if (runtime) {
+        return;
+      }
+
+      const timingEnabled = RpcTiming.isEnabled(options?.timing);
+      const rpcGroup = timingEnabled ? RpcTiming.applyMiddleware(asRpcGroup(group)) : asRpcGroup(group);
+      // Merge the timing middleware layer into the handler layer (rather than a conditional
+      // `.pipe(...)` element) so the pipeline stays a fixed tuple.
+      const handlersLayer = timingEnabled
+        ? Layer.merge(handlers, RpcTiming.serverLayer(RpcTiming.resolveOptions(options?.timing)))
+        : handlers;
+      const serverLayer = RpcServer.layer(asRpcGroup(rpcGroup), {
+        disableTracing: options?.disableTracing ?? true,
+        concurrency: options?.concurrency ?? 'unbounded',
+      }).pipe(
+        Layer.provide(handlersLayer),
+        Layer.provide(
+          RpcServer.layerProtocolWorkerRunner.pipe(Layer.provide(BrowserWorkerRunner.layerMessagePort(port))),
+        ),
+        Layer.orDie,
+      );
+
+      const current = ManagedRuntime.make(serverLayer);
+      try {
+        await current.runPromise(Effect.void);
+      } catch (error) {
+        // Leave the server un-opened on startup failure so a later open() can retry rather than
+        // returning early against a runtime that never started.
+        await current.dispose();
+        throw error;
+      }
+      runtime = current;
+    },
+
+    async close(): Promise<void> {
+      const current = runtime;
+      runtime = undefined;
+      await current?.dispose();
+    },
+  };
+};
+
+/**
+ * Serves an {@link RpcGroup} over a caller-supplied {@link RpcServer.Protocol} layer.
+ * Transport-agnostic counterpart to {@link makeClientOverProtocol}: consumers provide a byte
+ * protocol over a legacy transport (e.g. `@dxos/rpc`'s RpcPort layer for iframe/devtools bridges).
+ */
+export const serveOverProtocol = <G, H extends Layer.Layer<never, never, never>>(
+  protocol: Layer.Layer<RpcServer.Protocol>,
+  group: G,
+  handlers: H,
+  options?: ServeOptions,
+): GroupServer => {
+  let runtime: ManagedRuntime.ManagedRuntime<never, never> | undefined;
+  // Cache the in-flight open so concurrent opens share one initialization and a close during open
+  // can await it before disposing — otherwise `runtime` is unset mid-open and a fast open/close
+  // (e.g. client restart) leaks the runtime.
+  let openPromise: Promise<void> | undefined;
+
+  return {
+    async open(): Promise<void> {
+      if (openPromise) {
+        return openPromise;
+      }
+
+      openPromise = (async () => {
+        const timingEnabled = RpcTiming.isEnabled(options?.timing);
+        const rpcGroup = timingEnabled ? RpcTiming.applyMiddleware(asRpcGroup(group)) : asRpcGroup(group);
+        const handlersLayer = timingEnabled
+          ? Layer.merge(handlers, RpcTiming.serverLayer(RpcTiming.resolveOptions(options?.timing)))
+          : handlers;
+        const serverLayer = RpcServer.layer(asRpcGroup(rpcGroup), {
+          disableTracing: options?.disableTracing ?? true,
+          concurrency: options?.concurrency ?? 'unbounded',
+        }).pipe(Layer.provide(handlersLayer), Layer.provide(protocol), Layer.orDie);
+
+        const current = ManagedRuntime.make(serverLayer);
+        try {
+          await current.runPromise(Effect.void);
+        } catch (error) {
+          // Leave the server un-opened on startup failure so a later open() can retry.
+          openPromise = undefined;
+          await current.dispose();
+          throw error;
+        }
+        runtime = current;
+      })();
+      return openPromise;
+    },
+
+    async close(): Promise<void> {
+      if (openPromise) {
+        // Wait for an in-flight open so we dispose the runtime it created rather than leaking it.
+        await openPromise.catch(() => {});
+        openPromise = undefined;
+      }
+      const current = runtime;
+      runtime = undefined;
+      await current?.dispose();
+    },
+  };
+};

package/src/bridge-rpc.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as RpcClient from '@effect/rpc/RpcClient';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as Runtime from 'effect/Runtime';
+import * as Scope from 'effect/Scope';
+
+import { type Stream as PbStream } from '@dxos/codec-protobuf/stream';
+import { EffectEx } from '@dxos/effect';
+import { type BridgeService as BridgeServiceRpc } from '@dxos/protocols/proto/dxos/mesh/bridge';
+import { BridgeService } from '@dxos/protocols/rpc';
+
+import * as Rpc from './Rpc';
+import { pbStreamToStream, streamToPbStream } from './service-rpc';
+
+/**
+ * The system channel runs the WebRTC {@link BridgeServiceRpc} in the worker→tab direction: the worker
+ * calls the tab's network stack to proxy RTC connections. It is served over its own {@link MessagePort}
+ * (the reverse of the app port) via effect-rpc, replacing the legacy protobuf duplex peer.
+ *
+ * `BridgeServiceRpc` is the proto-shaped interface (`Promise`/{@link PbStream}) that
+ * `RtcTransportService` implements and `RtcTransportProxyFactory` consumes; the helpers below adapt
+ * it to and from the effect-rpc surface.
+ */
+
+const toError = (cause: unknown): Error => (cause instanceof Error ? cause : new Error(String(cause)));
+
+/**
+ * Serves a proto-shaped {@link BridgeServiceRpc} (the tab's `RtcTransportService`) over a
+ * {@link MessagePort} via effect-rpc. The worker consumes it with {@link makeBridgeServiceClient}.
+ */
+export const serveBridgeService = (port: MessagePort, service: BridgeServiceRpc): Rpc.GroupServer => {
+  const unary =
+    <Req, Res>(method: (request: Req) => Promise<Res>) =>
+    (payload: Req) =>
+      Effect.tryPromise({ try: () => method(payload), catch: toError });
+
+  const handlers = {
+    'BridgeService.open': (payload: Parameters<BridgeServiceRpc['open']>[0]) =>
+      pbStreamToStream(() => service.open(payload)),
+    'BridgeService.sendSignal': unary((request: Parameters<BridgeServiceRpc['sendSignal']>[0]) =>
+      service.sendSignal(request),
+    ),
+    'BridgeService.sendData': unary((request: Parameters<BridgeServiceRpc['sendData']>[0]) =>
+      service.sendData(request),
+    ),
+    'BridgeService.close': unary((request: Parameters<BridgeServiceRpc['close']>[0]) => service.close(request)),
+    'BridgeService.getDetails': unary((request: Parameters<BridgeServiceRpc['getDetails']>[0]) =>
+      service.getDetails(request),
+    ),
+    'BridgeService.getStats': unary((request: Parameters<BridgeServiceRpc['getStats']>[0]) =>
+      service.getStats(request),
+    ),
+  };
+
+  // Dispatched dynamically across the group; per-method handler types cannot be expressed statically.
+  return Rpc.serve(port, BridgeService.Rpcs, BridgeService.Rpcs.toLayer(handlers as never), {
+    disableTracing: true,
+    concurrency: 'unbounded',
+  });
+};
+
+/**
+ * Builds a proto-shaped {@link BridgeServiceRpc} backed by an effect-rpc client over a
+ * {@link MessagePort}. Used in the worker to hand `RtcTransportProxyFactory` a bridge that proxies to
+ * the tab. The returned `close` releases the transport scope.
+ */
+export const makeBridgeServiceClient = async (
+  port: MessagePort,
+): Promise<{ bridgeService: BridgeServiceRpc; close: () => Promise<void> }> =>
+  bridgeServiceClientFromEffect((scope) => Rpc.makeClient(port, BridgeService.Rpcs).pipe(Scope.extend(scope)));
+
+/**
+ * Builds a proto-shaped {@link BridgeServiceRpc} over a pre-built {@link RpcClient.Protocol} (the
+ * value the tag resolves to — e.g. the worker→client protocol handed to a worker-framework session
+ * via effect context) rather than a raw {@link MessagePort}.
+ */
+export const makeBridgeServiceClientOverProtocol = async (
+  protocol: RpcClient.Protocol['Type'],
+): Promise<{ bridgeService: BridgeServiceRpc; close: () => Promise<void> }> =>
+  bridgeServiceClientFromEffect((scope) =>
+    Rpc.makeClientOverProtocol(Layer.succeed(RpcClient.Protocol, protocol), BridgeService.Rpcs).pipe(
+      Scope.extend(scope),
+    ),
+  );
+
+/** Adapts an effect-rpc {@link BridgeService.Client} (built by the caller) to the proto-shaped surface. */
+const bridgeServiceClientFromEffect = async (
+  makeClient: (scope: Scope.Scope) => Effect.Effect<unknown, never, never>,
+): Promise<{ bridgeService: BridgeServiceRpc; close: () => Promise<void> }> => {
+  const scope = Effect.runSync(Scope.make());
+  const client = (await EffectEx.runPromise(makeClient(scope))) as BridgeService.Client;
+
+  const bridge = client.BridgeService;
+  const bridgeService: BridgeServiceRpc = {
+    open: (request) => streamToPbStream(Runtime.defaultRuntime, bridge.open(request)),
+    sendSignal: (request) => EffectEx.runPromise(bridge.sendSignal(request)),
+    sendData: (request) => EffectEx.runPromise(bridge.sendData(request)),
+    close: (request) => EffectEx.runPromise(bridge.close(request)),
+    getDetails: (request) => EffectEx.runPromise(bridge.getDetails(request)),
+    getStats: (request) => EffectEx.runPromise(bridge.getStats(request)),
+  };
+
+  return {
+    bridgeService,
+    close: async () => {
+      await EffectEx.runPromise(Scope.close(scope, Exit.void));
+    },
+  };
+};

package/src/config.ts

@@ -7,7 +7,6 @@
 export const DEFAULT_CLIENT_CHANNEL = 'dxos:app';
 export const DEFAULT_INTERNAL_CHANNEL = 'dxos:vault';
 export const DEFAULT_SHELL_CHANNEL = 'dxos:shell';
-export const DEFAULT_WORKER_BROADCAST_CHANNEL = 'dxos:shared-worker';
 
 /**
  * @deprecated

package/src/index.ts

@@ -2,12 +2,14 @@
 // Copyright 2020 DXOS.org
 //
 
-export * from './client';
+export * from './bridge-rpc';
 export * from './config';
+export * as Rpc from './Rpc';
 export type * from './echo';
 export type * from './halo';
 export * from './invitations';
 export * from './service';
+export * from './service-rpc';
 export type * from './shell';
 export * from './space';
 export * from './timeouts';