@dxos/messaging 0.10.0 → 0.11.0

package/src/signal-manager/memory-signal-manager.test.ts

@@ -0,0 +1,199 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, onTestFinished, test } from 'vitest';
+
+import { sleep } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { PublicKey } from '@dxos/keys';
+
+import { type Message, type PeerInfo } from '../signal-methods';
+import { MemorySignalManager, MemorySignalManagerContext } from './memory-signal-manager';
+
+// Exercises the subscription/routing behavior of the in-memory signal manager: point-to-point routing
+// by recipient, broadcast routing by tag intersection (DX-1125), fan-out, and unsubscribe lifecycle.
+
+const payload = (value: number[]) => ({ type_url: 'dxos.test.Message', value: new Uint8Array(value) });
+
+const randomPeer = (name: string): PeerInfo => ({
+  peerKey: PublicKey.random().toHex(),
+  identityDid: `did:test:${name}`,
+});
+
+/**
+ * A capture sink for a single subscription. Delivered messages are classified by shape: a
+ * point-to-point message carries a `recipient`; a broadcast carries `tags` and no `recipient`.
+ */
+const capture = () => {
+  const messages: Message[] = [];
+  const broadcasts: Message[] = [];
+  const onMessage = (message: Message) => {
+    if (message.recipient != null) {
+      messages.push(message);
+    } else {
+      broadcasts.push(message);
+    }
+  };
+  return { messages, broadcasts, onMessage };
+};
+
+const openManager = async (context: MemorySignalManagerContext): Promise<MemorySignalManager> => {
+  const manager = new MemorySignalManager(context);
+  await manager.open();
+  onTestFinished(() => manager.close());
+  return manager;
+};
+
+describe('MemorySignalManager', () => {
+  test('delivers a point-to-point message to the recipient subscription', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const receiver = await openManager(context);
+    const senderPeer = randomPeer('sender');
+    const receiverPeer = randomPeer('receiver');
+
+    const sink = capture();
+    await receiver.subscribeMessages({ peer: receiverPeer, onMessage: sink.onMessage });
+    await sender.sendMessage(Context.default(), {
+      author: senderPeer,
+      recipient: receiverPeer,
+      payload: payload([1, 2, 3]),
+    });
+
+    await expect.poll(() => sink.messages.length).toBe(1);
+    expect(sink.messages[0].author.peerKey).toBe(senderPeer.peerKey);
+    expect([...sink.messages[0].payload.value]).toEqual([1, 2, 3]);
+    expect(sink.broadcasts).toHaveLength(0);
+  });
+
+  test('routes point-to-point messages by recipient', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const receiverA = await openManager(context);
+    const receiverB = await openManager(context);
+    const peerA = randomPeer('a');
+    const peerB = randomPeer('b');
+
+    const sinkA = capture();
+    const sinkB = capture();
+    await receiverA.subscribeMessages({ peer: peerA, onMessage: sinkA.onMessage });
+    await receiverB.subscribeMessages({ peer: peerB, onMessage: sinkB.onMessage });
+
+    await sender.sendMessage(Context.default(), {
+      author: randomPeer('sender'),
+      recipient: peerB,
+      payload: payload([2]),
+    });
+
+    await expect.poll(() => sinkB.messages.length).toBe(1);
+    expect([...sinkB.messages[0].payload.value]).toEqual([2]);
+    // The message addressed to peerB is not delivered to peerA's subscription.
+    await sleep(20);
+    expect(sinkA.messages).toHaveLength(0);
+  });
+
+  test('fans a point-to-point message out to every subscription for the peer', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const receiver = await openManager(context);
+    const receiverPeer = randomPeer('receiver');
+
+    const first = capture();
+    const second = capture();
+    await receiver.subscribeMessages({ peer: receiverPeer, onMessage: first.onMessage });
+    await receiver.subscribeMessages({ peer: receiverPeer, onMessage: second.onMessage });
+    await sender.sendMessage(Context.default(), {
+      author: randomPeer('sender'),
+      recipient: receiverPeer,
+      payload: payload([7]),
+    });
+
+    await expect.poll(() => first.messages.length).toBe(1);
+    await expect.poll(() => second.messages.length).toBe(1);
+  });
+
+  test('stops delivery after unsubscribe', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const receiver = await openManager(context);
+    const senderPeer = randomPeer('sender');
+    const receiverPeer = randomPeer('receiver');
+
+    const sink = capture();
+    const unsubscribe = await receiver.subscribeMessages({ peer: receiverPeer, onMessage: sink.onMessage });
+    await sender.sendMessage(Context.default(), { author: senderPeer, recipient: receiverPeer, payload: payload([1]) });
+    await expect.poll(() => sink.messages.length).toBe(1);
+
+    await unsubscribe();
+    await sender.sendMessage(Context.default(), { author: senderPeer, recipient: receiverPeer, payload: payload([2]) });
+    await sleep(20);
+    expect(sink.messages).toHaveLength(1);
+  });
+
+  test('keeps delivering to remaining subscriptions after one unsubscribes', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const receiver = await openManager(context);
+    const receiverPeer = randomPeer('receiver');
+
+    const first = capture();
+    const second = capture();
+    const unsubscribeFirst = await receiver.subscribeMessages({ peer: receiverPeer, onMessage: first.onMessage });
+    await receiver.subscribeMessages({ peer: receiverPeer, onMessage: second.onMessage });
+
+    // Releasing one subscription keeps the shared-context connection alive for the other.
+    await unsubscribeFirst();
+    await sender.sendMessage(Context.default(), {
+      author: randomPeer('sender'),
+      recipient: receiverPeer,
+      payload: payload([5]),
+    });
+
+    await expect.poll(() => second.messages.length).toBe(1);
+    expect(first.messages).toHaveLength(0);
+  });
+
+  test('delivers a broadcast only to subscriptions whose tags intersect', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const receiver = await openManager(context);
+
+    const matching = capture();
+    const nonMatching = capture();
+    await receiver.subscribeMessages({ peer: randomPeer('a'), tags: ['type:a'], onMessage: matching.onMessage });
+    await receiver.subscribeMessages({ peer: randomPeer('b'), tags: ['type:b'], onMessage: nonMatching.onMessage });
+
+    await sender.sendMessage(Context.default(), {
+      author: randomPeer('sender'),
+      tags: ['type:a'],
+      payload: payload([4, 2]),
+    });
+
+    await expect.poll(() => matching.broadcasts.length).toBe(1);
+    expect(matching.broadcasts[0].tags).toContain('type:a');
+    expect([...matching.broadcasts[0].payload.value]).toEqual([4, 2]);
+    // Broadcasts are not point-to-point, and the non-intersecting subscription gets nothing.
+    expect(matching.messages).toHaveLength(0);
+    await sleep(20);
+    expect(nonMatching.broadcasts).toHaveLength(0);
+  });
+
+  test('rejects a message that sets neither or both of recipient and tags', async () => {
+    const context = new MemorySignalManagerContext();
+    const sender = await openManager(context);
+    const author = randomPeer('sender');
+
+    // Neither recipient nor tags.
+    await expect(sender.sendMessage(Context.default(), { author, payload: payload([1]) })).rejects.toThrow();
+    // Both recipient and tags.
+    await expect(
+      sender.sendMessage(Context.default(), {
+        author,
+        recipient: randomPeer('receiver'),
+        tags: ['type:a'],
+        payload: payload([1]),
+      }),
+    ).rejects.toThrow();
+  });
+});

package/src/signal-manager/memory-signal-manager.ts

@@ -13,9 +13,27 @@ import { type SwarmResponse } from '@dxos/protocols/proto/dxos/edge/messenger';
 import { type QueryRequest } from '@dxos/protocols/proto/dxos/edge/signal';
 import { ComplexMap, ComplexSet } from '@dxos/util';
 
-import { type Message, type PeerInfo, PeerInfoHash, type SignalStatus, type SwarmEvent } from '../signal-methods';
+import {
+  type Message,
+  type PeerInfo,
+  PeerInfoHash,
+  type SignalStatus,
+  type SubscribeMessagesParams,
+  type SwarmEvent,
+  type UnsubscribeCallback,
+} from '../signal-methods';
 import { type SignalManager } from './signal-manager';
 
+/**
+ * A single message subscription registered on a {@link MemorySignalManager} (DX-1125). Point-to-point
+ * delivery matches `peerKey`; broadcast delivery matches any intersection with `tags`.
+ */
+type MessageSubscription = {
+  peerKey: string;
+  tags: Set<string>;
+  onMessage: (message: Message) => void;
+};
+
 /**
  * Common signaling context that connects multiple MemorySignalManager instances.
  */
@@ -37,7 +55,11 @@ export class MemorySignalManager implements SignalManager {
   readonly statusChanged = new Event<SignalStatus[]>();
   readonly swarmEvent = new Event<SwarmEvent>();
 
-  readonly onMessage = new Event<Message>();
+  /**
+   * Active message subscriptions on this manager. Routing is encapsulated here (DX-1125): a delivered
+   * message is dispatched to every subscription it matches.
+   */
+  private readonly _subscriptions = new Set<MessageSubscription>();
 
   /**  Will be used to emit SwarmEvents on .open() and .close() */
   private _joinedSwarms = new ComplexSet<{ topic: PublicKey; peer: PeerInfo }>(
@@ -144,70 +166,88 @@ export class MemorySignalManager implements SignalManager {
     throw new Error('Not implemented');
   }
 
-  async sendMessage(
-    _ctx: Context,
-    {
-      author,
-      recipient,
-      payload,
-    }: {
-      author: PeerInfo;
-      recipient: PeerInfo;
-      payload: Any;
-    },
-  ): Promise<void> {
-    log('send message', { author, recipient, ...dec(payload) });
-
-    invariant(recipient);
+  async sendMessage(_ctx: Context, message: Message): Promise<void> {
     invariant(!this._ctx.disposed, 'Closed');
+    const { author, recipient, tags, payload } = message;
+    // Exactly one of point-to-point (`recipient`) or broadcast (`tags`) delivery (DX-1125).
+    invariant((recipient == null) !== !tags?.length, 'Exactly one of `recipient` or `tags` must be set');
 
     await this._freezeTrigger.wait();
 
-    const remote = this._context.connections.get(recipient);
-    if (!remote) {
-      log.warn('recipient is not subscribed for messages', { author, recipient });
-      return;
+    if (recipient != null) {
+      log('send message', { author, recipient, ...dec(payload) });
+      const remote = this._context.connections.get(recipient);
+      if (!remote) {
+        log.warn('recipient is not subscribed for messages', { author, recipient });
+        return;
+      }
+      remote._deliver(message);
+    } else {
+      // Broadcast: fan out to every subscriber in the shared context whose tags intersect.
+      log('broadcast message', { author, tags, ...dec(payload) });
+      for (const manager of new Set(this._context.connections.values())) {
+        manager._deliver(message);
+      }
     }
+  }
 
-    if (remote._ctx.disposed) {
-      log.warn('recipient is disposed', { author, recipient });
+  async subscribeMessages({ peer, tags = [], onMessage }: SubscribeMessagesParams): Promise<UnsubscribeCallback> {
+    invariant(!this._ctx.disposed, 'Closed');
+    log('subscribing', { peer, tags });
+    const subscription: MessageSubscription = { peerKey: peer.peerKey, tags: new Set(tags), onMessage };
+    this._subscriptions.add(subscription);
+    this._context.connections.set(peer, this);
+
+    return async () => {
+      log('unsubscribing', { peer, tags });
+      this._subscriptions.delete(subscription);
+      // Drop the shared-context connection entry only once no subscription for this peer remains.
+      if (![...this._subscriptions].some((sub) => sub.peerKey === peer.peerKey)) {
+        this._context.connections.delete(peer);
+      }
+    };
+  }
+
+  freeze(): void {
+    this._freezeTrigger.reset();
+  }
+
+  unfreeze(): void {
+    this._freezeTrigger.wake();
+  }
+
+  /**
+   * Route a delivered message to this manager's matching subscriptions once it is unfrozen and open.
+   */
+  private _deliver(message: Message): void {
+    if (this._ctx.disposed) {
+      log.warn('recipient is disposed', { message });
       return;
     }
 
-    remote._freezeTrigger
+    this._freezeTrigger
       .wait()
       .then(() => {
-        if (remote._ctx.disposed) {
-          log.warn('recipient is disposed', { author, recipient });
+        if (this._ctx.disposed) {
+          log.warn('recipient is disposed', { message });
           return;
         }
 
-        log('receive message', { author, recipient, ...dec(payload) });
-
-        remote.onMessage.emit({ author, recipient, payload });
+        log('receive message', { author: message.author, recipient: message.recipient, ...dec(message.payload) });
+        for (const subscription of this._subscriptions) {
+          if (message.recipient != null) {
+            if (subscription.peerKey === message.recipient.peerKey) {
+              subscription.onMessage(message);
+            }
+          } else if (message.tags?.some((tag) => subscription.tags.has(tag))) {
+            subscription.onMessage(message);
+          }
+        }
       })
       .catch((err) => {
         log.error('error while waiting for freeze', { err });
       });
   }
-
-  async subscribeMessages(peerInfo: PeerInfo): Promise<void> {
-    log('subscribing', { peerInfo });
-    this._context.connections.set(peerInfo, this);
-  }
-
-  async unsubscribeMessages(peerInfo: PeerInfo): Promise<void> {
-    log('unsubscribing', { peerInfo });
-    this._context.connections.delete(peerInfo);
-  }
-
-  freeze(): void {
-    this._freezeTrigger.reset();
-  }
-
-  unfreeze(): void {
-    this._freezeTrigger.wake();
-  }
 }
 const dec = (payload: Any) => {
   if (!payload.type_url.endsWith('ReliablePayload')) {

package/src/signal-manager/signal-manager.ts

@@ -2,6 +2,8 @@
 // Copyright 2020 DXOS.org
 //
 
+import * as Context from 'effect/Context';
+
 import { type Event } from '@dxos/async';
 import { type Lifecycle } from '@dxos/context';
 
@@ -14,3 +16,8 @@ export interface SignalManager extends SignalMethods, Required<Lifecycle> {
   statusChanged?: Event<SignalStatus[]>;
   getStatus?: () => SignalStatus[];
 }
+
+export class SignalManagerService extends Context.Tag('@dxos/messaging/SignalManager')<
+  SignalManagerService,
+  SignalManager
+>() {}

package/src/signal-manager/utils.ts

@@ -2,41 +2,50 @@
 // Copyright 2024 DXOS.org
 //
 
+import * as Runtime from 'effect/Runtime';
+
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
-import { type DevicesService, type IdentityService } from '@dxos/protocols/proto/dxos/client/services';
+import { subscribeStream } from '@dxos/protocols';
 import { DeviceKind } from '@dxos/protocols/proto/dxos/client/services';
+import { type DevicesService, type IdentityService } from '@dxos/protocols/rpc';
 
 export const setIdentityTags = ({
   identityService,
   devicesService,
+  runtime = Runtime.defaultRuntime,
   setTag,
 }: {
-  identityService: IdentityService;
-  devicesService: DevicesService;
+  identityService: IdentityService.Client;
+  devicesService: DevicesService.Client;
+  runtime?: Runtime.Runtime<never>;
   setTag: (k: string, v: string) => void;
 }) => {
-  identityService.queryIdentity().subscribe((idqr) => {
-    if (!idqr?.identity?.identityKey) {
-      log('empty response from identity service', { idqr });
-      return;
-    }
+  subscribeStream(runtime, identityService.IdentityService.queryIdentity(undefined), {
+    onData: (idqr) => {
+      if (!idqr?.identity?.identityKey) {
+        log('empty response from identity service', { idqr });
+        return;
+      }
 
-    setTag('identityKey', idqr.identity.identityKey.truncate());
+      setTag('identityKey', idqr.identity.identityKey.truncate());
+    },
   });
 
-  devicesService.queryDevices().subscribe((dqr) => {
-    if (!dqr || !dqr.devices || dqr.devices.length === 0) {
-      log('empty response from device service', { device: dqr });
-      return;
-    }
-    invariant(dqr, 'empty response from device service');
+  subscribeStream(runtime, devicesService.DevicesService.queryDevices(undefined), {
+    onData: (dqr) => {
+      if (!dqr || !dqr.devices || dqr.devices.length === 0) {
+        log('empty response from device service', { device: dqr });
+        return;
+      }
+      invariant(dqr, 'empty response from device service');
 
-    const thisDevice = dqr.devices.find((device) => device.kind === DeviceKind.CURRENT);
-    if (!thisDevice) {
-      log('no current device', { device: dqr });
-      return;
-    }
-    setTag('deviceKey', thisDevice.deviceKey.truncate());
+      const thisDevice = dqr.devices.find((device) => device.kind === DeviceKind.CURRENT);
+      if (!thisDevice) {
+        log('no current device', { device: dqr });
+        return;
+      }
+      setTag('deviceKey', thisDevice.deviceKey.truncate());
+    },
   });
 };

package/src/signal-methods.ts

@@ -3,7 +3,7 @@
 //
 
 import { type Event } from '@dxos/async';
-import { type Context, type Lifecycle } from '@dxos/context';
+import { type Context } from '@dxos/context';
 import { type Peer, type SwarmResponse } from '@dxos/protocols/proto/dxos/edge/messenger';
 import {
   type JoinRequest,
@@ -27,6 +27,33 @@ export type SignalStatus = {
   lastStateChange: Date;
 };
 
+/**
+ * Parameters for {@link SignalMethods.subscribeMessages}.
+ */
+export type SubscribeMessagesParams = {
+  /**
+   * The subscribing peer. Point-to-point messages addressed to this `peerKey` are delivered.
+   */
+  peer: PeerInfo;
+
+  /**
+   * OR-subscription tags (DX-1125). When provided, swarm broadcasts whose tags intersect this set are
+   * also delivered. Only meaningful for edge signaling; other transports ignore them.
+   */
+  tags?: string[];
+
+  /**
+   * Invoked for every message delivered to this subscription (point-to-point or matching broadcast).
+   */
+  onMessage: (message: Message) => void;
+};
+
+/**
+ * Tears down a subscription created by {@link SignalMethods.subscribeMessages} and releases its
+ * transport resources (edge tag registration / receive stream). The subscriber owns this lifecycle.
+ */
+export type UnsubscribeCallback = () => Promise<void>;
+
 /**
  * Message routing interface.
  */
@@ -38,11 +65,6 @@ export interface SignalMethods {
    */
   swarmEvent: Event<SwarmEvent>;
 
-  /**
-   * Emits when a message is received.
-   */
-  onMessage: Event<Message>;
-
   /**
    * Emits when the swarm state changes.
    */
@@ -64,29 +86,18 @@ export interface SignalMethods {
   query: (ctx: Context, params: QueryRequest) => Promise<SwarmResponse>;
 
   /**
-   * Send message to peer.
+   * Send a message. Point-to-point when `recipient` is set; a swarm broadcast (DX-1125) when `tags`
+   * are set — fanned out to every peer whose tag subscription intersects, with the target swarm taken
+   * from `author.swarmKey`. Exactly one of `recipient` / `tags` must be present. Broadcasts are only
+   * supported by edge signaling.
    */
   sendMessage: (ctx: Context, message: Message) => Promise<void>;
 
   /**
-   * Start receiving messages from peer.
-   * @deprecated
+   * Start receiving messages for `peer`: its point-to-point messages, plus — when `tags` are provided
+   * (DX-1125) — swarm broadcasts whose tags intersect. Matching messages are routed to
+   * `params.onMessage`; routing and the transport stream are owned here. Returns a callback that tears
+   * the subscription down; the subscriber owns that lifecycle.
    */
-  // TODO(burdon): Return unsubscribe function. Encapsulate callback/routing here.
-  subscribeMessages: (peer: PeerInfo) => Promise<void>;
-
-  /**
-   * Stop receiving messages from peer.
-   * @deprecated
-   */
-  unsubscribeMessages: (peer: PeerInfo) => Promise<void>;
-}
-
-/**
- * Signaling client.
- * TODO(mykola): Delete.
- * @deprecated
- */
-export interface SignalClientMethods extends SignalMethods, Required<Lifecycle> {
-  getStatus(): SignalStatus;
+  subscribeMessages: (params: SubscribeMessagesParams) => Promise<UnsubscribeCallback>;
 }

package/src/testing/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './test-builder';
+export * from './test-edge-mesh';
 export * from './test-peer';
 export * from './test-messages';
 export * from './utils';