swactor-development-history/cfuzz/CYCLE_19_ROUTER.md

Cycle 19: Router Actor for Pooled Message Distribution — Development History

Commit: c688f0a · 4 files · 528 insertions, 3 deletions

---

Motivation

Many workloads benefit from distributing messages across a pool of identical worker actors. Before this change, users had to manually manage actor pools: spawn N workers, track their addresses, implement distribution logic, and handle worker replacement on failure. A Router actor encapsulates this pattern — it receives messages and transparently forwards them to pool members using a configurable strategy.

Competitor Analysis

Framework	Pool/Router Model	Strategies	Auto-Replace
Erlang	poolboy (checkout/checkin), wpool (transparent forwarding, 6 strategies + custom)	RoundRobin, Random, BestWorker, Hash, Available, custom	Manual
Akka	Router actors (Pool vs Group), Resizer for dynamic sizing	RoundRobin, Random, SmallestMailbox, Balancing, Broadcast, ScatterGather, TailChopping, ConsistentHashing	Pool auto-creates, Group manual
Actix	SyncArbiter (shared queue, implicit work-stealing)	N/A (shared queue)	N/A
Kameo	ActorPool (least-connections, auto-replace dead workers)	Least-connections	Yes
Ractor	No built-in router (process groups only)	N/A	N/A
Swactor	Router<M> actor	RoundRobin, Random, Broadcast	Yes (via monitor + handle_down)

Key Findings

• Router-as-actor with transparent forwarding (wpool/Akka style) is the best fit — the router looks like a regular actor to callers
• User-space actor like Supervisor (Cycle 17), reusing monitor + handle_down for worker replacement
• SmallestMailbox deferred — requires runtime stats access not available in user-space
• ConsistentHashing deferred — requires a hash function parameter, can be added later as a builder method

Implementation

Router<M> Actor

• Generic over M: Message — same Incoming type as workers, enabling transparent forwarding
• Workers spawned in on_start, monitored via ctx.monitor(), auto-replaced via handle_down
• Reuses ActiveChild struct from Supervisor (addr + monitor_ref)

Routing Strategies

• RoutingStrategy::RoundRobin — sequential circular distribution via counter
• RoutingStrategy::Random — random worker selection via get_random() helper
• RoutingStrategy::Broadcast — clone message to all live workers (M: Clone required)

Fault Tolerance

• Dead worker detected via handle_down → factory invoked → new worker spawned and monitored
• Meltdown protection: total_restarts > max_restarts → ctx.stop_self()
• Cascading shutdown: on_stop sends stop signals to all workers

Configuration

• Router::new(pool_size, strategy, factory, max_restarts) — all-in-one constructor
• Factory: Arc<dyn Fn(&Ctx) -> Result<ActorAddress, Error> + Send + Sync>

Key files modified: src/actor.rs, tests/runtime_api.rs, docs/runtime.md

Design Decisions

• Router-as-actor (transparent forwarding) — callers send messages to the router's address as if it were a regular actor. The router forwards to pool members. This is the cleanest API: no special send function, no pool handle, just an address.
• User-space actor (not runtime primitive) — like Supervisor, Router is built entirely on existing APIs (spawn, monitor, handle_down, stop). This validates the actor system's composability.
• Generic over M — Router<M> has Incoming = M, same as the workers. Messages are forwarded with zero transformation. Type safety is enforced at compile time.
• Broadcast requires Clone — broadcasting clones the message for each worker. The Clone bound is only required when using the Broadcast strategy, enforced at the type level.
• SmallestMailbox deferred — would require reading per-actor mailbox depth from runtime stats, which isn't available from within a handler. Could be added with a stats query API.
• ConsistentHashing deferred — requires a hash function parameter (user must define which part of the message determines the routing key). Better to add as a builder method with a closure parameter.
• Reuses ActiveChild from Supervisor — the pattern of "track address + monitor ref, replace on death" is identical. Code sharing confirms the design consistency between Supervisor and Router.

Tests Added

7 new tests (141 → 148 total):

• router_round_robin_distributes_across_workers — 6 msgs to 3 workers, each gets 2
• router_broadcast_sends_to_all_workers — 1 msg, all 3 workers receive
• router_random_delivers_to_some_worker — 30 msgs across 3 workers, at least 2 workers used
• router_replaces_dead_worker — panicked worker auto-replaced, pool size maintained
• router_meltdown_after_max_restarts — 3 deaths with max_restarts=2 → router stops
• router_on_stop_kills_workers — stopping router cascades to all workers
• router_broadcast_multiple_messages_all_received — 5 msgs × 3 workers = 15 received

Result

• 148 tests pass (140 behavioral + 7 proptest + 1 doctest)
• Zero warnings, full workspace compiles
• Router validates the composability of the entire cfuzz feature set: monitoring (Cycle 13), lifecycle hooks (Cycle 9), handle_down (Cycle 17), and the ActiveChild pattern (Cycle 17)
• The cfuzz branch concludes with a comprehensive actor runtime featuring: fairness, backpressure, recovery, lifecycle management, timers, named registry, monitoring, groups, ask pattern, supervision trees, and routers