Struct RawStdioConnection 

pub struct RawStdioConnection { /* private fields */ }

A raw, framed connection to a child-process Context Graph Protocol provider. The low-level primitive StdioProvider is built on; public so conformance tools can drive the wire directly.

Implementations

impl RawStdioConnection

pub async fn spawn(program: &str, args: &[String]) -> Result<Self, HostError>

Spawn program with args as a CGP provider child, under the isolation contract (scrubbed env, own process group). Does not handshake — call RawStdioConnection::handshake next.

pub fn with_label(self, label: impl Into<String>) -> Self

Override the connection’s error label (defaults to the program name). StdioProvider sets it to the provider’s host-facing id.

pub async fn send(&mut self, env: &Envelope) -> Result<(), HostError>

Send one envelope as an NDJSON line.

pub async fn send_raw_line(&mut self, line: &str) -> Result<(), HostError>

Write a raw line to the provider’s stdin verbatim — the escape hatch conformance uses to inject a malformed line (SPEC.md §11). A trailing \n is appended if missing so the provider’s line reader unblocks.

pub async fn read_raw_line(&mut self) -> Result<Option<String>, HostError>

Read the next raw line, or None at EOF (the child closed stdout).

Bounded to [MAX_LINE_BYTES] via an incremental fill_buf/consume loop: a buggy or hostile child that streams bytes without ever emitting a newline would otherwise grow a single String without limit (the handshake/query timeouts bound time, not memory) and OOM the host.

pub async fn recv(&mut self) -> Result<Envelope, HostError>

Read the next envelope. A closed stream (the child died) is HostError::ProviderCrashed — never a hang or a panic (task deliverable 5).

pub async fn handshake( &mut self, ) -> Result<(ProviderInfo, Capabilities), HostError>

Perform the Context Graph Protocol handshake (SPEC.md §3): send handshake, expect handshake_ack, and reject an incompatible protocol version with a named error. Bounded by [HANDSHAKE_TIMEOUT] so a silent provider fails cleanly rather than hanging (task deliverable 1).

pub async fn shutdown(&mut self) -> Result<(), HostError>

Send shutdown and wait a bounded grace for the child to exit, killing the process group if it overstays (task deliverable 2). A provider that already died is not treated as a shutdown error.

Trait Implementations

impl Drop for RawStdioConnection

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.