55 lines
2.2 KiB
Markdown
55 lines
2.2 KiB
Markdown
|
# @open-matrix/federation
|
||
|
|
|
||
|
|
Matrix federation layer for cross-realm messaging with:
|
||
|
|
|
||
|
|
- **Tolerant MXURI parsing** (legacy compact + segmented `/-/` form)
|
||
|
|
- **Dual mailbox namespaces** (Strangler Fig)
|
||
|
|
- legacy: `public.ingress.<realm>` (Matrix-3 compatibility)
|
||
|
|
- mx ingress: `mx/in/1/<realm>/<shard>` (MXINGRESS/1)
|
||
|
|
- **Dual envelope profiles** (Strategy)
|
||
|
|
- legacy: Matrix-3 request/reply envelopes
|
||
|
|
- mxenv1: MXENV/1 envelopes (`Cmd|Evt|Result|Sub|Unsub|Nack`)
|
||
|
|
- **Edge gateway** bridging mailbox messages ↔ internal bus (`mx/1/<realm>/<toPath>`)
|
||
|
|
- **Federation subscription leasing** (streaming Evt forwarding)
|
||
|
|
- **Session directory** (principal → active tab realms) for unsolicited push
|
||
|
|
- **Hierarchical routing overlay** (MXROUTE-style route inbox forwarding)
|
||
|
|
- **Pluggable transport** with in-memory brokers for deterministic tests
|
||
|
|
|
||
|
|
No external npm dependencies are required to run unit + integration tests.
|
||
|
|
|
||
|
|
## Run
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm test
|
||
|
|
```
|
||
|
|
|
||
|
|
## Read the full design
|
||
|
|
|
||
|
|
Start with `DESIGN.md`.
|
||
|
|
|
||
|
|
## Code map
|
||
|
|
|
||
|
|
- Encoding + routing primitives
|
||
|
|
- `src/uri.ts` — tolerant MXURI parsing + canonicalization
|
||
|
|
- `src/topics.ts` — mailbox topics + internal topics + route inbox topics
|
||
|
|
- `src/envelope.ts` + `src/envelope_codec.ts` — legacy + MXENV/1 envelopes, tolerant decoding, profile-specific encoding
|
||
|
|
|
||
|
|
- Transports
|
||
|
|
- `src/transport/base.ts` — transport port
|
||
|
|
- `src/transport/inmem.ts` — in-memory exact-match broker + wildcard-filter broker
|
||
|
|
|
||
|
|
- Runtime components
|
||
|
|
- `src/runtime/edge_gateway.ts` — mailbox ↔ internal bus bridge
|
||
|
|
- `src/runtime/component_host.ts` — helper for registering internal "accepts" handlers
|
||
|
|
- `src/runtime/federation.ts` — subscription leases + Evt forwarding
|
||
|
|
- `src/runtime/directory.ts` — session directory + protocol facade
|
||
|
|
- `src/runtime/router.ts` — hierarchical routing overlay bridge
|
||
|
|
- `src/runtime/discovery.ts` + `src/runtime/resolved_client.ts` — endpoint resolution + fallback client
|
||
|
|
|
||
|
|
- Security building blocks
|
||
|
|
- `src/security/*` — replay cache, rate limiter, policy hooks, principal derivation
|
||
|
|
|
||
|
|
- Tests
|
||
|
|
- `tests/unit/*` — codecs and matching
|
||
|
|
- `tests/integration/*` — end-to-end request/reply, subscriptions, directory push, discovery fallback, routing overlay, security
|