pub enum Request {
Show 17 variants
RegisterService(RegisterServiceParams),
Status,
Invite(InviteParams),
Pair(PairParams),
PeerRemove(PeerRemoveParams),
PeerRename(PeerRenameParams),
PeerAdd(PeerAddParams),
OpenSession(OpenSessionParams),
RosterInstall(RosterInstallParams),
OrgJoin(OrgJoinParams),
SetRosterUrl(SetRosterUrlParams),
BlobPublish(BlobPublishParams),
BlobGrant(BlobGrantParams),
BlobList,
BlobFetch(BlobFetchParams),
AuditSummary,
Subscribe,
}Expand description
Control-API requests. Serialized as { "method": "...", "params": {...} }
(JSON-RPC-shaped; the id/jsonrpc envelope is added by the transport layer).
Each param-carrying variant wraps its named *Params struct — the ONE wire truth for that
method’s params, shared by clients (which serialize whole Requests) and the daemon (which
deserializes params into the same struct after its method-string dispatch). Adjacent
tagging serializes a newtype variant’s content as the struct’s fields, so the wire shape is
identical to inline variant bodies.
Servers dispatch on the method string and deserialize params per-method — tolerating
omitted / null / empty-object params for parameterless methods — rather than deserializing a
whole message into Request (adjacent tagging rejects params:{} for unit variants).
This keeps the wire tolerant for third-party clients (the versioned, additive-only surface).
Use method_of to extract the tag, then match + deserialize params per-method.
Variants§
RegisterService(RegisterServiceParams)
Register/update a [services.*] entry idempotently.
Status
Invite(InviteParams)
Mint a one-time pairing invite granting services. The daemon
answers an InviteResult carrying the copyable mcpmesh-invite: line. Tag
"invite" (snake_case). method_of needs no per-variant arm — it reads the
method string generically; the tag comes from rename_all.
Pair(PairParams)
Redeem a pairing invite. The daemon dials the inviter named by
invite_line on mcpmesh/pair/1, proves the secret, writes the mutual
(dial-back) PeerEntry, and answers a PairResult. Tag "pair"
(snake_case); method_of reads the method string generically.
PeerEntry — the durable allowlist row — lives in the daemon crate.
PeerRemove(PeerRemoveParams)
Remove a paired peer by petname (mcpmesh pair --remove). The daemon drops the
peer’s PeerEntry (identity) AND revokes its access by removing the petname from every
[services.*].allow (authorization) — the inverse of the pairing grant. Idempotent: a
petname with no entry / no allow membership is a clean no-op. Live in-flight sessions are
NOT severed here: existing sessions run to completion; the peer only loses the
ability to establish NEW authorized sessions. Tag "peer_remove" (snake_case);
method_of reads the method string generically (no per-variant arm).
PeerEntry — the durable allowlist row — lives in the daemon crate.
PeerRename(PeerRenameParams)
Rename a contact’s nickname (petname) authoritatively. Renames the
PERSON — every PeerEntry sharing user_id when given (one op for all their devices), else the
single petname entry (a provisional, no-user_id contact) — to to, AND rewrites the old
petname → to in every [services.*].allow so grants follow the rename. Refuses (error frame)
when to is empty or already names/grants a DIFFERENT identity — the same collision guard the
pairing rendezvous uses, so a rename can’t inherit another peer’s access. Tag "peer_rename";
host-privileged like the other pair ops.
PeerAdd(PeerAddParams)
RESERVED / INTERNAL (docs/local-protocol.md “Reserved / internal methods”): install a
peer directly from a raw endpoint_id — the trust-population stand-in for pairing behind
mcpmesh internal peer add. A deliberate, documented exception to the surface discipline
(raw endpoint identifiers otherwise never cross this socket); NOT part of the stable
vocabulary — do not build on it. Tag "peer_add".
OpenSession(OpenSessionParams)
Open a mesh session to peer/service; the daemon dials and pipes.
Distinct from the proxy’s job: this returns a session the client streams.
Named open_session rather than connect to avoid colliding
with the connect porcelain.
RosterInstall(RosterInstallParams)
Install a signed roster from a local file (the manual internal roster install path).
path is a LOCAL file the same-uid daemon reads (the daemon runs as the caller’s own
uid, so passing a path rather than the bytes crosses no trust boundary). org_root_pk
pins the org root on FIRST install (b64u:); omit it
once pinned (config carries it). Tag "roster_install".
OrgJoin(OrgJoinParams)
Pin the org root on a JOINER — WITHOUT a roster (the joiner has none yet; its poll loop
fetches the first one). Records [identity] org_id / org_root_pk / user_id / user_key.
user_key is a LOCAL path
(the key never crosses the API). Tag "org_join".
SetRosterUrl(SetRosterUrlParams)
Pin the HTTPS roster URL ([roster].url) in config. Written by org create --roster-url (the operator keeps it current) AND by join when the org invite carries one —
so the joiner’s poll loop bootstraps its FIRST roster. The daemon writes it under
reload_lock (single-writer), then the poll loop picks it up on the next daemon start. Tag
"set_roster_url".
BlobPublish(BlobPublishParams)
Publish a LOCAL file INTO a scope: the daemon adds the bytes to its gated
app-blob store and records the hash in scope. path is a local file the same-uid daemon
reads. Answers a BlobPublishResult carrying the mcpmesh/blob/1 ticket + hash.
Tag "blob_publish".
BlobGrant(BlobGrantParams)
Grant a scope to a principal — any flat-namespace entry: a group name, a user_id, or a
petname (the shared principal_set expansion). Tag
"blob_grant".
BlobList
List the daemon’s blob scopes (name → hashes + grants). Tag "blob_list".
BlobFetch(BlobFetchParams)
Fetch a mcpmesh/blob/1 ticket THROUGH the daemon (BLAKE3-verified streaming) and export the
verified blob to dest_path (a local file the same-uid daemon writes). Answers a
BlobFetchResult with the verified hash + byte length. Tag "blob_fetch".
AuditSummary
Summarize this node’s LOCAL audit log into per-peer / per-service SESSION counts
(local-only — the daemon reads its OWN audit dir, nothing is transmitted). The host Mesh surface
renders these as “who serves me / whom I serve / session counts”. Parameterless (like Status);
the server dispatches on the method string. Tag "audit_summary" (snake_case);
method_of reads the method string generically (no per-variant arm).
Subscribe
Open a live event stream (pairing liveness & health telemetry). Like open_session, the
connection STOPS being request/response after this call and becomes a one-way push stream
of StreamFrames. Parameterless. Tag "subscribe".