hivecast-sdk/packages/federation/tests/integration/component-topology-scenarios.spec.ts

/**
 * Matrix Component Topology Scenarios
 *
 * Tests ALL possible locations where Matrix components can be relative to each other:
 *
 * TOPOLOGY 1: Same Realm, Same Process
 *   - Component A and B in same daemon
 *   - Communication via local message bus
 *
 * TOPOLOGY 2: Same Realm, Different Process (Browser ↔ Daemon)
 *   - Browser component talks to daemon component
 *   - Both in same realm, communication via local broker
 *
 * TOPOLOGY 3: Cross-Realm (Daemon A ↔ Daemon B)
 *   - Daemon in realm-alpha talks to daemon in realm-beta
 *   - Communication via backbone (NATS leaf nodes)
 *
 * TOPOLOGY 4: Cross-Realm Browser to Remote Daemon
 *   - Browser in realm-alpha talks to daemon in realm-beta
 *   - Browser → local daemon (gateway) → backbone → remote daemon
 *
 * TOPOLOGY 5: Supervision Across Realms
 *   - Parent in realm-alpha supervises child in realm-beta
 *   - $join/$join_ack flow across federation
 */

import { describe, it } from 'node:test';
import { strict as assert } from 'node:assert';
import {
  FederationPeer, ExactInstanceResolver,
  WIRE_PROFILES,
  InMemoryFilterBroker,
  getLegacyIngressTopic,
  createLegacyRequest,
  serializeLegacyEnvelope,
} from '@open-matrix/federation';

describe('Matrix Component Topology Scenarios', () => {

  // ===========================================================================
  // TOPOLOGY 1: Same Realm, Same Process
  // ===========================================================================

  describe('Topology 1: Same Realm, Same Process', () => {

    it('component A calls component B within same daemon (local bus only)', async () => {
      const REALM = 'local-realm';

      // Simulates the local bus inside a single daemon
      const localBus = new InMemoryFilterBroker();

      // Component B: Calculator service
      localBus.subscribe(`calculator.accepts.multiply`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { a: number; b: number };
        };
        const result = req.params.a * req.params.b;
        localBus.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
          result: { product: result },
        }));
      });

      // Component A: Calls calculator
      let reply: unknown = null;
      const correlationId = 'local-call-123';
      const replyTopic = `_client.emits.reply-${correlationId}`;

      localBus.subscribe(replyTopic, (topic, payload) => {
        reply = JSON.parse(payload);
      });

      await new Promise(r => setTimeout(r, 50));

      // Component A sends request to Component B
      localBus.publish(`calculator.accepts.multiply`, JSON.stringify({
        correlationId,
        replyTo: replyTopic,
        params: { a: 7, b: 6 },
      }));

      await new Promise(r => setTimeout(r, 100));

      assert.ok(reply, 'Component A should receive reply from Component B');
      assert.deepStrictEqual(
        (reply as { result: { product: number } }).result,
        { product: 42 }
      );

      console.log('✓ Topology 1: Same realm/process - 7 × 6 = 42');
    });
  });

  // ===========================================================================
  // TOPOLOGY 2: Same Realm, Different Process (Browser ↔ Daemon)
  // ===========================================================================

  describe('Topology 2: Same Realm, Browser ↔ Daemon', () => {

    it('browser component calls daemon component via local broker', async () => {
      const REALM = 'my-app-realm';

      // Local broker shared between browser and daemon
      const localBroker = new InMemoryFilterBroker();

      // Daemon component: FileService
      localBroker.subscribe(`daemon.file.accepts.list`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { path: string };
        };
        // Simulated file listing
        localBroker.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
          result: {
            files: ['README.md', 'package.json', 'src/'],
            path: req.params.path,
          },
        }));
      });

      // Browser component: File Explorer
      let browserReceivedReply: unknown = null;
      const correlationId = 'browser-call-456';
      const replyTopic = `_browser.explorer.emits.reply-${correlationId}`;

      localBroker.subscribe(replyTopic, (topic, payload) => {
        browserReceivedReply = JSON.parse(payload);
      });

      await new Promise(r => setTimeout(r, 50));

      // Browser sends request to daemon
      localBroker.publish(`daemon.file.accepts.list`, JSON.stringify({
        correlationId,
        replyTo: replyTopic,
        params: { path: '/' },
      }));

      await new Promise(r => setTimeout(r, 100));

      assert.ok(browserReceivedReply, 'Browser should receive reply from daemon');
      assert.deepStrictEqual(
        (browserReceivedReply as { result: { files: string[] } }).result.files,
        ['README.md', 'package.json', 'src/']
      );

      console.log('✓ Topology 2: Browser ↔ Daemon (same realm) - file listing');
    });
  });

  // ===========================================================================
  // TOPOLOGY 3: Cross-Realm Daemon to Daemon
  // ===========================================================================

  describe('Topology 3: Cross-Realm Daemon ↔ Daemon', () => {

    it('daemon in realm-alpha queries daemon in realm-beta', async () => {
      const REALM_ALPHA = 'company-a.matrix';
      const REALM_BETA = 'company-b.matrix';

      // Backbone (simulates HiveMQ)
      const backbone = new InMemoryFilterBroker();

      // Local buses for each daemon
      const localBusAlpha = new InMemoryFilterBroker();
      const localBusBeta = new InMemoryFilterBroker();

      // EdgeGateway for each realm
      const gatewayAlpha = new FederationPeer({
        localRealm: REALM_ALPHA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusAlpha,
        internalTimeoutMs: 5000,
      });

      const gatewayBeta = new FederationPeer({
        localRealm: REALM_BETA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusBeta,
        internalTimeoutMs: 5000,
      });

      gatewayAlpha.start();
      gatewayBeta.start();

      // Daemon Beta: User Directory Service
      localBusBeta.subscribe(`directory.user.accepts.lookup`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { userId: string };
        };
        // Simulated user lookup
        localBusBeta.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
          result: {
            userId: req.params.userId,
            name: 'Alice Smith',
            email: 'alice@company-b.com',
            realm: REALM_BETA,
          },
        }));
      });

      // Daemon Alpha: Receives reply
      let crossRealmReply: unknown = null;
      backbone.subscribe(getLegacyIngressTopic(REALM_ALPHA), (topic, payload) => {
        const parsed = JSON.parse(payload);
        if (parsed.ok !== undefined) {
          crossRealmReply = parsed;
        }
      });

      await new Promise(r => setTimeout(r, 100));

      // Daemon Alpha requests user from Daemon Beta
      const request = createLegacyRequest({
        toRealm: REALM_BETA,
        toPath: 'directory.user.accepts.lookup',
        fromRealm: REALM_ALPHA,
        replyTo: '_daemon.client',
        correlationId: 'cross-daemon-789',
        body: { userId: 'user-123' },
      });

      backbone.publish(getLegacyIngressTopic(REALM_BETA), serializeLegacyEnvelope(request));

      await new Promise(r => setTimeout(r, 500));

      assert.ok(crossRealmReply, 'Alpha should receive reply from Beta');
      assert.strictEqual(
        (crossRealmReply as { body: { name: string } }).body.name,
        'Alice Smith'
      );

      console.log('✓ Topology 3: Daemon(Alpha) → Daemon(Beta) - user lookup');

      gatewayAlpha.stop();
      gatewayBeta.stop();
    });
  });

  // ===========================================================================
  // TOPOLOGY 4: Cross-Realm Browser to Remote Daemon
  // ===========================================================================

  describe('Topology 4: Cross-Realm Browser → Remote Daemon', () => {

    it('browser in realm-alpha calls service in realm-beta via federation', async () => {
      const REALM_ALPHA = 'browser-user-realm';
      const REALM_BETA = 'backend-service-realm';

      // Infrastructure
      const backbone = new InMemoryFilterBroker();
      const localBusAlpha = new InMemoryFilterBroker();
      const localBusBeta = new InMemoryFilterBroker();

      // Both realms have EdgeGateways
      const gatewayAlpha = new FederationPeer({
        localRealm: REALM_ALPHA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusAlpha,
        internalTimeoutMs: 5000,
      });

      const gatewayBeta = new FederationPeer({
        localRealm: REALM_BETA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusBeta,
        internalTimeoutMs: 5000,
      });

      gatewayAlpha.start();
      gatewayBeta.start();

      // Remote daemon (realm-beta): Weather service
      localBusBeta.subscribe(`weather.service.accepts.forecast`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { city: string };
        };
        localBusBeta.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
          result: {
            city: req.params.city,
            forecast: 'Sunny',
            temperature: 72,
            unit: 'F',
          },
        }));
      });

      // Browser (realm-alpha): Weather widget
      // In real scenario, browser talks to local daemon which forwards via EdgeGateway
      // Here we simulate the full flow

      let browserReply: unknown = null;
      backbone.subscribe(getLegacyIngressTopic(REALM_ALPHA), (topic, payload) => {
        const parsed = JSON.parse(payload);
        if (parsed.ok !== undefined) {
          browserReply = parsed;
        }
      });

      await new Promise(r => setTimeout(r, 100));

      // Browser's request routed through local EdgeGateway to remote realm
      const request = createLegacyRequest({
        toRealm: REALM_BETA,
        toPath: 'weather.service.accepts.forecast',
        fromRealm: REALM_ALPHA,
        replyTo: '_browser.widget.reply',
        correlationId: 'browser-to-remote-001',
        body: { city: 'Seattle' },
      });

      backbone.publish(getLegacyIngressTopic(REALM_BETA), serializeLegacyEnvelope(request));

      await new Promise(r => setTimeout(r, 500));

      assert.ok(browserReply, 'Browser should receive cross-realm reply');
      assert.strictEqual(
        (browserReply as { body: { forecast: string } }).body.forecast,
        'Sunny'
      );

      console.log('✓ Topology 4: Browser(Alpha) → Remote Daemon(Beta) - weather forecast');

      gatewayAlpha.stop();
      gatewayBeta.stop();
    });
  });

  // ===========================================================================
  // TOPOLOGY 5: Supervision Across Realms
  // ===========================================================================

  describe('Topology 5: Cross-Realm Supervision', () => {

    it('parent in realm-alpha supervises child in realm-beta ($join flow)', async () => {
      const REALM_ALPHA = 'supervisor-realm';
      const REALM_BETA = 'worker-realm';

      const backbone = new InMemoryFilterBroker();
      const localBusAlpha = new InMemoryFilterBroker();
      const localBusBeta = new InMemoryFilterBroker();

      const gatewayAlpha = new FederationPeer({
        localRealm: REALM_ALPHA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusAlpha,
        internalTimeoutMs: 5000,
      });

      const gatewayBeta = new FederationPeer({
        localRealm: REALM_BETA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusBeta,
        internalTimeoutMs: 5000,
      });

      gatewayAlpha.start();
      gatewayBeta.start();

      // Parent component in Alpha: handles $join requests
      let joinRequestReceived = false;
      localBusAlpha.subscribe(`parent.supervisor.accepts.$join`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { childId: string; childRealm: string };
        };
        joinRequestReceived = true;

        // Acknowledge the join
        localBusAlpha.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
          result: {
            status: 'joined',
            supervisorId: 'parent.supervisor',
            childId: req.params.childId,
          },
        }));
      });

      // Child sends $join from realm-beta to parent in realm-alpha
      let joinAckReceived: unknown = null;
      backbone.subscribe(getLegacyIngressTopic(REALM_BETA), (topic, payload) => {
        const parsed = JSON.parse(payload);
        if (parsed.ok !== undefined) {
          joinAckReceived = parsed;
        }
      });

      await new Promise(r => setTimeout(r, 100));

      // Child component in Beta sends $join to parent in Alpha
      const joinRequest = createLegacyRequest({
        toRealm: REALM_ALPHA,
        toPath: 'parent.supervisor.accepts.$join',
        fromRealm: REALM_BETA,
        replyTo: '_child.worker.reply',
        correlationId: 'join-request-001',
        body: {
          childId: 'child.worker',
          childRealm: REALM_BETA,
          componentClass: 'WorkerComponent',
        },
      });

      backbone.publish(getLegacyIngressTopic(REALM_ALPHA), serializeLegacyEnvelope(joinRequest));

      await new Promise(r => setTimeout(r, 500));

      assert.ok(joinRequestReceived, 'Parent should receive $join request');
      assert.ok(joinAckReceived, 'Child should receive $join_ack');
      assert.strictEqual(
        (joinAckReceived as { body: { status: string } }).body.status,
        'joined'
      );

      console.log('✓ Topology 5: Cross-realm supervision - $join flow');

      gatewayAlpha.stop();
      gatewayBeta.stop();
    });

    it('parent receives $exit notification from remote child', async () => {
      const REALM_ALPHA = 'supervisor-realm-2';
      const REALM_BETA = 'worker-realm-2';

      const backbone = new InMemoryFilterBroker();
      const localBusAlpha = new InMemoryFilterBroker();
      const localBusBeta = new InMemoryFilterBroker();

      const gatewayAlpha = new FederationPeer({
        localRealm: REALM_ALPHA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusAlpha,
        internalTimeoutMs: 5000,
      });

      const gatewayBeta = new FederationPeer({
        localRealm: REALM_BETA,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusBeta,
        internalTimeoutMs: 5000,
      });

      gatewayAlpha.start();
      gatewayBeta.start();

      // Parent subscribes to $exit events from child
      let exitEventReceived = false;
      let exitReason: string | undefined;

      localBusAlpha.subscribe(`parent.supervisor.accepts.$exit`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { childId: string; reason: string };
        };
        exitEventReceived = true;
        exitReason = req.params.reason;

        // Acknowledge receipt
        localBusAlpha.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
        }));
      });

      await new Promise(r => setTimeout(r, 100));

      // Child in Beta sends $exit to parent in Alpha
      const exitNotification = createLegacyRequest({
        toRealm: REALM_ALPHA,
        toPath: 'parent.supervisor.accepts.$exit',
        fromRealm: REALM_BETA,
        replyTo: '_child.worker.reply',
        correlationId: 'exit-notify-001',
        body: {
          childId: 'child.worker',
          reason: 'completed',
          result: { itemsProcessed: 100 },
        },
      });

      backbone.publish(getLegacyIngressTopic(REALM_ALPHA), serializeLegacyEnvelope(exitNotification));

      await new Promise(r => setTimeout(r, 500));

      assert.ok(exitEventReceived, 'Parent should receive $exit notification');
      assert.strictEqual(exitReason, 'completed');

      console.log('✓ Topology 5: Cross-realm supervision - $exit notification');

      gatewayAlpha.stop();
      gatewayBeta.stop();
    });
  });

  // ===========================================================================
  // BONUS: Complete Flow - Browser → Local Daemon → Remote Daemon → Response
  // ===========================================================================

  describe('Complete Flow: Full Stack Federation', () => {

    it('browser request travels through full federation stack', async () => {
      const BROWSER_REALM = 'end-user-app';
      const LOCAL_DAEMON_REALM = 'local-proxy';
      const REMOTE_SERVICE_REALM = 'cloud-api';

      const backbone = new InMemoryFilterBroker();
      const localBusBrowser = new InMemoryFilterBroker();  // Browser's local connection
      const localBusLocalDaemon = new InMemoryFilterBroker();
      const localBusRemote = new InMemoryFilterBroker();

      // Gateway for each realm
      const gatewayBrowser = new FederationPeer({
        localRealm: BROWSER_REALM,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusBrowser,
        internalTimeoutMs: 5000,
      });

      const gatewayLocalDaemon = new FederationPeer({
        localRealm: LOCAL_DAEMON_REALM,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusLocalDaemon,
        internalTimeoutMs: 5000,
      });

      const gatewayRemote = new FederationPeer({
        localRealm: REMOTE_SERVICE_REALM,
        profile: WIRE_PROFILES.matrix3,
        backbone,
        localBus: localBusRemote,
        internalTimeoutMs: 5000,
      });

      gatewayBrowser.start();
      gatewayLocalDaemon.start();
      gatewayRemote.start();

      // Remote cloud service: AI processing
      localBusRemote.subscribe(`ai.service.accepts.analyze`, (topic, payload) => {
        const req = JSON.parse(payload) as {
          replyTo: string;
          correlationId: string;
          params: { text: string };
        };
        localBusRemote.publish(req.replyTo, JSON.stringify({
          ok: true,
          correlationId: req.correlationId,
          result: {
            sentiment: 'positive',
            confidence: 0.92,
            processedBy: REMOTE_SERVICE_REALM,
          },
        }));
      });

      // Track the response
      let finalResponse: unknown = null;
      backbone.subscribe(getLegacyIngressTopic(BROWSER_REALM), (topic, payload) => {
        const parsed = JSON.parse(payload);
        if (parsed.ok !== undefined) {
          finalResponse = parsed;
        }
      });

      await new Promise(r => setTimeout(r, 100));

      // Browser initiates request to remote AI service
      const request = createLegacyRequest({
        toRealm: REMOTE_SERVICE_REALM,
        toPath: 'ai.service.accepts.analyze',
        fromRealm: BROWSER_REALM,
        replyTo: '_browser.app.reply',
        correlationId: 'full-stack-001',
        body: { text: 'Matrix federation is working great!' },
      });

      backbone.publish(getLegacyIngressTopic(REMOTE_SERVICE_REALM), serializeLegacyEnvelope(request));

      await new Promise(r => setTimeout(r, 500));

      assert.ok(finalResponse, 'Browser should receive response from remote cloud service');
      assert.strictEqual(
        (finalResponse as { body: { sentiment: string } }).body.sentiment,
        'positive'
      );

      console.log('✓ Complete Flow: Browser → Local → Remote → Response (sentiment: positive)');

      gatewayBrowser.stop();
      gatewayLocalDaemon.stop();
      gatewayRemote.stop();
    });
  });
});