trace2e_core/traceability/

mod.rs

//! Traceability module.
//!
//! This module provides a complete traceability solution for distributed systems,
//! enabling comprehensive data provenance tracking, policy enforcement, and compliance
//! monitoring across process boundaries and network connections.
pub mod api;
pub mod error;
pub mod infrastructure;
pub mod services;

// re-export types for convenience
pub use api::types;

/// Standard M2M API service stack with default component configuration.
///
/// Combines sequencer, provenance, and compliance services using the default
/// waiting queue mechanism for flow coordination. Suitable for most production
/// deployments requiring standard M2M functionality.
pub type M2mApiDefaultStack = api::m2m::M2mApiService<
    services::sequencer::WaitingQueueService<services::sequencer::SequencerService>,
    services::provenance::ProvenanceService,
    services::compliance::ComplianceService,
>;

/// Standard P2M API service stack parameterized by M2M client type.
///
/// Combines sequencer, provenance, and compliance services with a configurable
/// M2M client for distributed coordination. The generic parameter `M` allows
/// different M2M transport implementations to be used.
pub type P2mApiDefaultStack<M> = api::p2m::P2mApiService<
    services::sequencer::WaitingQueueService<services::sequencer::SequencerService>,
    services::provenance::ProvenanceService,
    services::compliance::ComplianceService,
    M,
>;

/// Standard O2M API service stack with default component configuration.
///
/// Combines provenance and compliance services for administrative operations.
/// Does not include sequencer as O2M operations are typically read-heavy
/// and don't require flow coordination.
pub type O2mApiDefaultStack<M> = api::o2m::O2mApiService<
    services::provenance::ProvenanceService,
    services::compliance::ComplianceService,
    services::consent::ConsentService,
    M,
>;

/// Initialize a complete middleware stack for production deployment.
///
/// Creates a fully configured middleware stack with all three API services
/// (M2M, P2M, O2M) using default component configurations. This is the
/// standard initialization method for production deployments.
///
/// # Arguments
/// * `node_id` - Unique identifier for this middleware node in the distributed system
/// * `max_retries` - Maximum retry attempts for the waiting queue (None for unlimited)
/// * `m2m_client` - Client service for M2M communication with remote middleware
/// * `enable_resource_validation` - Whether to enable resource validation for P2M requests
///
/// # Returns
/// A tuple containing (M2M service, P2M service, O2M service) ready for use
///
/// # Type Parameters
/// * `M` - M2M client type that implements the required service traits
pub fn init_middleware<M>(
    node_id: String,
    max_retries: Option<u32>,
    consent_timeout: u64,
    m2m_client: M,
    enable_resource_validation: bool,
) -> (M2mApiDefaultStack, P2mApiDefaultStack<M>, O2mApiDefaultStack<M>)
where
    M: tower::Service<
            api::M2mRequest,
            Response = api::M2mResponse,
            Error = error::TraceabilityError,
        > + Clone
        + Send
        + 'static,
    M::Future: Send,
{
    init_middleware_with_enrolled_resources(
        node_id,
        max_retries,
        consent_timeout,
        m2m_client,
        enable_resource_validation,
        0,
        0,
        0,
    )
}

/// Initialize a middleware stack with pre-enrolled resources for testing.
///
/// Creates a middleware stack identical to `init_middleware()` but with
/// pre-enrolled mock resources. This is useful for testing, benchmarking,
/// and simulation scenarios where actual process interactions are not needed.
///
/// # Arguments
/// * `node_id` - Unique identifier for this middleware node
/// * `max_retries` - Maximum retry attempts for the waiting queue
/// * `m2m_client` - Client service for M2M communication
/// * `enable_resource_validation` - Whether to enable resource validation for P2M requests
/// * `process_count` - Number of mock processes to pre-enroll
/// * `per_process_file_count` - Number of files to enroll per process
/// * `per_process_stream_count` - Number of streams to enroll per process
///
/// # Returns
/// A tuple containing (M2M service, P2M service, O2M service) with pre-enrolled resources
///
/// # Warning
/// Should only be used for testing purposes. Production deployments should use
/// `init_middleware()` and rely on actual process enrollment.
#[allow(clippy::too_many_arguments)]
pub fn init_middleware_with_enrolled_resources<M>(
    node_id: String,
    max_retries: Option<u32>,
    consent_timeout: u64,
    m2m_client: M,
    enable_resource_validation: bool,
    _process_count: u32,
    _per_process_file_count: u32,
    _per_process_stream_count: u32,
) -> (M2mApiDefaultStack, P2mApiDefaultStack<M>, O2mApiDefaultStack<M>)
where
    M: tower::Service<
            api::M2mRequest,
            Response = api::M2mResponse,
            Error = error::TraceabilityError,
        > + Clone
        + Send
        + 'static,
    M::Future: Send,
{
    let sequencer = tower::ServiceBuilder::new()
        .layer(tower::layer::layer_fn(|inner| {
            services::sequencer::WaitingQueueService::new(inner, max_retries)
        }))
        .service(services::sequencer::SequencerService::default());
    let provenance = services::provenance::ProvenanceService::new(node_id.clone());
    let consent = services::consent::ConsentService::new(consent_timeout);
    let compliance = services::compliance::ComplianceService::new(node_id, consent.clone());

    let m2m_service: M2mApiDefaultStack =
        api::m2m::M2mApiService::new(sequencer.clone(), provenance.clone(), compliance.clone());

    #[cfg(test)]
    let p2m_service: P2mApiDefaultStack<M> = api::p2m::P2mApiService::new(
        sequencer,
        provenance.clone(),
        compliance.clone(),
        m2m_client.clone(),
    )
    .with_resource_validation(enable_resource_validation)
    .with_enrolled_resources(
        _process_count,
        _per_process_file_count,
        _per_process_stream_count,
    );
    #[cfg(not(test))]
    let p2m_service: P2mApiDefaultStack<M> = api::p2m::P2mApiService::new(
        sequencer,
        provenance.clone(),
        compliance.clone(),
        m2m_client.clone(),
    )
    .with_resource_validation(enable_resource_validation);

    let o2m_service: O2mApiDefaultStack<M> =
        api::o2m::O2mApiService::new(provenance, compliance, consent, m2m_client);

    (m2m_service, p2m_service, o2m_service)
}