skills/docs/networking/network/network

@suaveplan/network - Core network interfaces: NetworkNode, NetworkPlugin, NetworkBus, MessageEnvelope, Transport, and plugin lifecycle management

Summary

Core network interfaces and runtime for the mesh system.

Documentation tree

• bus — (no submodules)
  • bus — (no submodules)
• envelope — (no submodules)
  • envelope — (no submodules)
• events — (no submodules)
  • events — (no submodules)
• manager — (no submodules)
  • manager — (no submodules)
• node — (no submodules)
  • node — (no submodules)
• plugin — (no submodules)
  • plugin — (no submodules)
• router — (no submodules)
  • router — (no submodules)
• timestamp — (no submodules)
  • timestamp — (no submodules)
• transport — (no submodules)
  • transport — (no submodules)
• version — (no submodules)
  • version — (no submodules)
• error-codes — Defines the stable error-code registry for the @suaveplan/network package. All runtime failures within the network co…

- [bus](./src/bus/bus.md) — _(no submodules)_- [envelope](./src/envelope/envelope.md) — _(no submodules)_- [envelope](./src/envelope/envelope.md) — _(no submodules)_- [events](./src/events/events.md) — _(no submodules)_- [events](./src/events/events.md) — _(no submodules)_- [manager](./src/manager/manager.md) — _(no submodules)_- [manager](./src/manager/manager.md) — _(no submodules)_- [node](./src/node/node.md) — _(no submodules)_- [node](./src/node/node.md) — _(no submodules)_- [plugin](./src/plugin/plugin.md) — _(no submodules)_- [plugin](./src/plugin/plugin.md) — _(no submodules)_- [router](./src/router/router.md) — _(no submodules)_- [router](./src/router/router.md) — _(no submodules)_- [timestamp](./src/timestamp/timestamp.md) — _(no submodules)_- [timestamp](./src/timestamp/timestamp.md) — _(no submodules)_- [transport](./src/transport/transport.md) — _(no submodules)_- [transport](./src/transport/transport.md) — _(no submodules)_- [version](./src/version/version.md) — _(no submodules)_- [version](./src/version/version.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable error-code registry for the `@suaveplan/network` package. All runtime failures within the network co…

• bus — (no submodules)- envelope — (no submodules)- envelope — (no submodules)- events — (no submodules)- events — (no submodules)- manager — (no submodules)- manager — (no submodules)- node — (no submodules)- node — (no submodules)- plugin — (no submodules)- plugin — (no submodules)- router — (no submodules)- router — (no submodules)- timestamp — (no submodules)- timestamp — (no submodules)- transport — (no submodules)- transport — (no submodules)- version — (no submodules)- version — (no submodules)- error-codes — Defines the stable error-code registry for the @suaveplan/network package. All runtime failures within the network co…
• bus — (no submodules)- envelope — (no submodules)- envelope — (no submodules)- events — (no submodules)- events — (no submodules)- manager — (no submodules)- manager — (no submodules)- node — (no submodules)- node — (no submodules)- plugin — (no submodules)- plugin — (no submodules)- router — (no submodules)- router — (no submodules)- timestamp — (no submodules)- timestamp — (no submodules)- transport — (no submodules)- transport — (no submodules)- version — (no submodules)- version — (no submodules)- error-codes — Defines the stable error-code registry for the @suaveplan/network package. All runtime failures within the network co…
• bus — (no submodules)- envelope — (no submodules) - envelope — (no submodules)- events — (no submodules) - events — (no submodules)- manager — (no submodules) - manager — (no submodules)- node — (no submodules) - node — (no submodules)- plugin — (no submodules) - plugin — (no submodules)- router — (no submodules) - router — (no submodules)- timestamp — (no submodules) - timestamp — (no submodules)- transport — (no submodules) - transport — (no submodules)- version — (no submodules) - version — (no submodules)- error-codes — Defines the stable error-code registry for the @suaveplan/network package. All runtime failures within the network co…

Purpose

@suaveplan/network provides the foundational abstractions that all other network plugins build upon: the NetworkNode entry-point, the NetworkPlugin lifecycle contract, the MessageEnvelope wire format, the NetworkBus event broker, the MessageRouter delivery layer, and the Transport abstraction. It also includes versioning and timestamp utilities for cross-node interoperability.

Features

• NetworkNode — single entry-point owning plugins, routing, and validation
• NetworkPlugin — strict four-phase lifecycle (install → start → stop → dispose)
• MessageEnvelope — Zod-validated wire format with TTL and loop detection
• NetworkBus — typed pub/sub with bounded-queue backpressure
• MessageRouter — unicast, broadcast, and fan-out routing across transports
• Transport — abstract contract for WebRTC, WebSocket, and custom protocols
• VersionInfo — semantic versioning with compatibility checks
• NetworkTimestamp — standardized timestamps with injectable clocks
• NetworkEvents — frozen registry of standard bus topics

Usage

Basic Example

import { NetworkNode, createEnvelope } from "@suaveplan/network";

const node = new NetworkNode();
await node.start();

const envelope = createEnvelope({
    type: "chat:message",
    senderId: "peer-a",
    targetId: "peer-b",
    payload: { text: "hello" },
});

await node.send(envelope);
await node.stop();

Advanced Example

import {
    NetworkNode,
    NetworkEvents,
    createEnvelope,
    type NetworkPlugin,
} from "@suaveplan/network";

const node = new NetworkNode();

node.networkBus.on(NetworkEvents.MESSAGE_RECEIVED, (msg) => {
    console.log("Received:", msg);
});

const plugin: NetworkPlugin = {
    name: "echo",
    install(n) {
        n.networkBus.on(NetworkEvents.MESSAGE_RECEIVED, (env) => {
            if (env.type === "echo") {
                n.send({ ...env, senderId: env.targetId!, targetId: env.senderId });
            }
        });
    },
    start() {},
    stop() {},
};

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

API Reference

See the per-module documentation in src/:

• src/plugin/ — NetworkPlugin interface
• src/node/ — NetworkNode class
• src/bus/ — NetworkBus class
• src/envelope/ — MessageEnvelope schema and helpers
• src/router/ — MessageRouter class
• src/transport/ — Transport interface
• src/manager/ — PluginManager class
• src/version/ — VersionInfo class
• src/timestamp/ — NetworkTimestamp class
• src/events/ — NetworkEvents constants

Implementation Notes

The network core is designed for loose coupling. Plugins communicate via the NetworkBus using typed events, not direct imports. This allows any plugin to be swapped out without changing other plugins. All envelopes are validated with Zod before routing, ensuring that malformed messages cannot propagate through the mesh. The PluginManager enforces deterministic lifecycle ordering to prevent resource leaks and race conditions.