@stacksjs/rpx/dist/load-balancer.d.ts

A modern and smart reverse proxy.

import type { LoadBalancerConfig, LoadBalancerStrategy, ProxyFrom } from './types';
/**
 * The ordered list of upstream `host:port` URLs a {@link ProxyFrom} resolves
 * to, ignoring weight/other per-upstream config. Lets callers cheaply compare
 * "does this pool still match this `from`" without rebuilding a full pool —
 * see `entryToRoute` in daemon.ts, which reconciles a cached pool against a
 * registry entry's current `from` on every call.
 */
export declare function resolveUpstreamUrls(from: ProxyFrom): string[];
/**
 * The first upstream's `host:port` from a {@link ProxyFrom}, for call sites
 * that need a single representative address (connection testing before the
 * pool exists, hosts-file checks, id derivation, log lines) rather than the
 * full pool. Defaults to `'localhost:5173'` to match rpx's historical
 * single-upstream default when `from` is unset.
 */
export declare function primaryUpstreamUrl(from?: ProxyFrom): string;
/**
 * Build a pool from a route's `from` (single string or array) plus optional
 * load-balancer config. Always returns at least one upstream when `from` is
 * set to a non-empty string/array; callers pass `''`/`[]` only for
 * static/redirect routes that carry no upstream at all (in which case use of
 * the pool is skipped entirely).
 */
export declare function createUpstreamPool(from: ProxyFrom, lbConfig?: LoadBalancerConfig): UpstreamPool;
/**
 * Pick the next upstream per the pool's configured strategy, considering only
 * currently-healthy upstreams (unless the pool is a degenerate single-upstream
 * pool — see {@link healthyUpstreams}). Returns `undefined` when the pool has
 * no upstreams at all, or every upstream (in an N>1 pool) is unhealthy — the
 * caller should respond with a 502 in that case.
 */
export declare function selectUpstream(pool: UpstreamPool): UpstreamState | undefined;
/** Record a successful outcome for `upstream` — passive health-check bookkeeping. */
export declare function markSuccess(pool: UpstreamPool, upstream: UpstreamState): void;
/** Record a failed outcome for `upstream` — passive health-check bookkeeping. */
export declare function markFailure(pool: UpstreamPool, upstream: UpstreamState): void;
/**
 * Start active health checking for `pool` when `healthCheck.enabled` — probes
 * every upstream on `healthCheck.interval`, independent of live traffic. No-op
 * (and idempotent) when active checks are disabled or already running. Always
 * pair with {@link stopHealthChecks} on server shutdown so the interval
 * doesn't leak.
 */
export declare function startHealthChecks(pool: UpstreamPool): void;
/** Stop active health checking for `pool`, if running. Safe to call repeatedly. */
export declare function stopHealthChecks(pool: UpstreamPool): void;
/** Per-upstream runtime state tracked across requests. */
export declare interface UpstreamState {
  url: string
  weight: number
  healthy: boolean
  activeConnections: number
  consecutiveFailures: number
  consecutiveSuccesses: number
}
declare interface ResolvedHealthCheckConfig {
  enabled: boolean
  path: string
  interval: number
  timeout: number
  healthyThreshold: number
  unhealthyThreshold: number
}
/** A route's normalized upstream pool + selection/health state. */
export declare interface UpstreamPool {
  upstreams: UpstreamState[]
  strategy: LoadBalancerStrategy
  healthCheck: ResolvedHealthCheckConfig
  cursor: number
  wrrCurrentWeights: number[]
  healthCheckTimer: ReturnType<typeof setInterval> | null
}