acton-reactive 9.0.0

/*
 * Copyright (c) 2024. Govcraft
 *
 * Licensed under either of
 *   * Apache License, Version 2.0 (the "License");
 *     you may not use this file except in compliance with the License.
 *     You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 *   * MIT license: http://opensource.org/licenses/MIT
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the applicable License for the specific language governing permissions and
 * limitations under that License.
 */

#![forbid(unsafe_code)]
#![forbid(missing_docs)] // Keep this to enforce coverage

//! # Acton Reactive
//!
//! This crate provides the foundational components for the Acton asynchronous
//! actor system, built on top of Tokio. It establishes a robust, message-passing
//! framework with clear separation of concerns for actor state, runtime management,
//! communication, and lifecycle.
//!
//! ## Key Concepts
//!
//! - **Actors (`ManagedActor`)**: Core computational units wrapping user-defined state
//!   and logic, managed by the runtime.
//! - **Handles (`ActorHandle`)**: External references for interacting with actors
//!   (sending messages, stopping, supervising).
//! - **Messaging**: Asynchronous communication via Tokio MPSC channels, using
//!   messages implementing the `ActonMessage` trait.
//! - **Broker (`Broker`)**: Central publish-subscribe mechanism for topic-based
//!   message distribution.
//! - **Lifecycle & Supervision**: Type-state pattern (`Idle`, `Started`) for actors,
//!   lifecycle hooks, and hierarchical supervision.
//! - **Runtime (`ActorRuntime`)**: Manages the overall system, including actor
//!   creation and shutdown.
//! - **Traits**: Core interfaces (`ActorHandleInterface`, `Broker`, `Subscriber`, etc.)
//!   define the framework's capabilities.
//!
//! ## Quick Start
//!
//! ```rust,ignore
//! use acton_reactive::prelude::*;
//!
//! #[acton_message]
//! struct MyMessage {
//!     content: String,
//! }
//! ```

/// Internal utilities and structures used throughout the Acton framework.
pub(crate) mod common;

/// Defines the core actor structures and logic.
pub(crate) mod actor;

/// Defines message types and envelopes used for communication.
pub(crate) mod message;

/// Defines core traits used throughout the Acton framework.
pub(crate) mod traits;

/// IPC (Inter-Process Communication) module for external process integration.
///
/// This module provides Unix Domain Socket communication infrastructure for
/// sending messages to actors from external processes.
///
/// This module provides all the public IPC types and functions for building
/// IPC clients and working with the IPC infrastructure.
///
/// # Feature Gate
///
/// This module is only available when the `ipc` feature is enabled.
#[cfg(feature = "ipc")]
pub mod ipc {
    pub use crate::common::ipc::{
        socket_exists, socket_is_alive, start_listener, ActorInfo, ConfigSource, ConnectionId,
        IpcClient, IpcClientConfig, IpcConfig, IpcDiscoverRequest, IpcDiscoverResponse, IpcEnvelope,
        IpcError, IpcLimitsConfig, IpcListenerHandle, IpcListenerStats, IpcPushNotification,
        IpcResponse, IpcStreamFrame, IpcSubscribeRequest, IpcSubscriptionResponse,
        IpcTimeoutsConfig, IpcTypeRegistry, IpcUnsubscribeRequest, PeerCredentials,
        ProtocolCapabilities, ProtocolVersionInfo, RateLimitConfig, ShutdownConfig, ShutdownResult,
        SocketConfig, SubscriptionManager, CONNECTION_LIMIT_REACHED_CODE,
        CONNECTION_REJECTED_CORRELATION_ID,
    };
    pub use crate::common::IpcNameInUse;

    /// Wire protocol for IPC message framing.
    ///
    /// This module provides functions for reading and writing IPC messages
    /// using the length-prefixed binary wire protocol.
    pub mod protocol {
        pub use crate::common::ipc::protocol::{
            is_discover, is_heartbeat, is_stream, is_subscribe, is_unsubscribe, read_envelope,
            read_frame, read_response, write_discover, write_discover_with_format,
            write_discovery_response, write_discovery_response_with_format, write_envelope,
            write_envelope_with_format, write_frame, write_heartbeat, write_push_with_format,
            write_response, write_response_with_format, write_stream_frame,
            write_stream_frame_with_format, write_subscribe_with_format,
            write_subscription_response, write_subscription_response_with_format,
            write_unsubscribe_with_format, Format, ProtocolVersion, HEADER_SIZE, HEADER_SIZE_V1,
            HEADER_SIZE_V2, MAX_FRAME_SIZE, MAX_SUPPORTED_VERSION, MIN_SUPPORTED_VERSION,
            MSG_TYPE_DISCOVER, MSG_TYPE_ERROR, MSG_TYPE_HEARTBEAT, MSG_TYPE_PUSH, MSG_TYPE_REQUEST,
            MSG_TYPE_RESPONSE, MSG_TYPE_STREAM, MSG_TYPE_SUBSCRIBE, MSG_TYPE_UNSUBSCRIBE,
            PROTOCOL_VERSION,
        };
    }
}

/// A prelude module for conveniently importing the most commonly used items.
///
/// This module re-exports essential types, traits, and macros from the Acton
/// framework and dependencies like `acton-ern` and `async-trait`, simplifying
/// the import process for users.
///
/// # Re-exports
///
/// ## Macros (from `acton-macro`)
/// *   [`acton_macro::acton_message`]: Attribute macro for defining Acton messages.
/// *   [`acton_macro::acton_actor`]: Attribute macro for defining Acton actors.
///
/// ## External Crates
/// *   [`acton_ern::*`](https://docs.rs/acton-ern): All items from the `acton-ern` crate for unique resource naming.
/// *   [`async_trait::async_trait`](https://docs.rs/async-trait/latest/async_trait/attr.async_trait.html): The macro for defining async functions in traits.
///
/// ## Core Types
/// *   [`crate::actor::ActorConfig`]: Configuration for creating new actors.
/// *   [`crate::actor::Idle`]: Type-state marker for an actor before it starts.
/// *   [`crate::actor::ManagedActor`]: The core actor structure managing state and runtime.
/// *   [`crate::actor::Started`]: Type-state marker for a running actor.
/// *   [`crate::common::ActonApp`]: Entry point for initializing the Acton system.
/// *   [`crate::common::Broker`]: The central message broker implementation.
/// *   [`crate::common::ActorHandle`]: Handle for interacting with an actor.
/// *   [`crate::common::BrokerRef`]: Alias for an [`ActorHandle`](crate::common::ActorHandle) that refers to the system broker.
/// *   [`crate::common::ParentRef`]: Alias for an [`ActorHandle`](crate::common::ActorHandle) that refers to a supervisor.
/// *   [`crate::common::Reply`]: Utility for creating standard message handler return types.
/// *   [`crate::common::ActorRuntime`]: Represents the initialized Acton runtime.
/// *   [`crate::common::AskError`]: Why a request/reply exchange produced no reply.
/// *   [`crate::common::DEFAULT_ASK_TIMEOUT`]: The deadline `ask` applies by default.
/// *   [`crate::message::BrokerRequest`]: Wrapper for messages intended for broadcast.
/// *   [`crate::message::BrokerRequestEnvelope`]: Specialized envelope for broadcast messages.
/// *   [`crate::message::MessageAddress`]: Addressable endpoint of an actor.
/// *   [`crate::message::OutboundEnvelope`]: Represents a message prepared for sending.
/// *   [`crate::message::SystemSignal`]: Lifecycle control signals, such as graceful termination.
/// *   [`crate::traits::ActonMessage`]: Marker trait for all valid messages.
/// *   [`crate::traits::ActorHandleInterface`]: Core trait defining actor interaction methods.
/// *   [`crate::traits::Broadcaster`]: Trait defining message broadcasting capabilities.
/// *   [`crate::traits::Request`]: Marks a message as expecting one reply, enabling `ask`.
/// *   [`crate::traits::Subscribable`]: Trait for managing message subscriptions.
/// *   [`crate::traits::Subscriber`]: Trait for accessing the message broker.
///
/// ## IPC Types (requires `ipc` feature)
///
/// These are re-exported only when the `ipc` feature is enabled; they are also
/// reachable under the crate's `ipc` module.
#[cfg_attr(
    feature = "ipc",
    doc = "*   [`crate::ipc::IpcTypeRegistry`]: Registry for IPC message type deserialization.
*   [`crate::ipc::IpcEnvelope`]: Envelope format for IPC messages.
*   [`crate::ipc::IpcResponse`]: Response envelope format for IPC.
*   [`crate::ipc::IpcError`]: Error types for IPC operations.
*   [`crate::ipc::IpcConfig`]: Configuration for IPC listener.
*   [`crate::ipc::IpcListenerHandle`]: Handle for managing IPC listener lifecycle.
*   [`crate::ipc::IpcListenerStats`]: Statistics for IPC listener."
)]
pub mod prelude {
    // Macros from acton-macro
    pub use acton_macro::*;

    // External crate re-exports
    pub use acton_ern::*;
    pub use async_trait::async_trait;
    pub use tokio;

    // Core types
    pub use crate::actor::{
        ActorConfig, BackoffDelay, ChildIndex, ChildRestarted, ChildSupervised, Escalation, Idle,
        ManagedActor, RestartGeneration, RestartLimitExceeded, RestartLimiter,
        RestartLimiterConfig, RestartPolicy, RestartStats, Started, SupervisedChild,
        SupervisionDecision, SupervisionError, SupervisionEscalated, SupervisionState,
        SupervisionStatus, SupervisionStrategy, TerminationReason, MAX_SUPERVISION_DEPTH,
    };
    pub use crate::common::{
        ActonApp, ActorHandle, ActorRuntime, AskError, Broker, BrokerRef, ParentRef, Reply,
        DEFAULT_ASK_TIMEOUT,
    };
    pub use crate::message::{
        BroadcastsFlushed, BrokerRequest, BrokerRequestEnvelope, ChildTerminated, FlushBroadcasts,
        MessageAddress, OutboundEnvelope, SystemSignal,
    };
    pub use crate::traits::{
        ActonMessage, ActorHandleInterface, Broadcaster, Request, Subscribable, Subscriber,
    };

    // IPC types (feature-gated)
    #[cfg(feature = "ipc")]
    pub use crate::common::ipc::{
        IpcClient, IpcClientConfig, IpcConfig, IpcEnvelope, IpcError, IpcListenerHandle,
        IpcListenerStats, IpcResponse, IpcTypeRegistry, RemoteActorRef, ShutdownResult,
    };
    #[cfg(feature = "ipc")]
    pub use crate::traits::RemoteRequest;
}