aura_effects/

lib.rs

//! # Aura Effects - Layer 3: Implementation (Stateless Effect Handlers)
//!
//! **Purpose**: Production-grade stateless effect handlers that delegate to OS services.
//!
//! This crate provides the Implementation Layer of the Aura architecture,
//! containing context-free, single-operation effect handlers that work in ANY
//! execution context (production, testing, simulation, choreographic).
//!
//! # Architecture Constraints
//!
//! **Layer 3 depends only on aura-core and external libraries** (foundation + libraries).
//! - MUST implement infrastructure effect traits defined in aura-core
//! - MUST be stateless (no shared mutable state between calls)
//! - MUST be single-party (each handler works independently)
//! - MUST be context-free (no assumptions about caller's context)
//! - MUST NOT depend on other Aura crates (domain crates, aura-protocol, etc.)
//! - MUST NOT do multi-handler coordination
//! - MUST NOT do multi-party protocol logic
//!
//! ## Stateful Boundary (compile-fail example)
//!
//! Handlers in Layer 3 are stateless. Stateful caches belong in Layer 6 services.
//!
//! ```compile_fail
//! use std::sync::RwLock;
//!
//! struct BadHandler {
//!     cache: RwLock<Vec<u8>>,
//! }
//!
//! compile_error!("Stateful caches must live in Layer 6 handlers, not aura-effects.");
//! ```
//!
//! # Required Infrastructure Effects
//!
//! This crate MUST provide handlers for:
//! - CryptoEffects: Ed25519 signing, hashing, key derivation
//! - NetworkEffects: TCP connections, message sending
//! - StorageEffects: File I/O, chunk operations
//! - TimeEffects: Current time, delays
//! - RandomEffects: Cryptographically secure randomness
//!
//! # What Belongs Here
//!
//! Basic effect implementations (RealCryptoHandler, ProductionLeakageHandler)
//! Storage backends (FilesystemStorageHandler, EncryptedStorage)
//! Network transports (TcpTransportHandler, WebSocketTransportHandler)
//! Time providers (RealTimeHandler), System handlers (LoggingSystemHandler)
//!
//! # What Does NOT Belong Here
//!
//! ✗ Multi-handler coordination (→ aura-protocol)
//! ✗ Choreographic bridges (→ aura-protocol)
//! ✗ Stateful orchestration (→ aura-protocol)
//! ✗ Complete protocols (→ feature crates)
//!
//! # Usage
//!
//! ```rust,ignore
//! use aura_effects::crypto::RealCryptoHandler;
//! use aura_effects::storage::FilesystemStorageHandler;
//! use aura_core::effects::{CryptoEffects, StorageEffects};
//!
//! // Use handlers directly for single operations
//! let crypto = RealCryptoHandler::new();
//! let signature = crypto.sign(&key, &message).await?;
//!
//! // Or compose into a runtime (done by aura-agent or aura-protocol)
//! let runtime = EffectSystemBuilder::production()
//!     .with_crypto(crypto)
//!     .with_storage(storage)
//!     .build();
//! ```

#[cfg(all(feature = "transparent_onion", not(any(test, debug_assertions))))]
compile_error!(
    "Feature `transparent_onion` is a debug/test/simulation-only tool and must \
     not be enabled in release production builds."
);

use cfg_if::cfg_if;

pub mod biometric;
pub mod console;
pub mod context;
/// Cryptographic effect handlers for signing, verification, and key derivation
pub mod crypto;
/// Indexed journal handler with B-tree indexes, Bloom filters, and Merkle trees
pub mod database;
/// Unified encrypted storage wrapper for transparent encryption at rest
pub mod encrypted_storage;
/// Error types for Layer 3 handler implementations.
pub mod error;
pub mod guard_interpreter;
pub mod identifiers;
pub mod leakage;
pub mod network_monitor;
pub mod noise;
pub mod query;
pub mod random;
pub mod reactive;
pub mod route_crypto;
pub mod runtime_capability;
pub mod secure;
#[cfg(feature = "simulation")]
pub mod simulation;
cfg_if! {
    if #[cfg(target_arch = "wasm32")] {
        #[path = "storage_wasm.rs"]
        pub mod storage;
    } else {
        pub mod storage;
    }
}
pub mod system;
pub mod time;
pub mod trace;

cfg_if! {
    if #[cfg(target_arch = "wasm32")] {
        pub mod transport;
    } else {
        pub mod transport;
        pub mod udp;
    }
}

// Re-export production handlers
pub use crate::storage::FilesystemStorageHandler;
pub use biometric::FallbackBiometricHandler;
pub use console::RealConsoleHandler;
pub use context::{EffectContext, StandardContextHandler};
pub use crypto::RealCryptoHandler;
pub use database::query::{AuraQuery, FactTerm, QueryError, QueryResult};
pub use encrypted_storage::{EncryptedStorage, EncryptedStorageConfig};
pub use error::Layer3Error;
pub use guard_interpreter::ProductionEffectInterpreter;
pub use identifiers::{
    new_account_id, new_authority_id, new_context_id, new_device_id, new_event_id, new_guardian_id,
    new_operation_id, new_session_id,
};
pub use leakage::ProductionLeakageHandler;
pub use network_monitor::NetworkMonitorHandler;
pub use noise::RealNoiseHandler;
pub use query::{
    format_rule, format_value, parse_arg_to_value, parse_fact_to_row, CapabilityPolicy,
    QueryHandler,
};
pub use random::RealRandomHandler;
pub use reactive::{ReactiveHandler, SignalGraph, SignalGraphStats};
pub use route_crypto::RealRouteCryptoHandler;
pub use runtime_capability::RuntimeCapabilityHandler;
pub use secure::RealSecureStorageHandler;
#[cfg(feature = "simulation")]
pub use simulation::FallbackSimulationHandler;
#[allow(deprecated)]
pub use time::{
    LogicalClockHandler, OrderClockHandler, PhysicalTimeHandler, TimeComparisonHandler,
};
#[cfg(not(target_arch = "wasm32"))]
pub use udp::RealUdpEffectsHandler;

// Transport effect handlers
cfg_if! {
    if #[cfg(target_arch = "wasm32")] {
        pub mod transport_effects {
            //! Transport effect implementations - Layer 3 stateless handlers.

            pub use crate::transport::{
                AddressResolver, BufferUtils, ConnectionMetrics, FramingHandler,
                RealTransportHandler, TimeoutHelper, TransportError, UrlValidator,
            };
        }
    } else {
        pub mod transport_effects {
            //! Transport effect implementations - Layer 3 stateless handlers

            pub use crate::transport::{
                // Utilities and helpers
                AddressResolver,
                BufferUtils,
                ConnectionMetrics,
                // Message processing
                FramingHandler,

                // Core transport handlers
                RealTransportHandler,
                TcpTransportHandler,
                TimeoutHelper,
                // Integration helpers
                TransportError,
                UrlValidator,

                // Web transport
                WebSocketTransportHandler,
            };
        }
    }
}

// Convenience re-exports for most common handlers
// Re-export system handlers
pub use system::{LoggingSystemHandler, MetricsSystemHandler, MonitoringSystemHandler};

// Convenience re-exports for most common transport handlers
cfg_if! {
    if #[cfg(target_arch = "wasm32")] {
        pub use transport_effects::{FramingHandler, RealTransportHandler, TransportError};
    } else {
        pub use transport_effects::{
            FramingHandler, RealTransportHandler, TcpTransportHandler, TransportError,
            WebSocketTransportHandler,
        };
    }
}

// Re-export core effect traits for convenience
pub use aura_core::effects::*;