Crate frust_devtools_protocol

Expand description

frust-devtools-protocol — the wire contract between an in-app Frust debug service and external tooling (frust-drive/frust-tui).

This is the one sanctioned crossing of the tooling-isolation charter (docs/ARCHITECTURE.md’s Cross-Unit Layer Dependencies: “frust-cli, frust-drive, and frust-tui depend on NO framework crate”). Both sides of the devtools wire depend on this crate, and only this crate, to agree on message shapes — neither side depends on the other, and this crate stays a leaf: serde (derive) + serde_json only, no tokio, no framework crate, no other frust-* crate. Pulling it into the tooling side must never drag framework or async-runtime code along with it.

§Framing

One JSON-RPC 2.0 object per \n-terminated line — no Content-Length headers. encode_line/decode_line are the pure (no I/O) serialize/discriminate pair; Incoming tells the caller whether a decoded line was a Request, Response, or Notification.

§Discovery and auth

A server announces its listening port — and the per-process token a client must present at handshake — with one printed line built from DISCOVERY_PREFIX. format_discovery_line/parse_discovery_line are the single formatter/parser pair the service and tooling share, and Discovery is what a parsed line yields. The token travels back to the server exactly once, in HandshakeParams; a connection that has not presented it is answered RpcError::UNAUTHORIZED for every other method.

§Methods

Method is the typed v1 method set; [messages]-derived re-exports below are each method’s typed params/result/notification-payload struct. This crate is pure data + pure functions — no I/O, no async, no runtime state of its own.

Re-exports§

pub use serde_json;

Structs§

AckResult: The ack result input_tap/input_scroll/input_text/ frame_stats_subscribe all reply with.
Discovery: A parsed discovery line: everything a client needs to open an authenticated connection.
FrameStats: frame_stats_subscribe acknowledges with crate::AckResult; the server then pushes this payload as the frame_stats notification body on every subsequent frame.
HandshakeInfo: handshake result — server identity plus the declared capability set a client uses to know which other methods are safe to call.
HandshakeParams: handshake request params — the per-process auth token the server printed on its discovery line (crate::format_discovery_line).
InputScrollParams: input_scroll request params (logical px; dx/dy are the scroll delta, same convention as a wheel/drag event elsewhere in the framework).
InputTapParams: input_tap request params (logical px, see RectPx’s doc).
InputTextParams: input_text request params.
MetricsSnapshot: metrics_snapshot result — v1 minimal (process RSS is best-effort/ platform-dependent, hence optional; uptime is always known).
Notification: A server→client push carrying no id and expecting no Response.
RectPx: A logical-px rectangle — the same coordinate space every framework InputEvent uses (docs/CODE_STANDARDS.md’s Interaction Semantics: “Events are logical-coordinate by the time they cross AppTree”).
Request: A client→server call awaiting a Response correlated by id.
Response: The reply to a Request, correlated by id. Exactly one of result/ error is present on the wire (JSON-RPC 2.0 §5) — modeled as the flattened ResponseOutcome rather than two Option fields so an invalid “both present”/“neither present” shape can’t be constructed.
RpcError: A JSON-RPC 2.0 error object (§5.1), plus a small implementation-defined custom range this protocol occupies for its own conditions.
ScreenshotResult: screenshot result. Declared in the protocol so the method/result shape exists for every client, but capability-gated in practice — a server with no Capability::Screenshot rejects the request with crate::RpcError::not_supported instead of ever returning this.
WidgetNode
WidgetProps: widget_props result.
WidgetPropsParams: widget_props request params.
WidgetTreeDump: widget_tree result. Nested (parent owns children: Vec<WidgetNode>) rather than a flat id-indexed list with parent pointers — the simplest v1 shape, and the one a debug client walks directly to render a tree view with no separate reconstruction pass.

Enums§

Capability: A capability a server may declare at handshake, gating which other methods a client should expect to succeed (screenshot is the v1 example — see crate::RpcError::NOT_SUPPORTED).
DecodeError: decode_line’s failure modes.
Incoming: A decoded line’s discriminated shape — crate::decode_line’s return type.
Method: A devtools protocol v1 method name, typed. crate::Request::method/ crate::Notification::method carry the plain String on the wire (JSON-RPC has no closed method set, and an unrecognized method must still decode — see docs/CODE_STANDARDS.md’s Naming Conventions and this crate’s forward-compat testing); a caller matches the decoded string against Method::from_str to dispatch, treating None as “unknown method” (→ RpcError::METHOD_NOT_FOUND on a server, or an ignored push on a client).
ResponseOutcome

Constants§

DISCOVERY_PREFIX: The exact substring a devtools server’s discovery line carries, followed immediately by a bare decimal port number.
FAILURE_PREFIX: The exact substring a shell logs (via format_failure_line) when the in-app devtools service is compiled in but could not start — a bind refused by the OS, an ephemeral-port exhaustion, a runtime that would not build. The human reason follows immediately.
JSONRPC_VERSION: The JSON-RPC 2.0 "jsonrpc" version literal every envelope carries.
PROTOCOL_VERSION: The devtools wire protocol version this crate implements — HandshakeInfo::protocol_version’s value.

Functions§

decode_line: Parses one NDJSON line into its discriminated Incoming shape.
encode_line: Serializes value to a single JSON-RPC line with no trailing newline — the caller appends \n when writing it to a stream (matching decode_line, which also takes one line with the newline already stripped).
format_discovery_line: Builds the one discovery line a server logs on start. The server side’s only formatter — see the module doc for the shape.
format_failure_line: Builds the one line a shell logs when the devtools service fails to start. The shell side’s only formatter — pair of parse_failure_line.
parse_discovery_line: Finds DISCOVERY_PREFIX anywhere in line — a substring search, not a line-start anchor — and parses the port (and optional token) that follow it.
parse_failure_line: Finds FAILURE_PREFIX anywhere in line (a substring search, for the same host-logger-prefix reason as parse_discovery_line) and returns the trimmed human reason after it, or None if the marker is absent or nothing non-empty follows it.
redact_discovery_token: Redacts the token value from a discovery line for safe logging/display.