@dxos/client-services 0.10.0 → 0.11.1

package/src/packlets/services/client-services-layer.ts

@@ -0,0 +1,186 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+
+import { EchoHostService } from '@dxos/echo-host';
+import { EdgeConnectionService } from '@dxos/edge-client';
+import { KeyringApiService } from '@dxos/keyring';
+import { SignalManagerService } from '@dxos/messaging';
+import { SwarmNetworkManagerService } from '@dxos/network-manager';
+import {
+  ContactsService,
+  DataService,
+  DevicesService,
+  EdgeAgentService,
+  FeedService,
+  IdentityService,
+  InvitationsService,
+  NetworkService,
+  QueryService,
+  SpacesService,
+} from '@dxos/protocols/rpc';
+
+import { EdgeAgentServiceImpl } from '../agents';
+import { DevicesServiceImpl } from '../devices';
+import { IdentityManagerService, IdentityServiceImpl } from '../identity';
+import { ContactsServiceImpl } from '../identity/contacts-service';
+import { EdgeIdentityRecoveryManagerService } from '../identity/identity-recovery-manager';
+import { InvitationsManagerService, InvitationsServiceImpl } from '../invitations';
+import { NetworkServiceImpl } from '../network';
+import { SpaceManagerService } from '../space';
+import { SpacesServiceImpl } from '../spaces';
+import { ClientServicesHostService } from './service-host';
+
+//
+// Each client RPC service handler is exposed as an individual Effect service tag. Handlers depend
+// directly on the lower-level component tags they consume (EchoHostService, IdentityManagerService,
+// …); only handlers that need lifecycle orchestration (identity creation, readiness gates)
+// additionally depend on {@link ClientServicesHostService} (the host provides itself into the stack).
+//
+
+/**
+ * Union of every client RPC service tag resolved from the stack.
+ */
+export type ClientServicesRpcContext =
+  | IdentityService.Tag
+  | ContactsService.Tag
+  | InvitationsService.Tag
+  | DevicesService.Tag
+  | SpacesService.Tag
+  | NetworkService.Tag
+  | EdgeAgentService.Tag
+  | DataService.Tag
+  | QueryService.Tag
+  | FeedService.Tag;
+
+// Identity creation is a lifecycle sequence and profile broadcast iterates live spaces, so both
+// remain orchestrator responsibilities resolved from {@link ClientServicesHostService}.
+// The impl is a {@link Resource}; its open/close lifecycle is bound to the layer scope.
+const identityServiceLayer = Layer.scoped(
+  IdentityService.Tag,
+  Effect.gen(function* () {
+    const identityManager = yield* IdentityManagerService;
+    const recoveryManager = yield* EdgeIdentityRecoveryManagerService;
+    const keyring = yield* KeyringApiService;
+    const host = yield* ClientServicesHostService;
+    const service = new IdentityServiceImpl(
+      identityManager,
+      recoveryManager,
+      keyring,
+      async (params, ctx) => {
+        const identity = await host.createIdentity(params, ctx);
+        await host.initialized.wait();
+        return identity;
+      },
+      (profile) => host.broadcastProfileUpdate(profile),
+    );
+    yield* Effect.acquireRelease(
+      Effect.promise(() => service.open()),
+      () => Effect.promise(() => service.close()),
+    );
+    return service;
+  }),
+);
+
+const contactsServiceLayer = Layer.effect(
+  ContactsService.Tag,
+  Effect.gen(function* () {
+    const identityManager = yield* IdentityManagerService;
+    const spaceManager = yield* SpaceManagerService;
+    const host = yield* ClientServicesHostService;
+    return new ContactsServiceImpl(identityManager, spaceManager, () => host.whenDataSpaceManagerReady());
+  }),
+);
+
+const invitationsServiceLayer = Layer.effect(
+  InvitationsService.Tag,
+  Effect.map(InvitationsManagerService, (invitationsManager) => new InvitationsServiceImpl(invitationsManager)),
+);
+
+const devicesServiceLayer = Layer.effect(
+  DevicesService.Tag,
+  Effect.gen(function* () {
+    const identityManager = yield* IdentityManagerService;
+    // Edge connection is absent in the non-edge stack, so resolve it optionally.
+    const edgeConnection = Option.getOrUndefined(yield* Effect.serviceOption(EdgeConnectionService));
+    return new DevicesServiceImpl(identityManager, edgeConnection);
+  }),
+);
+
+const spacesServiceLayer = Layer.effect(
+  SpacesService.Tag,
+  Effect.gen(function* () {
+    const identityManager = yield* IdentityManagerService;
+    const spaceManager = yield* SpaceManagerService;
+    const echoHost = yield* EchoHostService;
+    const host = yield* ClientServicesHostService;
+    return new SpacesServiceImpl(identityManager, spaceManager, echoHost, () => host.whenDataSpaceManagerReady());
+  }),
+);
+
+const networkServiceLayer = Layer.effect(
+  NetworkService.Tag,
+  Effect.gen(function* () {
+    const networkManager = yield* SwarmNetworkManagerService;
+    const signalManager = yield* SignalManagerService;
+    const edgeConnection = Option.getOrUndefined(yield* Effect.serviceOption(EdgeConnectionService));
+    return new NetworkServiceImpl(networkManager, signalManager, edgeConnection);
+  }),
+);
+
+const edgeAgentServiceLayer = Layer.effect(
+  EdgeAgentService.Tag,
+  Effect.gen(function* () {
+    const edgeConnection = Option.getOrUndefined(yield* Effect.serviceOption(EdgeConnectionService));
+    const host = yield* ClientServicesHostService;
+    return new EdgeAgentServiceImpl(() => host.whenEdgeAgentManagerReady(), edgeConnection);
+  }),
+);
+
+const dataServiceLayer = Layer.effect(
+  DataService.Tag,
+  Effect.map(EchoHostService, (echoHost) => echoHost.dataService),
+);
+
+const queryServiceLayer = Layer.effect(
+  QueryService.Tag,
+  Effect.map(EchoHostService, (echoHost) => echoHost.queryService),
+);
+
+const feedServiceLayer = Layer.effect(
+  FeedService.Tag,
+  Effect.map(EchoHostService, (echoHost) => echoHost.feedService),
+);
+
+/**
+ * Composes every client RPC service handler on top of the component tags exposed by the stack.
+ * Each handler keeps its own tag so callers resolve them individually from the stack runtime.
+ */
+export const ClientServicesRpcLayer: Layer.Layer<
+  ClientServicesRpcContext,
+  never,
+  | EchoHostService
+  | IdentityManagerService
+  | SpaceManagerService
+  | InvitationsManagerService
+  | EdgeIdentityRecoveryManagerService
+  | KeyringApiService
+  | SwarmNetworkManagerService
+  | SignalManagerService
+  | ClientServicesHostService
+> = Layer.mergeAll(
+  identityServiceLayer,
+  contactsServiceLayer,
+  invitationsServiceLayer,
+  devicesServiceLayer,
+  spacesServiceLayer,
+  networkServiceLayer,
+  edgeAgentServiceLayer,
+  dataServiceLayer,
+  queryServiceLayer,
+  feedServiceLayer,
+);

package/src/packlets/services/cross-device-space-synchronizer.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as EffectContext from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { type Context, type Lifecycle, Resource } from '@dxos/context';
+import { type CredentialProcessor, getCredentialAssertion } from '@dxos/credentials';
+import { assertState } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { type Credential } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+import { type Identity } from '../identity';
+import { DataSpaceManager, DataSpaceManagerService } from '../spaces';
+
+/**
+ * Replicates cross-device space membership and deletion credentials from the halo space.
+ */
+export interface CrossDeviceSpaceSynchronizer extends CredentialProcessor, Lifecycle {
+  setIdentity(identity: Identity): void;
+}
+
+/**
+ * Effect service tag for {@link CrossDeviceSpaceSynchronizer}.
+ */
+export class CrossDeviceSpaceSynchronizerService extends EffectContext.Tag(
+  '@dxos/client-services/CrossDeviceSpaceSynchronizer',
+)<CrossDeviceSpaceSynchronizerService, CrossDeviceSpaceSynchronizer>() {}
+
+class CrossDeviceSpaceSynchronizerImpl extends Resource implements CrossDeviceSpaceSynchronizer {
+  private _identity?: Identity;
+
+  constructor(private readonly dataSpaceManager: DataSpaceManager) {
+    super();
+  }
+
+  setIdentity(identity: Identity): void {
+    this._identity = identity;
+  }
+
+  protected override async _open(ctx: Context): Promise<void> {
+    assertState(this._identity, 'identity not set');
+    await this._identity.space.spaceState.addCredentialProcessor(this);
+  }
+
+  protected override async _close(ctx: Context): Promise<void> {
+    if (!this._identity) {
+      return;
+    }
+    await this._identity.space.spaceState.removeCredentialProcessor(this);
+  }
+
+  async processCredential(credential: Credential): Promise<void> {
+    assertState(this._identity, 'identity not set');
+    const assertion = getCredentialAssertion(credential);
+
+    // A space was tombstoned on another device: replicate the deletion locally.
+    if (assertion['@type'] === 'dxos.halo.credentials.SpaceDeleted') {
+      if (assertion.spaceKey.equals(this._identity.space.key)) {
+        // ignore halo space
+        return;
+      }
+      if (!this.dataSpaceManager) {
+        log('dataSpaceManager not initialized yet, ignoring space deletion', { details: assertion });
+        return;
+      }
+
+      try {
+        log('tombstoning space recorded in halo', { details: assertion });
+        await this.dataSpaceManager.handleRemoteSpaceDeleted(this._ctx, assertion.spaceKey);
+      } catch (err) {
+        log.catch(err);
+      }
+      return;
+    }
+
+    if (assertion['@type'] !== 'dxos.halo.credentials.SpaceMember') {
+      return;
+    }
+    if (assertion.spaceKey.equals(this._identity.space.key)) {
+      // ignore halo space
+      return;
+    }
+    if (!this.dataSpaceManager) {
+      log('dataSpaceManager not initialized yet, ignoring space admission', { details: assertion });
+      return;
+    }
+    // Do not re-accept a space that has been tombstoned (handles out-of-order credential replay).
+    if (this.dataSpaceManager.isSpaceDeleted(assertion.spaceKey)) {
+      log('space is deleted, ignoring space admission', { details: assertion });
+      return;
+    }
+    if (this.dataSpaceManager.spaces.has(assertion.spaceKey)) {
+      log('space already exists, ignoring space admission', { details: assertion });
+      return;
+    }
+
+    try {
+      log('accepting space recorded in halo', { details: assertion });
+      await this.dataSpaceManager.acceptSpace(this._ctx, {
+        spaceKey: assertion.spaceKey,
+        genesisFeedKey: assertion.genesisFeedKey,
+        tags: assertion.tags,
+      });
+    } catch (err) {
+      log.catch(err);
+    }
+  }
+}
+
+/**
+ * Creates a dormant {@link CrossDeviceSpaceSynchronizer} bound to the given data space manager.
+ */
+export const createCrossDeviceSpaceSynchronizer = (dataSpaceManager: DataSpaceManager): CrossDeviceSpaceSynchronizer =>
+  new CrossDeviceSpaceSynchronizerImpl(dataSpaceManager);
+
+/**
+ * Effect Layer constructing a dormant {@link CrossDeviceSpaceSynchronizer}.
+ */
+export const CrossDeviceSpaceSynchronizerLayer: Layer.Layer<
+  CrossDeviceSpaceSynchronizerService,
+  never,
+  DataSpaceManagerService
+> = Layer.effect(
+  CrossDeviceSpaceSynchronizerService,
+  Effect.gen(function* () {
+    const dataSpaceManager = yield* DataSpaceManagerService;
+    return createCrossDeviceSpaceSynchronizer(dataSpaceManager);
+  }),
+);

package/src/packlets/services/effect-rpc.test.ts

@@ -0,0 +1,314 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as BrowserWorker from '@effect/platform-browser/BrowserWorker';
+import * as BrowserWorkerRunner from '@effect/platform-browser/BrowserWorkerRunner';
+import * as Rpc from '@effect/rpc/Rpc';
+import * as RpcClient from '@effect/rpc/RpcClient';
+import * as RpcGroup from '@effect/rpc/RpcGroup';
+import * as RpcServer from '@effect/rpc/RpcServer';
+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 Schema from 'effect/Schema';
+import * as Scope from 'effect/Scope';
+import * as Stream from 'effect/Stream';
+import { describe, expect, onTestFinished, test } from 'vitest';
+
+import { Trigger, sleep } from '@dxos/async';
+import {
+  ClientRpcServer,
+  type ClientServicesHandlers,
+  type ClientServicesRpc,
+  makeClientServicesRpc,
+  makeServicesFromRpc,
+} from '@dxos/client-protocol';
+import { Stream as PbStream } from '@dxos/codec-protobuf/stream';
+import { EffectEx } from '@dxos/effect';
+import { PublicKey } from '@dxos/keys';
+import { IdentityNotInitializedError, TimeoutError } from '@dxos/protocols';
+import { type QueryStatusResponse, SpaceState, SystemStatus } from '@dxos/protocols/proto/dxos/client/services';
+import { MembershipPolicy } from '@dxos/protocols/proto/dxos/halo/credentials';
+import { SpacesService, SystemService } from '@dxos/protocols/rpc';
+
+//
+// Helpers & Schema for test suite 2
+//
+
+class User extends Schema.Class<User>('User')({
+  id: Schema.String,
+  name: Schema.String,
+}) {}
+
+class TestGroup extends RpcGroup.make(
+  Rpc.make('ping', {
+    success: Schema.String,
+    payload: {
+      message: Schema.String,
+    },
+  }),
+  Rpc.make('getUser', {
+    success: User,
+    payload: {
+      id: Schema.String,
+    },
+  }),
+) {}
+
+const handlers = TestGroup.toLayer(
+  Effect.gen(function* () {
+    return {
+      ping: ({ message }) => Effect.succeed(`pong: ${message}`),
+      getUser: ({ id }) => Effect.succeed(new User({ id, name: `User ${id}` })),
+    };
+  }),
+);
+
+const makeMessageChannel = () =>
+  Effect.gen(function* () {
+    const channel = new MessageChannel();
+    const port1 = channel.port1;
+    const port2 = channel.port2;
+
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        port1.close();
+        port2.close();
+      }),
+    );
+
+    return { port1, port2 };
+  });
+
+//
+// Helpers for test suite 1
+//
+
+const mockService = <T>(partial: Partial<T>): T => partial as T;
+
+const setupRpc = async (
+  services: () => Partial<ClientServicesHandlers>,
+  options?: { onRequest?: () => Promise<void> },
+): Promise<ClientServicesRpc> => {
+  const channel = new MessageChannel();
+  const proxyPort = channel.port1;
+  const serverPort = channel.port2;
+
+  const server = new ClientRpcServer({ services, port: serverPort, onRequest: options?.onRequest });
+  await server.open();
+  onTestFinished(() => server.close());
+
+  const scope = Effect.runSync(Scope.make());
+  onTestFinished(() => EffectEx.runPromise(Scope.close(scope, Exit.void)));
+  return EffectEx.runPromise(makeClientServicesRpc(proxyPort).pipe(Scope.extend(scope)));
+};
+
+const setup = async (
+  services: () => Partial<ClientServicesHandlers>,
+  options?: { onRequest?: () => Promise<void> },
+) => {
+  const rpc = await setupRpc(services, options);
+  return makeServicesFromRpc(rpc, Runtime.defaultRuntime);
+};
+
+//
+// Test Suites
+//
+
+describe('client services effect-rpc', () => {
+  test('unary call round trip preserves substituted types', async ({ expect }) => {
+    const spaceKey = PublicKey.random();
+    const proxy = await setup(() => ({
+      SpacesService: mockService<SpacesService.Handlers>({
+        ['SpacesService.createSpace']: () =>
+          Effect.succeed({
+            id: 'test-space',
+            spaceKey,
+            state: SpaceState.SPACE_READY,
+            membershipPolicy: MembershipPolicy.INVITE,
+            metrics: {},
+          }),
+      }),
+    }));
+
+    const space = await proxy.SpacesService!.createSpace({ membershipPolicy: MembershipPolicy.INVITE });
+    expect(space.id).toEqual('test-space');
+    expect(space.spaceKey).toBeInstanceOf(PublicKey);
+    expect(space.spaceKey.equals(spaceKey)).toBe(true);
+  });
+
+  test('streaming call round trip', async ({ expect }) => {
+    const proxy = await setup(() => ({
+      SystemService: mockService<SystemService.Handlers>({
+        ['SystemService.queryStatus']: (): Stream.Stream<QueryStatusResponse, Error> =>
+          Stream.fromIterable([{ status: SystemStatus.INACTIVE }, { status: SystemStatus.ACTIVE }]),
+      }),
+    }));
+
+    const statuses = await PbStream.consumeData(proxy.SystemService!.queryStatus({}));
+    expect(statuses.map((update) => update.status)).toEqual([SystemStatus.INACTIVE, SystemStatus.ACTIVE]);
+  });
+
+  test('stream errors propagate to the consumer', async ({ expect }) => {
+    const proxy = await setup(() => ({
+      SystemService: mockService<SystemService.Handlers>({
+        ['SystemService.queryStatus']: (): Stream.Stream<QueryStatusResponse, Error> =>
+          Stream.make({ status: SystemStatus.ACTIVE }).pipe(Stream.concat(Stream.fail(new Error('stream failed')))),
+      }),
+    }));
+
+    await expect(PbStream.consumeData(proxy.SystemService!.queryStatus({}))).rejects.toThrow('stream failed');
+  });
+
+  test('typed errors keep their identity across the wire', async ({ expect }) => {
+    const proxy = await setup(() => ({
+      SystemService: mockService<SystemService.Handlers>({
+        ['SystemService.getConfig']: () => Effect.fail(new IdentityNotInitializedError({ message: 'no identity' })),
+      }),
+    }));
+
+    const error = await proxy.SystemService!.getConfig().then(
+      () => undefined,
+      (err) => err,
+    );
+    expect(error).toBeInstanceOf(IdentityNotInitializedError);
+    expect(error.message).toContain('no identity');
+  });
+
+  test('calls fail when the service is not available', async ({ expect }) => {
+    const proxy = await setup(() => ({}));
+    await expect(proxy.SystemService!.getConfig()).rejects.toThrow(
+      'Service handler not available: SystemService.getConfig',
+    );
+  });
+
+  test('onRequest gates dispatch until ready', async ({ expect }) => {
+    const ready = new Trigger();
+    let called = false;
+    const proxy = await setup(
+      () => ({
+        SystemService: mockService<SystemService.Handlers>({
+          ['SystemService.getConfig']: () =>
+            Effect.sync(() => {
+              called = true;
+              return {};
+            }),
+        }),
+      }),
+      { onRequest: () => ready.wait() },
+    );
+
+    const request = proxy.SystemService!.getConfig();
+    await sleep(50);
+    expect(called).toBe(false);
+
+    ready.wake();
+    await request;
+    expect(called).toBe(true);
+  });
+
+  test('per-call timeout', async ({ expect }) => {
+    const proxy = await setup(() => ({
+      SystemService: mockService<SystemService.Handlers>({
+        ['SystemService.getConfig']: () => Effect.never,
+      }),
+    }));
+
+    await expect(proxy.SystemService!.getConfig(undefined, { timeout: 100 })).rejects.toThrow(TimeoutError);
+  });
+
+  test('effect-native rpc surface: unary and stream', async ({ expect }) => {
+    const rpc = await setupRpc(() => ({
+      SystemService: mockService<SystemService.Handlers>({
+        ['SystemService.getConfig']: () =>
+          Effect.succeed({ runtime: { client: { remoteSource: 'https://example.com' } } }),
+        ['SystemService.queryStatus']: (): Stream.Stream<QueryStatusResponse, Error> =>
+          Stream.make({ status: SystemStatus.ACTIVE }),
+      }),
+    }));
+
+    const config = await EffectEx.runPromise(rpc.SystemService.getConfig(undefined));
+    expect(config.runtime?.client?.remoteSource).toEqual('https://example.com');
+
+    const statuses = await EffectEx.runPromise(rpc.SystemService.queryStatus({}).pipe(Stream.runCollect));
+    expect([...statuses].map((update) => update.status)).toEqual([SystemStatus.ACTIVE]);
+  });
+});
+
+describe('effect-rpc tests', () => {
+  test(
+    '1. just regular test with a couple rpcs',
+    Effect.fnUntraced(function* () {
+      const { port1, port2 } = yield* makeMessageChannel();
+
+      const serverLayer = Layer.mergeAll(
+        handlers,
+        RpcServer.layerProtocolWorkerRunner.pipe(Layer.provide(BrowserWorkerRunner.layerMessagePort(port2))),
+      );
+
+      yield* RpcServer.make(TestGroup, { disableTracing: true }).pipe(Effect.provide(serverLayer), Effect.forkScoped);
+
+      const clientLayer = RpcClient.layerProtocolWorker({ size: 1 }).pipe(
+        Layer.provide(BrowserWorker.layerPlatform(() => port1)),
+      );
+
+      yield* Effect.gen(function* () {
+        const client = yield* RpcClient.make(TestGroup, { disableTracing: true });
+        const pongResult = yield* client.ping({ message: 'hello' });
+        expect(pongResult).toBe('pong: hello');
+
+        const userResult = yield* client.getUser({ id: '42' });
+        expect(userResult.id).toBe('42');
+        expect(userResult.name).toBe('User 42');
+      }).pipe(Effect.provide(clientLayer));
+    }),
+  );
+
+  test(
+    '3. two message channels to one server (simulating 2 tabs one worker)',
+    Effect.fnUntraced(function* () {
+      const channel1 = yield* makeMessageChannel();
+      const channel2 = yield* makeMessageChannel();
+
+      const serverLayer1 = Layer.mergeAll(
+        handlers,
+        Layer.fresh(RpcServer.layerProtocolWorkerRunner).pipe(
+          Layer.provide(BrowserWorkerRunner.layerMessagePort(channel1.port2)),
+        ),
+      );
+
+      const serverLayer2 = Layer.mergeAll(
+        handlers,
+        Layer.fresh(RpcServer.layerProtocolWorkerRunner).pipe(
+          Layer.provide(BrowserWorkerRunner.layerMessagePort(channel2.port2)),
+        ),
+      );
+
+      yield* RpcServer.make(TestGroup, { disableTracing: true }).pipe(Effect.provide(serverLayer1), Effect.forkScoped);
+
+      yield* RpcServer.make(TestGroup, { disableTracing: true }).pipe(Effect.provide(serverLayer2), Effect.forkScoped);
+
+      const clientLayer1 = RpcClient.layerProtocolWorker({ size: 1 }).pipe(
+        Layer.provide(BrowserWorker.layerPlatform(() => channel1.port1)),
+      );
+
+      yield* Effect.gen(function* () {
+        const client = yield* RpcClient.make(TestGroup, { disableTracing: true });
+        const result = yield* client.ping({ message: 'tab1' });
+        expect(result).toBe('pong: tab1');
+      }).pipe(Effect.provide(clientLayer1));
+
+      const clientLayer2 = RpcClient.layerProtocolWorker({ size: 1 }).pipe(
+        Layer.provide(BrowserWorker.layerPlatform(() => channel2.port1)),
+      );
+
+      yield* Effect.gen(function* () {
+        const client = yield* RpcClient.make(TestGroup, { disableTracing: true });
+        const result = yield* client.ping({ message: 'tab2' });
+        expect(result).toBe('pong: tab2');
+      }).pipe(Effect.provide(clientLayer2));
+    }),
+  );
+});