Struct Node 

pub struct Node { /* private fields */ }

A running in-process node. Dropping it does NOT stop serving — call shutdown.

Implementations

impl Node

pub async fn control(&self) -> Result<ControlClient, ClientError>

A control connection to THIS node: the same typed mcpmesh-local/1 client a sidecar consumer gets from connect_control_default, over an in-memory pipe. Cheap; open one per concurrent conversation — a session/stream upgrade (open_session, subscribe) consumes its connection, exactly as on the socket.

pub fn endpoint_id(&self) -> EndpointId

This node’s mesh identity — what a peer’s invite/pair flow binds to.

pub fn accept_protocol( &self, alpn: &[u8], handler: Arc<dyn DynProtocolHandler>, ) -> Result<()>

Serve a custom protocol on alpn, through this node’s existing trust gate (#67).

What this is for. mcpmesh has already built the hard parts of a P2P application platform — identity, pairing, a trust gate, relay fallback, discovery, rate limiting, a connection registry — and exposes one protocol shape on top: request/response MCP over bi-streams. Anything that does not fit (realtime media wanting datagrams, efficient bulk transfer, an app-level overlay) was out of reach however well the identity layer suited it. The alternative was a SECOND endpoint with a second identity, which discards the gate, the pairing relationship and the relay config — and makes your users pair twice.

Your handler runs behind the same gate as every built-in protocol. An unauthorized or revoked peer is closed before accept is called; the connection is entered in the registry, so revoking that peer SEVERS it mid-protocol rather than waiting for it to end. You get the authenticated EndpointId from connection.remote_id(), and it is the same identity _meta["mcpmesh/peer"] names on the MCP path.

use std::sync::Arc;
use mcpmesh_node::iroh;

#[derive(Debug)]
struct MyProto;

impl iroh::protocol::ProtocolHandler for MyProto {
    async fn accept(
        &self,
        conn: iroh::endpoint::Connection,
    ) -> Result<(), iroh::protocol::AcceptError> {
        let _peer = conn.remote_id(); // the AUTHENTICATED caller
        Ok(())
    }
}

node.accept_protocol(b"app/myproto/1", Arc::new(MyProto))?;

The mcpmesh/ prefix is reserved and registering under it is an error — the accept loop dispatches its own protocols by exact ALPN before consulting this registry, so a handler there would be silently dead, and one on a name mcpmesh adds later would flip from working to dead on an upgrade. app/… is the suggested convention.

Takes effect for connections negotiated from now on. ALPN is chosen at handshake, so a peer already connected cannot use the new protocol. Register during startup, before you announce the node as ready, unless that is genuinely what you want.

Registering the same alpn twice replaces the handler; connections already running under the old one continue on it.

pub fn endpoint_addr(&self) -> EndpointAddr

This node’s currently-dialable address (#67) — its endpoint id plus whatever direct addresses and relay it has, exactly what a pairing invite embeds.

For handing an address to a peer OUT-OF-BAND, when your application has its own channel for that and does not want a pairing invite. Carries transport vocabulary by nature, which is why it is a typed accessor rather than anything on the control surface.

A snapshot: addresses change as the network does, and immediately after boot it may hold only local ones. It authorizes nothing — a peer dialling this still faces the trust gate.

pub async fn connect_protocol( &self, peer: &str, alpn: &[u8], ) -> Result<Connection>

Dial peer on a custom alpn — the client half of accept_protocol (#67).

peer may be a paired nickname, a b64u: user_id, an eid: device principal, or — in roster mode — a rostered user_id. That resolution, plus the stored dial-address hint and this node’s relay configuration, is most of what makes this worth using over a raw endpoint: an embedder holding only “alice” has no way to turn that into an address, and one that stood up its own endpoint would not have the pairing that produced it.

For a person with several devices the candidates are tried IN ORDER — roster candidates first, primary before mirror — and the first that connects wins. That is weaker than open_session’s staggered race, which this deliberately does not reproduce: racing means opening connections you then abandon, and an embedder’s protocol may not be safe to half-open. Each attempt is bounded by the same DIAL_TIMEOUT the service dial uses, so an unreachable first device costs that timeout rather than hanging.

let conn = node.connect_protocol("alice", b"app/myproto/1").await?;
let (send, recv) = conn.open_bi().await?;

This does not authorize anything. It dials; the REMOTE side’s gate decides whether to admit you, and will close the connection if you are not paired with them. Symmetrically, your own handler is protected by your gate — see accept_protocol.

Errors when peer resolves to nobody, or when the dial fails. A peer that is simply offline is a dial failure, not a distinct condition.

pub fn sign_app(&self, domain: &[u8], msg: &[u8]) -> [u8; 64]

Sign an application payload with this node’s DEVICE key, under the embedder’s own domain (#59).

What this is for. mcpmesh authenticates the transport: inside a session, _meta["mcpmesh/peer"] says who is calling. That answers nothing about a payload which outlives its connection — anything store-and-forward (offline delivery, a relay, a mailbox, an app-level overlay) handles bytes whose author is not the peer that delivered them, and the transport authenticated the FORWARDER. This attributes the ORIGIN, against the same identity the transport already proves, so an embedder needs no second key, no second backup/revocation story, and no binding protocol tying the two together.

domain is yours; pick one per statement KIND (b"chat/message/1", b"mailbox/receipt/1"). A signature is only as narrow as its domain, and sharing one across two shapes lets a value from either be read as the other. mcpmesh’s own domains are out of reach whatever you choose — see mcpmesh_trust::app for why that is a property of the preimage rather than of your discipline.

Verify with verify_app, which needs no node.

Not a control verb, deliberately. Signing over the JSON-RPC socket would put the device key’s authority behind an IPC surface shared by every consumer of that socket. This is an in-process seam for the embedder that owns the node.

pub fn verify_app( endpoint_id: &EndpointId, domain: &[u8], msg: &[u8], sig: &[u8; 64], ) -> bool

Verify an application payload signed by endpoint_id under domain (#59).

An associated function: verification needs no node, which is the point — a consumer checking a relayed payload has the peer’s EndpointId and nothing else.

Returns false for a bad signature, a mismatched domain/message, or malformed bytes. It never panics: every input is attacker-supplied by construction.

It answers “which device produced these bytes” and nothing else. Whether that device was ENTITLED to make the statement is the embedder’s authorization question, answered from the embedder’s own state.

pub async fn wait(&self)

Resolves once shutdown has been requested — by shutdown from another handle, or by the control protocol’s shutdown verb (e.g. an operator driving this node’s control connection).

pub async fn shutdown(self)

Stop serving: raise the shutdown signal, stop the accept/poll/background loops and every live control connection (subscription streams end immediately; in-flight control requests get a dropped connection — acceptable, shutdown means shutdown), and close the endpoint (a graceful QUIC close — live sessions end cleanly).

Trait Implementations

impl Debug for Node

Hand-rolled: the boot internals are not Debug; the identity is the one diagnostic a {:?} needs.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.