1a0419dc0c
Full SDK workspace: core, contracts, sdk, cli, browser-host, browser-kit, federation, omega-core, oracle, self-healing, strategies, tools, emacs. Clean extraction from the development monorepo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
623 lines
20 KiB
TypeScript
623 lines
20 KiB
TypeScript
/**
|
||
* 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();
|
||
});
|
||
});
|
||
});
|