saddle-runtime 0.2.0-rc.3

//! Framework-internal adapter for one generated compiled-route capability.
//!
//! This protocol is public only because Rust has no cross-crate friend
//! visibility. It is non-stable, is not re-exported by the Saddle facade and
//! has no business entry point. Runtime does not claim that an implementation
//! is trustworthy: the approved build must pin the sole Service implementation
//! and the sole assembly site.

use std::future::Future;

use saddle_admission::{
    DbPermitDomain, DbRequestPermit, DbRouteResources, ManagedBytes, ManagedResponse,
    ManagedResponseOutput, RequestMemory,
};

/// Closed, protocol-independent response semantics.
///
/// The approved Service adapter is the sole production classifier. There is
/// no numeric/string/unknown constructor and no fallback class; Transport must
/// exhaustively map all variants to its own fixed framing policy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ResponseOutcomeClass {
    Success,
    InvalidRequest,
    BusinessRejected,
    Unavailable,
    Internal,
}

/// One current-account payload paired with its mandatory semantic class.
pub struct CompiledResponseOutcome {
    class: ResponseOutcomeClass,
    payload: ManagedResponse,
}

impl CompiledResponseOutcome {
    pub fn success(payload: ManagedResponse) -> Self {
        Self {
            class: ResponseOutcomeClass::Success,
            payload,
        }
    }

    pub fn invalid_request(payload: ManagedResponse) -> Self {
        Self {
            class: ResponseOutcomeClass::InvalidRequest,
            payload,
        }
    }

    pub fn business_rejected(payload: ManagedResponse) -> Self {
        Self {
            class: ResponseOutcomeClass::BusinessRejected,
            payload,
        }
    }

    pub fn unavailable(payload: ManagedResponse) -> Self {
        Self {
            class: ResponseOutcomeClass::Unavailable,
            payload,
        }
    }

    pub fn internal(payload: ManagedResponse) -> Self {
        Self {
            class: ResponseOutcomeClass::Internal,
            payload,
        }
    }

    pub(crate) fn class(&self) -> ResponseOutcomeClass {
        self.class
    }

    pub(crate) fn payload(&self) -> &ManagedResponse {
        &self.payload
    }
}

impl ManagedResponseOutput for CompiledResponseOutcome {
    fn managed_response(&self) -> &ManagedResponse {
        &self.payload
    }
}

pub use crate::admission::{
    CompiledRetryToken, OfficialCompiledDriverFinalizer, OfficialCompiledLiveSnapshot,
    OfficialCompiledRouteCoordinator, OfficialCompiledRuntimeFinalizer,
    OfficialCompiledShutdownReport, OfficialCompiledTcpOutcome, OfficialHttpRouteCoordinator,
    OfficialHttpTcpOutcome, OfficialTcpAttemptProfile, OfficialTcpRejectReason,
    OfficialTcpStopReason, PublishedTcpIdentity, WaitingCompiledTcp, WaitingHttpTcp,
};

/// A sealed-route adapter consumed by Runtime's unique official entry
/// coordinator.
///
/// There is deliberately no blanket implementation, closure implementation,
/// default method, or Runtime-owned numeric route descriptor. One indivisible
/// `Proof` must drive the managed commitment, DB/no-DB resources, response
/// capacity and concrete execution Future.
pub trait CompiledRouteAdapter: Send + Sync + 'static {
    type Proof: Copy + Send + Sync + Unpin + 'static;
    type Context: Send + Unpin + 'static;
    type Error: Send + 'static;
    type Future: Future<Output = Result<ManagedResponse, Self::Error>> + Send + 'static;

    /// Returns the complete managed commitment already frozen into `proof`.
    fn managed_commitment(&self, proof: Self::Proof) -> Result<usize, Self::Error>;

    /// Returns the response-builder capacity frozen into the same `proof`.
    fn response_capacity(&self, proof: Self::Proof) -> Result<usize, Self::Error>;

    /// Derives the exact DB/no-DB Admission resources from the same `proof`.
    ///
    /// A DB route must reject a missing or mismatched domain. A no-DB route
    /// must return `DbRouteResources::none()`.
    fn db_resources<'a>(
        &self,
        proof: Self::Proof,
        domain: Option<&'a DbPermitDomain>,
    ) -> Result<DbRouteResources<'a>, Self::Error>;

    /// Synchronously validates `proof`, the optional current-account permit
    /// and the response capacity, then constructs the one concrete owned
    /// execution Future. Implementations must create the fixed
    /// `ManagedResponseBuilder` from this short `RequestMemory` borrow before
    /// returning.
    fn execute(
        &self,
        proof: Self::Proof,
        context: Self::Context,
        body: ManagedBytes,
        permit: Option<DbRequestPermit>,
        memory: &RequestMemory,
    ) -> Result<Self::Future, Self::Error>;
}

/// Classified successor used by the HTTP framing coordinator.
///
/// It intentionally has no blanket bridge from `CompiledRouteAdapter`: the
/// approved Service implementation must classify both synchronous and
/// asynchronous execution outcomes and always return a current-account
/// payload.
pub trait ClassifiedCompiledRouteAdapter: Send + Sync + 'static {
    type Proof: Copy + Send + Sync + Unpin + 'static;
    type Context: Send + Unpin + 'static;
    type Error: Send + 'static;
    type Future: Future<Output = CompiledResponseOutcome> + Send + 'static;

    fn managed_commitment(&self, proof: Self::Proof) -> Result<usize, Self::Error>;

    fn response_capacity(&self, proof: Self::Proof) -> Result<usize, Self::Error>;

    fn db_resources<'a>(
        &self,
        proof: Self::Proof,
        domain: Option<&'a DbPermitDomain>,
    ) -> Result<DbRouteResources<'a>, Self::Error>;

    fn execute(
        &self,
        proof: Self::Proof,
        context: Self::Context,
        body: ManagedBytes,
        permit: Option<DbRequestPermit>,
        memory: &RequestMemory,
    ) -> Self::Future;
}