From 8b4db03632604848fbac90e139682706cd07a153 Mon Sep 17 00:00:00 2001 From: 3Tn0 Date: Thu, 19 Nov 2026 17:03:59 +0300 Subject: [PATCH 1/2] feat: add round-robin connection balancing --- README.md | 9 +- lib/core.ts | 12 ++- lib/dispatcher.ts | 74 ++++++++++++++-- lib/types.ts | 25 ++++++ tests/dispatcher.test.js | 181 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 291 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b33f8ca..25d7d98 100644 --- a/README.md +++ b/README.md @@ -64,11 +64,14 @@ export const {db, CoreBaseModel, helpers} = initDB({ - `suppressStatusLogs`: Boolean value that disables database health-check status logs (useful for developers) - `beforeTerminate`: Function called before terminating a connection, must return a Promise - `topologyMode`: Connection topology, either `primary-replica` (the default) or `proxy` + - `balancingStrategy`: How a host is chosen for `db.replica` (and for both `db.primary` and `db.replica` in `proxy` mode), an object with a `kind` field: + - `{kind: 'fastest'}` (the default): always picks the host with the lowest latest health-check latency; among equally fast hosts, the first one in the connection list + - `{kind: 'round-robin', latencyTolerance?: number}`: healthy hosts are used in turn, spreading load across them. Without `latencyTolerance`, every healthy host takes part regardless of latency, so with hosts in several data centers part of the load goes to distant ones. Set `latencyTolerance` (in milliseconds) to rotate only hosts whose latest health-check latency is within that value of the fastest one, e.g. `10` to skip distant hosts, or `0` to rotate only the hosts sharing the lowest latency - `knexOptions`: Non-required additional options that will be passed to Knex before initialization - `onKnexCreated`: Optional callback called synchronously for each Knex instance created by the dispatcher, before database health checks start. Use it to attach instrumentation, event listeners, or plugins that do not require an active database connection. If it throws, initialization fails. The callback receives the Knex instance and returns nothing. - `onHealthcheck`: Optional synchronous callback called after each database health check with a snapshot of every host's availability, latency, and role. In `primary-replica` mode, unavailable hosts have the `unknown` role; proxy connections do not include a role. It is called even when `suppressStatusLogs` is enabled. Callback errors do not interrupt database routing or subsequent health checks. -When all connection strings point to equivalent proxy or router instances, such as SPQR routers, use `proxy` mode. Healthy endpoints are then eligible for both primary and replica queries, and the endpoint with the lowest latest health-check latency is selected: +When all connection strings point to equivalent proxy or router instances, such as SPQR routers, use `proxy` mode. Healthy endpoints are then eligible for both primary and replica queries, and the endpoint with the lowest latest health-check latency is selected (with the `round-robin` balancing strategy, endpoints are rotated instead): ```typescript initDB({ @@ -96,14 +99,14 @@ The `initDB` constructor exports three elements: `db`, `CoreBaseModel`, and `hel ### db -`db`: Instance of the [PGDispatcher](https://github.com/gravity-ui/postgreskit/blob/main/lib/dispatcher.ts) module responsible for connection balancing. Under the hood, this module creates N instances of knex (N is the number of hosts passed in `connectionString`). By default, it polls the database hosts every `healthcheckInterval` milliseconds, requesting if they are primary hosts or replica hosts (using the `SELECT pg_is_in_recovery()` query). In `proxy` topology mode, it uses `SELECT 1` instead and routes both `db.primary` and `db.replica` to the fastest healthy endpoint. +`db`: Instance of the [PGDispatcher](https://github.com/gravity-ui/postgreskit/blob/main/lib/dispatcher.ts) module responsible for connection balancing. Under the hood, this module creates N instances of knex (N is the number of hosts passed in `connectionString`). By default, it polls the database hosts every `healthcheckInterval` milliseconds, requesting if they are primary hosts or replica hosts (using the `SELECT pg_is_in_recovery()` query). In `proxy` topology mode, it uses `SELECT 1` instead and routes both `db.primary` and `db.replica` to the fastest healthy endpoint (or rotates between healthy endpoints with the `round-robin` balancing strategy). Public `db` methods: - `ready`: Function that returns a Promise that is resolved after the database connection has been established. This function is useful when you do not want to start query processing until the database is ready: for this, add `await db.ready(); next()` as middleware - `terminate`: Terminates all connections and returns a Promise which is resolved after `knex.destroy()` executes for each connection - `primary`: Getter that always points at the knex instance targeting the current primary host. If there is no primary host, when trying to access `db.primary`, you will get an error with the `ERR_DB_READ_ONLY` code -- `replica`: Getter that always points at the knex instance targeting the fastest available replica host. The speed is determined from the latest health-check query response time. If only the primary host is available, `db.replica` returns it, logging a warning about an attempt to read from the `primary` replica. If no host is available, `db.replica` throws an error with the `ERR_DB_UNAVAILABLE` code +- `replica`: Getter that points at the knex instance targeting the fastest available replica host. The speed is determined from the latest health-check query response time. With the `round-robin` balancing strategy, healthy replicas (limited by `latencyTolerance`, if set) are returned in turn, so consecutive accesses may return different instances and therefore replicas with different replication lag. If only the primary host is available, `db.replica` returns it, logging a warning about an attempt to read from the `primary` replica. If no host is available, `db.replica` throws an error with the `ERR_DB_UNAVAILABLE` code Both `db.primary` and `db.replica` point to regular knex instances that can do everything described in the [knex documentation](https://knexjs.org/). diff --git a/lib/core.ts b/lib/core.ts index 523d3ca..9850c96 100644 --- a/lib/core.ts +++ b/lib/core.ts @@ -4,9 +4,17 @@ import {type Constructor, Model} from 'objection'; import {defaultDispatcherOptions, defaultExLogger, defaultKnexOptions} from './constants'; import {PGDispatcher} from './dispatcher'; -import type {BaseModel, ExLogger, PGHealthcheckHandler, TopologyMode} from './types'; +import type { + BalancingStrategy, + BaseModel, + ExLogger, + PGHealthcheckHandler, + TopologyMode, +} from './types'; export type { + BalancingStrategy, + FastestBalancingStrategy, PGConnectionRole, PGConnectionStatus, PGHealthcheckHandler, @@ -14,6 +22,7 @@ export type { PGPrimaryReplicaConnectionStatus, PGPrimaryReplicaHealthcheckStatus, PGProxyHealthcheckStatus, + RoundRobinBalancingStrategy, TopologyMode, } from './types'; @@ -24,6 +33,7 @@ export interface CoreDBDispatcherOptions { suppressHealthcheckStatusLogs?: boolean; beforeTerminate?: () => Promise; topologyMode?: TopologyMode; + balancingStrategy?: BalancingStrategy; } export type GetModelParams = {cancelOnTimeout?: boolean; useLimitInFirst?: boolean}; diff --git a/lib/dispatcher.ts b/lib/dispatcher.ts index 796af36..07349c9 100644 --- a/lib/dispatcher.ts +++ b/lib/dispatcher.ts @@ -4,6 +4,7 @@ import knexBuilder from 'knex'; import type {Knex} from 'knex'; import type { + BalancingStrategy, Dict, ExLogger, PDOptions, @@ -49,6 +50,40 @@ interface PDCheckupResult { primary: boolean; } +// returns the first connection with the lowest latency, so ties go to the earliest one +function fastestConnection(candidates: PDConnection[]) { + let fastest = candidates[0]; + + for (const candidate of candidates) { + if (candidate.latency < fastest.latency) { + fastest = candidate; + } + } + + return fastest; +} + +function validateBalancingStrategy(strategy?: BalancingStrategy): BalancingStrategy { + if (strategy?.kind !== 'round-robin') { + return {kind: 'fastest'}; + } + + const {latencyTolerance} = strategy; + + if ( + latencyTolerance !== undefined && + (!Number.isFinite(latencyTolerance) || latencyTolerance < 0) + ) { + throw new Error( + `balancingStrategy.latencyTolerance must be a non-negative finite number, got ${String( + latencyTolerance, + )}`, + ); + } + + return {kind: 'round-robin', latencyTolerance}; +} + export class PDError extends Error { code?: string; } @@ -63,6 +98,8 @@ export class PGDispatcher { private hcTimer?: Timeout | null; private isInit = false; private isTerminating = false; + private readonly balancingStrategy: BalancingStrategy; + private balancingCursor = 0; constructor({ connections = [], @@ -76,6 +113,8 @@ export class PGDispatcher { throw new Error('Empty connections list is not allowed'); } + this.balancingStrategy = validateBalancingStrategy(options.balancingStrategy); + this.connections = connections.map((connectionString) => { const url = new URL(connectionString); const knex = knexBuilder({ @@ -163,7 +202,7 @@ export class PGDispatcher { this.checkConnectionsAvailability(); if (this.isProxyMode) { - return this.fastestHealthyConnection.knex; + return this.selectConnection(this.healthyConnections).knex; } const primaryConnections = this.connections.filter((c) => c.primary); @@ -189,14 +228,13 @@ export class PGDispatcher { this.checkConnectionsAvailability(); if (this.isProxyMode) { - return this.fastestHealthyConnection.knex; + return this.selectConnection(this.healthyConnections).knex; } const replicaConnections = this.healthyConnections.filter((c) => !c.primary); if (replicaConnections.length) { - const fastestReplica = replicaConnections.sort((a, b) => a.latency - b.latency)[0]; - return fastestReplica.knex; + return this.selectConnection(replicaConnections).knex; } if (this.connections.length > 1) { this.logger.error({message: 'No alive replica available, using master for read'}); @@ -389,8 +427,32 @@ export class PGDispatcher { return this.options.topologyMode === 'proxy'; } - private get fastestHealthyConnection() { - return this.healthyConnections.sort((a, b) => a.latency - b.latency)[0]; + // `candidates` must be non-empty. + private selectConnection(candidates: PDConnection[]) { + const strategy = this.balancingStrategy; + + if (strategy.kind === 'round-robin') { + return this.selectRoundRobin(candidates, strategy.latencyTolerance); + } + + return fastestConnection(candidates); + } + + // Rotates between all connections or, when `latencyTolerance` is set, only those whose + // latest health-check latency is within `latencyTolerance` ms of the fastest one. + private selectRoundRobin(candidates: PDConnection[], latencyTolerance?: number) { + let eligible = candidates; + + if (latencyTolerance !== undefined) { + const minLatency = fastestConnection(candidates).latency; + eligible = candidates.filter((c) => c.latency <= minLatency + latencyTolerance); + } + + // the window may shrink between health checks, so wrap the stored position into it + const index = this.balancingCursor % eligible.length; + this.balancingCursor = index + 1; + + return eligible[index]; } private checkConnectionsAvailability() { diff --git a/lib/types.ts b/lib/types.ts index cec05a8..85c9111 100644 --- a/lib/types.ts +++ b/lib/types.ts @@ -3,6 +3,30 @@ import type {PGDispatcher} from './dispatcher'; export type TopologyMode = 'primary-replica' | 'proxy'; +/** + * always the connection with the lowest latest health-check latency; + * among equally fast ones, the first in the connections list (default) + */ +export interface FastestBalancingStrategy { + kind: 'fastest'; +} + +/** + * every healthy connection in turn; with `latencyTolerance`, only those whose latest + * health-check latency is within that many ms of the lowest one + */ +export interface RoundRobinBalancingStrategy { + kind: 'round-robin'; + /** + * latency window in ms: when set, only connections whose latest health-check latency + * is within this value of the lowest one are rotated (0 — only the fastest ones). + * When omitted, all healthy connections are rotated + */ + latencyTolerance?: number; +} + +export type BalancingStrategy = FastestBalancingStrategy | RoundRobinBalancingStrategy; + export interface PGConnectionStatus { readonly host: string; readonly healthy: boolean; @@ -39,6 +63,7 @@ export interface PDOptions { suppressHealthcheckStatusLogs?: boolean; beforeTerminate: () => Promise; topologyMode: TopologyMode; + balancingStrategy?: BalancingStrategy; } export type Dict = {[key: string]: unknown}; diff --git a/tests/dispatcher.test.js b/tests/dispatcher.test.js index cf75419..f844a44 100644 --- a/tests/dispatcher.test.js +++ b/tests/dispatcher.test.js @@ -5,6 +5,7 @@ jest.mock('knex', () => jest.fn()); const knexBuilder = require('knex'); const {defaultDispatcherOptions} = require('../build/constants'); +const {initDB} = require('../build/core'); const {PGDispatcher} = require('../build/dispatcher'); const activeDispatchers = []; @@ -322,3 +323,183 @@ describe('PGDispatcher healthcheck timer cleanup', () => { expect(jest.getTimerCount()).toBe(0); }); }); + +describe('PGDispatcher balancing strategies', () => { + function pick(dispatcher, role, times) { + return Array.from({length: times}, () => dispatcher[role]); + } + + // health-check latencies are measured with real timers; pin them to avoid jitter + function setLatencies(dispatcher, latencies) { + dispatcher.connections.forEach((connection, index) => { + connection.latency = latencies[index]; + }); + } + + function createReplicaSet(replicaCount, options) { + const primary = createKnex(successfulCheckup({pg_is_in_recovery: false})); + const replicas = Array.from({length: replicaCount}, () => + createKnex(successfulCheckup({pg_is_in_recovery: true})), + ); + const {dispatcher} = createDispatcher([primary, ...replicas], options); + + return {dispatcher, primary, replicas}; + } + + test('routes to the fastest replica when no balancing strategy is provided', async () => { + const {dispatcher, primary, replicas} = createReplicaSet(3); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 3, 1, 2]); + + expect(new Set(pick(dispatcher, 'replica', 4))).toEqual(new Set([replicas[1]])); + expect(dispatcher.primary).toBe(primary); + }); + + test('fastest does not rotate equally fast replicas', async () => { + const {dispatcher, replicas} = createReplicaSet(3, {balancingStrategy: {kind: 'fastest'}}); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 1, 1, 2]); + + expect(new Set(pick(dispatcher, 'replica', 4))).toEqual(new Set([replicas[0]])); + }); + + test.each([-1, NaN, Infinity, null, '10'])( + 'rejects an invalid latencyTolerance: %p', + (latencyTolerance) => { + // validation runs before any knex instance is created, so no knex mocks are queued + expect( + () => + new PGDispatcher({ + connections: ['postgresql://user:password@database-0.example/db'], + logger: {info: jest.fn(), error: jest.fn()}, + options: { + ...defaultDispatcherOptions, + balancingStrategy: {kind: 'round-robin', latencyTolerance}, + }, + }), + ).toThrow('balancingStrategy.latencyTolerance must be a non-negative finite number'); + }, + ); + + test('uses the validated strategy after the original options are changed', async () => { + const balancingStrategy = {kind: 'round-robin', latencyTolerance: 10}; + const {dispatcher, replicas} = createReplicaSet(2, {balancingStrategy}); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 1, 2]); + balancingStrategy.latencyTolerance = -1; + + expect(pick(dispatcher, 'replica', 2)).toEqual(replicas); + }); + + test('initDB uses the configured strategy to select proxies', async () => { + const proxies = [ + createKnex(successfulCheckup({value: 1})), + createKnex(successfulCheckup({value: 1})), + ]; + proxies.forEach((proxy) => knexBuilder.mockImplementationOnce(() => proxy)); + + const {db, terminate} = initDB({ + connectionString: 'postgresql://db-0.example/db,postgresql://db-1.example/db', + dispatcherOptions: { + topologyMode: 'proxy', + healthcheckInterval: 60_000, + balancingStrategy: {kind: 'round-robin'}, + }, + logger: {info: jest.fn(), error: jest.fn()}, + }); + activeDispatchers.push(db); + + try { + await db.ready(); + setLatencies(db, [1, 2]); + + expect(pick(db, 'primary', 2)).toEqual(proxies); + } finally { + process.removeListener('SIGINT', terminate); + } + }); + + test('round-robin with a zero window rotates only equally fast replicas', async () => { + const {dispatcher, replicas} = createReplicaSet(3, { + balancingStrategy: {kind: 'round-robin', latencyTolerance: 0}, + }); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 1, 1, 2]); + + expect(pick(dispatcher, 'replica', 4)).toEqual([ + replicas[0], + replicas[1], + replicas[0], + replicas[1], + ]); + }); + + test('rotates replicas whose latency is within the tolerance window', async () => { + const {dispatcher, replicas} = createReplicaSet(3, { + balancingStrategy: {kind: 'round-robin', latencyTolerance: 10}, + }); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 2, 12, 13]); + + expect(pick(dispatcher, 'replica', 4)).toEqual([ + replicas[0], + replicas[1], + replicas[0], + replicas[1], + ]); + }); + + test('round-robin without a window uses every healthy replica regardless of latency', async () => { + const primary = createKnex(successfulCheckup({pg_is_in_recovery: false})); + const replicas = [0, 30, 60].map((latency) => + createKnex(successfulCheckup({pg_is_in_recovery: true}, latency)), + ); + const unhealthyReplica = createKnex(failedCheckup); + const {dispatcher} = createDispatcher([primary, ...replicas, unhealthyReplica], { + balancingStrategy: {kind: 'round-robin'}, + }); + + await dispatcher.ready(); + + expect(pick(dispatcher, 'replica', 6)).toEqual([...replicas, ...replicas]); + }); + + test('keeps rotating evenly after the window shrinks', async () => { + const {dispatcher, replicas} = createReplicaSet(3, { + balancingStrategy: {kind: 'round-robin', latencyTolerance: 0}, + }); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 1, 1, 1]); + + pick(dispatcher, 'replica', 2); // position now points at the third replica + setLatencies(dispatcher, [1, 1, 1, 100]); + + expect(pick(dispatcher, 'replica', 4)).toEqual([ + replicas[0], + replicas[1], + replicas[0], + replicas[1], + ]); + }); + + test('proxy mode rotates both roles across proxies within the tolerance window', async () => { + const proxies = [0, 1, 2].map(() => createKnex(successfulCheckup({value: 1}))); + const {dispatcher} = createDispatcher(proxies, { + topologyMode: 'proxy', + balancingStrategy: {kind: 'round-robin', latencyTolerance: 10}, + }); + + await dispatcher.ready(); + setLatencies(dispatcher, [1, 5, 80]); + + for (const role of ['primary', 'replica']) { + expect(new Set(pick(dispatcher, role, 4))).toEqual(new Set(proxies.slice(0, 2))); + } + }); +}); From 8d07dd8dbae1c40824c795cc536f46fed27edea9 Mon Sep 17 00:00:00 2001 From: 3Tn0 Date: Thu, 19 Nov 2026 19:15:02 +0300 Subject: [PATCH 2/2] refactor: rename latencyTolerance to latencyToleranceMs Make the unit clear at the call site. --- README.md | 4 ++-- lib/dispatcher.ts | 24 ++++++++++++------------ lib/types.ts | 4 ++-- tests/dispatcher.test.js | 20 ++++++++++---------- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 25d7d98..d98788d 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ export const {db, CoreBaseModel, helpers} = initDB({ - `topologyMode`: Connection topology, either `primary-replica` (the default) or `proxy` - `balancingStrategy`: How a host is chosen for `db.replica` (and for both `db.primary` and `db.replica` in `proxy` mode), an object with a `kind` field: - `{kind: 'fastest'}` (the default): always picks the host with the lowest latest health-check latency; among equally fast hosts, the first one in the connection list - - `{kind: 'round-robin', latencyTolerance?: number}`: healthy hosts are used in turn, spreading load across them. Without `latencyTolerance`, every healthy host takes part regardless of latency, so with hosts in several data centers part of the load goes to distant ones. Set `latencyTolerance` (in milliseconds) to rotate only hosts whose latest health-check latency is within that value of the fastest one, e.g. `10` to skip distant hosts, or `0` to rotate only the hosts sharing the lowest latency + - `{kind: 'round-robin', latencyToleranceMs?: number}`: healthy hosts are used in turn, spreading load across them. Without `latencyToleranceMs`, every healthy host takes part regardless of latency, so with hosts in several data centers part of the load goes to distant ones. Set `latencyToleranceMs` to rotate only hosts whose latest health-check latency is within that value of the fastest one, e.g. `10` to skip distant hosts, or `0` to rotate only the hosts sharing the lowest latency - `knexOptions`: Non-required additional options that will be passed to Knex before initialization - `onKnexCreated`: Optional callback called synchronously for each Knex instance created by the dispatcher, before database health checks start. Use it to attach instrumentation, event listeners, or plugins that do not require an active database connection. If it throws, initialization fails. The callback receives the Knex instance and returns nothing. - `onHealthcheck`: Optional synchronous callback called after each database health check with a snapshot of every host's availability, latency, and role. In `primary-replica` mode, unavailable hosts have the `unknown` role; proxy connections do not include a role. It is called even when `suppressStatusLogs` is enabled. Callback errors do not interrupt database routing or subsequent health checks. @@ -106,7 +106,7 @@ Public `db` methods: - `ready`: Function that returns a Promise that is resolved after the database connection has been established. This function is useful when you do not want to start query processing until the database is ready: for this, add `await db.ready(); next()` as middleware - `terminate`: Terminates all connections and returns a Promise which is resolved after `knex.destroy()` executes for each connection - `primary`: Getter that always points at the knex instance targeting the current primary host. If there is no primary host, when trying to access `db.primary`, you will get an error with the `ERR_DB_READ_ONLY` code -- `replica`: Getter that points at the knex instance targeting the fastest available replica host. The speed is determined from the latest health-check query response time. With the `round-robin` balancing strategy, healthy replicas (limited by `latencyTolerance`, if set) are returned in turn, so consecutive accesses may return different instances and therefore replicas with different replication lag. If only the primary host is available, `db.replica` returns it, logging a warning about an attempt to read from the `primary` replica. If no host is available, `db.replica` throws an error with the `ERR_DB_UNAVAILABLE` code +- `replica`: Getter that points at the knex instance targeting the fastest available replica host. The speed is determined from the latest health-check query response time. With the `round-robin` balancing strategy, healthy replicas (limited by `latencyToleranceMs`, if set) are returned in turn, so consecutive accesses may return different instances and therefore replicas with different replication lag. If only the primary host is available, `db.replica` returns it, logging a warning about an attempt to read from the `primary` replica. If no host is available, `db.replica` throws an error with the `ERR_DB_UNAVAILABLE` code Both `db.primary` and `db.replica` point to regular knex instances that can do everything described in the [knex documentation](https://knexjs.org/). diff --git a/lib/dispatcher.ts b/lib/dispatcher.ts index 07349c9..3d8ea07 100644 --- a/lib/dispatcher.ts +++ b/lib/dispatcher.ts @@ -68,20 +68,20 @@ function validateBalancingStrategy(strategy?: BalancingStrategy): BalancingStrat return {kind: 'fastest'}; } - const {latencyTolerance} = strategy; + const {latencyToleranceMs} = strategy; if ( - latencyTolerance !== undefined && - (!Number.isFinite(latencyTolerance) || latencyTolerance < 0) + latencyToleranceMs !== undefined && + (!Number.isFinite(latencyToleranceMs) || latencyToleranceMs < 0) ) { throw new Error( - `balancingStrategy.latencyTolerance must be a non-negative finite number, got ${String( - latencyTolerance, + `balancingStrategy.latencyToleranceMs must be a non-negative finite number, got ${String( + latencyToleranceMs, )}`, ); } - return {kind: 'round-robin', latencyTolerance}; + return {kind: 'round-robin', latencyToleranceMs}; } export class PDError extends Error { @@ -432,20 +432,20 @@ export class PGDispatcher { const strategy = this.balancingStrategy; if (strategy.kind === 'round-robin') { - return this.selectRoundRobin(candidates, strategy.latencyTolerance); + return this.selectRoundRobin(candidates, strategy.latencyToleranceMs); } return fastestConnection(candidates); } - // Rotates between all connections or, when `latencyTolerance` is set, only those whose - // latest health-check latency is within `latencyTolerance` ms of the fastest one. - private selectRoundRobin(candidates: PDConnection[], latencyTolerance?: number) { + // Rotates between all connections or, when `latencyToleranceMs` is set, only those whose + // latest health-check latency is within `latencyToleranceMs` of the fastest one. + private selectRoundRobin(candidates: PDConnection[], latencyToleranceMs?: number) { let eligible = candidates; - if (latencyTolerance !== undefined) { + if (latencyToleranceMs !== undefined) { const minLatency = fastestConnection(candidates).latency; - eligible = candidates.filter((c) => c.latency <= minLatency + latencyTolerance); + eligible = candidates.filter((c) => c.latency <= minLatency + latencyToleranceMs); } // the window may shrink between health checks, so wrap the stored position into it diff --git a/lib/types.ts b/lib/types.ts index 85c9111..7572b04 100644 --- a/lib/types.ts +++ b/lib/types.ts @@ -12,7 +12,7 @@ export interface FastestBalancingStrategy { } /** - * every healthy connection in turn; with `latencyTolerance`, only those whose latest + * every healthy connection in turn; with `latencyToleranceMs`, only those whose latest * health-check latency is within that many ms of the lowest one */ export interface RoundRobinBalancingStrategy { @@ -22,7 +22,7 @@ export interface RoundRobinBalancingStrategy { * is within this value of the lowest one are rotated (0 — only the fastest ones). * When omitted, all healthy connections are rotated */ - latencyTolerance?: number; + latencyToleranceMs?: number; } export type BalancingStrategy = FastestBalancingStrategy | RoundRobinBalancingStrategy; diff --git a/tests/dispatcher.test.js b/tests/dispatcher.test.js index f844a44..606c884 100644 --- a/tests/dispatcher.test.js +++ b/tests/dispatcher.test.js @@ -366,8 +366,8 @@ describe('PGDispatcher balancing strategies', () => { }); test.each([-1, NaN, Infinity, null, '10'])( - 'rejects an invalid latencyTolerance: %p', - (latencyTolerance) => { + 'rejects an invalid latencyToleranceMs: %p', + (latencyToleranceMs) => { // validation runs before any knex instance is created, so no knex mocks are queued expect( () => @@ -376,20 +376,20 @@ describe('PGDispatcher balancing strategies', () => { logger: {info: jest.fn(), error: jest.fn()}, options: { ...defaultDispatcherOptions, - balancingStrategy: {kind: 'round-robin', latencyTolerance}, + balancingStrategy: {kind: 'round-robin', latencyToleranceMs}, }, }), - ).toThrow('balancingStrategy.latencyTolerance must be a non-negative finite number'); + ).toThrow('balancingStrategy.latencyToleranceMs must be a non-negative finite number'); }, ); test('uses the validated strategy after the original options are changed', async () => { - const balancingStrategy = {kind: 'round-robin', latencyTolerance: 10}; + const balancingStrategy = {kind: 'round-robin', latencyToleranceMs: 10}; const {dispatcher, replicas} = createReplicaSet(2, {balancingStrategy}); await dispatcher.ready(); setLatencies(dispatcher, [1, 1, 2]); - balancingStrategy.latencyTolerance = -1; + balancingStrategy.latencyToleranceMs = -1; expect(pick(dispatcher, 'replica', 2)).toEqual(replicas); }); @@ -424,7 +424,7 @@ describe('PGDispatcher balancing strategies', () => { test('round-robin with a zero window rotates only equally fast replicas', async () => { const {dispatcher, replicas} = createReplicaSet(3, { - balancingStrategy: {kind: 'round-robin', latencyTolerance: 0}, + balancingStrategy: {kind: 'round-robin', latencyToleranceMs: 0}, }); await dispatcher.ready(); @@ -440,7 +440,7 @@ describe('PGDispatcher balancing strategies', () => { test('rotates replicas whose latency is within the tolerance window', async () => { const {dispatcher, replicas} = createReplicaSet(3, { - balancingStrategy: {kind: 'round-robin', latencyTolerance: 10}, + balancingStrategy: {kind: 'round-robin', latencyToleranceMs: 10}, }); await dispatcher.ready(); @@ -471,7 +471,7 @@ describe('PGDispatcher balancing strategies', () => { test('keeps rotating evenly after the window shrinks', async () => { const {dispatcher, replicas} = createReplicaSet(3, { - balancingStrategy: {kind: 'round-robin', latencyTolerance: 0}, + balancingStrategy: {kind: 'round-robin', latencyToleranceMs: 0}, }); await dispatcher.ready(); @@ -492,7 +492,7 @@ describe('PGDispatcher balancing strategies', () => { const proxies = [0, 1, 2].map(() => createKnex(successfulCheckup({value: 1}))); const {dispatcher} = createDispatcher(proxies, { topologyMode: 'proxy', - balancingStrategy: {kind: 'round-robin', latencyTolerance: 10}, + balancingStrategy: {kind: 'round-robin', latencyToleranceMs: 10}, }); await dispatcher.ready();