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.

actr-runtime 0.1.6