swactor/crates/node/README.md

# node

The `node` crate produces the `swactor` binary — the batteries-included entry point for running a swactor node. It composes the actor runtime, SWIM-based cluster membership, content-addressed datastore, data streams, an HTTP dashboard, and an optional embedded relay server into a single process.

Run `swactor --help` for full CLI usage.

## What a Default Node Does

### Identity

Every node has a persistent Ed25519 keypair stored at `~/.swactor/identity/node.key.json`. This is the node's identity across restarts — deleting it makes the node appear as a new peer to the cluster. The keypair's public key doubles as the node ID (used in SWIM, peer auth, and invite codes). A deterministic human-readable name (e.g. `swift-falcon`) is derived from the key so you can tell nodes apart in logs and the dashboard.

### Networking

The default transport is **iroh** (QUIC over UDP). Nodes find each other via invite codes — base58-encoded public keys exchanged out-of-band. `swactor join <code>` adds a peer to the allow-list and sets it as the seed node for the next startup.

Once connected, **SWIM protocol** handles cluster membership: protocol probes every 500ms, 600ms probe timeout (tuned for relay round-trips), 2 indirect probes, 4s suspicion window. All intervals are in ticks where **1 tick = 100ms** (the main loop period).

**Peer auth** operates in two modes: open (no `peers_file`) or allow-list (`peers.json`). In allow-list mode, SWIM messages from unknown nodes are dropped at the transport layer. New peers can be added via `swactor join` or the dashboard UI, both of which hot-update the allow-list.

> **Note (deferred, not urgent): gossip opens a fresh QUIC stream per message.**
> The iroh driver reuses the per-peer *connection* but opens and finishes a new
> uni-stream for every gossip/SWIM message (`iroh_driver.rs` `send_wire` →
> `open_uni`/`finish` per send; reader does `accept_uni` + `read_to_end` per
> message). The stream-per-message shape exists only because the wire frame has
> no payload-length field and relies on stream-EOF to delimit. No per-message RTT
> is paid (uni-streams are unilateral), but each send costs a tokio task spawn, a
> fresh read-side allocation, and a slot against `max_concurrent_uni_streams`.
>
> Two cheaper shapes, when it's worth doing:
> - **QUIC datagrams** for the small probe traffic (Ping/Ack/PingReq). One
>   datagram = one self-delimiting message, no stream state at all, and
>   best-effort delivery *matches* SWIM's own loss-tolerance instead of fighting
>   it with redundant QUIC retransmits. Capped at ~path-MTU, so it doesn't cover
>   large gossip (e.g. a `JoinResponse` with a big member list).
> - **One persistent length-prefixed stream per connection** for the larger /
>   must-arrive messages — the same persistent-stream discipline used for blob
>   edges.
>
> Low priority; tracked here so it isn't lost.

### Relay

Nodes with a public IP auto-promote to embedded relay servers (port 3340). Candidacy is evaluated at startup: the node checks its outbound IP is non-RFC1918 and the relay port is bindable. Relay URLs are announced via SWIM gossip so other nodes discover them automatically. Nodes behind NAT use relays for indirect connectivity — this is why the probe timeout is 600ms instead of the typical 300ms.

### Storage

The **datastore** is a content-addressed, chunked store. Default config persists to `~/.swactor/datastore/`. Auth is enabled by default (ACL files in `~/.swactor/auth/`). The datastore runs as a group of actors inside the runtime and is driven by the main tick loop — GC runs every 1000 ticks (~100s) and dissemination every 50 ticks (~5s). A `StreamManager` actor bridges iroh QUIC streams into the datastore for bulk data transfer between nodes.

Disable with `--no-datastore`. Use `--storage-path` to change location, or omit it from config for in-memory only.

### Observability

An HTTP dashboard serves on **port 9090**. It exposes runtime stats, cluster membership state, tracing output, and a peer management UI (add/remove peers). The dashboard receives a snapshot of the distribution layer every tick.

### State & Lifecycle

All persistent state lives under `~/.swactor/`. Deleting this directory fully resets the node (new identity, empty cluster, empty datastore). The node shuts down cleanly on SIGINT (Ctrl+C). `swactor install` copies the binary to `~/.swactor/bin/swactor` and registers it as a system service (systemd user unit, OpenRC/sysvinit init script, or `@reboot` crontab depending on the host).

## Exposed Ports

| Port | Service | Configurable via |
|------|---------|-----------------|
| 9090 | HTTP dashboard | `--dashboard-port` |
| 3340 | Embedded relay (if eligible) | `--relay-port` |

## Data Directory (`~/.swactor/`)

```
~/.swactor/
├── node.toml          # Node configuration
├── peers.json         # Peer allow-list
├── identity/
│   └── node.key.json  # Persistent Ed25519 keypair
├── datastore/         # Content-addressed chunk storage
├── auth/              # ACL and owner key files
└── bin/
    └── swactor        # Installed binary (after `swactor install`)
```

## Architecture

```
CLI Args + TOML Config
        │
        ▼
  Config Resolution (CLI > config > defaults)
        │
        ▼
  Identity (Ed25519 Keypair) ──► Node Name
        │
        ▼
  ┌─────────────────────────────────────────────┐
  │              Actor Runtime                   │
  │  (2 threads, StdExtension, stats hook)       │
  │                                              │
  │  ┌──────────────┐  ┌──────────────────────┐  │
  │  │ StreamManager │  │   Datastore Group    │  │
  │  │   (actor)     │◄─┤ (store, gateway,     │  │
  │  │               │  │  bridge actors)      │  │
  │  └──────────────┘  └──────────────────────┘  │
  └──────────────┬──────────────────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────┐
  │   Distribution Driver (iroh)     │
  │  SWIM probes, gossip, relay      │
  └──────────────┬───────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────┐
  │         HTTP Dashboard           │
  │  :9090 — stats, tracing, peers   │
  └──────────────────────────────────┘
                 │
                 ▼
         Main Tick Loop (100ms)
    recv → tick → streams → joins →
    heartbeats → snapshot → datastore
```