847 lines · 27.4 KB · Rust
RawDownload
//! 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.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t