Routing Strategies

A strategy is a pluggable algorithm that answers one question: given a set of eligible candidates for a unit of work, which one wins? It is the decision-making core of Ductor's routing pipeline — the swappable part that turns "these three candidates all qualify" into "route to candidate B, and here's why." A strategy produces a Route (Decision), and its explanation is the seed of the work's eventual Receipt.

Most strategies rank candidates by weight, load, score, or learned value. A few — shark_tank (broadcast-and-claim) and the capacity marketplace — clear work through a market: candidates effectively bid, and the winner is chosen by market rules rather than a fixed score. Those are the clearing-native strategies. Priced market clearing (auctions, ping/post) runs today for lead distribution. Agent RFQ — humans and agents bidding on work — extends the same machinery: typed bid terms, buyer-side clearing, authenticated submission, a published task spec, disclosure-scoped discovery, and an autonomous agent bidder all ship as opt-in surfaces (agent_rfq.enabled, and agent_rfq.bidder_enabled separately gating agent spending). Executing the won work — turning an award into a run — is on the roadmap.

Everything a strategy needs is handed to it in a single request, and everything it decides comes back in a single response. Strategies never touch the database, Redis, or the network directly — the pipeline loads the facts, calls the strategy, and commits the result. That separation is what lets you swap a naive round-robin for a revenue-maximizing scorer without changing anything else.

The Strategy interface

Every strategy implements two methods, defined in pkg/strategy/interface.go:

type Strategy interface {
    // Info returns metadata: name, versions, capabilities. Called FIRST,
    // during loading, for compatibility checking — before any Select call.
    Info() Info

    // Select chooses one candidate from req.Candidates (guaranteed non-empty).
    // MUST be safe for concurrent calls from many goroutines.
    Select(ctx context.Context, req *SelectRequest) (*SelectResponse, error)
}

Implementations must be:

• Thread-safe — Select may be called concurrently from many goroutines. Any internal state (counters, cursors) must be synchronized.
• Stateless, or backed by thread-safe state — a round-robin counter is fine if it uses atomics or a shared cache; a plain map is not.
• Idempotent for identical inputs — the same request should produce the same decision. (Randomized and bandit strategies are the deliberate exception: their non-determinism is part of the contract.)

The hot path: Info first, then Select

Loading a strategy is a two-phase handshake:

1. Info() is called once, at load time. It returns the strategy's Name, InterfaceVersion, PluginVersion, optional MinRouterVersion, and its declared Capabilities. Ductor checks interface-version compatibility here and refuses to load anything it can't speak to. Info() never runs on the hot path.
2. Select() is called on every routing decision. This is the hot path: it receives a *SelectRequest, returns a *SelectResponse, and must be fast and concurrency-safe. req.Candidates is guaranteed non-empty — the pipeline returns an error before calling a strategy if filtering left nothing.

What a strategy receives and returns

The SelectRequest (in pkg/strategy/types.go) carries everything the strategy is allowed to see:

Each Candidate exposes ID, Weight, CurrentLoad, MaxConcurrent, Location, Attributes, Tags, a pre-computed rule Score, and LastAssignedAt. A strategy reads whichever of these it needs.

The SelectResponse carries the decision back:

The registry

Strategies are discovered and instantiated through the Registry (pkg/strategy/registry.go). It maps a name to a factory, creates instances lazily, and resolves aliases.

reg := strategy.NewRegistry()
builtin.RegisterBuiltins(reg)              // register the built-in pack
reg.RegisterAlias("rr", "smooth_weighted_round_robin")

s, err := reg.Get("smooth_weighted_round_robin") // lazy, lock-free hot path

Key properties:

• Lazy, exactly-once instantiation. Factories run inside a sync.Once on first Get; after that, lookups are a lock-free sync.Map load. A factory can safely call back into the registry to resolve a dependency (for example, fair_catchup resolving its base strategy) without deadlocking.
• Aliases. RegisterAlias(alias, target) points a second name at an existing factory. Alias chains resolve transitively with cycle protection. Every strategy's documented aliases below are real registry aliases.
• Configured instances. Configure(instanceName, factoryName, config) and GetWithConfig(name, config) produce named or per-config instances so the same algorithm can be bound to different parameters in different pools.

A pool names the strategy it wants; the routing pipeline calls reg.Get(name) and runs Select. Swapping a pool's strategy is a config change, not a redeploy.

The built-in registry

Ductor includes the following built-in strategy names. Aliases resolve to the same strategy factory.

Two contrib modules add more names when installed and enabled:

• predicted (modules/strategies/predicted/register.go) — predicted_value plus the bandits thompson_sampling, linucb, and bandit. See Learning.
• geographic (modules/strategies/geographic) — geo_nearest and geo_weighted. See Geo.

Capability interfaces

The base Strategy interface is deliberately small. A strategy that can do more implements an optional capability interface and advertises it in Info().Capabilities. The pipeline type-asserts for the interface before using it, so a strategy only pays for what it supports.

The remaining capabilities are pure metadata (no method): CapabilityWeighted (honors candidate weights), CapabilityStateful (keeps state across selections), CapabilityGeoAware (uses location), CapabilityMetrics (exposes Prometheus metrics), CapabilityMultiWinner (marks several winners in one slate), and CapabilityPipelineStage (opts a strategy into bounded composite / pipeline execution). The complete set — eleven constants — lives in pkg/strategy/version.go; IsValidCapability and AllCapabilities enumerate them.

Params, modes, and aliases

Throughout these pages each strategy is documented with three consistent attributes:

• Params — typed, tunable knobs. Each has a kind (slider, number, boolean, string, enum), a default, and for numeric kinds a min/max/step. Params are validated against their spec before they reach a pool, so dead knobs never get persisted (pkg/strategy/validate_params.go).
• Modes — the shape of selection a strategy operates in: weighted, scoring, single, ranked, multi_winner, or broadcast. A strategy may support more than one.
• Aliases — alternative registry names that resolve to the same strategy.

Choosing a strategy

Start from the problem, not the algorithm:

Browse by category