Routers

Concept

A router is an actor that fans out messages to a pool of routees using a routing strategy. You send messages to the router; it forwards them to one or more routees according to the configured strategy. Routers are not cluster-relocatable. If the host node leaves or crashes, the router and its routees are not automatically re-spawned elsewhere.

Sending Messages

Messages to a router must be wrapped in a Broadcast envelope. Use Tell to send:

ctx.Tell(routerPID, actor.NewBroadcast(myMessage))

The router unwraps the payload and dispatches it to its routees based on the routing strategy.

Routing Strategies

Standard Strategies (Fire-and-Forget)

These strategies never wait for replies. They are fire-and-forget; routees process messages asynchronously.

Strategy	Behavior
RoundRobin	Rotate through routees in order
Random	Pick a random routee
FanOut	Send to all routees concurrently (default)
ConsistentHash	Route messages with the same key to the same routee (sticky sessions)

Reply-Based Strategies

When you need the router to observe replies and relay the first successful response back to the sender, use one of these. Outcomes are delivered asynchronously to the sender as ordinary messages (not via Ask).

Strategy	Behavior
Scatter-Gather First	Sends the request to all routees concurrently. The first successful reply within the time budget is forwarded to the original sender. Late replies are ignored. If no routee replies in time, the sender receives a `StatusFailure`.
Tail-Chopping	Probes one routee at a time (in random order). If no response arrives before the interval, sends to the next routee. Repeats until a routee replies, all routees are tried, or the global deadline expires. First success wins; otherwise the sender receives a `StatusFailure`.

Spawning a Router

Use SpawnRouter on the actor system:

routerPID, err := system.SpawnRouter(ctx, "my-router", 5, &MyWorker{}, actor.WithRoutingStrategy(actor.RoundRobinRouting))

Parameters:

name – Router actor name
poolSize – Number of routees to spawn (must be > 0)
routeesKind – Actor type for routees (a pointer to a struct implementing Actor)
opts – Router options (see below)

Router Options

Option	Description
`WithRoutingStrategy(strategy)`	Set RoundRobin, Random, FanOut, or ConsistentHash. Default is FanOut.
`WithConsistentHashRouter(extractor)`	Use consistent-hash routing. `extractor` is a `MessageRoutingKeyExtractor` (`func(msg any) string`). Messages with the same key go to the same routee. Returns empty string to fall back to random.
`WithConsistentHashVirtualNodes(n)`	Virtual nodes per routee for the hash ring (default 150). Only with `WithConsistentHashRouter`.
`WithConsistentHashHasher(h)`	Custom hash function for the ring (default xxh3). Only with `WithConsistentHashRouter`.
`AsScatterGatherFirst(within)`	Use scatter-gather-first. `within` is the total time budget for any reply.
`AsTailChopping(within, interval)`	Use tail-chopping. `within` is the global deadline; `interval` is the delay between successive attempts. Requires `interval` > 0 and `within` > 0; typically `interval` < `within`.
`WithRestartRouteeOnFailure(maxRetries, timeout)`	On routee panic: restart the routee (up to `maxRetries` within `timeout`).
`WithStopRouteeOnFailure()`	On routee panic: stop and remove the routee from the pool. Default.
`WithResumeRouteeOnFailure()`	On routee panic: resume the routee (keep state, continue processing).

Examples

// Round-robin across 10 workers
system.SpawnRouter(ctx, "workers", 10, &Worker{}, actor.WithRoutingStrategy(actor.RoundRobinRouting))

// Consistent-hash: same order ID always routes to the same routee
system.SpawnRouter(ctx, "order-router", 5, &OrderWorker{},
    actor.WithConsistentHashRouter(func(msg any) string {
        switch m := msg.(type) {
        case *OrderCommand:
            return m.OrderID
        case *PaymentEvent:
            return m.CustomerID
        default:
            return "" // fall back to random
        }
    }),
)

// Scatter-gather: first reply within 500ms wins
system.SpawnRouter(ctx, "lookup", 5, &LookupActor{}, actor.AsScatterGatherFirst(500*time.Millisecond))

// Tail-chopping: try every 200ms for up to 2s
system.SpawnRouter(ctx, "probe", 5, &ProbeActor{}, actor.AsTailChopping(2*time.Second, 200*time.Millisecond))

// Restart failing routees up to 3 times within 1s
system.SpawnRouter(ctx, "resilient", 5, &Worker{}, actor.WithRestartRouteeOnFailure(3, time.Second))

Control Messages

Routers accept these control messages via Tell or Ask:

Message	Usage	Response
`GetRoutees`	Query current routee names	`Routees` (use `Ask`)
`AdjustRouterPoolSize`	Scale pool at runtime	None (fire-and-forget)

GetRoutees

resp, err := ctx.Ask(routerPID, &actor.GetRoutees{}, 500*time.Millisecond)
if err == nil {
    r := resp.(*actor.Routees)
    for _, name := range r.Names() {
        // resolve and use
    }
}

AdjustRouterPoolSize

poolSize > 0: Add that many routees
poolSize < 0: Remove that many routees
poolSize == 0: No-op

ctx.Tell(routerPID, actor.NewAdjustRouterPoolSize(5))   // grow by 5
ctx.Tell(routerPID, actor.NewAdjustRouterPoolSize(-3)) // shrink by 3

Handling Replies (Scatter-Gather / Tail-Chopping)

For reply-based strategies, the sender receives either:

The first successful reply from a routee (as a normal message)
A StatusFailure if the deadline expires or all routees fail

Handle both in your actor’s Receive:

func (a *MyActor) Receive(ctx *actor.ReceiveContext) {
    switch msg := ctx.Message().(type) {
    case *MySuccessResponse:
        // first successful reply
    case *actor.StatusFailure:
        // timeout or all failures
    }
}

When to Use

Load balancing – RoundRobin or Random across a pool of workers
Sticky sessions / partition affinity – ConsistentHash when messages with the same key (e.g. order ID, customer ID) must always go to the same routee
Parallel processing – FanOut for pub/sub, cache invalidation, multi-sink processing
Fastest responder – Scatter-Gather First when you want the first successful reply
Controlled probing – Tail-Chopping when you prefer sequential probing with bounded fan-out

Routee Supervision

When a routee panics, the router receives a PanicSignal and applies the configured directive:

Stop (default): Terminate the routee and remove it from the pool
Restart: Restart the routee (with retry limits)
Resume: Keep the routee and continue processing

If all routees are stopped and none remain, the router shuts down and unhandled messages go to the deadletter.

Getting Started

Actor

Grains

Remoting

Cluster

Observability

Advanced

Architecture

Contribution

Reference

Meta Framework

Concept

Sending Messages

Routing Strategies

Standard Strategies (Fire-and-Forget)

Reply-Based Strategies

Spawning a Router

Router Options

Examples

Control Messages

GetRoutees

AdjustRouterPoolSize

Handling Replies (Scatter-Gather / Tail-Chopping)

When to Use

Routee Supervision

​Concept

​Sending Messages

​Routing Strategies

​Standard Strategies (Fire-and-Forget)

​Reply-Based Strategies

​Spawning a Router

​Router Options

​Examples

​Control Messages

​GetRoutees

​AdjustRouterPoolSize

​Handling Replies (Scatter-Gather / Tail-Chopping)

​When to Use

​Routee Supervision

Concept

Sending Messages

Routing Strategies

Standard Strategies (Fire-and-Forget)

Reply-Based Strategies

Spawning a Router

Router Options

Examples

Control Messages

GetRoutees

AdjustRouterPoolSize

Handling Replies (Scatter-Gather / Tail-Chopping)

When to Use

Routee Supervision