openprot-mctp-api

Platform-independent MCTP types, traits, and stack facade.

Overview

This crate defines the API contract between MCTP applications and the MCTP server. It provides two layers:

MctpClient trait — low-level service-transport interface for req, listener, recv, send, drop_handle, plus local EID control (get_eid / set_eid). Platform-specific clients implement this trait over a chosen transport (for example Pigweed IPC, sockets, or test doubles).
Stack facade (stack module) — high-level entry point that wraps any MctpClient and returns typed channel objects (StackListener, StackReqChannel, StackRespChannel) that implement the MctpListener / MctpReqChannel / MctpRespChannel traits.

This two-layer design hides both the concrete MCTP stack implementation (which lives inside the server process) and the transport mechanism from application code. Applications depend only on the high-level traits; swapping the transport or stack requires no application changes.

┌─────────────────────┐
│   Application       │  uses Stack facade, then channel traits
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│   Stack (this crate)│  wraps any MctpClient, returns typed channel handles
└─────────┬───────────┘
          │ MctpClient trait
          ▼
┌─────────────────────┐
│  MctpClient impl    │  encodes wire protocol, uses a transport backend
│  (IPC/sockets/test) │
└─────────┬───────────┘
          │ Transport
          ▼
┌─────────────────────┐
│   MCTP Server       │  owns the concrete MCTP stack (mctp-lib, etc.)
└─────────────────────┘

Key Types

Handle — opaque handle for listeners, request, or response channels
RecvMetadata — metadata from a successful receive (msg_type, tag, remote_eid, payload_size)
MctpError / ResponseCode — error types (InternalError, NoSpace, AddrInUse, TimedOut, BadArgument, ServerRestarted)

High-level API (`stack` module)

Type	Trait	Obtained via
`Stack<C>`	—	`Stack::new(client)`
`StackListener<'_, C>`	`MctpListener`	`stack.listener(msg_type, timeout)`
`StackReqChannel<'_, C>`	`MctpReqChannel`	`stack.req(eid, timeout)`
`StackRespChannel<'_, C>`	`MctpRespChannel`	returned by `StackListener::recv`

All channel types release their server-side handle automatically on Drop.

Low-level API (`MctpClient` trait)

Method	Description
`req(eid)`	Allocate a request handle for a remote EID
`listener(msg_type)`	Register to receive messages of a given type
`get_eid() / set_eid(eid)`	Read/write the local endpoint ID
`recv(handle, timeout, buf)`	Receive a message on a handle
`send(handle, msg_type, eid, tag, ic, buf)`	Send a message (request or response)
`drop_handle(handle)`	Release a handle

Design: Strategy Pattern

Stack<C: MctpClient> applies the Strategy pattern:

Context → Stack<C> holds the strategy and exposes the high-level API
Strategy trait → MctpClient defines the service-transport operations (req, listener, recv, send, drop_handle) and local EID control (get_eid/set_eid).
Concrete strategies → transport-specific MctpClient implementations (for example IPC clients) and test DirectClient

Application code enters through the Stack facade and then operates on channels implementing MctpListener / MctpReqChannel / MctpRespChannel. During initialization, a concrete MctpClient is provided to Stack::new(client); after that, protocol logic remains transport-agnostic.

This gives two independent axes of variation:

Concern	How to swap
MCTP stack implementation (mctp-lib, etc.)	Replace the server process — no API change
OS / IPC transport	Provide a different `MctpClient` impl to `Stack::new`
Application logic	Written against the high-level traits — unchanged across both

The wire module implements binary request/response encoding. It is used internally by transport client implementations and server endpoints; applications do not use it directly.

Dependencies

This crate currently has no external Rust crate dependencies. It is no_std compatible and relies on core plus internal modules.