`backpressure`

(no submodules)

Purpose

Bounds memory growth on a busy RPC channel by exposing two primitives: the logical CallBudget for outstanding in-flight calls, and the physical BoundedQueue for frames-in-transit and stream-chunk buffers. Both reject overflow rather than allocating without bound — the failure mode is a synchronous WORKER_RPC.BACKPRESSURE throw at the call site, not an OOM kill on the worker thread.

The two layers are deliberately distinct: a call budget counts logical requests (decremented on response receipt regardless of frame count), while the bounded queue counts wire frames (decremented on dequeue). Decoupling them lets streaming workloads — where one call yields many frames — back-pressure on chunk delivery without blocking new calls.

Features

CallBudget(max) with acquire() / release() semantics and a synchronous-throw exhaustion path.
BoundedQueue(policy) with three modes:
- "fail" — throw WORKER_RPC.BACKPRESSURE on overflow.
- "drop-oldest" — evict head, push new (head-drop).
- "drop-newest" — refuse new, leaving the queue untouched.
DEFAULT_BACKPRESSURE — high-water-mark 64, mode "fail".
Validation: both classes reject non-positive caps with WORKER_RPC.BACKPRESSURE.

Usage: Basic

import { CallBudget, DEFAULT_BACKPRESSURE, BoundedQueue } from "@suaveplan/api-worker-rpc/backpressure";

const budget = new CallBudget(1024);
budget.acquire();   // throws WORKER_RPC.BACKPRESSURE when full
budget.release();

Usage: Advanced

import { BoundedQueue, type BackpressurePolicy } from "@suaveplan/api-worker-rpc/backpressure";

const lossy: BackpressurePolicy = { highWaterMark: 8, mode: "drop-oldest" };
const queue = new BoundedQueue<Frame>(lossy);
queue.enqueue(frame);  // never throws; head evicted on overflow

const strict: BackpressurePolicy = { highWaterMark: 1024, mode: "fail" };
const strictQueue = new BoundedQueue<Frame>(strict);
try {
    strictQueue.enqueue(frame);
} catch (e) {
    if (e instanceof WorkerRpcError && e.code === "WORKER_RPC.BACKPRESSURE") {
        // back off
    }
}

API Reference

interface BackpressurePolicy { highWaterMark: number; mode: BackpressureMode }.
type BackpressureMode = "fail" | "drop-oldest" | "drop-newest".
DEFAULT_BACKPRESSURE: BackpressurePolicy.
class CallBudget(max) — acquire(), release(), inFlight, capacity.
class BoundedQueue<T>(policy?) — enqueue(v): boolean, dequeue(): T|undefined, peek(), drain(), size.

Implementation Notes

release() is tolerant of extra calls (never goes negative) so late-arriving responses or duplicate acks cannot underflow the budget.
drop-oldest mutates in-place rather than allocating a new array so the buffer never grows beyond highWaterMark.
drop-newest returns false from enqueue so callers can distinguish accepted from refused; drop-oldest returns true unconditionally (the eviction is implicit).

3.0 KiB Raw Blame History

backpressure