@rljson/network 0.0.1

package/dist/layers/cloud-layer.d.ts

@@ -0,0 +1,156 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { CloudConfig } from '../types/network-config.ts';
+import { NodeIdentity } from '../identity/node-identity.ts';
+import { PeerProbe } from '../types/peer-probe.ts';
+import { DiscoveryLayer, DiscoveryLayerEventName, DiscoveryLayerEvents } from './discovery-layer.ts';
+/** Response from cloud registration / polling */
+export interface CloudPeerListResponse {
+    /** Peers known to the cloud for this domain */
+    peers: NodeInfo[];
+    /** Hub assigned by the cloud (null if not yet decided) */
+    assignedHub: NodeId | null;
+}
+/** Abstraction over HTTP fetch for testability */
+export interface CloudHttpClient {
+    /**
+     * Register this node with the cloud service.
+     * @param endpoint - Cloud service base URL
+     * @param info - This node's info
+     * @param apiKey - Optional API key
+     * @returns The peer list response from the cloud
+     */
+    register(endpoint: string, info: NodeInfo, apiKey?: string): Promise<CloudPeerListResponse>;
+    /**
+     * Poll the cloud for the latest peer list and hub assignment.
+     * @param endpoint - Cloud service base URL
+     * @param nodeId - This node's ID
+     * @param domain - This node's domain
+     * @param apiKey - Optional API key
+     * @returns The peer list response from the cloud
+     */
+    poll(endpoint: string, nodeId: NodeId, domain: string, apiKey?: string): Promise<CloudPeerListResponse>;
+    /**
+     * Report probe results to the cloud.
+     * @param endpoint - Cloud service base URL
+     * @param nodeId - This node's ID
+     * @param probes - Probe results to report
+     * @param apiKey - Optional API key
+     */
+    reportProbes(endpoint: string, nodeId: NodeId, probes: PeerProbe[], apiKey?: string): Promise<void>;
+}
+/** Factory type for creating a CloudHttpClient */
+export type CreateCloudHttpClient = () => CloudHttpClient;
+/**
+ * Create a real HTTP client using globalThis.fetch.
+ * @returns A CloudHttpClient backed by the Fetch API
+ */
+export declare function defaultCreateCloudHttpClient(): CloudHttpClient;
+/** Injectable dependencies for CloudLayer (testing) */
+export interface CloudLayerDeps {
+    /** Custom HTTP client factory — defaults to real fetch */
+    createHttpClient?: CreateCloudHttpClient;
+}
+/**
+ * Cloud discovery layer — cross-network fallback (Try 2).
+ *
+ * Registers with a cloud service, periodically polls for peer list and
+ * hub assignment, and reports local probe results. The cloud has the full
+ * picture across all nodes and **dictates** the hub (unlike broadcast,
+ * which uses local election).
+ *
+ * On startup, registers with the cloud endpoint. If registration fails
+ * (endpoint unreachable, auth error), start() returns false and the
+ * NetworkManager falls through to the Static layer (Try 3).
+ */
+export declare class CloudLayer implements DiscoveryLayer {
+    private readonly _config?;
+    readonly name = "cloud";
+    private _active;
+    private _identity;
+    private _pollTimer;
+    private _peers;
+    private _assignedHub;
+    private _listeners;
+    private readonly _httpClient;
+    private _consecutivePollFailures;
+    private _basePollIntervalMs;
+    private _currentPollIntervalMs;
+    private _maxBackoffMs;
+    private _reRegisterThreshold;
+    /**
+     * Create a CloudLayer.
+     * @param _config - Cloud configuration (endpoint, apiKey, pollInterval)
+     * @param deps - Injectable dependencies for testing
+     */
+    constructor(_config?: CloudConfig | undefined, deps?: CloudLayerDeps);
+    /**
+     * Start the cloud layer.
+     *
+     * 1. Check if cloud is enabled and endpoint configured
+     * 2. Register this node with the cloud
+     * 3. Process initial peer list and hub assignment
+     * 4. Start periodic polling
+     * @param identity - This node's identity
+     * @returns true if cloud is available, false otherwise
+     */
+    start(identity: NodeIdentity): Promise<boolean>;
+    /** Stop the layer and clean up resources */
+    stop(): Promise<void>;
+    /** Whether this layer is currently active */
+    isActive(): boolean;
+    /** Get all currently known peers from cloud discovery */
+    getPeers(): NodeInfo[];
+    /**
+     * Get the hub assigned by the cloud.
+     * The cloud **dictates** the hub — it has the full picture.
+     */
+    getAssignedHub(): NodeId | null;
+    /** Get current consecutive poll failure count (for diagnostics/testing) */
+    getConsecutivePollFailures(): number;
+    /** Get current effective poll interval including backoff (for diagnostics/testing) */
+    getCurrentPollIntervalMs(): number;
+    /**
+     * Report local probe results to the cloud.
+     * The cloud uses these to build a connectivity graph and assign hubs.
+     * @param probes - Probe results from the local ProbeScheduler
+     */
+    reportProbes(probes: PeerProbe[]): Promise<void>;
+    /**
+     * Subscribe to layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Unsubscribe from layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Schedule the next poll using setTimeout.
+     * Uses the current (possibly backed-off) interval.
+     */
+    private _schedulePoll;
+    /**
+     * Poll the cloud for latest peer list and hub assignment.
+     *
+     * After many consecutive failures, attempts re-registration instead
+     * of a regular poll (the cloud may have expired our registration).
+     *
+     * On success: resets failure counter and backoff interval.
+     * On failure: increments counter and doubles interval (capped at maxBackoffMs).
+     */
+    private _poll;
+    /**
+     * Process a cloud response: update peers and hub assignment.
+     * @param response - The cloud's peer list response
+     */
+    private _processResponse;
+    /**
+     * Emit a typed event to all registered listeners.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}

package/dist/layers/discovery-layer.d.ts

@@ -0,0 +1,45 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { NodeIdentity } from '../identity/node-identity.ts';
+/** Events emitted by a DiscoveryLayer */
+export interface DiscoveryLayerEvents {
+    /** A new peer was discovered */
+    'peer-discovered': (peer: NodeInfo) => void;
+    /** A previously known peer is no longer reachable */
+    'peer-lost': (nodeId: string) => void;
+    /** This layer is assigning/dictating a specific hub */
+    'hub-assigned': (nodeId: string | null) => void;
+}
+/** Valid event names for DiscoveryLayer */
+export type DiscoveryLayerEventName = keyof DiscoveryLayerEvents;
+/**
+ * Contract for all discovery mechanisms.
+ *
+ * Each layer decides HOW to discover peers. The NetworkManager tries layers
+ * in cascade order and uses the most autonomous one that produces a result.
+ */
+export interface DiscoveryLayer {
+    /** Layer name: 'broadcast' | 'cloud' | 'static' | 'manual' */
+    readonly name: string;
+    /**
+     * Start the layer. Returns false if this layer is not available
+     * (e.g., no config, no network interface, etc.).
+     * @param identity - This node's identity
+     */
+    start(identity: NodeIdentity): Promise<boolean>;
+    /** Stop the layer and clean up resources */
+    stop(): Promise<void>;
+    /** Whether this layer is currently active */
+    isActive(): boolean;
+    /** Get all currently known peers from this layer */
+    getPeers(): NodeInfo[];
+    /**
+     * Get the hub this layer has assigned/dictated.
+     * Some layers (static, cloud, manual) dictate the hub.
+     * Others (broadcast) return null — hub is elected, not assigned.
+     */
+    getAssignedHub(): NodeId | null;
+    /** Subscribe to layer events */
+    on<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /** Unsubscribe from layer events */
+    off<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+}

package/dist/layers/manual-layer.d.ts

@@ -0,0 +1,56 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { NodeIdentity } from '../identity/node-identity.ts';
+import { DiscoveryLayer, DiscoveryLayerEventName, DiscoveryLayerEvents } from './discovery-layer.ts';
+/**
+ * Always-present manual override layer.
+ *
+ * Cannot be disabled. Allows a human (or programmatic caller) to force
+ * a specific hub, overriding whatever the automatic cascade decided.
+ * Clearing the override returns control to the cascade.
+ *
+ * ManualLayer does NOT discover peers — it only overrides hub assignment.
+ */
+export declare class ManualLayer implements DiscoveryLayer {
+    readonly name = "manual";
+    private _active;
+    private _assignedHub;
+    private _listeners;
+    /**
+     * Start always succeeds — manual layer cannot be disabled.
+     * @param _identity - Node identity (unused by manual layer)
+     */
+    start(_identity: NodeIdentity): Promise<boolean>;
+    /** Stop the layer */
+    stop(): Promise<void>;
+    /** Always active after start */
+    isActive(): boolean;
+    /** Manual layer does not discover peers */
+    getPeers(): NodeInfo[];
+    /** Get the manually assigned hub, or null if no override is set */
+    getAssignedHub(): NodeId | null;
+    /**
+     * Force a specific node as the hub.
+     * @param nodeId - The nodeId to assign as hub
+     */
+    assignHub(nodeId: NodeId): void;
+    /** Clear the manual override — returns control to the automatic cascade */
+    clearOverride(): void;
+    /**
+     * Subscribe to layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Unsubscribe from layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Emit a typed event to all registered listeners.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}

package/dist/layers/static-layer.d.ts

@@ -0,0 +1,61 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { StaticConfig } from '../types/network-config.ts';
+import { NodeIdentity } from '../identity/node-identity.ts';
+import { DiscoveryLayer, DiscoveryLayerEventName, DiscoveryLayerEvents } from './discovery-layer.ts';
+/**
+ * Static discovery layer — last resort fallback (Try 3).
+ *
+ * Reads a hardcoded `hubAddress` from config. If set, produces a synthetic
+ * peer for the hub and returns it as the assigned hub. If not set, `start()`
+ * returns false.
+ *
+ * Static config is not a dead end — if a more autonomous layer (broadcast,
+ * cloud) starts producing results, the NetworkManager upgrades automatically.
+ */
+export declare class StaticLayer implements DiscoveryLayer {
+    private readonly _config?;
+    readonly name = "static";
+    private _active;
+    private _hubAddress;
+    private _hubNodeId;
+    private _syntheticPeer;
+    private _listeners;
+    /**
+     * Create a StaticLayer.
+     * @param _config - Static config with optional hubAddress
+     */
+    constructor(_config?: StaticConfig | undefined);
+    /**
+     * Start the layer. Returns false if no hubAddress is configured.
+     * @param identity - This node's identity (used for domain info on synthetic peer)
+     */
+    start(identity: NodeIdentity): Promise<boolean>;
+    /** Stop the layer */
+    stop(): Promise<void>;
+    /** Whether this layer is currently active */
+    isActive(): boolean;
+    /** Get the synthetic peer for the configured hub (or empty array) */
+    getPeers(): NodeInfo[];
+    /** Get the statically configured hub nodeId */
+    getAssignedHub(): NodeId | null;
+    /** Get the raw hub address string ("ip:port") */
+    getHubAddress(): string | null;
+    /**
+     * Subscribe to layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Unsubscribe from layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Emit a typed event to all registered listeners.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}

package/dist/network-manager.d.ts

@@ -0,0 +1,149 @@
+import { NodeId, NodeInfo } from './types/node-info.ts';
+import { NetworkConfig } from './types/network-config.ts';
+import { NetworkTopology } from './types/network-topology.ts';
+import { TopologyChangedEvent, RoleChangedEvent, HubChangedEvent } from './types/network-events.ts';
+import { NodeIdentity } from './identity/node-identity.ts';
+import { BroadcastLayerDeps } from './layers/broadcast-layer.ts';
+import { CloudLayerDeps } from './layers/cloud-layer.ts';
+import { ProbeScheduler, ProbeFn } from './probing/probe-scheduler.ts';
+/** Events emitted by NetworkManager */
+export interface NetworkManagerEvents {
+    'topology-changed': (event: TopologyChangedEvent) => void;
+    'role-changed': (event: RoleChangedEvent) => void;
+    'hub-changed': (event: HubChangedEvent) => void;
+    'peer-joined': (peer: NodeInfo) => void;
+    'peer-left': (nodeId: string) => void;
+}
+/** Valid event names for NetworkManager */
+export type NetworkManagerEventName = keyof NetworkManagerEvents;
+/** Options for NetworkManager constructor */
+export interface NetworkManagerOptions {
+    /** Custom probe function (e.g. for testing) */
+    probeFn?: ProbeFn;
+    /**
+     * Number of consecutive probe failures before declaring a peer
+     * unreachable (default: 3). Passed through to ProbeScheduler.
+     */
+    failThreshold?: number;
+    /** Injectable dependencies for BroadcastLayer (e.g. mock sockets) */
+    broadcastDeps?: BroadcastLayerDeps;
+    /** Injectable dependencies for CloudLayer (e.g. mock HTTP client) */
+    cloudDeps?: CloudLayerDeps;
+}
+/**
+ * Central orchestrator for network topology.
+ *
+ * Starts all configured discovery layers, merges peer tables,
+ * applies the fallback cascade, and emits topology events.
+ *
+ * Supports ManualLayer + StaticLayer + hub election via probing.
+ * Broadcast and Cloud layers will be added in later epics.
+ */
+export declare class NetworkManager {
+    private readonly _config;
+    private _identity;
+    private _running;
+    /** Always-present manual override layer */
+    private readonly _manualLayer;
+    /** Try 1: UDP broadcast discovery */
+    private readonly _broadcastLayer;
+    /** Try 2: Cloud discovery fallback */
+    private readonly _cloudLayer;
+    /** Try 3: Static config fallback */
+    private readonly _staticLayer;
+    /** Merged peer table */
+    private readonly _peerTable;
+    /** Probe scheduler for reachability checking */
+    private readonly _probeScheduler;
+    /** Event listeners */
+    private _listeners;
+    /** Current topology snapshot */
+    private _currentHubId;
+    private _currentRole;
+    private _formedBy;
+    /**
+     * Create a NetworkManager.
+     * @param _config - Network configuration
+     * @param options - Optional overrides (e.g. custom probe function)
+     */
+    constructor(_config: NetworkConfig, options?: NetworkManagerOptions);
+    /**
+     * Start the network manager.
+     *
+     * Creates node identity, starts all layers, attaches to peer table,
+     * and performs initial hub computation.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the network manager.
+     *
+     * Stops all layers and clears state.
+     */
+    stop(): Promise<void>;
+    /** Whether the manager is currently running */
+    isRunning(): boolean;
+    /**
+     * Get the current topology snapshot.
+     * @returns The current network topology
+     */
+    getTopology(): NetworkTopology;
+    /**
+     * Get the probe scheduler for direct access to probe results.
+     * @returns The ProbeScheduler instance
+     */
+    getProbeScheduler(): ProbeScheduler;
+    /**
+     * Get this node's identity.
+     * Throws if called before start().
+     */
+    getIdentity(): NodeIdentity;
+    /**
+     * Manually assign a hub node, overriding the cascade.
+     * @param nodeId - The node to designate as hub
+     */
+    assignHub(nodeId: NodeId): void;
+    /**
+     * Clear the manual hub override, returning to cascade logic.
+     */
+    clearOverride(): void;
+    /**
+     * Subscribe to network manager events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends NetworkManagerEventName>(event: E, cb: NetworkManagerEvents[E]): void;
+    /**
+     * Unsubscribe from network manager events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends NetworkManagerEventName>(event: E, cb: NetworkManagerEvents[E]): void;
+    /**
+     * Compute the hub using the fallback cascade.
+     *
+     * Priority:
+     *   1. Manual override (human knows best)
+     *   2. Election among probed peers (most autonomous)
+     *      - formedBy 'broadcast' if broadcast layer provided peers
+     *      - formedBy 'election' otherwise
+     *   3. Cloud assignment (sees full picture, dictates hub)
+     *   4. Static config (last resort)
+     *   5. Nothing → unassigned
+     */
+    private _computeHub;
+    /**
+     * Recompute topology and emit events if anything changed.
+     */
+    private _recomputeTopology;
+    /**
+     * Resolve the hub address ("ip:port") from the current hub.
+     * Uses static config's hubAddress if the hub is from static layer.
+     */
+    private _resolveHubAddress;
+    /**
+     * Emit a typed event.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}