Skip to content

Commit c2cc566

Browse files
committed
refactor(sandbox): adopt typed network mediation source
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
2 parents ac22cde + 9156aa5 commit c2cc566

11 files changed

Lines changed: 228 additions & 222 deletions

File tree

‎crates/openshell-isolation-interface/src/contract.rs‎

Lines changed: 39 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
//! `attach` is atomic from the caller's perspective: it establishes and binds
2525
//! the boundary, returns `Bound`, or fails closed. It never binds a resource
2626
//! already bound to an active boundary. Binary identity travels on every
27-
//! [`PendingNetworkOpen`], resolved for that exact socket and process
27+
//! [`PendingTcpOpen`], resolved for that exact socket and process
2828
//! generation; an unresolved identity denies the open.
2929
//!
3030
//! The contract is transport-neutral. Concrete topology implementations keep
@@ -355,17 +355,12 @@ pub trait IsolationBackend: Send + Sync {
355355
/// code is running.
356356
#[async_trait]
357357
pub trait BoundBoundary: Send {
358-
/// The mediation service's backend-neutral source of workload connections.
358+
/// The mediation service's backend-neutral source of workload network
359+
/// requests. TCP and DNS remain typed operations so consumers cannot mix
360+
/// their framing, decisions, or response semantics.
359361
/// Retained by the supervisor before consuming `Bound`.
360362
fn network_mediation_source(&self) -> Arc<dyn NetworkMediationSource>;
361363

362-
/// Optional transport for workload DNS exchanges. Backends that expose
363-
/// this source keep DNS inside the supervisor-owned policy path rather
364-
/// than granting the workload access to a resolver socket.
365-
fn dns_mediation_source(&self) -> Option<Arc<dyn DnsMediationSource>> {
366-
None
367-
}
368-
369364
/// Trusted host-side dial target for the well-known host-gateway aliases.
370365
///
371366
/// Backends return this when the mediation service runs outside the
@@ -822,7 +817,7 @@ pub trait BoundaryLoopbackConnector: Send + Sync {
822817
// ============================================================================
823818

824819
/// Executable identity for one accepted connection, resolved by the backend and
825-
/// delivered on [`PendingNetworkOpen`] before the mediation service evaluates
820+
/// delivered on [`PendingTcpOpen`] before the mediation service evaluates
826821
/// policy.
827822
///
828823
/// A missing digest is `None`, never an empty value; policy that requires an
@@ -911,12 +906,27 @@ pub struct NetworkSocketMetadata {
911906

912907
/// Typed supervisor decision for one pending TCP open.
913908
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
914-
pub enum NetworkOpenResult {
909+
pub enum TcpOpenDecision {
915910
/// L4 authorization and a bounded relay handler are ready. L7 policy still
916911
/// applies to bytes after the local connection commits.
917912
RelayReady,
918913
/// The socket remains unchanged and connect returns this positive errno.
919-
Denied { errno: i32 },
914+
Denied(TcpOpenDenial),
915+
}
916+
917+
/// Placement-neutral reason why a staged TCP open was not committed.
918+
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
919+
pub enum TcpOpenDenial {
920+
/// The admitted network policy rejected the request.
921+
PolicyDenied,
922+
/// The backend could not resolve authoritative executable identity.
923+
IdentityUnavailable,
924+
/// The requested destination could not be validated.
925+
InvalidDestination,
926+
/// A bounded mediation resource was exhausted.
927+
ResourceExhausted,
928+
/// The mediation path became unavailable before commit.
929+
MediationUnavailable,
920930
}
921931

922932
/// Timing captured while one mediated operation crosses the sandbox boundary.
@@ -947,10 +957,10 @@ impl Default for MediationTiming {
947957
/// A staged workload TCP open delivered before its local relay is committed.
948958
///
949959
/// An `Err` identity must be denied and audited. The supervisor owns
950-
/// `result`; dropping it cancels the open without changing the workload socket.
951-
pub struct PendingNetworkOpen {
960+
/// `decision`; dropping it cancels the open without changing the workload socket.
961+
pub struct PendingTcpOpen {
952962
/// Staged byte stream whose workload side is committed only after
953-
/// [`NetworkOpenResult::RelayReady`].
963+
/// [`TcpOpenDecision::RelayReady`].
954964
pub stream: BoundaryDuplexStream,
955965
/// Executable identity, resolved by the backend for this connection.
956966
pub binary_identity: Result<BinaryIdentity, ResolveError>,
@@ -963,7 +973,7 @@ pub struct PendingNetworkOpen {
963973
/// Monotonic stage timing for performance diagnostics.
964974
pub timing: MediationTiming,
965975
/// Single-use completion channel back to the sandbox broker.
966-
pub result: oneshot::Sender<NetworkOpenResult>,
976+
pub decision: oneshot::Sender<TcpOpenDecision>,
967977
}
968978

969979
/// A logical per-boundary stream of workload connections, consumed by the
@@ -972,28 +982,33 @@ pub struct PendingNetworkOpen {
972982
/// It may wrap a dedicated listener or a demultiplexed view over shared
973983
/// transport; how it reaches the separate supervisor is backend-private. A
974984
/// trusted backend component associates
975-
/// every returned connection with its active boundary without relying solely on
976-
/// a transport tuple or workload-provided identifier. An `Err` from `accept`
977-
/// means the source itself is unusable and fails the boundary closed.
985+
/// every returned request with its active boundary without relying solely on a
986+
/// transport tuple or workload-provided identifier. TCP and DNS use separate
987+
/// accepts so they can be consumed concurrently with independent backpressure.
988+
/// An `Err` means that mediation lane is unusable and fails closed.
978989
#[async_trait]
979990
pub trait NetworkMediationSource: Send + Sync {
980991
/// Await the next staged workload TCP open.
981-
async fn accept(&self) -> Result<PendingNetworkOpen, BackendError>;
992+
async fn accept_tcp(&self) -> Result<PendingTcpOpen, BackendError>;
993+
994+
/// Await the next workload DNS query.
995+
async fn accept_dns(&self) -> Result<PendingDnsQuery, BackendError>;
982996
}
983997

984998
/// DNS transport used by one workload exchange.
985999
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
9861000
pub enum DnsTransport {
9871001
/// One DNS wire datagram without a TCP length prefix.
9881002
Udp,
989-
/// One two-byte-length-prefixed DNS message.
1003+
/// One DNS message received over a TCP resolver connection.
9901004
Tcp,
9911005
}
9921006

9931007
/// One workload DNS request and its fail-closed response channel.
994-
pub struct MediatedDnsQuery {
995-
/// DNS request bytes in the framing selected by [`Self::transport`].
996-
pub request: Vec<u8>,
1008+
pub struct PendingDnsQuery {
1009+
/// Exactly one DNS wire message, without a DNS-over-TCP length prefix.
1010+
/// The backend removes and restores transport framing.
1011+
pub message: Vec<u8>,
9971012
/// Workload DNS transport.
9981013
pub transport: DnsTransport,
9991014
/// Identity of the process that issued the DNS request when the backend
@@ -1007,11 +1022,3 @@ pub struct MediatedDnsQuery {
10071022
/// Single-use response channel owned by the backend adapter.
10081023
pub response: oneshot::Sender<Result<Vec<u8>, BackendError>>,
10091024
}
1010-
1011-
/// Logical per-boundary stream of DNS exchanges. The backend handles syscall,
1012-
/// packet, or guest-agent transport details; the supervisor owns policy DNS.
1013-
#[async_trait]
1014-
pub trait DnsMediationSource: Send + Sync {
1015-
/// Await the next DNS query from this boundary.
1016-
async fn accept(&self) -> Result<MediatedDnsQuery, BackendError>;
1017-
}

‎crates/openshell-isolation-interface/src/mediation.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ pub struct MediationFrame {
5050

5151
#[derive(Clone, Debug, Serialize, Deserialize)]
5252
pub struct DnsQueryWire {
53-
pub request: Vec<u8>,
53+
pub message: Vec<u8>,
5454
pub transport: DnsTransport,
5555
pub identity: BinaryIdentityWire,
5656
pub timing: MediationTimingWire,

‎crates/openshell-isolation-interface/src/remote.rs‎

Lines changed: 26 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,10 @@ use crate::AgentSpec;
2020
use crate::contract::{
2121
BackendError, BoundBoundary, BoundaryDuplexStream, BoundaryExec, BoundaryExitStatus,
2222
BoundaryInput, BoundaryLoopbackConnector, BoundaryOutput, BoundaryProcess, BoundarySignal,
23-
BoundaryTerminal, ConfirmedBoundary, DnsMediationSource, ExecSession, ExecSpec,
24-
IsolationBackend, LoopbackTarget, MediatedDnsQuery, MediationTiming, NetworkMediationSource,
25-
NetworkOpenResult, PendingNetworkOpen, ProcessAttachment, ReadyBoundary, RunningBoundary,
26-
SandboxContext, VerifiedTopologyDescriptor,
23+
BoundaryTerminal, ConfirmedBoundary, ExecSession, ExecSpec, IsolationBackend, LoopbackTarget,
24+
MediationTiming, NetworkMediationSource, PendingDnsQuery, PendingTcpOpen, ProcessAttachment,
25+
ReadyBoundary, RunningBoundary, SandboxContext, TcpOpenDecision, TcpOpenDenial,
26+
VerifiedTopologyDescriptor,
2727
};
2828
use async_trait::async_trait;
2929
use hyper_util::rt::TokioIo;
@@ -53,13 +53,13 @@ const MIN_BOOTSTRAP_TOKEN_BYTES: usize = 32;
5353

5454
/// Host-side remote boundary implementation registered with the supervisor.
5555
#[derive(Debug)]
56-
pub struct RemoteIsolationBackend {
56+
pub struct OpenShellRuntimeBackend {
5757
backend_name: String,
5858
ca_file_paths: Arc<std::sync::Mutex<Option<(PathBuf, PathBuf)>>>,
5959
provider_credentials: openshell_core::provider_credentials::ProviderCredentialState,
6060
}
6161

62-
impl RemoteIsolationBackend {
62+
impl OpenShellRuntimeBackend {
6363
pub fn new(
6464
backend_name: impl Into<String>,
6565
ca_file_paths: Arc<std::sync::Mutex<Option<(PathBuf, PathBuf)>>>,
@@ -74,7 +74,7 @@ impl RemoteIsolationBackend {
7474
}
7575

7676
#[async_trait]
77-
impl IsolationBackend for RemoteIsolationBackend {
77+
impl IsolationBackend for OpenShellRuntimeBackend {
7878
fn backend_name(&self) -> &str {
7979
&self.backend_name
8080
}
@@ -112,10 +112,7 @@ impl IsolationBackend for RemoteIsolationBackend {
112112
agent: sandbox.agent,
113113
policy: sandbox.policy,
114114
sandbox_id: sandbox.sandbox_id,
115-
mediation: Arc::new(RemoteNetworkMediation {
116-
client: client.clone(),
117-
}),
118-
dns_mediation: Arc::new(RemoteDnsMediation { client }),
115+
mediation: Arc::new(RemoteNetworkMediation { client }),
119116
host_gateway_ip,
120117
ca_file_paths: self.ca_file_paths.clone(),
121118
provider_credentials: self.provider_credentials.clone(),
@@ -274,7 +271,6 @@ struct RemoteBound {
274271
policy: openshell_core::policy::SandboxPolicy,
275272
sandbox_id: String,
276273
mediation: Arc<RemoteNetworkMediation>,
277-
dns_mediation: Arc<RemoteDnsMediation>,
278274
host_gateway_ip: Option<std::net::IpAddr>,
279275
ca_file_paths: Arc<std::sync::Mutex<Option<(PathBuf, PathBuf)>>>,
280276
provider_credentials: openshell_core::provider_credentials::ProviderCredentialState,
@@ -291,10 +287,6 @@ impl BoundBoundary for RemoteBound {
291287
self.mediation.clone()
292288
}
293289

294-
fn dns_mediation_source(&self) -> Option<Arc<dyn DnsMediationSource>> {
295-
Some(self.dns_mediation.clone())
296-
}
297-
298290
fn host_gateway_ip(&self) -> Option<std::net::IpAddr> {
299291
self.host_gateway_ip
300292
}
@@ -753,7 +745,7 @@ struct RemoteNetworkMediation {
753745

754746
#[async_trait]
755747
impl NetworkMediationSource for RemoteNetworkMediation {
756-
async fn accept(&self) -> Result<PendingNetworkOpen, BackendError> {
748+
async fn accept_tcp(&self) -> Result<PendingTcpOpen, BackendError> {
757749
let (stream, response) = self.client.open_exchange(Request::AcceptNetwork).await?;
758750
let Response::NetworkConnected {
759751
identity,
@@ -765,10 +757,10 @@ impl NetworkMediationSource for RemoteNetworkMediation {
765757
else {
766758
return Err(unexpected_response("network_connected", &response));
767759
};
768-
let (result, completion) = tokio::sync::oneshot::channel();
760+
let (decision, completion) = tokio::sync::oneshot::channel();
769761
let (proxy_stream, transport_stream) = tokio::io::duplex(64 * 1024);
770762
tokio::spawn(complete_network_open(stream, transport_stream, completion));
771-
Ok(PendingNetworkOpen {
763+
Ok(PendingTcpOpen {
772764
stream: Box::new(proxy_stream),
773765
binary_identity: identity.into_result(),
774766
destination,
@@ -781,19 +773,11 @@ impl NetworkMediationSource for RemoteNetworkMediation {
781773
sandbox_queue_wait: Duration::from_micros(timing.queue_wait_us),
782774
supervisor_received_at: Instant::now(),
783775
},
784-
result,
776+
decision,
785777
})
786778
}
787-
}
788779

789-
/// Pulls sandbox DNS wire exchanges over authenticated control streams.
790-
struct RemoteDnsMediation {
791-
client: Arc<BoundaryClient>,
792-
}
793-
794-
#[async_trait]
795-
impl DnsMediationSource for RemoteDnsMediation {
796-
async fn accept(&self) -> Result<MediatedDnsQuery, BackendError> {
780+
async fn accept_dns(&self) -> Result<PendingDnsQuery, BackendError> {
797781
loop {
798782
let session = self.client.mediation_session().await?;
799783
match session.accept_dns().await {
@@ -808,11 +792,11 @@ impl DnsMediationSource for RemoteDnsMediation {
808792
async fn complete_network_open(
809793
mut boundary: BoundaryDuplexStream,
810794
mut transport: tokio::io::DuplexStream,
811-
completion: tokio::sync::oneshot::Receiver<NetworkOpenResult>,
795+
completion: tokio::sync::oneshot::Receiver<TcpOpenDecision>,
812796
) {
813-
let decision = completion.await.unwrap_or(NetworkOpenResult::Denied {
814-
errno: cancellation_errno(),
815-
});
797+
let decision = completion
798+
.await
799+
.unwrap_or(TcpOpenDecision::Denied(TcpOpenDenial::MediationUnavailable));
816800
let Ok(payload) = serde_json::to_vec(&decision) else {
817801
return;
818802
};
@@ -826,22 +810,11 @@ async fn complete_network_open(
826810
{
827811
return;
828812
}
829-
if matches!(decision, NetworkOpenResult::RelayReady) {
813+
if matches!(decision, TcpOpenDecision::RelayReady) {
830814
let _ = tokio::io::copy_bidirectional(&mut boundary, &mut transport).await;
831815
}
832816
}
833817

834-
const fn cancellation_errno() -> i32 {
835-
#[cfg(unix)]
836-
{
837-
libc::ECANCELED
838-
}
839-
#[cfg(not(unix))]
840-
{
841-
125
842-
}
843-
}
844-
845818
const MEDIATION_EVENT_QUEUE: usize = 256;
846819
struct OutboundMediationFrame {
847820
kind: MediationFrameKind,
@@ -850,7 +823,7 @@ struct OutboundMediationFrame {
850823
}
851824

852825
struct ClientMediationSession {
853-
dns: tokio::sync::Mutex<tokio::sync::mpsc::Receiver<MediatedDnsQuery>>,
826+
dns: tokio::sync::Mutex<tokio::sync::mpsc::Receiver<PendingDnsQuery>>,
854827
healthy: Arc<AtomicBool>,
855828
}
856829

@@ -875,7 +848,7 @@ impl ClientMediationSession {
875848
self.healthy.load(Ordering::Acquire)
876849
}
877850

878-
async fn accept_dns(&self) -> Result<MediatedDnsQuery, BackendError> {
851+
async fn accept_dns(&self) -> Result<PendingDnsQuery, BackendError> {
879852
self.dns.lock().await.recv().await.ok_or_else(|| {
880853
BackendError::Unavailable("persistent DNS mediation session ended".to_string())
881854
})
@@ -884,7 +857,7 @@ impl ClientMediationSession {
884857

885858
async fn run_client_mediation(
886859
stream: BoundaryDuplexStream,
887-
dns_tx: tokio::sync::mpsc::Sender<MediatedDnsQuery>,
860+
dns_tx: tokio::sync::mpsc::Sender<PendingDnsQuery>,
888861
) -> std::io::Result<()> {
889862
let (mut reader, mut writer) = tokio::io::split(stream);
890863
let (outbound_tx, mut outbound_rx) =
@@ -913,7 +886,7 @@ async fn run_client_mediation(
913886

914887
async fn dispatch_client_mediation_frame(
915888
frame: MediationFrame,
916-
dns_tx: &tokio::sync::mpsc::Sender<MediatedDnsQuery>,
889+
dns_tx: &tokio::sync::mpsc::Sender<PendingDnsQuery>,
917890
outbound: &tokio::sync::mpsc::Sender<OutboundMediationFrame>,
918891
) -> std::io::Result<()> {
919892
match frame.kind {
@@ -941,8 +914,8 @@ async fn dispatch_client_mediation_frame(
941914
}
942915
});
943916
dns_tx
944-
.send(MediatedDnsQuery {
945-
request: query.request,
917+
.send(PendingDnsQuery {
918+
message: query.message,
946919
transport: query.transport,
947920
binary_identity: query.identity.into_result(),
948921
timing: MediationTiming {
@@ -1717,7 +1690,7 @@ mod tests {
17171690
let session = ClientMediationSession::start(Box::new(client_stream));
17181691
let server = tokio::spawn(async move {
17191692
let query = DnsQueryWire {
1720-
request: vec![1, 2, 3],
1693+
message: vec![1, 2, 3],
17211694
transport: crate::contract::DnsTransport::Udp,
17221695
identity: crate::boundary_protocol::BinaryIdentityWire::Resolved {
17231696
binary_path: PathBuf::from("/usr/bin/dig"),
@@ -1747,7 +1720,7 @@ mod tests {
17471720
);
17481721
});
17491722
let query = session.accept_dns().await.unwrap();
1750-
assert_eq!(query.request, [1, 2, 3]);
1723+
assert_eq!(query.message, [1, 2, 3]);
17511724
assert_eq!(
17521725
query.binary_identity.unwrap().binary_path,
17531726
PathBuf::from("/usr/bin/dig")

0 commit comments

Comments
 (0)