//! One generation-aware registry for native and kernel-backed capabilities. use std::collections::BTreeMap;use std::fmt;use std::sync::{Arc, Mutex, Weak}; use crate::accounting::{LimitError, Reservation, ResourceClass, ResourceLedger}; pub type CapabilityId = u64;/// Capability IDs are never recycled within one VM/session generation, so the/// per-capability generation remains one. The session generation is part of/// every validated identity and distinguishes separate VM lifetimes.pub type CapabilityGeneration = u64;pub type SessionGeneration = u64; const NON_RECYCLING_CAPABILITY_GENERATION: CapabilityGeneration = 1; #[derive(Clone, Copy, Debug, Eq, PartialEq)]pub enum CapabilityKind { TcpSocket, TcpListener, UnixSocket, UnixListener, UdpSocket, TlsTransport, Http2Connection, Http2Stream,} impl CapabilityKind { pub const fn is_socket(self) -> bool { matches!( self, Self::TcpSocket | Self::TcpListener | Self::UnixSocket | Self::UnixListener | Self::UdpSocket | Self::Http2Connection ) } pub const fn is_connection(self) -> bool { matches!( self, Self::TcpSocket | Self::UnixSocket | Self::Http2Connection ) }} #[derive(Clone, Debug, Eq, PartialEq)]pub enum CapabilityBackend { Native { local_id: String }, Kernel { socket_id: u64 },} #[derive(Clone, Copy, Debug, Eq, PartialEq)]pub enum CapabilityLifecycle { Allocating, Open, Closing, Failed, Closed,} #[derive(Clone, Debug, Eq, PartialEq)]pub struct CapabilitySnapshot { pub session_generation: SessionGeneration, pub id: CapabilityId, pub generation: CapabilityGeneration, pub kind: CapabilityKind, pub backend: CapabilityBackend, pub lifecycle: CapabilityLifecycle, pub referenced: bool,} #[derive(Debug)]pub enum CapabilityError { Limit(LimitError), IdExhausted, RegistryClosed, Stale { id: CapabilityId, supplied_generation: CapabilityGeneration, }, WrongSession { id: CapabilityId, expected: SessionGeneration, actual: SessionGeneration, }, WrongKind { id: CapabilityId, expected: CapabilityKind, actual: CapabilityKind, }, InvalidTransition { id: CapabilityId, from: CapabilityLifecycle, to: CapabilityLifecycle, }, Poisoned,} impl fmt::Display for CapabilityError { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Limit(error) => error.fmt(formatter), Self::IdExhausted => formatter.write_str( "ERR_AGENTOS_CAPABILITY_ID_EXHAUSTED: capability id space exhausted", ), Self::RegistryClosed => formatter.write_str( "ERR_AGENTOS_CAPABILITY_REGISTRY_CLOSED: VM capability admission is closed", ), Self::Stale { id, supplied_generation, } => write!( formatter, "ERR_AGENTOS_STALE_CAPABILITY: capability {id} generation {supplied_generation} is not active" ), Self::WrongSession { id, expected, actual, } => write!( formatter, "ERR_AGENTOS_CAPABILITY_SESSION: capability {id} belongs to VM generation {actual}, not {expected}" ), Self::WrongKind { id, expected, actual, } => write!( formatter, "ERR_AGENTOS_CAPABILITY_KIND: capability {id} has kind {actual:?}, expected {expected:?}" ), Self::InvalidTransition { id, from, to } => write!( formatter, "ERR_AGENTOS_CAPABILITY_LIFECYCLE: capability {id} cannot transition from {from:?} to {to:?}" ), Self::Poisoned => formatter.write_str( "ERR_AGENTOS_CAPABILITY_REGISTRY_POISONED: capability registry lock poisoned", ), } }} impl std::error::Error for CapabilityError {} impl From<LimitError> for CapabilityError { fn from(value: LimitError) -> Self { Self::Limit(value) }} #[derive(Debug)]struct CapabilityEntry { snapshot: CapabilitySnapshot,} #[derive(Debug)]struct RegistryState { next_id: CapabilityId, open: bool, pending: usize, entries: BTreeMap<CapabilityId, CapabilityEntry>,} #[derive(Debug)]struct RegistryInner { session_generation: SessionGeneration, ledger: Arc<ResourceLedger>, state: Mutex<RegistryState>, admission_changed: tokio::sync::Notify, settled: tokio::sync::Notify,} #[derive(Clone, Debug)]pub struct CapabilityRegistry { inner: Arc<RegistryInner>,} impl CapabilityRegistry { pub fn new(session_generation: SessionGeneration, ledger: Arc<ResourceLedger>) -> Self { Self { inner: Arc::new(RegistryInner { session_generation, ledger, state: Mutex::new(RegistryState { next_id: 1, open: true, pending: 0, entries: BTreeMap::new(), }), admission_changed: tokio::sync::Notify::new(), settled: tokio::sync::Notify::new(), }), } } pub fn session_generation(&self) -> SessionGeneration { self.inner.session_generation } pub fn resources(&self) -> Arc<ResourceLedger> { Arc::clone(&self.inner.ledger) } /// Acquire every count permit before allocating the descriptor/backend. pub fn reserve(&self, kind: CapabilityKind) -> Result<PendingCapability, CapabilityError> { { let state = self .inner .state .lock() .map_err(|_| CapabilityError::Poisoned)?; if !state.open { return Err(CapabilityError::RegistryClosed); } } let capability = self.inner.ledger.reserve(ResourceClass::Capabilities, 1)?; // One possible ready-set entry is reserved with every admitted // capability. Readiness for a live handle therefore cannot fail after // the backend has already become observable. let ready_handle = self.inner.ledger.reserve(ResourceClass::ReadyHandles, 1)?; let socket = kind .is_socket() .then(|| self.inner.ledger.reserve(ResourceClass::Sockets, 1)) .transpose()?; let connection = kind .is_connection() .then(|| self.inner.ledger.reserve(ResourceClass::Connections, 1)) .transpose()?; { let mut state = self .inner .state .lock() .map_err(|_| CapabilityError::Poisoned)?; if !state.open { return Err(CapabilityError::RegistryClosed); } state.pending = state .pending .checked_add(1) .ok_or(CapabilityError::IdExhausted)?; } Ok(PendingCapability { registry: Arc::clone(&self.inner), kind, reservations: vec![Some(capability), Some(ready_handle), socket, connection] .into_iter() .flatten() .collect(), counted: true, }) } /// Pause an async source at admission instead of accepting/reading and then /// queueing uncharged state. The notification is armed before each retry so /// a concurrent release cannot be missed. pub async fn reserve_when_available( &self, kind: CapabilityKind, ) -> Result<PendingCapability, CapabilityError> { loop { let changed = self.inner.ledger.capacity_changed(); let admission_changed = self.inner.admission_changed.notified(); match self.reserve(kind) { Ok(pending) => return Ok(pending), Err(CapabilityError::Limit(error)) if error.requested > error.limit => { return Err(CapabilityError::Limit(error)); } Err(CapabilityError::Limit(_)) => { tokio::select! { _ = changed => {} _ = admission_changed => {} } } Err(error) => return Err(error), } } } pub fn snapshot(&self, id: CapabilityId) -> Option<CapabilitySnapshot> { self.inner .state .lock() .ok()? .entries .get(&id) .map(|entry| entry.snapshot.clone()) } pub fn snapshots(&self) -> Vec<CapabilitySnapshot> { self.inner .state .lock() .map(|state| { state .entries .values() .map(|entry| entry.snapshot.clone()) .collect() }) .unwrap_or_else(|_| { eprintln!( "ERR_AGENTOS_CAPABILITY_REGISTRY_POISONED: failed to snapshot capability registry" ); Vec::new() }) } pub fn close_admission(&self) -> Result<(), CapabilityError> { self.inner .state .lock() .map_err(|_| CapabilityError::Poisoned)? .open = false; self.inner.admission_changed.notify_waiters(); Ok(()) } pub fn active_len(&self) -> usize { self.inner .state .lock() .map(|state| state.entries.len()) .unwrap_or(0) } pub fn outstanding_len(&self) -> usize { self.inner .state .lock() .map(|state| state.pending.saturating_add(state.entries.len())) .unwrap_or(usize::MAX) } pub async fn wait_empty(&self) { loop { let settled = self.inner.settled.notified(); if self.outstanding_len() == 0 { return; } settled.await; } }} #[derive(Debug)]pub struct PendingCapability { registry: Arc<RegistryInner>, kind: CapabilityKind, reservations: Vec<Reservation>, counted: bool,} impl PendingCapability { /// Commit only after the backend has been allocated. Dropping before commit /// rolls admission back; dropping the returned lease closes the registry row. pub fn commit( mut self, backend: CapabilityBackend, ) -> Result<CapabilityLease, CapabilityError> { let (id, generation) = { let mut state = self .registry .state .lock() .map_err(|_| CapabilityError::Poisoned)?; if !state.open { return Err(CapabilityError::RegistryClosed); } if state.pending == 0 { eprintln!( "ERR_AGENTOS_CAPABILITY_ACCOUNTING_UNDERFLOW: pending commit without admission" ); return Err(CapabilityError::Poisoned); } let id = state.next_id; let next_id = id.checked_add(1).ok_or(CapabilityError::IdExhausted)?; state.pending -= 1; self.counted = false; state.next_id = next_id; let generation = NON_RECYCLING_CAPABILITY_GENERATION; let replaced = state.entries.insert( id, CapabilityEntry { snapshot: CapabilitySnapshot { session_generation: self.registry.session_generation, id, generation, kind: self.kind, backend, lifecycle: CapabilityLifecycle::Open, referenced: true, }, }, ); if let Some(previous) = replaced { eprintln!( "ERR_AGENTOS_CAPABILITY_ID_REUSED: monotonic capability id {id} was already active" ); state.entries.insert(id, previous); return Err(CapabilityError::Poisoned); } (id, generation) }; Ok(CapabilityLease { registry: Arc::downgrade(&self.registry), id, generation, reservations: std::mem::take(&mut self.reservations), }) }} impl Drop for PendingCapability { fn drop(&mut self) { if self.counted { match self.registry.state.lock() { Ok(mut state) => { if state.pending == 0 { eprintln!( "ERR_AGENTOS_CAPABILITY_ACCOUNTING_UNDERFLOW: pending reservation released at zero" ); } else { state.pending -= 1; } } Err(_) => eprintln!( "ERR_AGENTOS_CAPABILITY_REGISTRY_POISONED: pending reservation release failed" ), } self.counted = false; self.registry.settled.notify_waiters(); } }} #[derive(Debug)]pub struct CapabilityLease { registry: Weak<RegistryInner>, id: CapabilityId, generation: CapabilityGeneration, reservations: Vec<Reservation>,} impl CapabilityLease { pub fn id(&self) -> CapabilityId { self.id } pub fn generation(&self) -> CapabilityGeneration { self.generation } /// Validate a guest-visible alias against the live registry row before an /// operation reaches its backend. pub fn validate( &self, session_generation: SessionGeneration, kind: CapabilityKind, ) -> Result<(), CapabilityError> { let registry = self .registry .upgrade() .ok_or(CapabilityError::RegistryClosed)?; let state = registry .state .lock() .map_err(|_| CapabilityError::Poisoned)?; let entry = state.entries.get(&self.id).ok_or(CapabilityError::Stale { id: self.id, supplied_generation: self.generation, })?; if entry.snapshot.generation != self.generation { return Err(CapabilityError::Stale { id: self.id, supplied_generation: self.generation, }); } if entry.snapshot.session_generation != session_generation { return Err(CapabilityError::WrongSession { id: self.id, expected: session_generation, actual: entry.snapshot.session_generation, }); } if entry.snapshot.kind != kind { return Err(CapabilityError::WrongKind { id: self.id, expected: kind, actual: entry.snapshot.kind, }); } Ok(()) } Lines 1–500 of 847. Load more
//! One generation-aware registry for native and kernel-backed capabilities. use std::collections::BTreeMap; use std::fmt; use std::sync::{Arc, Mutex, Weak}; use crate::accounting::{LimitError, Reservation, ResourceClass, ResourceLedger}; pub type CapabilityId = u64; /// Capability IDs are never recycled within one VM/session generation, so the /// per-capability generation remains one. The session generation is part of /// every validated identity and distinguishes separate VM lifetimes. pub type CapabilityGeneration = u64; pub type SessionGeneration = u64; const NON_RECYCLING_CAPABILITY_GENERATION: CapabilityGeneration = 1; #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum CapabilityKind { TcpSocket, TcpListener, UnixSocket, UnixListener, UdpSocket, TlsTransport, Http2Connection, Http2Stream, } impl CapabilityKind { pub const fn is_socket(self) -> bool { matches!( self, Self::TcpSocket | Self::TcpListener | Self::UnixSocket | Self::UnixListener | Self::UdpSocket | Self::Http2Connection ) } pub const fn is_connection(self) -> bool { matches!( self, Self::TcpSocket | Self::UnixSocket | Self::Http2Connection ) } } #[derive(Clone, Debug, Eq, PartialEq)] pub enum CapabilityBackend { Native { local_id: String }, Kernel { socket_id: u64 }, } #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum CapabilityLifecycle { Allocating, Open, Closing, Failed, Closed, } #[derive(Clone, Debug, Eq, PartialEq)] pub struct CapabilitySnapshot { pub session_generation: SessionGeneration, pub id: CapabilityId, pub generation: CapabilityGeneration, pub kind: CapabilityKind, pub backend: CapabilityBackend, pub lifecycle: CapabilityLifecycle, pub referenced: bool, } #[derive(Debug)] pub enum CapabilityError { Limit(LimitError), IdExhausted, RegistryClosed, Stale { id: CapabilityId, supplied_generation: CapabilityGeneration, }, WrongSession { id: CapabilityId, expected: SessionGeneration, actual: SessionGeneration, }, WrongKind { id: CapabilityId, expected: CapabilityKind, actual: CapabilityKind, }, InvalidTransition { id: CapabilityId, from: CapabilityLifecycle, to: CapabilityLifecycle, }, Poisoned, } impl fmt::Display for CapabilityError { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Limit(error) => error.fmt(formatter), Self::IdExhausted => formatter.write_str( "ERR_AGENTOS_CAPABILITY_ID_EXHAUSTED: capability id space exhausted", ), Self::RegistryClosed => formatter.write_str( "ERR_AGENTOS_CAPABILITY_REGISTRY_CLOSED: VM capability admission is closed", ), Self::Stale { id, supplied_generation, } => write!( formatter, "ERR_AGENTOS_STALE_CAPABILITY: capability {id} generation {supplied_generation} is not active" ), Self::WrongSession { id, expected, actual, } => write!( formatter, "ERR_AGENTOS_CAPABILITY_SESSION: capability {id} belongs to VM generation {actual}, not {expected}" ), Self::WrongKind { id, expected, actual, } => write!( formatter, "ERR_AGENTOS_CAPABILITY_KIND: capability {id} has kind {actual:?}, expected {expected:?}" ), Self::InvalidTransition { id, from, to } => write!( formatter, "ERR_AGENTOS_CAPABILITY_LIFECYCLE: capability {id} cannot transition from {from:?} to {to:?}" ), Self::Poisoned => formatter.write_str( "ERR_AGENTOS_CAPABILITY_REGISTRY_POISONED: capability registry lock poisoned", ), } } } impl std::error::Error for CapabilityError {} impl From<LimitError> for CapabilityError { fn from(value: LimitError) -> Self { Self::Limit(value) } } #[derive(Debug)] struct CapabilityEntry { snapshot: CapabilitySnapshot, } #[derive(Debug)] struct RegistryState { next_id: CapabilityId, open: bool, pending: usize, entries: BTreeMap<CapabilityId, CapabilityEntry>, } #[derive(Debug)] struct RegistryInner { session_generation: SessionGeneration, ledger: Arc<ResourceLedger>, state: Mutex<RegistryState>, admission_changed: tokio::sync::Notify, settled: tokio::sync::Notify, } #[derive(Clone, Debug)] pub struct CapabilityRegistry { inner: Arc<RegistryInner>, } impl CapabilityRegistry { pub fn new(session_generation: SessionGeneration, ledger: Arc<ResourceLedger>) -> Self { Self { inner: Arc::new(RegistryInner { session_generation, ledger, state: Mutex::new(RegistryState { next_id: 1, open: true, pending: 0, entries: BTreeMap::new(), }), admission_changed: tokio::sync::Notify::new(), settled: tokio::sync::Notify::new(), }), } } pub fn session_generation(&self) -> SessionGeneration { self.inner.session_generation } pub fn resources(&self) -> Arc<ResourceLedger> { Arc::clone(&self.inner.ledger) } /// Acquire every count permit before allocating the descriptor/backend. pub fn reserve(&self, kind: CapabilityKind) -> Result<PendingCapability, CapabilityError> { { let state = self .inner .state .lock() .map_err(|_| CapabilityError::Poisoned)?; if !state.open { return Err(CapabilityError::RegistryClosed); } } let capability = self.inner.ledger.reserve(ResourceClass::Capabilities, 1)?; // One possible ready-set entry is reserved with every admitted // capability. Readiness for a live handle therefore cannot fail after // the backend has already become observable. let ready_handle = self.inner.ledger.reserve(ResourceClass::ReadyHandles, 1)?; let socket = kind .is_socket() .then(|| self.inner.ledger.reserve(ResourceClass::Sockets, 1)) .transpose()?; let connection = kind .is_connection() .then(|| self.inner.ledger.reserve(ResourceClass::Connections, 1)) .transpose()?; { let mut state = self .inner .state .lock() .map_err(|_| CapabilityError::Poisoned)?; if !state.open { return Err(CapabilityError::RegistryClosed); } state.pending = state .pending .checked_add(1) .ok_or(CapabilityError::IdExhausted)?; } Ok(PendingCapability { registry: Arc::clone(&self.inner), kind, reservations: vec![Some(capability), Some(ready_handle), socket, connection] .into_iter() .flatten() .collect(), counted: true, }) } /// Pause an async source at admission instead of accepting/reading and then /// queueing uncharged state. The notification is armed before each retry so /// a concurrent release cannot be missed. pub async fn reserve_when_available( &self, kind: CapabilityKind, ) -> Result<PendingCapability, CapabilityError> { loop { let changed = self.inner.ledger.capacity_changed(); let admission_changed = self.inner.admission_changed.notified(); match self.reserve(kind) { Ok(pending) => return Ok(pending), Err(CapabilityError::Limit(error)) if error.requested > error.limit => { return Err(CapabilityError::Limit(error)); } Err(CapabilityError::Limit(_)) => { tokio::select! { _ = changed => {} _ = admission_changed => {} } } Err(error) => return Err(error), } } } pub fn snapshot(&self, id: CapabilityId) -> Option<CapabilitySnapshot> { self.inner .state .lock() .ok()? .entries .get(&id) .map(|entry| entry.snapshot.clone()) } pub fn snapshots(&self) -> Vec<CapabilitySnapshot> { self.inner .state .lock() .map(|state| { state .entries .values() .map(|entry| entry.snapshot.clone()) .collect() }) .unwrap_or_else(|_| { eprintln!( "ERR_AGENTOS_CAPABILITY_REGISTRY_POISONED: failed to snapshot capability registry" ); Vec::new() }) } pub fn close_admission(&self) -> Result<(), CapabilityError> { self.inner .state .lock() .map_err(|_| CapabilityError::Poisoned)? .open = false; self.inner.admission_changed.notify_waiters(); Ok(()) } pub fn active_len(&self) -> usize { self.inner .state .lock() .map(|state| state.entries.len()) .unwrap_or(0) } pub fn outstanding_len(&self) -> usize { self.inner .state .lock() .map(|state| state.pending.saturating_add(state.entries.len())) .unwrap_or(usize::MAX) } pub async fn wait_empty(&self) { loop { let settled = self.inner.settled.notified(); if self.outstanding_len() == 0 { return; } settled.await; } } } #[derive(Debug)] pub struct PendingCapability { registry: Arc<RegistryInner>, kind: CapabilityKind, reservations: Vec<Reservation>, counted: bool, } impl PendingCapability { /// Commit only after the backend has been allocated. Dropping before commit /// rolls admission back; dropping the returned lease closes the registry row. pub fn commit( mut self, backend: CapabilityBackend, ) -> Result<CapabilityLease, CapabilityError> { let (id, generation) = { let mut state = self .registry .state .lock() .map_err(|_| CapabilityError::Poisoned)?; if !state.open { return Err(CapabilityError::RegistryClosed); } if state.pending == 0 { eprintln!( "ERR_AGENTOS_CAPABILITY_ACCOUNTING_UNDERFLOW: pending commit without admission" ); return Err(CapabilityError::Poisoned); } let id = state.next_id; let next_id = id.checked_add(1).ok_or(CapabilityError::IdExhausted)?; state.pending -= 1; self.counted = false; state.next_id = next_id; let generation = NON_RECYCLING_CAPABILITY_GENERATION; let replaced = state.entries.insert( id, CapabilityEntry { snapshot: CapabilitySnapshot { session_generation: self.registry.session_generation, id, generation, kind: self.kind, backend, lifecycle: CapabilityLifecycle::Open, referenced: true, }, }, ); if let Some(previous) = replaced { eprintln!( "ERR_AGENTOS_CAPABILITY_ID_REUSED: monotonic capability id {id} was already active" ); state.entries.insert(id, previous); return Err(CapabilityError::Poisoned); } (id, generation) }; Ok(CapabilityLease { registry: Arc::downgrade(&self.registry), id, generation, reservations: std::mem::take(&mut self.reservations), }) } } impl Drop for PendingCapability { fn drop(&mut self) { if self.counted { match self.registry.state.lock() { Ok(mut state) => { if state.pending == 0 { eprintln!( "ERR_AGENTOS_CAPABILITY_ACCOUNTING_UNDERFLOW: pending reservation released at zero" ); } else { state.pending -= 1; } } Err(_) => eprintln!( "ERR_AGENTOS_CAPABILITY_REGISTRY_POISONED: pending reservation release failed" ), } self.counted = false; self.registry.settled.notify_waiters(); } } } #[derive(Debug)] pub struct CapabilityLease { registry: Weak<RegistryInner>, id: CapabilityId, generation: CapabilityGeneration, reservations: Vec<Reservation>, } impl CapabilityLease { pub fn id(&self) -> CapabilityId { self.id } pub fn generation(&self) -> CapabilityGeneration { self.generation } /// Validate a guest-visible alias against the live registry row before an /// operation reaches its backend. pub fn validate( &self, session_generation: SessionGeneration, kind: CapabilityKind, ) -> Result<(), CapabilityError> { let registry = self .registry .upgrade() .ok_or(CapabilityError::RegistryClosed)?; let state = registry .state .lock() .map_err(|_| CapabilityError::Poisoned)?; let entry = state.entries.get(&self.id).ok_or(CapabilityError::Stale { id: self.id, supplied_generation: self.generation, })?; if entry.snapshot.generation != self.generation { return Err(CapabilityError::Stale { id: self.id, supplied_generation: self.generation, }); } if entry.snapshot.session_generation != session_generation { return Err(CapabilityError::WrongSession { id: self.id, expected: session_generation, actual: entry.snapshot.session_generation, }); } if entry.snapshot.kind != kind { return Err(CapabilityError::WrongKind { id: self.id, expected: kind, actual: entry.snapshot.kind, }); } Ok(()) }