@actrium/actr-dom

Actor-RTC Framework Demo

A distributed real-time communication framework demo built on WebRTC and the Actor model.

Overview

This project demonstrates a distributed system architecture that combines the classic Actor model with modern WebRTC transport. Each process is treated as a coarse-grained actor, communicates peer-to-peer over WebRTC, and uses a dual-path processing model to optimize different kinds of traffic.

Key Features

• Coarse-grained Actor model: Process-level actor abstraction for simpler distributed design
• Native WebRTC support: Built-in NAT traversal and peer-to-peer connectivity
• Dual-path processing:
  • State Path: Reliable ordered control-message handling
  • Fast Path: Low-latency streaming data handling
• Type safety: Contract-driven development based on Protobuf
• ACL-aware discovery: Secure discovery with access control list support

---

Documentation

The repository includes a complete set of design and development documents. A practical reading order is:

Part 1: Concepts & Architecture

Start here to build a shared mental model of the framework.

1. Ecosystem Overview (recommended first)
2. Concepts and Architecture
3. ActorSystem and Actor
4. Interacting with the Outside World
5. Inter-Actor Communication Patterns
6. Framework Internal Protocols

Part 2: Guides & Practices

Hands-on material for building with the framework.

1. Developer Guide (quick start)
2. Project Manifest and CLI (CLI reference)
3. Actor Cookbook (advanced patterns)
4. Testing Your Actors
5. Media Sources and Tracks (scenario-specific guidance)

Part 3: How It Works

For contributors and readers who want implementation-level details.

1. How It Works (implementation overview)
2. Deep-dive Topics (includes the detailed 3.1 to 3.13 documents)

Appendix

• Glossary

---

Quick Start

Prerequisites

• Rust: 1.88+ (install guide)
• Node.js: 16+ (download)
• protoc: Protocol Buffer compiler

  # Ubuntu/Debian
  sudo apt install protobuf-compiler
  
  # macOS
  brew install protobuf

One-Command Demo

# 1. Set up the project (install dependencies and build)
./run_demo.sh setup

# 2. Run the full demo
./run_demo.sh demo

Project Structure

actor-rtc/
├── docs/                          # framework design documents
├── proto/                         # Protobuf definitions
├── actor-rtc-framework/          # core framework crate
├── signaling-server/             # Node.js signaling server
├── examples/                     # example applications
└── run_demo.sh                   # automation script

Contributing

Contributions of all kinds are welcome.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push the branch (git push origin feature/AmazingFeature)
5. Open a pull request

Release Train (Maintainers)

Use the manual workflow Release Train (Basic) for the monorepo-managed foundation crates, protoc tools, supported SDK crates, and actr-cli with one shared stable version.

• Workflow file: .github/workflows/release-train.yml
• Local/CI entrypoint: scripts/release-train.sh
• Required secrets:
  • CARGO_REGISTRY_TOKEN — crates.io publishing
  • PYPI_API_TOKEN — PyPI publishing (optional; omit to skip Python)
  • PACKAGE_SYNC_GITHUB_TOKEN — dispatch Swift/Kotlin/TS package-sync workflows
• npm publishing uses Trusted Publishing (OIDC) via id-token: write; no NPM_TOKEN secret is needed.
• Reports are generated under release/reports/ and uploaded as workflow artifacts.

The release train publishes all components in a single run:

1. Foundation crates → protoc-gen crates → Python (optional) → SDK → CLI
2. Final Git tag created (vX.Y.Z)
3. Swift package-sync dispatched (Actrium/actr-swift-package-sync)
4. Kotlin package-sync dispatched (Actrium/actr-kotlin-package-sync)
5. TypeScript npm package published (@actrium/actr from bindings/typescript/)
6. Web npm packages published (@actrium/actr-dom, @actrium/actr-web, @actrium/actr-web-react) via bindings/web/scripts/publish.sh

Pre-release support is available via the pre_release workflow input, which accepts semver X.Y.Z-<id> and publishes npm packages with --tag pre (does not affect the latest dist-tag).

License

This project is released under the MIT License.