SuavePlan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
45cbcd515a390780b927cfd036384edc9541a2fb
skills/docs/networking/network/network-plugin-server-bridge/README.md
admin 949299f58d first commit
2026-05-29 08:20:56 +01:00

19 KiB
Raw Blame History

@suaveplan/network-plugin-server-bridge - Tier-0 host ↔ central-server bridge for the Suaveplan mesh: ServerGateway (transport-agnostic, 2× heartbeat disconnect detection), GracefulDegradationFsm (online → degrading → offline → recovering → online), OfflineModeCoordinator (autonomous mode + token-grace extension), LogBuffer (circular signed-log replay queue), ReconciliationProtocol (server-watermark-driven differential with LWW conflict resolution), CommandDispatcher (Ed25519 signature + nonce-replay protection), HeartbeatMultiplexer (Tier-0 batch forwarding), four hosting-model coordinators (PURE_CLIENT, SERVER_BASED, SERVER_TO_CLIENT_FAILOVER, CLIENT_WITH_SERVER_BACKUP), and ServerBridgePlugin facade with tier gate.

Summary

Tier-0 host ↔ central-server bridge for the Suaveplan mesh.

ServerBridgePlugin ties together every subsystem the bridge needs:

  • ServerGateway — transport-agnostic byte channel with a heartbeat loop and 2× heartbeat disconnect detection.
  • GracefulDegradationFsm — five-state FSM (online → degrading → offline → recovering → online) with strict transition validation.
  • OfflineModeCoordinator — switches mesh to autonomous mode on disconnect, extends token grace, blocks new sessions, emits server:offline / server:online.
  • LogBuffer — circular replay queue for signed activity logs with entryHash dedup, seq-ordered drain, partial-progress cursor.
  • ReconciliationProtocol — server-watermark-driven differential with last-writer-wins conflict resolution (host wins ties).
  • CommandDispatcher — Ed25519 signature validation (verifier injected), nonce + maxAge replay protection, dispatch to per-type handlers and command:<type> bus topics.
  • HeartbeatMultiplexer — Tier-0 batches per-peer heartbeats and forwards aggregated batches upstream so peers don't each open a server WebSocket.
  • Hosting models — four coordinators (PureClientCoordinator, ServerBasedCoordinator, FailoverCoordinator, BackupCoordinator) implementing PURE_CLIENT, SERVER_BASED, SERVER_TO_CLIENT_FAILOVER, CLIENT_WITH_SERVER_BACKUP per NET-56.

Documentation tree

- [log-buffer](./src/buffer/log-buffer.md) — _(no submodules)_- [command](./src/command/command-dispatcher.md) — _(no submodules)_- [command-dispatcher](./src/command/command-dispatcher.md) — _(no submodules)_- [fsm](./src/fsm/graceful-degradation-fsm.md) — _(no submodules)_- [graceful-degradation-fsm](./src/fsm/graceful-degradation-fsm.md) — _(no submodules)_- [gateway](./src/gateway/server-gateway.md) — _(no submodules)_- [server-gateway](./src/gateway/server-gateway.md) — _(no submodules)_- [backup-coordinator](./src/hosting/backup-coordinator.md) — `BackupCoordinator` implements the `CLIENT_WITH_SERVER_BACKUP` model: clients host normally and the server is a backup…

Install

bun add @suaveplan/network-plugin-server-bridge

Quick start

import { NetworkBus, NetworkNode } from "@suaveplan/network";
import {
    FailoverCoordinator,
    ServerBridgePlugin,
} from "@suaveplan/network-plugin-server-bridge";

const node = new NetworkNode({ id: "host-1", networkBus: new NetworkBus() });
const plugin = new ServerBridgePlugin({
    tierGate: () => topology.localTier() === 0,
    transportFactory: () => openWebSocket(serverUrl),
    heartbeatIntervalMs: 1_000,
    bufferCapacity: 10_000,
    tokenGraceMs: 30_000,
    extendedTokenGraceMs: 5 * 60_000,
    verifyCommand: (canon, sig) => ed25519Verify(sig, canon, serverPubKey),
    currentMeshEpoch: () => meshEpoch.current(),
    sessionAttributor: (entry) => extractSession(entry),
    hostingCoordinator: new FailoverCoordinator({
        serverAvailable: () => gateway.connectionState() === "open",
        mintToken: (req) => sign(req),
    }),
    heartbeatBatchWindowMs: 500,
    heartbeatSink: async (batch) => gateway.send(encode(batch)),
});

node.use(plugin);
await node.start();

Modules

Reference in New Issue View Git Blame Copy Permalink