add docs, protocol, plugins, README, CHANGELOG
This commit is contained in:
parent
1d2209bfac
commit
f262da222b
GPG key ID:
253067914055423B
44 changed files with 9269 additions and 0 deletions
174
docs/02-protocol/federation/README.md
Normal file
174
docs/02-protocol/federation/README.md
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue