use ocp_types::{Capabilities, ContextQuery, ContextQueryResult, ProviderInfo};
use serde::{Deserialize, Serialize};
use crate::error::HostError;
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Envelope {
Handshake { protocol_version: String },
HandshakeAck {
protocol_version: String,
provider: ProviderInfo,
capabilities: Capabilities,
},
Query { query: ContextQuery },
Frames { result: ContextQueryResult },
Shutdown,
Error { message: String },
}
pub fn envelope_kind(env: &Envelope) -> &'static str {
match env {
Envelope::Handshake { .. } => "handshake",
Envelope::HandshakeAck { .. } => "handshake_ack",
Envelope::Query { .. } => "query",
Envelope::Frames { .. } => "frames",
Envelope::Shutdown => "shutdown",
Envelope::Error { .. } => "error",
}
}
pub fn encode_line(env: &Envelope) -> Result<String, HostError> {
let mut line = serde_json::to_string(env).map_err(|e| HostError::Wire(e.to_string()))?;
line.push('\n');
Ok(line)
}
pub fn decode_line(line: &str) -> Result<Envelope, HostError> {
serde_json::from_str(line.trim_end()).map_err(|e| HostError::Wire(e.to_string()))
}
pub fn versions_compatible(a: &str, b: &str) -> bool {
protocol_family(a) == protocol_family(b)
}
fn protocol_family(version: &str) -> &str {
match version.split_once('.') {
Some((family, _)) => family,
None => version,
}
}
#[cfg(test)]
mod tests {
use super::*;
use ocp_types::capability::QueryCapability;
use ocp_types::{DataFlow, FrameKind, PROTOCOL_VERSION};
fn sample_ack() -> Envelope {
Envelope::HandshakeAck {
protocol_version: PROTOCOL_VERSION.to_string(),
provider: ProviderInfo {
name: "ocp-docs".into(),
version: "0.1.0".into(),
data_flow: DataFlow {
reads: true,
writes: false,
egress: false,
},
},
capabilities: Capabilities {
query: QueryCapability {
kinds: vec!["doc".into()],
filters: vec![],
},
..Capabilities::default()
},
}
}
#[test]
fn envelope_kind_matches_the_serialized_type_tag_for_every_variant() {
let variants: Vec<Envelope> = vec![
Envelope::Handshake {
protocol_version: PROTOCOL_VERSION.to_string(),
},
sample_ack(),
Envelope::Query {
query: ContextQuery {
goal: "g".into(),
query_text: None,
embedding: None,
kinds: vec![],
anchors: vec![],
max_frames: 1,
max_tokens: 1,
as_of: None,
},
},
Envelope::Frames {
result: ContextQueryResult {
frames: vec![],
truncated: false,
dropped_estimate: None,
},
},
Envelope::Shutdown,
Envelope::Error {
message: "m".into(),
},
];
for env in &variants {
let value: serde_json::Value =
serde_json::from_str(encode_line(env).unwrap().trim_end()).unwrap();
assert_eq!(
value["type"].as_str(),
Some(envelope_kind(env)),
"envelope_kind drifted from the serde tag for {env:?}"
);
}
}
#[test]
fn envelope_roundtrips_through_a_single_ndjson_line() {
let env = sample_ack();
let line = encode_line(&env).unwrap();
assert!(line.ends_with('\n'), "a frame is exactly one line");
assert_eq!(line.matches('\n').count(), 1, "no embedded newlines");
let back = decode_line(&line).unwrap();
assert_eq!(back, env);
}
#[test]
fn query_envelope_carries_ocp_types_shapes_verbatim() {
let query = ContextQuery {
goal: "fix the failing test".into(),
query_text: None,
embedding: None,
kinds: vec![FrameKind::Doc],
anchors: vec![],
max_frames: 5,
max_tokens: 2000,
as_of: None,
};
let env = Envelope::Query {
query: query.clone(),
};
let line = encode_line(&env).unwrap();
match decode_line(&line).unwrap() {
Envelope::Query { query: back } => assert_eq!(back, query),
other => panic!("expected query, got {}", envelope_kind(&other)),
}
}
#[test]
fn a_garbage_line_is_a_clean_wire_error_never_a_panic() {
let err = decode_line("this is not json {{{").unwrap_err();
assert!(matches!(err, HostError::Wire(_)));
}
#[test]
fn version_families_interoperate_within_a_major_but_not_across() {
assert!(versions_compatible("ocp/1.0-draft", "ocp/1.0"));
assert!(versions_compatible("ocp/1.0-draft", "ocp/1.0-draft"));
assert!(versions_compatible(PROTOCOL_VERSION, "ocp/1.9"));
assert!(!versions_compatible("ocp/1.0-draft", "ocp/2.0"));
assert!(!versions_compatible("ocp/1.0", "mcp/1.0"));
}
}