use std::cmp::Ordering;
use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
use serde::{Deserialize, Serialize};
use serde_json::Value;
mod proof;
mod strict_json;
pub mod authoring;
pub use proof::{
canonicalize_proof_value, child_proof_message, handshake_params_digest, host_proof_message,
};
pub use strict_json::{MAX_STRICT_JSON_NESTING, decode_strict, encode_compact};
pub const PROCESS_PROFILE: &str = "lenso-process-jsonrpc-http-v1";
pub const VALUE_PROFILE: &str = "lenso-json-value-v1";
pub const PROVIDE_REQUEST_PROFILE: &str = "provide-request-v1";
pub const HANDSHAKE_METHOD: &str = "lenso.process.v1.handshake";
pub const REQUEST_METHOD: &str = "lenso.process.v1.request";
pub const CANCEL_METHOD: &str = "lenso.process.v1.cancel";
pub const SHUTDOWN_METHOD: &str = "lenso.process.v1.shutdown";
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ReadinessRecord {
pub protocol: String,
pub data_port: u16,
pub control_port: u16,
}
impl ReadinessRecord {
pub fn validate(&self) -> Result<(), ProtocolError> {
if self.protocol != PROCESS_PROFILE {
return Err(ProtocolError::new("unsupported Process Protocol profile"));
}
if self.data_port == 0 || self.control_port == 0 || self.data_port == self.control_port {
return Err(ProtocolError::new(
"readiness requires distinct non-zero data and control ports",
));
}
Ok(())
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ProtocolError {
detail: String,
}
impl ProtocolError {
fn new(detail: impl Into<String>) -> Self {
Self {
detail: detail.into(),
}
}
#[must_use]
pub fn detail(&self) -> &str {
&self.detail
}
}
impl std::fmt::Display for ProtocolError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(&self.detail)
}
}
impl std::error::Error for ProtocolError {}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PeerLimits {
pub max_http_body_bytes: u64,
pub max_control_http_body_bytes: u64,
pub max_concurrent_requests: u32,
pub child_request_queue_capacity: u32,
pub max_retired_correlation_ids: u32,
pub control_queue_capacity: u32,
}
impl PeerLimits {
#[must_use]
pub const fn v1_defaults() -> Self {
Self {
max_http_body_bytes: 65_536,
max_control_http_body_bytes: 16_384,
max_concurrent_requests: 32,
child_request_queue_capacity: 32,
max_retired_correlation_ids: 65_536,
control_queue_capacity: 32,
}
}
pub fn validate(&self) -> Result<(), ProtocolError> {
validate_limit("max_http_body_bytes", self.max_http_body_bytes, 1_048_576)?;
validate_limit(
"max_control_http_body_bytes",
self.max_control_http_body_bytes,
65_536,
)?;
validate_limit(
"max_concurrent_requests",
u64::from(self.max_concurrent_requests),
256,
)?;
validate_limit(
"child_request_queue_capacity",
u64::from(self.child_request_queue_capacity),
1_024,
)?;
validate_limit(
"max_retired_correlation_ids",
u64::from(self.max_retired_correlation_ids),
1_048_576,
)?;
validate_limit(
"control_queue_capacity",
u64::from(self.control_queue_capacity),
256,
)
}
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OperationDescriptor {
pub operation: String,
pub interaction: InteractionKind,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum InteractionKind {
Request,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CapabilityDescriptor {
pub capability_id: String,
pub descriptor_version: String,
pub descriptor_digest: String,
pub operations: Vec<OperationDescriptor>,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OutboundBindingDescriptor {
pub binding_id: String,
pub capability_id: String,
pub descriptor_version: String,
pub descriptor_digest: String,
pub provider_instance: String,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HandshakeIdentity {
pub protocol_profile: String,
pub value_profile: String,
pub plugin_instance: String,
pub plugin_generation: String,
pub generation_spec_digest: String,
pub artifact_digest: String,
pub effective_host_grant_set_digest: String,
pub interaction_profiles: Vec<String>,
pub provided_capabilities: Vec<CapabilityDescriptor>,
pub outbound_bindings: Vec<OutboundBindingDescriptor>,
pub peer_limits: PeerLimits,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HandshakeParams {
pub identity: HandshakeIdentity,
pub host_nonce: String,
pub host_proof: String,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HandshakeResult {
pub identity: HandshakeIdentity,
pub session: String,
pub child_proof: String,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InvocationExtension {
pub key: String,
pub value: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub issuer: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub audience: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub proof: Option<String>,
#[serde(default, skip_serializing_if = "is_false")]
pub sealed: bool,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestParams {
pub session: String,
pub correlation_id: String,
pub capability_id: String,
pub descriptor_version: String,
pub descriptor_digest: String,
pub operation: String,
pub interaction: InteractionKind,
pub caller_instance: Option<String>,
pub remaining_timeout_nanos: Option<String>,
#[serde(default)]
pub extensions: Vec<InvocationExtension>,
pub payload: Value,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestResult {
pub session: String,
pub correlation_id: String,
pub outcome: ProcessOutcome,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum ProcessOutcome {
Success { value: Value },
Domain { error: Value },
Runtime { failure: ChildRuntimeFailure },
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum ChildRuntimeFailure {
ResourceExhausted { operation: String },
PluginFailure { detail: String },
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CancelParams {
pub session: String,
pub correlation_id: String,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ShutdownParams {
pub session: String,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ControlAck {
pub session: String,
pub accepted: bool,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct JsonRpcRequest<T> {
pub jsonrpc: String,
pub id: String,
pub method: String,
pub params: T,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct JsonRpcSuccess<T> {
pub jsonrpc: String,
pub id: String,
pub result: T,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct JsonRpcErrorObject {
pub code: i32,
pub message: String,
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct JsonRpcError {
pub jsonrpc: String,
pub id: Option<String>,
pub error: JsonRpcErrorObject,
}
impl HandshakeIdentity {
pub fn validate(&self) -> Result<(), ProtocolError> {
if self.protocol_profile != PROCESS_PROFILE {
return Err(ProtocolError::new("unsupported Process Protocol profile"));
}
if self.value_profile != VALUE_PROFILE {
return Err(ProtocolError::new("unsupported portable value profile"));
}
validate_token("plugin_instance", &self.plugin_instance)?;
validate_decimal("plugin_generation", &self.plugin_generation)?;
validate_digest("generation_spec_digest", &self.generation_spec_digest)?;
validate_digest("artifact_digest", &self.artifact_digest)?;
validate_digest(
"effective_host_grant_set_digest",
&self.effective_host_grant_set_digest,
)?;
validate_sorted_unique("interaction_profiles", &self.interaction_profiles, Ord::cmp)?;
if self.interaction_profiles.as_slice() != [PROVIDE_REQUEST_PROFILE] {
return Err(ProtocolError::new(
"V1 requires exactly the provide-request-v1 interaction profile",
));
}
validate_sorted_unique(
"provided_capabilities",
&self.provided_capabilities,
|left, right| left.capability_id.cmp(&right.capability_id),
)?;
if self.provided_capabilities.is_empty() {
return Err(ProtocolError::new(
"at least one provided Capability is required",
));
}
for descriptor in &self.provided_capabilities {
descriptor.validate()?;
}
if !self.outbound_bindings.is_empty() {
return Err(ProtocolError::new(
"outbound bindings require a selected consume profile",
));
}
self.peer_limits.validate()
}
}
impl CapabilityDescriptor {
fn validate(&self) -> Result<(), ProtocolError> {
validate_token("capability_id", &self.capability_id)?;
validate_token("descriptor_version", &self.descriptor_version)?;
validate_digest("descriptor_digest", &self.descriptor_digest)?;
validate_sorted_unique("operations", &self.operations, |left, right| {
left.operation.cmp(&right.operation)
})?;
if self.operations.is_empty() {
return Err(ProtocolError::new(
"provided Capability operations cannot be empty",
));
}
for operation in &self.operations {
validate_token("operation", &operation.operation)?;
}
Ok(())
}
}
impl HandshakeParams {
pub fn validate(&self) -> Result<(), ProtocolError> {
self.identity.validate()?;
decode_base64url_32("host_nonce", &self.host_nonce)?;
decode_base64url_32("host_proof", &self.host_proof)?;
Ok(())
}
}
impl HandshakeResult {
pub fn validate_against(&self, expected: &HandshakeIdentity) -> Result<(), ProtocolError> {
self.identity.validate()?;
if &self.identity != expected {
return Err(ProtocolError::new("child handshake identity mismatch"));
}
decode_base64url_32("session", &self.session)?;
decode_base64url_32("child_proof", &self.child_proof)?;
Ok(())
}
}
impl RequestParams {
pub fn validate(&self) -> Result<(), ProtocolError> {
decode_base64url_32("session", &self.session)?;
validate_decimal("correlation_id", &self.correlation_id)?;
validate_token("capability_id", &self.capability_id)?;
validate_token("descriptor_version", &self.descriptor_version)?;
validate_digest("descriptor_digest", &self.descriptor_digest)?;
validate_token("operation", &self.operation)?;
if let Some(caller) = &self.caller_instance {
validate_token("caller_instance", caller)?;
}
if let Some(timeout) = &self.remaining_timeout_nanos {
validate_decimal("remaining_timeout_nanos", timeout)?;
}
validate_sorted_unique("extensions", &self.extensions, |left, right| {
left.key.cmp(&right.key)
})?;
for extension in &self.extensions {
extension.validate()?;
}
Ok(())
}
}
impl InvocationExtension {
fn validate(&self) -> Result<(), ProtocolError> {
validate_token("extension key", &self.key)?;
let decoded = base64::engine::general_purpose::STANDARD
.decode(&self.value)
.map_err(|_| ProtocolError::new("extension value must be padded Base64"))?;
if base64::engine::general_purpose::STANDARD.encode(decoded) != self.value {
return Err(ProtocolError::new(
"extension value must use canonical padded Base64",
));
}
validate_sorted_unique("extension audience", &self.audience, |left, right| {
left.cmp(right)
})?;
Ok(())
}
}
impl RequestResult {
pub fn validate(&self) -> Result<(), ProtocolError> {
decode_base64url_32("session", &self.session)?;
validate_decimal("correlation_id", &self.correlation_id)?;
if let ProcessOutcome::Runtime { failure } = &self.outcome {
match failure {
ChildRuntimeFailure::ResourceExhausted { operation } => {
validate_token("operation", operation)?;
}
ChildRuntimeFailure::PluginFailure { detail } => {
if detail.is_empty() || detail.len() > 1_024 {
return Err(ProtocolError::new(
"Plugin Failure detail must contain 1..=1024 bytes",
));
}
}
}
}
Ok(())
}
}
impl CancelParams {
pub fn validate(&self) -> Result<(), ProtocolError> {
decode_base64url_32("session", &self.session)?;
validate_decimal("correlation_id", &self.correlation_id).map(|_| ())
}
}
impl ShutdownParams {
pub fn validate(&self) -> Result<(), ProtocolError> {
decode_base64url_32("session", &self.session)?;
Ok(())
}
}
impl ControlAck {
pub fn validate(&self) -> Result<(), ProtocolError> {
decode_base64url_32("session", &self.session)?;
if !self.accepted {
return Err(ProtocolError::new(
"control acknowledgement must be accepted",
));
}
Ok(())
}
}
impl<T> JsonRpcRequest<T> {
pub fn validate_envelope(&self, expected_method: &str) -> Result<(), ProtocolError> {
if self.jsonrpc != "2.0" {
return Err(ProtocolError::new("jsonrpc must equal 2.0"));
}
validate_decimal("JSON-RPC id", &self.id)?;
if self.method != expected_method {
return Err(ProtocolError::new("unexpected JSON-RPC method"));
}
Ok(())
}
}
impl<T> JsonRpcSuccess<T> {
pub fn validate_envelope(&self, expected_id: &str) -> Result<(), ProtocolError> {
if self.jsonrpc != "2.0" {
return Err(ProtocolError::new("jsonrpc must equal 2.0"));
}
validate_decimal("JSON-RPC id", &self.id)?;
if self.id != expected_id {
return Err(ProtocolError::new("JSON-RPC response id mismatch"));
}
Ok(())
}
}
impl JsonRpcError {
pub fn validate(&self) -> Result<(), ProtocolError> {
if self.jsonrpc != "2.0" {
return Err(ProtocolError::new("jsonrpc must equal 2.0"));
}
if let Some(id) = &self.id {
validate_decimal("JSON-RPC id", id)?;
}
if !matches!(self.error.code, -32700 | -32600 | -32601 | -32602 | -32603) {
return Err(ProtocolError::new("unsupported JSON-RPC error code"));
}
if self.error.message.is_empty() || self.error.message.len() > 256 {
return Err(ProtocolError::new(
"JSON-RPC error message must contain 1..=256 bytes",
));
}
Ok(())
}
}
fn validate_limit(name: &str, value: u64, maximum: u64) -> Result<(), ProtocolError> {
if value == 0 || value > maximum {
return Err(ProtocolError::new(format!(
"{name} must be within 1..={maximum}"
)));
}
Ok(())
}
fn validate_token(name: &str, value: &str) -> Result<(), ProtocolError> {
if value.is_empty()
|| value.len() > 256
|| !value.bytes().all(|byte| {
byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-' | b'@' | b'/' | b':')
})
{
return Err(ProtocolError::new(format!(
"{name} must be a 1..=256 byte portable token"
)));
}
Ok(())
}
fn validate_decimal(name: &str, value: &str) -> Result<u64, ProtocolError> {
if value.is_empty()
|| (value.len() > 1 && value.starts_with('0'))
|| !value.bytes().all(|byte| byte.is_ascii_digit())
{
return Err(ProtocolError::new(format!(
"{name} must be a canonical non-negative decimal string"
)));
}
value.parse::<u64>().map_err(|_| {
ProtocolError::new(format!(
"{name} exceeds the unsigned 64-bit decimal profile"
))
})
}
fn validate_digest(name: &str, value: &str) -> Result<(), ProtocolError> {
let Some(hex) = value.strip_prefix("sha256:") else {
return Err(ProtocolError::new(format!(
"{name} must use a sha256: prefix"
)));
};
if hex.len() != 64
|| !hex
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
{
return Err(ProtocolError::new(format!(
"{name} must contain 64 lowercase hexadecimal characters"
)));
}
Ok(())
}
fn decode_base64url_32(name: &str, value: &str) -> Result<[u8; 32], ProtocolError> {
let decoded = URL_SAFE_NO_PAD
.decode(value)
.map_err(|_| ProtocolError::new(format!("{name} must be canonical base64url")))?;
let decoded: [u8; 32] = decoded
.try_into()
.map_err(|_| ProtocolError::new(format!("{name} must encode exactly 32 bytes")))?;
if URL_SAFE_NO_PAD.encode(decoded) != value {
return Err(ProtocolError::new(format!(
"{name} must be canonical unpadded base64url"
)));
}
Ok(decoded)
}
fn validate_sorted_unique<T>(
name: &str,
values: &[T],
compare: impl Fn(&T, &T) -> Ordering,
) -> Result<(), ProtocolError> {
if values
.windows(2)
.any(|pair| compare(&pair[0], &pair[1]) != Ordering::Less)
{
return Err(ProtocolError::new(format!(
"{name} must be strictly canonical-sorted and unique"
)));
}
Ok(())
}
#[allow(clippy::trivially_copy_pass_by_ref)]
const fn is_false(value: &bool) -> bool {
!*value
}