174 lines
3.8 KiB
Markdown
174 lines
3.8 KiB
Markdown
# Federation
|
||
|
||
> Status: Phase 3 — design draft, not yet implemented.
|
||
> This document describes the intended design. Details may change.
|
||
|
||
---
|
||
|
||
## Goal
|
||
|
||
Federation allows independent VNOX nodes to communicate with each other.
|
||
Users on one node can join channels, send messages, and voice-chat with
|
||
users on a different node — without either node being subordinate to the other.
|
||
|
||
There is no central federation server. Every node is equal.
|
||
|
||
---
|
||
|
||
## Identity in federation
|
||
|
||
Federated identity format:
|
||
|
||
```
|
||
user@node
|
||
```
|
||
|
||
Examples:
|
||
```
|
||
raven@nightcore.lnex
|
||
0xmist@dev.vnox.io
|
||
you@192.168.1.10
|
||
```
|
||
|
||
The `node` part is a resolvable address: domain, IP, or LNEx node ID.
|
||
The `user` part is the short form of the user's pubkey (or their chosen nickname,
|
||
disambiguated by pubkey if collision).
|
||
|
||
---
|
||
|
||
## What can be federated
|
||
|
||
| Feature | Status |
|
||
|---------|--------|
|
||
| Text chat bridging | Phase 3 |
|
||
| Voice relay across nodes | Phase 3 |
|
||
| Channel sharing | Phase 3 |
|
||
| Identity sync | Phase 3 |
|
||
| Permissions across nodes | Phase 4 |
|
||
| Encrypted federation | Phase 4 |
|
||
|
||
---
|
||
|
||
## Node discovery
|
||
|
||
Three strategies are planned. A node may use any combination.
|
||
|
||
### 1. Bootstrap list
|
||
|
||
A static list of known nodes in `config.toml`:
|
||
|
||
```toml
|
||
[federation]
|
||
bootstrap = [
|
||
"relay.nightcore.lnex",
|
||
"192.168.1.20:7700",
|
||
]
|
||
```
|
||
|
||
Simple and predictable. Suitable for private networks.
|
||
|
||
### 2. DNS SRV records
|
||
|
||
A node publishes its LNEx endpoint via DNS:
|
||
|
||
```
|
||
_lnex._udp.nightcore.lnex. SRV 0 0 7700 nightcore.lnex.
|
||
```
|
||
|
||
Allows discovery via domain name without hardcoded IPs.
|
||
|
||
### 3. DHT (future)
|
||
|
||
For fully decentralized discovery without any bootstrap list or DNS.
|
||
Not planned until Phase 4.
|
||
|
||
---
|
||
|
||
## Federation routing
|
||
|
||
When a client on node A wants to reach node B:
|
||
|
||
```
|
||
Client (node A)
|
||
│
|
||
▼
|
||
Gateway A ──── resolves node B address (DNS / bootstrap)
|
||
│
|
||
▼
|
||
LNEx Federation handshake (node A → node B)
|
||
│ mutual auth: exchange pubkeys
|
||
│ negotiate: shared channels, relay policy
|
||
▼
|
||
Established federation link
|
||
│
|
||
├── text: messages forwarded via TCP federation channel
|
||
└── voice: packets relayed via UDP federation relay path
|
||
```
|
||
|
||
### Federation link lifecycle
|
||
|
||
1. Node A initiates connection to node B
|
||
2. Both nodes authenticate using their node keypairs
|
||
3. Nodes exchange a list of channels available for bridging
|
||
4. A federation session is established with a session token
|
||
5. Session is kept alive with periodic PING/PONG
|
||
6. On disconnect, pending messages are queued for retry
|
||
|
||
---
|
||
|
||
## Voice relay across nodes
|
||
|
||
```
|
||
Client A (node A)
|
||
│ UDP
|
||
▼
|
||
Voice Node A
|
||
│ UDP (federation relay path)
|
||
▼
|
||
Voice Node B
|
||
│ UDP
|
||
▼
|
||
Client B (node B)
|
||
```
|
||
|
||
Voice packets are forwarded between voice nodes using the same
|
||
LNEx UDP packet format. The federation relay path adds one hop
|
||
and ~1–10ms additional latency depending on network distance.
|
||
|
||
---
|
||
|
||
## Channel bridging
|
||
|
||
A channel can be bridged between two nodes. Bridged channels appear
|
||
in both node's channel lists. Messages and voice from either side
|
||
flow through the federation link.
|
||
|
||
```toml
|
||
# On node A config
|
||
[federation.bridges]
|
||
"#general" = "nightcore.lnex/#general"
|
||
```
|
||
|
||
---
|
||
|
||
## Anti-spam and rate limiting
|
||
|
||
Federation links are subject to rate limiting to prevent a rogue node
|
||
from flooding a target node.
|
||
|
||
Limits (configurable):
|
||
- max federation connections per node: 16
|
||
- max bridged channels: 64
|
||
- message rate per federation link: 100/s
|
||
- voice packet rate per relayed user: standard voice rate
|
||
|
||
A node can block or denylist other nodes in `config.toml`.
|
||
|
||
---
|
||
|
||
## Open questions (TODO)
|
||
|
||
- How to handle split-brain: node B is temporarily unreachable during a conversation
|
||
- Message history sync across federated nodes
|
||
- Permission model for federated users (what can a `user@external-node` do on your node)
|
||
- Trust levels: `trusted` / `untrusted` / `blocked` per federation link
|