runact 1.3.2

A Rust-native actor runtime with BEAM-style processes
Documentation

Runact

A Rust-native concurrent runtime and application platform inspired by BEAM.

Vision

Runact is one ecosystem, with multiple layers and crates. It provides the foundation for web applications, AI agents, remote AI agent servers, PaperOS, network services, background workers, CLI applications, real-time applications, and automation systems.

Runact is the platform. runact-web is Runact's web layer.

See Development Plan for the full architecture.

Features

  • Actor trait — synchronous fn handle(&mut self, msg, ctx) with typed messages
  • Work-stealing scheduler — per-worker RunQueue, steal-half protocol, reduction-based cooperative yield
  • Request-reply — Runtime::request() with RequestHandle::recv()/try_recv()/recv_timeout()
  • Supervision — RestartStrategy::OneForOne with exponential backoff
  • Compute pool — offload CPU-intensive work to a thread pool with panic isolation and cancellation
  • Timers — one-shot and periodic with drift correction
  • Cancellation — cooperative CancellationToken with parent→child propagation
  • Structured concurrency — TaskGroup for scoped task lifetimes
  • Async tasks — native executor for standard Rust Futures with Runtime::spawn_task, TaskHandle, panic isolation, and deterministic shutdown
  • Process management — spawn processes, stdin/stdout/stderr, exit status, timeout, cancellation
  • TCP networking — reactor, TcpListener, TcpStream with OS readiness integration (Linux epoll)
  • Resources — type-safe capability-based resource management
  • Backpressure — bounded mailbox with MailboxFull error on overflow
  • Hot code loading (feature-gated hot_code_loading) — Pattern 2 dynamic supervision: load new actor module versions at runtime; new child actors automatically use the latest code without restarting
  • Observability — structured logging via tracing

Quick Start

use runact::{Actor, ActorId, ActorContext, ActorError, Runtime};

struct Greeter;

impl Actor for Greeter {
    type Message = String;

    fn handle(&mut self, msg: String, _ctx: &mut ActorContext) -> Result<(), ActorError> {
        println!("Hello, {}!", msg);
        Ok(())
    }
}

let mut runtime = Runtime::new().unwrap();
let id = runtime.spawn(Greeter).unwrap();
runtime.send(id, "world".to_string()).unwrap();

Documentation

  • The Runact Runtime — A Reference Manual — Comprehensive reference covering core concepts, the actor system, async tasks, compute pool, TCP networking, HTTP/WebSocket, message fragmentation, agent servers, REST APIs, API reference, invariants, and architectural decisions. Available as PDF.
  • Development Plan — Full 53-section architecture and platform vision
  • Architecture — Full architectural document with runtime model, invariants, and development order
  • Async Runtime — Architectural boundary: Runact schedules asynchronous work, I/O libraries define it (Future executor, task lifecycle, cancellation, timers, task groups)
  • Runtime + Networking Plan — TCP, async runtime, and remote AI agent support plan
  • Vision — Design priorities and long-term evolution
  • Roadmap — Development phases and current status
  • Getting Started — Walkthrough of core APIs
  • Supervision — Supervision trees and restart strategies
  • Compute — CPU-intensive work offloading
  • Timers — One-shot and periodic timers
  • Resources — Capability-based resource management
  • Hot Code Loading — Pattern 2 dynamic supervision with version-aware actor spawning
  • Actor Communication Principles — 24 principles for message flow and invariants
  • Scheduler — BEAM-style scheduler with work stealing
  • Runtime API — Top-level Runtime API reference
  • Actors — Actor trait, ActorId, ActorContext, ownership model
  • Security — Capability-based security model
  • Object Model — Core runtime types reference
  • Protocol — Message envelope and request/reply protocol
  • API Reference

runact-web

A companion crate providing HTTP/1.1 and WebSocket support built on top of Runact's TCP layer:

  • Router — URL routing with path parameters (:id), middleware chain
  • Request/Response — HTTP/1.1 request parsing and response construction
  • WebSocketServer — RFC 6455 WebSocket server with ping/pong heartbeats, message fragmentation/reassembly, and adapter for both std::net::TcpStream and Runact's native TCP
  • Examples: websocket_echo, websocket_chat, agent_server, agent_api

See examples and tests.

MSRV

Rust 1.85 (edition 2024).

License

MIT OR Apache-2.0