feat(routing): add weighted strategy with smooth weighted round-robin selector

Add a third routing strategy alongside round-robin (default) and
fill-first that distributes traffic across credentials according
to a configurable weight per key. The new WeightedSelector uses
the smooth weighted round-robin algorithm popularized by nginx
(Wensong Zhang) so weights like 7:3 yield an interleaved 7:3 share
without long runs on any single credential.

Each key type (ClaudeKey, CodexKey, GeminiKey, OpenAICompatibility,
VertexCompatKey) gains an optional 'weight' field that the
synthesizer propagates to auth.Attributes['weight']. Missing,
non-positive, or unparsable weights coerce to 1 so a misconfigured
credential still participates fairly. Priority remains a strict
tier above weight - high-priority credentials are exhausted before
weights inside lower tiers are considered.

Wire the strategy through builder.go, service.go hot reload, and
the management API normalize function. The selector is intentionally
not registered as a built-in selector so the conductor's legacy
pick path drives it directly, keeping the scheduler fast-path
unchanged.

Documented in config.example.yaml. Covered by 9 unit tests in
sdk/cliproxy/auth/weighted_selector_test.go including the canonical
SWRR sequence, ratio convergence over 1000 picks, default-weight
behavior, priority dominance, per-route state isolation, and a
concurrency stress test.

Author: conversun

config.example.yaml

@@ -112,7 +112,15 @@ quota-exceeded:
 
 # Routing strategy for selecting credentials when multiple match.
 routing:
-  strategy: "round-robin" # round-robin (default), fill-first
+  strategy: "round-robin" # round-robin (default), fill-first, weighted
+  # round-robin: even cyclic distribution across all available credentials.
+  # fill-first:  always use the first available credential; "burns" one before
+  #              moving to the next. Useful to stagger rolling-window quotas.
+  # weighted:    smooth weighted round-robin (nginx SWRR). Each credential's
+  #              `weight` field sets its relative traffic share. Missing or
+  #              non-positive weights default to 1. Priority still dominates:
+  #              higher-priority credentials are exhausted first; weights only
+  #              rank credentials inside the same priority tier.
   # Enable universal session-sticky routing for all clients.
   # Session IDs are extracted from: metadata.user_id (Claude Code session format),
   # X-Session-ID, Session_id (Codex), X-Amp-Thread-Id (Amp CLI),
@@ -149,6 +157,8 @@ nonstream-keepalive-interval: 0
 # Gemini API keys
 # gemini-api-key:
 #   - api-key: "AIzaSy...01"
+#     priority: 10 # higher tiers are picked before lower tiers
+#     weight: 7    # only used when routing.strategy is "weighted"
 #     prefix: "test" # optional: require calls like "test/gemini-3-pro-preview" to target this credential
 #     base-url: "https://generativelanguage.googleapis.com"
 #     headers:

internal/api/handlers/management/config_basic.go

@@ -286,6 +286,8 @@ func normalizeRoutingStrategy(strategy string) (string, bool) {
 		return "round-robin", true
 	case "fill-first", "fillfirst", "ff":
 		return "fill-first", true
+	case "weighted", "weight", "w":
+		return "weighted", true
 	default:
 		return "", false
 	}

internal/config/config.go

@@ -393,6 +393,11 @@ type ClaudeKey struct {
 	// Higher values are preferred; defaults to 0.
 	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
 
+	// Weight controls relative traffic share when routing.strategy is "weighted".
+	// Higher values receive proportionally more traffic. Defaults to 0 (treated as 1 by the selector).
+	// Ignored by other strategies.
+	Weight int `yaml:"weight,omitempty" json:"weight,omitempty"`
+
 	// Prefix optionally namespaces models for this credential (e.g., "teamA/claude-sonnet-4").
 	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
 
@@ -446,6 +451,11 @@ type CodexKey struct {
 	// Higher values are preferred; defaults to 0.
 	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
 
+	// Weight controls relative traffic share when routing.strategy is "weighted".
+	// Higher values receive proportionally more traffic. Defaults to 0 (treated as 1 by the selector).
+	// Ignored by other strategies.
+	Weight int `yaml:"weight,omitempty" json:"weight,omitempty"`
+
 	// Prefix optionally namespaces models for this credential (e.g., "teamA/gpt-5-codex").
 	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
 
@@ -494,6 +504,11 @@ type GeminiKey struct {
 	// Higher values are preferred; defaults to 0.
 	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
 
+	// Weight controls relative traffic share when routing.strategy is "weighted".
+	// Higher values receive proportionally more traffic. Defaults to 0 (treated as 1 by the selector).
+	// Ignored by other strategies.
+	Weight int `yaml:"weight,omitempty" json:"weight,omitempty"`
+
 	// Prefix optionally namespaces models for this credential (e.g., "teamA/gemini-3-pro-preview").
 	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
 
@@ -584,6 +599,11 @@ type OpenAICompatibility struct {
 	// Higher values are preferred; defaults to 0.
 	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
 
+	// Weight controls relative traffic share when routing.strategy is "weighted".
+	// Higher values receive proportionally more traffic. Defaults to 0 (treated as 1 by the selector).
+	// Ignored by other strategies.
+	Weight int `yaml:"weight,omitempty" json:"weight,omitempty"`
+
 	// Disabled prevents this provider from being used for routing.
 	Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`
 

internal/config/vertex_compat.go

@@ -17,6 +17,11 @@ type VertexCompatKey struct {
 	// Higher values are preferred; defaults to 0.
 	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
 
+	// Weight controls relative traffic share when routing.strategy is "weighted".
+	// Higher values receive proportionally more traffic. Defaults to 0 (treated as 1 by the selector).
+	// Ignored by other strategies.
+	Weight int `yaml:"weight,omitempty" json:"weight,omitempty"`
+
 	// Prefix optionally namespaces model aliases for this credential (e.g., "teamA/vertex-pro").
 	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
 

internal/watcher/synthesizer/config.go

@@ -67,6 +67,9 @@ func (s *ConfigSynthesizer) synthesizeGeminiKeys(ctx *SynthesisContext) []*corea
 		if entry.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(entry.Priority)
 		}
+		if entry.Weight != 0 {
+			attrs["weight"] = strconv.Itoa(entry.Weight)
+		}
 		if base != "" {
 			attrs["base_url"] = base
 		}
@@ -114,6 +117,9 @@ func (s *ConfigSynthesizer) synthesizeClaudeKeys(ctx *SynthesisContext) []*corea
 		if ck.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(ck.Priority)
 		}
+		if ck.Weight != 0 {
+			attrs["weight"] = strconv.Itoa(ck.Weight)
+		}
 		if base != "" {
 			attrs["base_url"] = base
 		}
@@ -161,6 +167,9 @@ func (s *ConfigSynthesizer) synthesizeCodexKeys(ctx *SynthesisContext) []*coreau
 		if ck.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(ck.Priority)
 		}
+		if ck.Weight != 0 {
+			attrs["weight"] = strconv.Itoa(ck.Weight)
+		}
 		if ck.BaseURL != "" {
 			attrs["base_url"] = ck.BaseURL
 		}
@@ -225,6 +234,9 @@ func (s *ConfigSynthesizer) synthesizeOpenAICompat(ctx *SynthesisContext) []*cor
 			if compat.Priority != 0 {
 				attrs["priority"] = strconv.Itoa(compat.Priority)
 			}
+			if compat.Weight != 0 {
+				attrs["weight"] = strconv.Itoa(compat.Weight)
+			}
 			if key != "" {
 				attrs["api_key"] = key
 			}
@@ -259,6 +271,9 @@ func (s *ConfigSynthesizer) synthesizeOpenAICompat(ctx *SynthesisContext) []*cor
 			if compat.Priority != 0 {
 				attrs["priority"] = strconv.Itoa(compat.Priority)
 			}
+			if compat.Weight != 0 {
+				attrs["weight"] = strconv.Itoa(compat.Weight)
+			}
 			if hash := diff.ComputeOpenAICompatModelsHash(compat.Models); hash != "" {
 				attrs["models_hash"] = hash
 			}
@@ -304,6 +319,9 @@ func (s *ConfigSynthesizer) synthesizeVertexCompat(ctx *SynthesisContext) []*cor
 		if compat.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(compat.Priority)
 		}
+		if compat.Weight != 0 {
+			attrs["weight"] = strconv.Itoa(compat.Weight)
+		}
 		if key != "" {
 			attrs["api_key"] = key
 		}

sdk/cliproxy/auth/selector.go

@@ -35,6 +35,19 @@ type RoundRobinSelector struct {
 // rolling-window subscription caps (e.g. chat message limits).
 type FillFirstSelector struct{}
 
+// WeightedSelector distributes traffic across credentials using the smooth
+// weighted round-robin algorithm popularized by nginx (Wensong Zhang).
+// Each auth's relative share is taken from its "weight" attribute, defaulting
+// to 1 when missing or non-positive. Within a priority tier, the algorithm
+// produces a smooth, drift-free distribution that avoids long runs on a single
+// credential while still honoring the configured ratios over time.
+// Reference: https://github.com/phusion/nginx/commit/27e9498
+type WeightedSelector struct {
+	mu      sync.Mutex
+	states  map[string]map[string]int // provider:model -> authID -> currentWeight
+	maxKeys int
+}
+
 type blockReason int
 
 const (
@@ -128,6 +141,24 @@ func authPriority(auth *Auth) int {
 	return parsed
 }
 
+// authWeight reads the integer weight from an auth's attributes. Missing,
+// blank, invalid, or non-positive values resolve to 1 so a credential without
+// an explicit weight still participates fairly alongside weighted peers.
+func authWeight(auth *Auth) int {
+	if auth == nil || auth.Attributes == nil {
+		return 1
+	}
+	raw := strings.TrimSpace(auth.Attributes["weight"])
+	if raw == "" {
+		return 1
+	}
+	parsed, err := strconv.Atoi(raw)
+	if err != nil || parsed < 1 {
+		return 1
+	}
+	return parsed
+}
+
 func canonicalModelKey(model string) string {
 	model = strings.TrimSpace(model)
 	if model == "" {
@@ -368,6 +399,84 @@ func (s *FillFirstSelector) Pick(ctx context.Context, provider, model string, op
 	return available[0], nil
 }
 
+// Pick selects the next available auth using smooth weighted round-robin.
+// Each call advances every candidate's current weight by its configured weight,
+// chooses the candidate with the highest current weight, then subtracts the
+// total weight from the winner. This produces a jitter-free interleaving that
+// matches the configured ratio over any sufficiently long window.
+func (s *WeightedSelector) Pick(ctx context.Context, provider, model string, opts cliproxyexecutor.Options, auths []*Auth) (*Auth, error) {
+	_ = opts
+	now := time.Now()
+	available, err := getAvailableAuths(auths, provider, model, now)
+	if err != nil {
+		return nil, err
+	}
+	available = preferCodexWebsocketAuths(ctx, provider, available)
+	if len(available) == 1 {
+		return available[0], nil
+	}
+
+	key := provider + ":" + canonicalModelKey(model)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.states == nil {
+		s.states = make(map[string]map[string]int)
+	}
+	limit := s.maxKeys
+	if limit <= 0 {
+		limit = 4096
+	}
+	state, ok := s.states[key]
+	if !ok {
+		if len(s.states) >= limit {
+			s.states = make(map[string]map[string]int)
+		}
+		state = make(map[string]int)
+		s.states[key] = state
+	}
+
+	// Smooth weighted round-robin: advance every candidate's current weight by
+	// its configured weight, pick the maximum, and subtract the total from it.
+	var best *Auth
+	var bestCurrent int
+	totalWeight := 0
+	for _, auth := range available {
+		if auth == nil {
+			continue
+		}
+		w := authWeight(auth)
+		totalWeight += w
+		cw := state[auth.ID] + w
+		state[auth.ID] = cw
+		if best == nil || cw > bestCurrent || (cw == bestCurrent && auth.ID < best.ID) {
+			best = auth
+			bestCurrent = cw
+		}
+	}
+	if best == nil {
+		return nil, &Error{Code: "auth_not_found", Message: "selector returned no auth"}
+	}
+	state[best.ID] = bestCurrent - totalWeight
+
+	// Bound state size by pruning entries for auths that are no longer in the
+	// available set. Done opportunistically when the map grows much larger than
+	// the candidate set to keep the common-case fast.
+	if len(state) > 4*len(available)+8 {
+		keep := make(map[string]struct{}, len(available))
+		for _, auth := range available {
+			if auth != nil {
+				keep[auth.ID] = struct{}{}
+			}
+		}
+		for id := range state {
+			if _, ok := keep[id]; !ok {
+				delete(state, id)
+			}
+		}
+	}
+	return best, nil
+}
+
 func isAuthBlockedForModel(auth *Auth, model string, now time.Time) (bool, blockReason, time.Time) {
 	if auth == nil {
 		return true, blockReasonOther, time.Time{}