@rljson/network 0.0.1

package/dist/peer-table.d.ts

@@ -0,0 +1,79 @@
+import { NodeId, NodeInfo } from './types/node-info.ts';
+import { DiscoveryLayer } from './layers/discovery-layer.ts';
+/** Events emitted by PeerTable */
+export interface PeerTableEvents {
+    'peer-joined': (peer: NodeInfo) => void;
+    'peer-left': (nodeId: string) => void;
+}
+type PeerTableEventName = keyof PeerTableEvents;
+/**
+ * Merged view of all peers from all discovery layers.
+ *
+ * Deduplicates by nodeId — a peer known by multiple layers appears once.
+ * Emits `peer-joined`/`peer-left` when the merged set changes.
+ */
+export declare class PeerTable {
+    /** All known peers, keyed by nodeId */
+    private _peers;
+    /** Per-layer peer sets, for deduplication tracking */
+    private _layerPeers;
+    /** Event listeners */
+    private _listeners;
+    /** Self nodeId — excluded from the peer table */
+    private _selfId;
+    /**
+     * Set the self nodeId so it's excluded from the peer table.
+     * @param nodeId - This node's own ID
+     */
+    setSelfId(nodeId: NodeId): void;
+    /**
+     * Attach a discovery layer — subscribes to its peer events.
+     * Also imports any peers the layer already knows about.
+     * @param layer - The discovery layer to attach
+     */
+    attachLayer(layer: DiscoveryLayer): void;
+    /** Get all known peers as an array */
+    getPeers(): NodeInfo[];
+    /**
+     * Get a specific peer by nodeId.
+     * @param nodeId - The peer's nodeId
+     */
+    getPeer(nodeId: NodeId): NodeInfo | undefined;
+    /** Get the number of known peers */
+    get size(): number;
+    /** Clear all peers and layer tracking */
+    clear(): void;
+    /**
+     * Subscribe to peer table events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends PeerTableEventName>(event: E, cb: PeerTableEvents[E]): void;
+    /**
+     * Unsubscribe from peer table events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends PeerTableEventName>(event: E, cb: PeerTableEvents[E]): void;
+    /**
+     * Add a peer from a specific layer.
+     * Only emits peer-joined if this is a genuinely new peer.
+     * @param layerName - Name of the source layer
+     * @param peer - The peer to add
+     */
+    private _addPeerFromLayer;
+    /**
+     * Remove a peer from a specific layer.
+     * Only emits peer-left if no other layer still knows about this peer.
+     * @param layerName - Name of the source layer
+     * @param nodeId - The peer's nodeId
+     */
+    private _removePeerFromLayer;
+    /**
+     * Emit a typed event.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}
+export {};

package/dist/probing/peer-prober.d.ts

@@ -0,0 +1,21 @@
+import { PeerProbe } from '../types/peer-probe.ts';
+import { NodeId } from '../types/node-info.ts';
+/** Options for a single probe */
+export interface ProbeOptions {
+    /** TCP connect timeout in ms (default: 2000) */
+    timeoutMs?: number;
+}
+/**
+ * Probes a peer's reachability via real TCP connect.
+ *
+ * Opens a TCP socket to host:port, measures the time until the
+ * connection is established (or fails), then closes the socket.
+ * This is the same technique used by `tcping` and similar tools.
+ * @param host - The peer's IP address or hostname
+ * @param port - The peer's port
+ * @param fromNodeId - This node's ID (for the probe result)
+ * @param toNodeId - The peer's node ID (for the probe result)
+ * @param options - Probe options (timeout, etc.)
+ * @returns A PeerProbe with reachability and latency
+ */
+export declare function probePeer(host: string, port: number, fromNodeId: NodeId, toNodeId: NodeId, options?: ProbeOptions): Promise<PeerProbe>;

package/dist/probing/probe-scheduler.d.ts

@@ -0,0 +1,119 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { PeerProbe } from '../types/peer-probe.ts';
+import { ProbeOptions } from './peer-prober.ts';
+/** Function signature for probing a single peer */
+export type ProbeFn = (host: string, port: number, fromNodeId: NodeId, toNodeId: NodeId, options?: ProbeOptions) => Promise<PeerProbe>;
+/** Events emitted by ProbeScheduler */
+export interface ProbeSchedulerEvents {
+    /** Emitted after a full probe cycle completes */
+    'probes-updated': (probes: PeerProbe[]) => void;
+    /** Emitted when a peer becomes unreachable */
+    'peer-unreachable': (nodeId: NodeId, probe: PeerProbe) => void;
+    /** Emitted when a peer becomes reachable (again) */
+    'peer-reachable': (nodeId: NodeId, probe: PeerProbe) => void;
+}
+/** Valid event names for ProbeScheduler */
+export type ProbeSchedulerEventName = keyof ProbeSchedulerEvents;
+/** Options for ProbeScheduler constructor */
+export interface ProbeSchedulerOptions {
+    /** Interval between probe cycles in ms (default: 10000) */
+    intervalMs?: number;
+    /** Timeout per individual probe in ms (default: 2000) */
+    timeoutMs?: number;
+    /** Custom probe function — real TCP by default */
+    probeFn?: ProbeFn;
+    /**
+     * Number of consecutive probe failures before declaring a peer
+     * unreachable (default: 3). Prevents flapping on transient failures.
+     * A single success resets the counter immediately.
+     */
+    failThreshold?: number;
+}
+/**
+ * Periodically probes all known peers for reachability.
+ *
+ * Uses real TCP connect probes by default, but accepts an injectable
+ * probe function for unit testing.
+ *
+ * Emits events when probe results change (peer went down / came back up).
+ */
+export declare class ProbeScheduler {
+    private _intervalMs;
+    private _timeoutMs;
+    private _failThreshold;
+    private _selfId;
+    private _running;
+    private _timer;
+    /** Latest probe results, keyed by toNodeId */
+    private _probes;
+    /** Previous reachability state, for change detection */
+    private _wasReachable;
+    /** Consecutive failure count per peer, for flap dampening */
+    private _failCount;
+    /** Event listeners */
+    private _listeners;
+    /** The probe function — real TCP by default, injectable for tests */
+    private readonly _probeFn;
+    /** Peers to probe — updated externally via setPeers() */
+    private _peers;
+    /**
+     * Create a ProbeScheduler.
+     * @param options - Configuration options
+     */
+    constructor(options?: ProbeSchedulerOptions);
+    /**
+     * Start the scheduler.
+     * @param selfId - This node's ID (excluded from probing)
+     */
+    start(selfId: NodeId): void;
+    /**
+     * Schedule the next probe cycle using setTimeout.
+     * Chaining (instead of setInterval) prevents overlapping cycles.
+     */
+    private _scheduleNext;
+    /** Stop the scheduler and clear state */
+    stop(): void;
+    /** Whether the scheduler is currently running */
+    isRunning(): boolean;
+    /**
+     * Update the list of peers to probe.
+     * Call this when the peer table changes.
+     * Self is automatically excluded at probe time.
+     * @param peers - The current peer list
+     */
+    setPeers(peers: NodeInfo[]): void;
+    /** Get all latest probe results */
+    getProbes(): PeerProbe[];
+    /**
+     * Get the latest probe result for a specific peer.
+     * @param nodeId - The peer's nodeId
+     */
+    getProbe(nodeId: NodeId): PeerProbe | undefined;
+    /**
+     * Run a single probe cycle manually.
+     * Useful for tests that need immediate results without waiting.
+     */
+    runOnce(): Promise<PeerProbe[]>;
+    /**
+     * Subscribe to scheduler events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends ProbeSchedulerEventName>(event: E, cb: ProbeSchedulerEvents[E]): void;
+    /**
+     * Unsubscribe from scheduler events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends ProbeSchedulerEventName>(event: E, cb: ProbeSchedulerEvents[E]): void;
+    /**
+     * Run one probe cycle: probe all peers in parallel.
+     */
+    private _runCycle;
+    /**
+     * Emit a typed event.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}

package/dist/src/example.ts

@@ -0,0 +1,105 @@
+// @license
+// Copyright (c) 2025 Rljson
+//
+// Use of this source code is governed by terms that can be
+// found in the LICENSE file in the root of this package.
+
+import { exampleNodeInfo } from './types/node-info.ts';
+import type { NodeInfo } from './types/node-info.ts';
+import { examplePeerProbe } from './types/peer-probe.ts';
+import { exampleNetworkTopology } from './types/network-topology.ts';
+import { defaultNetworkConfig } from './types/network-config.ts';
+import { NetworkManager } from './network-manager.ts';
+import { electHub } from './election/hub-election.ts';
+
+export const example = async () => {
+  const l = console.log;
+  const h1 = (text: string) => l(`${text}`);
+  const h2 = (text: string) => l(`  ${text}`);
+  const p = (text: string) => l(`    ${text}`);
+
+  h1('NodeInfo');
+  h2('Describes a node in the network');
+  p(JSON.stringify(exampleNodeInfo, null, 2));
+
+  h1('PeerProbe');
+  h2('Result of probing a peer');
+  p(JSON.stringify(examplePeerProbe, null, 2));
+
+  h1('NetworkTopology');
+  h2('Snapshot of the current network topology');
+  p(JSON.stringify(exampleNetworkTopology, null, 2));
+
+  h1('NetworkConfig');
+  h2('Default configuration with broadcast enabled');
+  p(JSON.stringify(defaultNetworkConfig('office-sync', 3000), null, 2));
+
+  h1('HubElection');
+  h2('Deterministic hub election from candidates + probes');
+  const candidates: NodeInfo[] = [
+    {
+      nodeId: 'node-a',
+      hostname: 'ws-a',
+      localIps: ['10.0.0.1'],
+      domain: 'test',
+      port: 3000,
+      startedAt: 1000,
+    },
+    {
+      nodeId: 'node-b',
+      hostname: 'ws-b',
+      localIps: ['10.0.0.2'],
+      domain: 'test',
+      port: 3000,
+      startedAt: 900,
+    },
+    {
+      nodeId: 'node-c',
+      hostname: 'ws-c',
+      localIps: ['10.0.0.3'],
+      domain: 'test',
+      port: 3000,
+      startedAt: 1100,
+    },
+  ];
+  const probes = [
+    { ...examplePeerProbe, toNodeId: 'node-a', reachable: true },
+    { ...examplePeerProbe, toNodeId: 'node-b', reachable: true },
+    { ...examplePeerProbe, toNodeId: 'node-c', reachable: false },
+  ];
+  const result = electHub(candidates, probes, null, 'node-a');
+  p(`Winner: ${result.hubId}, reason: ${result.reason}`);
+  p('(node-b wins: earliest startedAt among reachable peers)');
+
+  h1('NetworkManager');
+  h2('Start with static hub → manual override → revert');
+
+  const config = {
+    ...defaultNetworkConfig('office-sync', 3000),
+    static: { hubAddress: '192.168.1.100:3000' },
+  };
+  const manager = new NetworkManager(config);
+
+  manager.on('role-changed', (e) => {
+    p(`Role changed: ${e.previous} → ${e.current}`);
+  });
+
+  await manager.start();
+  p(
+    `Topology: role=${manager.getTopology().myRole}, formedBy=${manager.getTopology().formedBy}`,
+  );
+
+  manager.assignHub('custom-hub');
+  p(`After manual override: formedBy=${manager.getTopology().formedBy}`);
+
+  manager.clearOverride();
+  p(`After clearing override: formedBy=${manager.getTopology().formedBy}`);
+
+  await manager.stop();
+  p('Manager stopped');
+};
+
+/*
+// Run via "npx vite-node src/example.ts"
+example();
+*/

package/dist/types/network-config.d.ts

@@ -0,0 +1,63 @@
+/** Configuration for the UDP broadcast discovery layer (Try 1) */
+export interface BroadcastConfig {
+    /** Whether broadcast discovery is enabled (default: true) */
+    enabled: boolean;
+    /** UDP port for announcements (default: 41234) */
+    port: number;
+    /** How often to announce in ms (default: 5000) */
+    intervalMs?: number;
+    /** Remove peer after N ms silence (default: 15000) */
+    timeoutMs?: number;
+}
+/** Configuration for the cloud discovery layer (Try 2) */
+export interface CloudConfig {
+    /** Whether cloud discovery is enabled (default: false) */
+    enabled: boolean;
+    /** Cloud service URL */
+    endpoint: string;
+    /** Authentication key */
+    apiKey?: string;
+    /** How often to poll in ms (default: 30000) */
+    pollIntervalMs?: number;
+    /** Maximum backoff interval when cloud is unreachable in ms (default: 300000 = 5 min) */
+    maxBackoffMs?: number;
+    /** Attempt re-registration after this many consecutive poll failures (default: 10) */
+    reRegisterAfterFailures?: number;
+}
+/** Configuration for the static discovery layer (Try 3) */
+export interface StaticConfig {
+    /** Hardcoded hub address — "ip:port" */
+    hubAddress?: string;
+}
+/** Configuration for peer probing */
+export interface ProbingConfig {
+    /** Whether probing is enabled (default: true) */
+    enabled: boolean;
+    /** How often to probe all peers in ms (default: 10000) */
+    intervalMs?: number;
+    /** Probe timeout in ms (default: 2000) */
+    timeoutMs?: number;
+}
+/** Full network configuration */
+export interface NetworkConfig {
+    /** Network domain — which group of nodes discover each other */
+    domain: string;
+    /** Port this node listens on when hub */
+    port: number;
+    /** Where to persist nodeId (default: ~/.rljson-network/) */
+    identityDir?: string;
+    /** Try 1: Broadcast — primary automatic discovery */
+    broadcast?: BroadcastConfig;
+    /** Try 2: Cloud — first fallback (optional, must be explicitly configured) */
+    cloud?: CloudConfig;
+    /** Try 3: Static — last resort fallback (optional) */
+    static?: StaticConfig;
+    /** Peer probing configuration */
+    probing?: ProbingConfig;
+}
+/**
+ * Create a default NetworkConfig with broadcast enabled.
+ * @param domain - Network domain name
+ * @param port - Port this node listens on
+ */
+export declare function defaultNetworkConfig(domain: string, port: number): NetworkConfig;

package/dist/types/network-events.d.ts

@@ -0,0 +1,33 @@
+import { NodeInfo } from './node-info.ts';
+import { NetworkTopology, NodeRole } from './network-topology.ts';
+/** Emitted when the network topology changes */
+export interface TopologyChangedEvent {
+    topology: NetworkTopology;
+}
+/** Emitted when this node's role changes */
+export interface RoleChangedEvent {
+    previous: NodeRole;
+    current: NodeRole;
+}
+/** Emitted when the hub node changes */
+export interface HubChangedEvent {
+    previousHub: string | null;
+    currentHub: string | null;
+}
+/** Map of all events emitted by NetworkManager */
+export interface NetworkEventMap {
+    'topology-changed': TopologyChangedEvent;
+    'role-changed': RoleChangedEvent;
+    'hub-changed': HubChangedEvent;
+    'peer-joined': NodeInfo;
+    'peer-left': string;
+}
+/** All valid network event names */
+export declare const networkEventNames: readonly ["topology-changed", "role-changed", "hub-changed", "peer-joined", "peer-left"];
+export type NetworkEventName = (typeof networkEventNames)[number];
+/** Example TopologyChangedEvent for tests and documentation */
+export declare const exampleTopologyChangedEvent: TopologyChangedEvent;
+/** Example RoleChangedEvent for tests and documentation */
+export declare const exampleRoleChangedEvent: RoleChangedEvent;
+/** Example HubChangedEvent for tests and documentation */
+export declare const exampleHubChangedEvent: HubChangedEvent;

package/dist/types/network-topology.d.ts

@@ -0,0 +1,29 @@
+import { NodeInfo } from './node-info.ts';
+import { PeerProbe } from './peer-probe.ts';
+/** Possible roles a node can have in the network */
+export declare const nodeRoles: readonly ["hub", "client", "unassigned"];
+export type NodeRole = (typeof nodeRoles)[number];
+/** Which discovery layer formed the current topology */
+export declare const formedByValues: readonly ["broadcast", "cloud", "election", "manual", "static"];
+export type FormedBy = (typeof formedByValues)[number];
+/** Snapshot of the current network topology */
+export interface NetworkTopology {
+    /** Network domain */
+    domain: string;
+    /** NodeId of the current hub, or null if unassigned */
+    hubNodeId: string | null;
+    /** "ip:port" of the hub, ready to pass to Socket.IO */
+    hubAddress: string | null;
+    /** Which discovery layer produced this topology */
+    formedBy: FormedBy;
+    /** Timestamp when this topology was formed */
+    formedAt: number;
+    /** All known nodes, keyed by nodeId */
+    nodes: Record<string, NodeInfo>;
+    /** Latest probe results */
+    probes: PeerProbe[];
+    /** This node's role in the topology */
+    myRole: NodeRole;
+}
+/** Example NetworkTopology for tests and documentation */
+export declare const exampleNetworkTopology: NetworkTopology;

package/dist/types/node-info.d.ts

@@ -0,0 +1,19 @@
+/** Unique identifier for a node in the network */
+export type NodeId = string;
+/** Information about a node in the network */
+export interface NodeInfo {
+    /** Persistent UUID, generated once, stored on disk */
+    nodeId: NodeId;
+    /** Machine name (os.hostname()) */
+    hostname: string;
+    /** All non-internal IPv4 addresses */
+    localIps: string[];
+    /** Network domain — which group of nodes discover each other */
+    domain: string;
+    /** Port this node listens on when hub */
+    port: number;
+    /** Timestamp of node start */
+    startedAt: number;
+}
+/** Example NodeInfo for tests and documentation */
+export declare const exampleNodeInfo: NodeInfo;

package/dist/types/peer-probe.d.ts

@@ -0,0 +1,15 @@
+/** Result of probing a peer's reachability */
+export interface PeerProbe {
+    /** Node that initiated the probe */
+    fromNodeId: string;
+    /** Node that was probed */
+    toNodeId: string;
+    /** Whether the peer was reachable */
+    reachable: boolean;
+    /** TCP round-trip in ms, -1 if unreachable */
+    latencyMs: number;
+    /** Timestamp of measurement */
+    measuredAt: number;
+}
+/** Example PeerProbe for tests and documentation */
+export declare const examplePeerProbe: PeerProbe;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@rljson/network",
+  "version": "0.0.1",
+  "description": "Networking middle layer providing basic advertising and discovery as well as cloud fall backs and basic config.",
+  "homepage": "https://github.com/rljson/network",
+  "bugs": "https://github.com/rljson/network/issues",
+  "private": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rljson/network.git"
+  },
+  "main": "dist/network.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
+    "@vitest/coverage-v8": "^4.0.6",
+    "cross-env": "^10.1.0",
+    "eslint": "~9.39.1",
+    "eslint-plugin-jsdoc": "^61.1.12",
+    "eslint-plugin-tsdoc": "^0.4.0",
+    "globals": "^16.5.0",
+    "jsdoc": "^4.0.5",
+    "read-pkg": "^9.0.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.3",
+    "vite": "^7.1.12",
+    "vite-node": "^3.2.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^4.0.6",
+    "vitest-dom": "^0.1.1"
+  },
+  "dependencies": {},
+  "scripts": {
+    "build": "pnpm exec vite build && tsc && node scripts/copy-readme-to-dist.js",
+    "test": "pnpm exec vitest run --coverage && pnpm run lint",
+    "prebuild": "npm run test",
+    "lint": "pnpm exec eslint",
+    "updateGoldens": "cross-env UPDATE_GOLDENS=true pnpm test"
+  }
+}