Crate actr_runtime 

Actor-RTC Runtime Layer

Runtime infrastructure for the Actor-RTC framework, providing complete Actor lifecycle management and message transport capabilities.

Overview

actr-runtime is the core runtime library that powers Actor nodes. It provides:

• Actor Lifecycle: System initialization, node startup/shutdown
• Message Transport: Multi-layer architecture (Wire → Transport → Gate → Dispatch)
• Communication Modes: Intra-process (zero-copy) and cross-process (WebRTC/WebSocket)
• Message Persistence: SQLite-backed mailbox with ACID guarantees

Architecture Layers

┌─────────────────────────────────────────────────────┐
│  Lifecycle Management (ActrSystem → ActrNode → ActrRef)
├─────────────────────────────────────────────────────┤
│  Layer 3: Inbound Dispatch                          │  DataStreamRegistry
│           (Fast Path Routing)                       │  MediaFrameRegistry
├─────────────────────────────────────────────────────┤
│  Layer 2: Outbound Gate                             │  InprocOutGate
│           (Message Sending)                         │  OutprocOutGate
├─────────────────────────────────────────────────────┤
│  Layer 1: Transport                                 │  Lane (core abstraction)
│           (Channel Management)                      │  InprocTransportManager
│                                                     │  OutprocTransportManager
├─────────────────────────────────────────────────────┤
│  Layer 0: Wire                                      │  WebRtcGate
│           (Physical Connections)                    │  WebRtcCoordinator
│                                                     │  SignalingClient
└─────────────────────────────────────────────────────┘

Core Types

Lifecycle Management

The runtime follows a three-phase lifecycle:

use actr_runtime::prelude::*;

#[tokio::main]
async fn main() -> ActorResult<()> {
    // Phase 1: Create generic-free infrastructure
    let config = actr_config::Config::default();
    let system = ActrSystem::new(config).await?;

    // Phase 2: Attach business logic (Workload)
    let node = system.attach(MyWorkload::default());

    // Phase 3: Start and get running node
    let running = node.start().await?;

    // Option 1: Convenience method (wait for Ctrl+C and shutdown)
    running.wait_for_ctrl_c_and_shutdown().await?;

    // Option 2: Manual control (for custom shutdown logic)
    // tokio::signal::ctrl_c().await?;
    // running.shutdown().await?;

    Ok(())
}

Transport Abstraction

Lane is the core transport abstraction, representing a unidirectional message channel:

use actr_runtime::transport::Lane;
use actr_protocol::PayloadType;

// Lane supports 4 variants:
// - WebRtcDataChannel: Reliable/Signal/LatencyFirst
// - WebRtcMediaTrack: Real-time media
// - Mpsc: Intra-process (zero-copy)
// - WebSocket: Fallback transport

// Send message through lane
lane.send(data).await?;

// Receive from lane
let data = lane.recv().await?;

Communication Modes

Intra-process (Shell ↔ Workload)

use actr_runtime::transport::InprocTransportManager;

let mgr = InprocTransportManager::new();

// Zero-serialization, direct RpcEnvelope passing
let response = mgr.send_request(
    PayloadType::RpcReliable,
    None,  // identifier
    envelope
).await?;

Cross-process (WebRTC/WebSocket)

use actr_runtime::transport::OutprocTransportManager;

let mgr = OutprocTransportManager::new(config);

// Protobuf serialization, automatic protocol negotiation
mgr.send(&dest, PayloadType::RpcReliable, &data).await?;

Message Persistence

All incoming messages go through the Mailbox (State Path):

use actr_mailbox::{Mailbox, MessagePriority};

// Enqueue message (persisted to SQLite)
let msg_id = mailbox.enqueue(from, payload, MessagePriority::Normal).await?;

// Dequeue batch (ordered by priority)
let messages = mailbox.dequeue().await?;

// Process and acknowledge
for msg in messages {
    process_message(&msg).await?;
    mailbox.ack(msg.id).await?;
}

Feature Status

✅ Implemented

• Actor lifecycle management (ActrSystem/ActrNode/ActrRef)
• 4-Lane transport architecture (WebRTC DataChannel + MediaTrack)
• WebSocket signaling client
• Intra-process zero-copy channels
• SQLite-backed mailbox with priorities
• Context factory for message handling
• Basic service discovery helpers (RouteCandidates)
• Distributed tracing integration (feature opentelemetry, Jaeger/OTLP)

⏳ Pending

• Health checks and metrics collection
• Prometheus metrics export

Usage Note

This is a low-level runtime library. For application development, use the high-level framework APIs provided by actr-framework which builds on top of this runtime.

Re-exports

pub use observability::ObservabilityGuard;

pub use observability::init_observability;

pub use actr_ref::ActrRef;

pub use lifecycle::ActrNode;

pub use lifecycle::ActrSystem;

pub use lifecycle::NetworkEventHandle;

pub use inbound::DataStreamCallback;

pub use inbound::DataStreamRegistry;

pub use inbound::MediaFrameRegistry;

pub use inbound::MediaTrackCallback;

pub use outbound::InprocOutGate;

pub use outbound::OutGate;

pub use outbound::OutprocOutGate;

pub use transport::DataLane;

pub use transport::DefaultWireBuilder;

pub use transport::DefaultWireBuilderConfig;

pub use transport::DestTransport;

pub use transport::ExponentialBackoff;

pub use transport::InprocTransportManager;

pub use transport::NetworkError;

pub use transport::NetworkResult;

pub use transport::OutprocTransportManager;

pub use transport::WireBuilder;

pub use transport::WireHandle;

pub use transport::TransportManager;

pub use wire::AuthConfig;

pub use wire::AuthType;

pub use wire::ReconnectConfig;

pub use wire::SignalingClient;

pub use wire::SignalingConfig;

pub use wire::SignalingStats;

pub use wire::WebRtcCoordinator;

pub use wire::WebRtcGate;

pub use wire::WebRtcNegotiator;

pub use wire::WebSocketConnection;

pub use wire::WebSocketSignalingClient;

pub use context_factory::ContextFactory;

pub use error::RuntimeError;

pub use error::RuntimeResult;

pub use monitoring::Alert;

pub use monitoring::AlertConfig;

pub use monitoring::AlertSeverity;

pub use monitoring::Monitor;

pub use monitoring::MonitoringConfig;

pub use resource::ResourceConfig;

pub use resource::ResourceManager;

pub use resource::ResourceQuota;

pub use resource::ResourceUsage;

Modules

actr_ref

ActrRef - Lightweight reference to a running Actor

context

Runtime Context Implementation

context_factory

Context factory

error

Runtime layer error definition

inbound

Inbound Layer 3: Inbound dispatch layer

lifecycle

Lifecycle management layer (non-architectural layer)

monitoring

monitoringandalert

observability

outbound

Outbound Layer 2: Outbound gate abstraction layer

prelude

Convenience prelude module

resource

Resource management

transport

Transport Layer 1: Transport layer

wire

Wire Layer 0: Physical wire layer

Structs

ActrId

ActrType

IceServer

ICE 服务器配置

MailboxStats

邮箱的统计信息

MediaSample

Media sample data from WebRTC native track

MessageRecord

从队列中取出的消息记录

WebRtcConfig

WebRTC 配置

Enums

Dest

Destination identifier

MediaType

Media type enum

MessagePriority

消息优先级

MessageStatus

消息处理状态

ProtocolError

Protocol-level errors primarily related to data structure and format validity.

Constants

INITIAL_CONNECTION_TIMEOUT

Traits

Mailbox

邮箱接口 - 定义消息持久化的核心操作

Type Aliases

ActorResult

Actor result type - commonly used in framework and runtime