magpipe

License PRs Welcome Platform Issues Repo Size Tags Version

Watchers Forks Stars Followers

Magpie Bridge pipe transport for Dart: one shared UDP socket, many connections.

  • MagHub: binds the shared socket once and multiplexes every connection registered on it (inbound datagrams are routed by remote endpoint). The hub runs no timers: call hub.keepAlive(now) periodically (e.g. once a second on your own timer) to heartbeat idle links and re-connect dead ones (docs/client.md §6, §8). hub.close() disconnects everything and closes the shared socket.
  • BridgeLink / DirectLink: connection to the relay server (B=1, with the SYN?/SYN!/ACK! handshake, heartbeat and enigma) or directly to a peer (B=0, stateless).
  • Packet framing: bridge/direct packet classes and factories (SYN?/SYN!/ACK!, FAIL/DONE, ACPT/DENY, PING/PONG, FIN?/FIN!, NOOP, DATA/COPY), including signed ReliablePacket (HMAC-SHA256).
  • Enigma: decrypts the handshake secret with HKDF-SHA256 + AES-256-GCM (HkdfEnc / HkdfSha256).
  • Receiving: the default processPacket answers "COPY" to data packets and "PONG" to heartbeats; override it on your pipe subclass to plug in your own dedup, fragment reassembly and delivery.
  • Observing: a MagpieDelegate receives every packet received through the link - handshake waves included; pass it to MagHub.create / the MagHub constructor (delegate) without subclassing anything. Datagrams from endpoints with no registered link are reported via onUnknownPeer(data, remote) - the app decides whether to dial them.

See docs/protocol.md in the Magpie Bridge repository for the wire format and docs/client.md for the client behaviour.

Install

dependencies:
  magpipe: ^1.0.0

Or, from the command line:

dart pub add magpipe

Usage

// feeds the encrypted handshake; an empty Enigma only works against a
// server with encrypted mode OFF. Load the shared app secrets first:
final enigma = Enigma();
enigma.updateSecrets({'app-key': ikmBytes});  // name -> input key material (Uint8List)
final config = Config();  // timing knobs (heartbeat/handshake intervals, ...)
final delegate = MyDelegate();  // observes every packet (a no-op works too)

final hub = await MagHub.create(enigma: enigma, config: config, delegate: delegate);

// bridge connection to the relay server (B=1):
final bridge = hub.connectBridge(server);
// the handshake runs in the background: getBridgePipe returns null
// until it completes (bridge.ready)
final bridgePipe = hub.getBridgePipe(server, targetBid);

// direct connection to a peer (B=0):
final direct = hub.connect(peer);
final directPipe = hub.getDirectPipe(peer);

// send data through a pipe (sn/index/count for the reliability layer):
directPipe.sendData(payload, sn: 1);

// or send a pre-built packet through the same pipe:
directPipe.sendPacket(packet);

// keep-alive pass: call periodically, e.g. once a second
hub.keepAlive(DateTime.now());

...
hub.disconnect(server);

// done: disconnects every link and closes the shared socket
hub.close();

License

MIT — see LICENSE.

Libraries

client
Client layer: the hub, links and pipes of the pipe transport.
common
Common layer: re-exports the magpie_bridge SDK facades.
magpipe
Magpie Bridge pipe transport: one shared UDP socket, many connections.
utils
Utility layer: config, coding, crypto and payload helpers.