@molecule/api-upstream-balancer-default

Default upstream-balancer provider for molecule.dev.

Health-aware round-robin over a host's upstream set, with a failure cooldown, a retry that lands on a different member, and drain-awareness. In-memory state only; wire it once per process (or create several with createProvider() for tests).

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider, pickUpstream } from '@molecule/api-upstream-balancer'
import { provider } from '@molecule/api-upstream-balancer-default'

setProvider(provider)
const target = pickUpstream('app.example.com', members)

Type

provider

Installation

npm install @molecule/api-upstream-balancer-default @molecule/api-upstream-balancer

API

Functions

`upstreamKey(upstream)`

host:port — the identity a failure mark, a draining mark and the cursor use.

function upstreamKey(upstream: Pick<UpstreamMember, 'host' | 'port'>): string

upstream — Any upstream member.

Returns: The key.

`createProvider(options)`

Create an upstream balancer with its own cursors and marks.

function createProvider(
  options?: UpstreamBalancerPolicy & { now?: () => number },
): UpstreamBalancerProvider

options — The cooldown and an injectable clock (tests).

Returns: The balancer.

Constants

`DEFAULT_UPSTREAM_FAILURE_COOLDOWN_MS`

How long a member stays skipped after a failed attempt.

const DEFAULT_UPSTREAM_FAILURE_COOLDOWN_MS: 10000

`provider`

The shared provider instance.

const provider: UpstreamBalancerProvider

Core Interface

Implements @molecule/api-upstream-balancer interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-upstream-balancer'
import { provider } from '@molecule/api-upstream-balancer-default'

export function setupUpstreamBalancerDefault(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

@molecule/api-upstream-balancer ^1.0.0

Runtime Dependencies

@molecule/api-upstream-balancer
One member is returned unchanged, so a single-instance deployment keeps exactly its previous code path.
Suspect and draining members are skipped while any other member is eligible; when none is, one member is still returned.
reset() is test-only and drops every cursor and mark.

`@molecule/api-upstream-balancer-default`

How it works

Reference