acton-reactive 8.2.0

Acton Reactive is the main crate of the Acton framework, designed for building reactive, event-driven, and asynchronous systems. It provides intuitive abstractions to make working with distributed actors seamless and efficient.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

/*
 * 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.
 */

//! IPC (Inter-Process Communication) support for acton-reactive.
//!
//! This module provides type registration, serialization infrastructure, and
//! Unix Domain Socket (UDS) listener for sending messages across process
//! boundaries. All items in this module are only available when the `ipc`
//! feature is enabled.
//!
//! # Overview
//!
//! External processes cannot directly access Tokio MPSC channels used for internal
//! actor communication. The IPC module bridges this gap by providing:
//!
//! - A type registry for mapping message type names to deserializers
//! - Serializable envelope types for IPC message framing
//! - An actor registry for mapping logical names to actor handles
//! - A Unix Domain Socket listener for external process communication
//! - A wire protocol with length-prefixed framing
//!
//! # Key Components
//!
//! * [`IpcTypeRegistry`]: Central registry for mapping type IDs to serialization handlers.
//!   Message types must be registered before they can be received via IPC.
//!
//! * [`IpcEnvelope`]: The standard envelope format for IPC messages, containing
//!   correlation ID, target actor, message type, and serialized payload.
//!
//! * [`IpcResponse`]: Response envelope format with correlation ID matching and
//!   success/error reporting.
//!
//! * [`IpcError`]: Error types specific to IPC operations.
//!
//! * [`IpcConfig`]: Configuration for IPC listener with XDG-compliant socket paths.
//!
//! * [`IpcListenerHandle`]: Handle for managing the IPC listener lifecycle.
//!
//! # Example
//!
//! ```rust,ignore
//! use acton_reactive::prelude::*;
//! use serde::{Serialize, Deserialize};
//!
//! #[derive(Clone, Debug, Serialize, Deserialize)]
//! struct PriceUpdate {
//!     symbol: String,
//!     price: f64,
//! }
//!
//! // Register the message type for IPC
//! let mut runtime = ActonApp::launch_async().await;
//! runtime.ipc_registry().register::<PriceUpdate>("PriceUpdate");
//!
//! // Expose an actor for IPC access
//! let actor = runtime.new_actor::<()>();
//! let handle = actor.start().await;
//! runtime.ipc_expose("price_service", handle);
//!
//! // Start the IPC listener (Phase 2)
//! let listener_handle = runtime.start_ipc_listener().await?;
//! ```

// --- Public Re-exports ---
// These are intentionally public API items for external consumers

pub use config::IpcConfig;
pub use listener::{
    run as start_listener, socket_exists, socket_is_alive, IpcListenerHandle, IpcListenerStats,
    ShutdownResult,
};
pub use registry::IpcTypeRegistry;

// Subscription manager types - used by external clients for broker forwarding
#[allow(unused_imports)]
pub use subscription_manager::{
    create_push_channel, ConnectionId, PushReceiver, PushSender, SubscriptionManager,
    SubscriptionStats,
};

// IPC types - used by external clients for message serialization
#[allow(unused_imports)]
pub use types::{
    ActorInfo, IpcDiscoverRequest, IpcDiscoverResponse, IpcEnvelope, IpcError, IpcPushNotification,
    IpcResponse, IpcStreamFrame, IpcSubscribeRequest, IpcSubscriptionResponse,
    IpcUnsubscribeRequest, ProtocolCapabilities, ProtocolVersionInfo,
};

// IPC client - channel-based client for connecting to an acton-reactive server
pub use client::{IpcClient, IpcClientConfig};

// Re-export config types for users who want to customize defaults
pub use config::{
    IpcLimitsConfig, IpcTimeoutsConfig, RateLimitConfig, ShutdownConfig, SocketConfig,
};

// Assert public API types are constructable - compile-time check
const _: () = {
    fn _assert_config_types_usable() {
        let _rate_limit = RateLimitConfig::default();
        let _shutdown = ShutdownConfig::default();
    }
};

// --- Submodules ---

/// Channel-based IPC client for connecting to an acton-reactive server.
pub mod client;

/// IPC configuration with XDG-compliant socket path handling.
mod config;

/// Unix Domain Socket listener for IPC communication.
mod listener;

/// Wire protocol implementation for IPC message framing.
pub mod protocol;

/// Token bucket rate limiter for IPC connections.
mod rate_limiter;

/// Defines the [`IpcTypeRegistry`] for message type registration.
mod registry;

/// Subscription manager for IPC broker forwarding.
pub mod subscription_manager;

/// Defines IPC-specific types: [`IpcEnvelope`], [`IpcResponse`], [`IpcError`].
mod types;