Routers

​

Concept

​

Sending messages

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

​

Routing strategies

​

Standard strategies (fire-and-forget)

• RoundRobin: Rotate through routees in a fixed order (spawn order), cycling back to the first after the last.
• Random: Pick a random routee.
• FanOut: Send a copy to every routee (default). Each routee receives the copies in the order the router handled the broadcasts.
• ConsistentHash: Route messages with the same key to the same routee (sticky sessions).

​

Reply-based strategies

• 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

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

• 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

• WithRoutingStrategy: Set RoundRobin, Random, FanOut, or ConsistentHash. Default is FanOut.
• WithConsistentHashRouter: 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: Virtual nodes per routee for the hash ring (default 150). Only with WithConsistentHashRouter.
• WithConsistentHashHasher: Custom hash function for the ring (default xxh3). Only with WithConsistentHashRouter.
• AsScatterGatherFirst: Use scatter-gather-first. within is the total time budget for any reply.
• AsTailChopping: 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: On routee panic: restart the routee (up to maxRetries attempts, timeout apart).
• 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 attempts 1s apart
system.SpawnRouter(ctx, "resilient", 5, &Worker{}, actor.WithRestartRouteeOnFailure(3, time.Second))

​

Control messages

• GetRoutees: Usage: Query current routee names. Response: Routees (use Ask).
• AdjustRouterPoolSize: Usage: Scale pool at runtime. Response: 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)

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

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

• 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