hivecast-sdk/packages/federation/docs/integrating_into_matrix3.md

Integrating this POC into Matrix-3 (TS)

This POC is structured as an Anti-Corruption Layer around the existing Matrix-3 federation implementation.

1) Tolerant URI parsing (WireCodec.parseSemanticTopic)

You can port src/uri.ts::parseMatrixUri() into your existing WireCodec.parseSemanticTopic() implementation.

Key properties:

• Accept both:
  • legacy compact: matrix://realm/mount/component.path.accepts.msg
  • segmented: matrix://realm/mount/-/component/path/accepts/msg
• Canonical output should be (realm?, mountSegments[], componentPath, plane, messageName, toPath) where:

toPath = <mount...>/<componentPath>.<plane>.<messageName>

Tab realms:

matrix://home/~tab/<tabId>/...   => realm = `${home}.tab.${tabId}`

This does not require changing existing URIs; it simply extends the grammar.

2) Wire profile as a Strategy

Introduce a WireProfile (Strategy pattern) controlling:

• which ingress namespaces to subscribe to (Strangler Fig)
• which encoding to use for outbound envelopes

From this POC:

• matrix3: legacy mailbox topics + legacy JSON envelopes
• mxenv1: MXINGRESS/1 mailbox topics + MXENV/1 envelopes

3) Dual-subscription (Strangler Fig)

Servers should subscribe to both:

• public.ingress.<realm>
• mx/in/1/<realm>/00

Then decode both envelope formats with a tolerant reader.

This permits incremental migration without a flag day.

4) Reply encoding rule

This POC replies "same-as-incoming":

• request arrives as legacy => reply legacy
• request arrives as mxenv1 => reply mxenv1

If you want a stricter policy ("always reply mxenv1"), you need discovery (MXDISC/1) to avoid breaking clients.

5) Transport port

The POC defines a tiny transport port:

interface Transport {
  publish(topic: string, payload: string): void;
  subscribe(topic: string, handler: (topic: string, payload: string) => void): () => void;
}

You can adapt your existing NatsTransport to this in ~20 LOC.