Node ↔ Gateway Communication

This document is the source contract for the hand-mirrored Go message types in the Erebrus node and gateway repositories. Changes must remain additive within protocol v2 so older nodes and gateways can ignore fields they do not know.

Every frame uses the envelope:

{"type":"hello","data":{}}

Node hello

The node sends hello whenever the WebSocket connects. Drop-capable nodes add an optional capabilities.drop object and a coarse services.drop state:

{
  "type": "hello",
  "data": {
    "node_id": "12D3...",
    "version": "2.0.0",
    "capabilities": {
      "access_mode": "public",
      "drop": {
        "enabled": true,
        "accepts_public_uploads": true,
        "webui_available": false
      }
    },
    "services": {
      "vpn": "active",
      "drop": "active"
    }
  }
}

capabilities.drop is omitted by nodes that do not implement Drop. File operations remain available through the authenticated Erebrus gateway.

Node heartbeat

Drop-capable nodes add an optional drop object to heartbeat. The Kubo version is also mirrored in versions.kubo, while services.drop preserves the existing coarse service model.

{
  "type": "heartbeat",
  "data": {
    "ts": 1765584000,
    "status": "online",
    "versions": {
      "node": "2.0.0",
      "kubo": "0.42.0"
    },
    "services": {
      "vpn": "active",
      "drop": "active"
    },
    "drop": {
      "state": "active",
      "kubo_version": "0.42.0",
      "repo_size_bytes": 1048576,
      "storage_max_bytes": 10000000000,
      "num_objects": 12
    }
  }
}

Drop service states are:

disabled | starting | active | degraded | full | unreachable

The gateway uses exact capacity for admission control. Public discovery must project only eligibility and a coarse available | low | full capacity state. Neither message may contain the Kubo RPC URL, credentials, private keys, or private organization data.