use std::process::Stdio;
use std::time::Duration;
use async_trait::async_trait;
use ocp_types::{Capabilities, ContextQuery, ContextQueryResult, PROTOCOL_VERSION, ProviderInfo};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::process::{Child, ChildStdin, ChildStdout, Command};
use tokio::sync::Mutex as TokioMutex;
use crate::error::HostError;
use crate::provider::ContextProvider;
use crate::wire::{Envelope, decode_line, encode_line, envelope_kind, versions_compatible};
const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(10);
const SHUTDOWN_GRACE: Duration = Duration::from_secs(2);
const MAX_LINE_BYTES: usize = 16 * 1024 * 1024;
pub struct RawStdioConnection {
stdin: ChildStdin,
stdout: BufReader<ChildStdout>,
child: Child,
#[cfg_attr(not(unix), allow(dead_code))]
pgid: Option<i32>,
label: String,
}
impl RawStdioConnection {
pub async fn spawn(program: &str, args: &[String]) -> Result<Self, HostError> {
let mut cmd = Command::new(program);
cmd.args(args);
cmd.stdin(Stdio::piped());
cmd.stdout(Stdio::piped());
cmd.stderr(Stdio::inherit());
cmd.kill_on_drop(true);
cmd.env_clear();
if let Ok(path) = std::env::var("PATH") {
cmd.env("PATH", path);
}
if let Ok(home) = std::env::var("HOME") {
cmd.env("HOME", home);
}
#[cfg(unix)]
{
unsafe {
cmd.pre_exec(|| {
libc::setsid();
Ok(())
});
}
}
let mut child = cmd
.spawn()
.map_err(|e| HostError::Spawn(format!("{program}: {e}")))?;
let stdin = child
.stdin
.take()
.ok_or_else(|| HostError::Spawn(format!("{program}: child has no stdin pipe")))?;
let stdout = child
.stdout
.take()
.ok_or_else(|| HostError::Spawn(format!("{program}: child has no stdout pipe")))?;
#[cfg(unix)]
let pgid = child.id().map(|id| id as i32);
#[cfg(not(unix))]
let pgid = None;
Ok(Self {
stdin,
stdout: BufReader::new(stdout),
child,
pgid,
label: program.to_string(),
})
}
pub fn with_label(mut self, label: impl Into<String>) -> Self {
self.label = label.into();
self
}
pub async fn send(&mut self, env: &Envelope) -> Result<(), HostError> {
let line = encode_line(env)?;
self.send_raw_line(&line).await
}
pub async fn send_raw_line(&mut self, line: &str) -> Result<(), HostError> {
let label = self.label.clone();
let transport = |e: std::io::Error| match e.kind() {
std::io::ErrorKind::BrokenPipe => HostError::ProviderCrashed { id: label.clone() },
_ => HostError::Transport {
id: label.clone(),
message: e.to_string(),
},
};
self.stdin
.write_all(line.as_bytes())
.await
.map_err(transport)?;
if !line.ends_with('\n') {
self.stdin.write_all(b"\n").await.map_err(transport)?;
}
self.stdin.flush().await.map_err(transport)?;
Ok(())
}
pub async fn read_raw_line(&mut self) -> Result<Option<String>, HostError> {
let label = self.label.clone();
let transport = |message: String| HostError::Transport {
id: label.clone(),
message,
};
let mut bytes: Vec<u8> = Vec::new();
loop {
let buf = self
.stdout
.fill_buf()
.await
.map_err(|e| transport(e.to_string()))?;
if buf.is_empty() {
break; }
if let Some(pos) = buf.iter().position(|&b| b == b'\n') {
bytes.extend_from_slice(&buf[..=pos]);
self.stdout.consume(pos + 1);
break;
}
bytes.extend_from_slice(buf);
let consumed = buf.len();
self.stdout.consume(consumed);
if bytes.len() > MAX_LINE_BYTES {
return Err(transport(format!(
"provider emitted a line exceeding {MAX_LINE_BYTES} bytes without a newline"
)));
}
}
if bytes.is_empty() {
Ok(None)
} else {
Ok(Some(String::from_utf8_lossy(&bytes).into_owned()))
}
}
pub async fn recv(&mut self) -> Result<Envelope, HostError> {
match self.read_raw_line().await? {
Some(line) => decode_line(&line),
None => Err(HostError::ProviderCrashed {
id: self.label.clone(),
}),
}
}
pub async fn handshake(&mut self) -> Result<(ProviderInfo, Capabilities), HostError> {
self.send(&Envelope::Handshake {
protocol_version: PROTOCOL_VERSION.to_string(),
})
.await?;
let ack = match tokio::time::timeout(HANDSHAKE_TIMEOUT, self.recv()).await {
Ok(result) => result?,
Err(_) => {
return Err(HostError::Timeout {
id: self.label.clone(),
timeout_ms: HANDSHAKE_TIMEOUT.as_millis() as u64,
});
}
};
match ack {
Envelope::HandshakeAck {
protocol_version,
provider,
capabilities,
} => {
if !versions_compatible(PROTOCOL_VERSION, &protocol_version) {
return Err(HostError::VersionMismatch {
host: PROTOCOL_VERSION.to_string(),
provider: provider.name,
provider_version: protocol_version,
});
}
Ok((provider, capabilities))
}
other => Err(HostError::UnexpectedEnvelope {
id: self.label.clone(),
expected: "handshake_ack".into(),
got: envelope_kind(&other).into(),
}),
}
}
pub async fn shutdown(&mut self) -> Result<(), HostError> {
let _ = self.send(&Envelope::Shutdown).await;
let label = self.label.clone();
match tokio::time::timeout(SHUTDOWN_GRACE, self.child.wait()).await {
Ok(Ok(_)) => Ok(()),
Ok(Err(e)) => Err(HostError::Transport {
id: label,
message: e.to_string(),
}),
Err(_) => {
self.kill_group();
Ok(())
}
}
}
fn kill_group(&mut self) {
#[cfg(unix)]
if let Some(pgid) = self.pgid {
unsafe {
libc::kill(-pgid, libc::SIGKILL);
}
}
let _ = self.child.start_kill();
}
}
impl Drop for RawStdioConnection {
fn drop(&mut self) {
self.kill_group();
}
}
pub struct StdioProvider {
id: String,
info: ProviderInfo,
capabilities: Capabilities,
conn: TokioMutex<RawStdioConnection>,
}
impl StdioProvider {
pub async fn spawn(
id: impl Into<String>,
program: &str,
args: &[String],
) -> Result<Self, HostError> {
let id = id.into();
let mut conn = RawStdioConnection::spawn(program, args)
.await?
.with_label(id.clone());
let (info, capabilities) = conn.handshake().await?;
Ok(Self {
id,
info,
capabilities,
conn: TokioMutex::new(conn),
})
}
}
#[async_trait]
impl ContextProvider for StdioProvider {
fn id(&self) -> &str {
&self.id
}
fn info(&self) -> &ProviderInfo {
&self.info
}
fn capabilities(&self) -> &Capabilities {
&self.capabilities
}
async fn query(&self, query: &ContextQuery) -> Result<ContextQueryResult, HostError> {
let mut conn = self.conn.lock().await;
conn.send(&Envelope::Query {
query: query.clone(),
})
.await?;
match conn.recv().await? {
Envelope::Frames { result } => Ok(result),
Envelope::Error { message } => Err(HostError::Provider {
id: self.id.clone(),
message,
}),
other => Err(HostError::UnexpectedEnvelope {
id: self.id.clone(),
expected: "frames".into(),
got: envelope_kind(&other).into(),
}),
}
}
async fn shutdown(&self) -> Result<(), HostError> {
let mut conn = self.conn.lock().await;
conn.shutdown().await
}
}
#[cfg(all(test, unix))]
mod tests {
use super::*;
use ocp_types::{ContextFrame, FrameKind};
fn bash_provider(script: &str) -> (String, Vec<String>) {
(
"bash".to_string(),
vec!["-c".to_string(), script.to_string()],
)
}
fn ack_line(version: &str) -> String {
let ack = Envelope::HandshakeAck {
protocol_version: version.to_string(),
provider: ProviderInfo {
name: "bash-fixture".into(),
version: "0.0.1".into(),
data_flow: ocp_types::DataFlow {
reads: true,
writes: false,
egress: false,
},
},
capabilities: Capabilities {
query: ocp_types::capability::QueryCapability {
kinds: vec!["doc".into()],
filters: vec![],
},
..Capabilities::default()
},
};
serde_json::to_string(&ack).unwrap()
}
fn frames_line() -> String {
let frame = ContextFrame {
id: "frm_1".into(),
kind: FrameKind::Doc,
title: "README".into(),
content: "hello from a stdio provider".into(),
uri: Some("file:///README.md".into()),
score: 0.7,
token_cost: 12,
valid_from: None,
valid_to: None,
recorded_at: None,
provenance: vec![],
citation_label: Some("README.md".into()),
embedding: None,
relations: vec![],
};
let env = Envelope::Frames {
result: ContextQueryResult {
frames: vec![frame],
truncated: false,
dropped_estimate: None,
},
};
serde_json::to_string(&env).unwrap()
}
fn sample_query() -> ContextQuery {
ContextQuery {
goal: "g".into(),
query_text: None,
embedding: None,
kinds: vec![],
anchors: vec![],
max_frames: 5,
max_tokens: 4000,
as_of: None,
}
}
#[tokio::test]
async fn full_handshake_and_query_round_trip_over_stdio() {
let script = format!(
"read h; printf '%s\\n' '{}'; read q; printf '%s\\n' '{}'",
ack_line(PROTOCOL_VERSION),
frames_line()
);
let (program, args) = bash_provider(&script);
let provider = StdioProvider::spawn("docs", &program, &args)
.await
.expect("handshake should succeed");
assert_eq!(provider.id(), "docs");
assert_eq!(provider.info().name, "bash-fixture");
assert!(provider.capabilities().query.kinds.contains(&"doc".into()));
let result = provider.query(&sample_query()).await.expect("query ok");
assert_eq!(result.frames.len(), 1);
assert_eq!(result.frames[0].title, "README");
}
#[tokio::test]
async fn an_incompatible_protocol_version_is_a_named_error_not_a_hang() {
let script = format!("read h; printf '%s\\n' '{}'", ack_line("ocp/2.0"));
let (program, args) = bash_provider(&script);
let err = match StdioProvider::spawn("docs", &program, &args).await {
Ok(_) => panic!("a version mismatch must reject the provider"),
Err(e) => e,
};
match err {
HostError::VersionMismatch {
provider_version, ..
} => assert_eq!(provider_version, "ocp/2.0"),
other => panic!("expected VersionMismatch, got {other}"),
}
}
#[tokio::test]
async fn a_child_dying_after_handshake_surfaces_as_provider_crashed() {
let script = format!(
"read h; printf '%s\\n' '{}'; exit 0",
ack_line(PROTOCOL_VERSION)
);
let (program, args) = bash_provider(&script);
let provider = StdioProvider::spawn("docs", &program, &args)
.await
.expect("handshake ok");
let err = provider
.query(&sample_query())
.await
.expect_err("a dead child must error, not hang");
assert!(
matches!(err, HostError::ProviderCrashed { .. }),
"expected ProviderCrashed, got {err}"
);
}
#[tokio::test]
async fn the_child_is_spawned_with_a_scrubbed_environment() {
let injected = ["PWD", "SHLVL", "_", "HOME", "PATH", "OLDPWD"];
let leaked = std::env::vars()
.map(|(k, _)| k)
.find(|k| !injected.contains(&k.as_str()) && !k.is_empty())
.expect("the test process has at least one non-allowlisted env var");
let mut conn = RawStdioConnection::spawn("bash", &["-c".into(), "env".into()])
.await
.expect("spawn env");
let mut child_keys = Vec::new();
while let Some(line) = conn.read_raw_line().await.expect("read env line") {
if let Some((key, _)) = line.trim_end().split_once('=') {
child_keys.push(key.to_string());
}
}
assert!(
!child_keys.contains(&leaked),
"scrubbed child leaked parent env var `{leaked}` — credentials must not cross (§3.5)"
);
}
}