Ids become gamecult.model.*.v3. Every document is encoded by one named MessagePack codec in contract.rs with unknown fields refused, and publishes a JSON Schema generated from its type (schemas/). The envelope's ciphertext is binary. Each frame is a cultnet.operation_request.v0 / operation_response.v0 for service gamecult.model.connector, operation invoke, its message_id the request id, its payload the base64 of the sealed envelope; the carriage is checked before any decryption. frame_bytes_for_payload and payload_bytes_for_frame measure the carriage. Golden v3 fixtures and their generator (tests/wire_golden_v3.rs) pin drift. The test debt of the kit lift (each identity field, each contract_refusal arm, request ids measured in bytes) is paid in the rewritten code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
229 lines
7.9 KiB
Rust
229 lines
7.9 KiB
Rust
use std::net::{SocketAddr, TcpStream};
|
|
use std::time::Duration;
|
|
|
|
use thiserror::Error;
|
|
use zeroize::Zeroizing;
|
|
|
|
use crate::contract::{TransportInvocation, TransportKey, TransportResult};
|
|
use crate::envelope::{
|
|
MAX_IDENTITY_BYTES, ServiceError, TransportFrameError, decode_result_frame, decrypt_result,
|
|
encode_invocation_frame, encrypt_invocation, read_transport_frame, write_transport_frame,
|
|
};
|
|
|
|
#[derive(Clone)]
|
|
pub struct ConnectorClient {
|
|
endpoint: SocketAddr,
|
|
security: TransportKey,
|
|
max_frame_bytes: usize,
|
|
response_timeout: Option<Duration>,
|
|
}
|
|
|
|
impl ConnectorClient {
|
|
pub fn new(
|
|
endpoint: SocketAddr,
|
|
connection_key: impl Into<String>,
|
|
max_frame_bytes: usize,
|
|
response_timeout: Option<Duration>,
|
|
) -> Result<Self, ConnectorClientError> {
|
|
if endpoint.port() == 0
|
|
|| endpoint.ip().is_unspecified()
|
|
|| endpoint.ip().is_multicast()
|
|
|| endpoint.ip() == std::net::Ipv4Addr::BROADCAST
|
|
|| !(4096..=u32::MAX as usize).contains(&max_frame_bytes)
|
|
|| response_timeout.is_some_and(|timeout| timeout.is_zero())
|
|
{
|
|
return Err(ConnectorClientError::InvalidConfig);
|
|
}
|
|
let connection_key = Zeroizing::new(connection_key.into());
|
|
let security = TransportKey::from_connection_secret(connection_key.as_str())?;
|
|
Ok(Self {
|
|
endpoint,
|
|
security,
|
|
max_frame_bytes,
|
|
response_timeout,
|
|
})
|
|
}
|
|
|
|
pub fn execute(
|
|
&self,
|
|
invocation: &TransportInvocation,
|
|
) -> Result<TransportResult, ConnectorClientError> {
|
|
if invocation.request_id().len() > MAX_IDENTITY_BYTES {
|
|
return Err(ConnectorClientError::RequestIdTooLong);
|
|
}
|
|
let request = encode_invocation_frame(&encrypt_invocation(invocation, &self.security)?)?;
|
|
let connect_timeout = self
|
|
.response_timeout
|
|
.unwrap_or(Duration::from_secs(10))
|
|
.min(Duration::from_secs(10));
|
|
let mut stream = TcpStream::connect_timeout(&self.endpoint, connect_timeout)
|
|
.map_err(ConnectorClientError::Connection)?;
|
|
stream
|
|
.set_read_timeout(self.response_timeout)
|
|
.and_then(|()| stream.set_write_timeout(self.response_timeout))
|
|
.map_err(ConnectorClientError::Connection)?;
|
|
write_transport_frame(&mut stream, &request, self.max_frame_bytes)
|
|
.map_err(client_frame_error)?;
|
|
let response =
|
|
read_transport_frame(&mut stream, self.max_frame_bytes).map_err(client_frame_error)?;
|
|
let envelope = decode_result_frame(&response)?;
|
|
decrypt_result(&envelope, &self.security, invocation).map_err(Into::into)
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod client_endpoint_tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn client_admits_explicit_unicast_and_refuses_non_destinations() {
|
|
for endpoint in ["127.0.0.1:4103", "172.19.0.1:4103", "[::1]:4103"] {
|
|
assert!(
|
|
ConnectorClient::new(
|
|
endpoint.parse().unwrap(),
|
|
"bounded-client-endpoint-key",
|
|
64 * 1024,
|
|
Some(Duration::from_secs(1)),
|
|
)
|
|
.is_ok(),
|
|
"{endpoint} should be an admissible explicit destination"
|
|
);
|
|
}
|
|
for endpoint in [
|
|
"0.0.0.0:4103",
|
|
"255.255.255.255:4103",
|
|
"224.0.0.1:4103",
|
|
"[::]:4103",
|
|
"[ff02::1]:4103",
|
|
"127.0.0.1:0",
|
|
] {
|
|
assert!(matches!(
|
|
ConnectorClient::new(
|
|
endpoint.parse().unwrap(),
|
|
"bounded-client-endpoint-key",
|
|
64 * 1024,
|
|
Some(Duration::from_secs(1)),
|
|
),
|
|
Err(ConnectorClientError::InvalidConfig)
|
|
));
|
|
}
|
|
}
|
|
}
|
|
|
|
#[derive(Debug, Error)]
|
|
pub enum ConnectorClientError {
|
|
#[error("invalid connector client configuration")]
|
|
InvalidConfig,
|
|
#[error("connector client connection failed")]
|
|
Connection(#[source] std::io::Error),
|
|
#[error("connector frame exceeded its bound")]
|
|
FrameSize,
|
|
#[error("request id is longer than the connector identity bound")]
|
|
RequestIdTooLong,
|
|
#[error(transparent)]
|
|
Transport(#[from] ServiceError),
|
|
}
|
|
|
|
fn client_frame_error(error: TransportFrameError) -> ConnectorClientError {
|
|
match error {
|
|
TransportFrameError::Connection(error) => ConnectorClientError::Connection(error),
|
|
TransportFrameError::Size => ConnectorClientError::FrameSize,
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod fixture_tests {
|
|
use super::*;
|
|
use crate::fixtures::*;
|
|
use crate::{contract::*, envelope::*};
|
|
|
|
#[test]
|
|
fn shared_client_transports_one_exact_encrypted_request_and_result() {
|
|
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
|
|
let endpoint = listener.local_addr().unwrap();
|
|
let invocation = invocation();
|
|
let expected = invocation.clone();
|
|
let security = security("epiphany-distinct-test-key");
|
|
let server = std::thread::spawn(move || {
|
|
let (mut stream, _) = listener.accept().unwrap();
|
|
let request = read_transport_frame(&mut stream, 64 * 1024).unwrap();
|
|
let envelope = decode_invocation_frame(&request).unwrap();
|
|
assert_eq!(decrypt_invocation(&envelope, &security).unwrap(), expected);
|
|
let response = encrypt_result(
|
|
&TransportResult::refused(&expected, Refusal::ModelNotAllowed),
|
|
&security,
|
|
)
|
|
.unwrap();
|
|
write_transport_frame(
|
|
&mut stream,
|
|
&encode_result_frame(&response).unwrap(),
|
|
64 * 1024,
|
|
)
|
|
.unwrap();
|
|
});
|
|
|
|
let client = ConnectorClient::new(
|
|
endpoint,
|
|
"epiphany-distinct-test-key",
|
|
64 * 1024,
|
|
Some(Duration::from_secs(1)),
|
|
)
|
|
.unwrap();
|
|
assert_eq!(
|
|
client.execute(&invocation).unwrap().disposition,
|
|
TransportDisposition::Refused(Refusal::ModelNotAllowed)
|
|
);
|
|
server.join().unwrap();
|
|
}
|
|
|
|
#[test]
|
|
fn an_over_long_request_id_is_refused_locally_before_any_byte_is_sent() {
|
|
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
|
|
listener.set_nonblocking(true).unwrap();
|
|
let client = ConnectorClient::new(
|
|
listener.local_addr().unwrap(),
|
|
"epiphany-distinct-test-key",
|
|
64 * 1024,
|
|
Some(Duration::from_secs(1)),
|
|
)
|
|
.unwrap();
|
|
let mut long = invocation();
|
|
long.request.request_id = "r".repeat(MAX_IDENTITY_BYTES + 1);
|
|
assert!(matches!(
|
|
client.execute(&long),
|
|
Err(ConnectorClientError::RequestIdTooLong)
|
|
));
|
|
assert_eq!(
|
|
listener.accept().unwrap_err().kind(),
|
|
std::io::ErrorKind::WouldBlock,
|
|
"the client must not even connect"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn the_client_measures_a_request_id_in_bytes() {
|
|
let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
|
|
listener.set_nonblocking(true).unwrap();
|
|
let client = ConnectorClient::new(
|
|
listener.local_addr().unwrap(),
|
|
"epiphany-distinct-test-key",
|
|
64 * 1024,
|
|
Some(Duration::from_secs(1)),
|
|
)
|
|
.unwrap();
|
|
// 86 characters, 258 bytes: under the bound by characters, over by bytes.
|
|
let id = "\u{20AC}".repeat(86);
|
|
assert_eq!((id.chars().count(), id.len()), (86, 258));
|
|
let mut long = invocation();
|
|
long.request.request_id = id;
|
|
assert!(matches!(
|
|
client.execute(&long),
|
|
Err(ConnectorClientError::RequestIdTooLong)
|
|
));
|
|
assert_eq!(
|
|
listener.accept().unwrap_err().kind(),
|
|
std::io::ErrorKind::WouldBlock,
|
|
"the client must not even connect"
|
|
);
|
|
}
|
|
}
|