skills/plugins/library-navigator/skills/api-stack/api-gateway/sp-api-gateway-balancer-round-robin/SKILL.md

name, description

name	description
sp-api-gateway-balancer-round-robin	Round-robin load-balancer strategy for @suaveplan/api-gateway. select() returns the next healthy target in registration order via a per-instance counter, distributing evenly (within ±1). Drop-in variant package — register under "round-robin" in a BalancerRegistry.

@suaveplan/api-gateway-balancer-round-robin

Purpose

Round-robin load-balancer strategy for @suaveplan/api-gateway. select() returns the next selectable target in registration order via a per-instance counter, distributing evenly (within ±1) across the healthy set.

One package per strategy: the core gateway depends on no concrete strategy and resolves one per route through its BalancerRegistry, so you register exactly the strategies you use.

Architecture

Component	Source	Role
roundRobinBalancer	src/round-robin/round-robin.ts	LoadBalancerFactory implementing the ILoadBalancer contract

File Structure

src/
  index.ts              # Exports roundRobinBalancer
  round-robin/
    round-robin.ts      # Strategy implementation
    round-robin.md      # Module docs
    round-robin.test.ts

Entry Points

Import	Exports
@suaveplan/api-gateway-balancer-round-robin	roundRobinBalancer
@suaveplan/api-gateway-balancer-round-robin/round-robin/round-robin	Same from feature subpath

Patterns

Register and use

import { createBalancerRegistry, createGateway } from "@suaveplan/api-gateway";
import { roundRobinBalancer } from "@suaveplan/api-gateway-balancer-round-robin";

const balancers = createBalancerRegistry();
balancers.register("round-robin", roundRobinBalancer);

const gateway = createGateway({
    balancers,
    routes: [
        {
            pattern: "/api/*",
            targets: [
                { id: "a", url: "https://a.svc" },
                { id: "b", url: "https://b.svc" },
            ],
        },
    ],
});

Constraints

• Drop-in variant — depends only on @suaveplan/api-gateway types and tslib.
• Even distribution — targets receive requests within ±1 of each other.
• Per-instance counter — each balancer instance maintains its own position.
• Dependencies: @suaveplan/api-gateway, tslib.

Checklist

• Read src/round-robin/round-robin.ts before modifying strategy
• Preserve even distribution semantics
• Ensure counter wraps correctly across the healthy set