72 lines
1.9 KiB
Markdown
72 lines
1.9 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```ts
|
||
|
|
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.
|