Initial broker design and implementation

.github/workflows/ci.yml

@@ -230,6 +230,13 @@ jobs:
           # - `litebox_platform_windows_userland` is allowed to have `std` access,
           #   since it is a purely-userland implementation.
           #
+          # - `litebox_broker_transport` is allowed to have `std` access,
+          #   since it owns hosted concrete broker transport implementations,
+          #   including the current Unix-domain-socket control channel.
+          #
+          # - `litebox_broker_userland` is allowed to have `std` access,
+          #   since it is the hosted userland broker executable.
+          #
           # - `litebox_platform_lvbs` has a custom target (`no_std`), so it does
           #   not work with the current no_std checker.
           #
@@ -285,6 +292,8 @@ jobs:
           #   can safely use std.
           find . -type f -name 'Cargo.toml' \
             -not -path './Cargo.toml' \
+            -not -path './litebox_broker_transport/Cargo.toml' \
+            -not -path './litebox_broker_userland/Cargo.toml' \
             -not -path './litebox_platform_linux_userland/Cargo.toml' \
             -not -path './litebox_platform_windows_userland/Cargo.toml' \
             -not -path './litebox_runner_linux_on_windows_userland/Cargo.toml' \

Cargo.toml

@@ -1,7 +1,13 @@
 [workspace]
 resolver = "2"
 members = [
-    "litebox", 
+    "litebox",
+    "litebox_broker_local",
+    "litebox_broker_core",
+    "litebox_broker_protocol",
+    "litebox_broker_host",
+    "litebox_broker_transport",
+    "litebox_broker_userland",
     "litebox_common_linux",
     "litebox_common_windows",
     "litebox_common_optee",
@@ -29,6 +35,12 @@ members = [
 ]
 default-members = [
     "litebox",
+    "litebox_broker_local",
+    "litebox_broker_core",
+    "litebox_broker_protocol",
+    "litebox_broker_host",
+    "litebox_broker_transport",
+    "litebox_broker_userland",
     "litebox_common_linux",
     "litebox_common_windows",
     "litebox_common_optee",

dev_tests/src/ratchet.rs

@@ -34,6 +34,7 @@ fn ratchet_globals() -> Result<()> {
     ratchet(
         &[
             ("dev_bench/", 1),
+            ("litebox_broker_core/", 1),
             ("litebox/", 9),
             ("litebox_platform_linux_kernel/", 6),
             ("litebox_platform_linux_userland/", 5),

litebox/Cargo.toml

@@ -20,6 +20,8 @@ buddy_system_allocator = { version = "0.11.0", default-features = false, feature
 # Depend on (currently unreleased) slabmalloc `main`, which contains some fixes on top of `0.11.0`
 slabmalloc = { git = "https://github.com/gz/rust-slabmalloc.git", rev = "19480b2e82704210abafe575fb9699184c1be110" }
 litebox_util_log = { version = "0.1.0", path = "../litebox_util_log" }
+litebox_broker_local = { version = "0.1.0", path = "../litebox_broker_local" }
+litebox_broker_protocol = { version = "0.1.0", path = "../litebox_broker_protocol" }
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.60.2", features = [

litebox/src/broker/error.rs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use litebox_broker_protocol::ErrorCode;
+
+use crate::event::{counter::EventCounterError, polling::TryOpError};
+
+/// Error returned by the deployment-provided broker control path.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum BrokerControlError {
+    /// The broker control transport failed.
+    Transport,
+    /// The broker returned an operation error.
+    Broker(ErrorCode),
+    /// The broker returned a response shape that does not match the request.
+    UnexpectedResponse,
+}
+
+/// Internal normalized error for broker-backed object adapters.
+///
+/// This keeps protocol/control-channel failures separate from the public
+/// object-specific API error exposed by each local-core facade.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum BrokerObjectError {
+    /// The deployment-provided broker control path failed.
+    Control,
+    /// The broker rejected the cached object handle, type, or rights.
+    InvalidObject,
+    /// The object operation would block in its current broker-side state.
+    WouldBlock,
+    /// The object or broker-side state cannot grow further.
+    ResourceExhausted,
+    /// The broker returned a response shape that does not match the request.
+    UnexpectedResponse,
+    /// The broker reported a non-recoverable or unsupported object error.
+    Internal,
+}
+
+impl From<BrokerControlError> for BrokerObjectError {
+    fn from(error: BrokerControlError) -> Self {
+        match error {
+            BrokerControlError::Transport => Self::Control,
+            BrokerControlError::Broker(error) => error.into(),
+            BrokerControlError::UnexpectedResponse => Self::UnexpectedResponse,
+        }
+    }
+}
+
+impl From<ErrorCode> for BrokerObjectError {
+    fn from(error: ErrorCode) -> Self {
+        match error {
+            ErrorCode::InvalidRights
+            | ErrorCode::UnknownObject
+            | ErrorCode::WrongObjectType
+            | ErrorCode::StaleHandle => Self::InvalidObject,
+            ErrorCode::WouldBlock => Self::WouldBlock,
+            ErrorCode::ResourceExhausted => Self::ResourceExhausted,
+            _ => Self::Internal,
+        }
+    }
+}
+
+pub(crate) fn map_broker_object_result<T>(
+    result: Result<T, BrokerObjectError>,
+) -> Result<T, TryOpError<EventCounterError>> {
+    match result {
+        Ok(value) => Ok(value),
+        Err(BrokerObjectError::WouldBlock) => Err(TryOpError::TryAgain),
+        Err(error) => Err(TryOpError::Other(error.into())),
+    }
+}
+
+impl From<BrokerObjectError> for EventCounterError {
+    fn from(error: BrokerObjectError) -> Self {
+        match error {
+            BrokerObjectError::WouldBlock => Self::WouldBlock,
+            BrokerObjectError::ResourceExhausted => Self::ResourceExhausted,
+            BrokerObjectError::UnexpectedResponse => Self::UnexpectedResponse,
+            BrokerObjectError::Control
+            | BrokerObjectError::InvalidObject
+            | BrokerObjectError::Internal => Self::Io,
+        }
+    }
+}

litebox/src/broker/mod.rs

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use alloc::sync::Arc;
+
+use litebox_broker_local::{BrokerLocal, BrokerLocalError};
+use litebox_broker_protocol::{CoreRequest, CoreResponse, LocalControlChannel};
+
+use crate::sync::{Mutex, RawSyncPrimitivesProvider};
+
+pub(crate) mod error;
+pub use error::BrokerControlError;
+
+/// Local-core access to the negotiated broker control channel.
+///
+/// LiteBox owns broker-backed local objects and constructs broker protocol
+/// requests. Deployment code owns endpoint selection and supplies the connected
+/// transport behind this protocol-level boundary.
+pub trait BrokerControl: Send + Sync {
+    /// Sends one active BrokerCore request and returns its response.
+    fn request(
+        &self,
+        request: CoreRequest,
+    ) -> core::result::Result<CoreResponse, BrokerControlError>;
+}
+
+struct BrokerLocalControl<Platform: RawSyncPrimitivesProvider, T> {
+    local: Mutex<Platform, BrokerLocal<T>>,
+}
+
+impl<Platform, T> BrokerLocalControl<Platform, T>
+where
+    Platform: RawSyncPrimitivesProvider,
+{
+    const fn new(local: BrokerLocal<T>) -> Self {
+        Self {
+            local: Mutex::new(local),
+        }
+    }
+}
+
+impl<Platform, T> BrokerControl for BrokerLocalControl<Platform, T>
+where
+    Platform: RawSyncPrimitivesProvider,
+    T: LocalControlChannel + Send,
+{
+    fn request(
+        &self,
+        request: CoreRequest,
+    ) -> core::result::Result<CoreResponse, BrokerControlError> {
+        self.local
+            .lock()
+            .active_core_request(request)
+            .map_err(broker_control_error)
+    }
+}
+
+fn broker_control_error<E>(error: BrokerLocalError<E>) -> BrokerControlError {
+    match error {
+        BrokerLocalError::Broker(error) => BrokerControlError::Broker(error),
+        BrokerLocalError::UnexpectedResponse(_) => BrokerControlError::UnexpectedResponse,
+        _ => BrokerControlError::Transport,
+    }
+}
+
+pub(crate) fn control_from_local<Platform, T>(local: BrokerLocal<T>) -> Arc<dyn BrokerControl>
+where
+    Platform: RawSyncPrimitivesProvider,
+    T: LocalControlChannel + Send + 'static,
+{
+    Arc::new(BrokerLocalControl::<Platform, T>::new(local))
+}
+
+pub(crate) struct BrokerState<Platform: RawSyncPrimitivesProvider> {
+    control: Option<Arc<dyn BrokerControl>>,
+    _marker: core::marker::PhantomData<Platform>,
+}
+
+impl<Platform: RawSyncPrimitivesProvider> BrokerState<Platform> {
+    pub(crate) fn new(control: Option<Arc<dyn BrokerControl>>) -> Self {
+        Self {
+            control,
+            _marker: core::marker::PhantomData,
+        }
+    }
+
+    pub(crate) fn control(&self) -> Option<Arc<dyn BrokerControl>> {
+        self.control.clone()
+    }
+}