export { BdpEstimator }; export type { GrowDecision, AxisDecision }; /** Per-axis verdict on a settled probe. `grow` = sample saturated ≥ 2/3 of * current window (or saturation gate disabled) and not at cap. */ type AxisDecision = 'grow' | 'sample-too-small' | 'at-cap'; /** `acknowledged` is true when a probe was in flight to settle (false for * a stale ack arriving after a transport reset). Per-axis decisions are * independent — caller commits each axis's grow separately. */ type GrowDecision = { acknowledged: boolean; bytes: AxisDecision; msgs: AxisDecision; }; /** * gRPC-style adaptive flow-control window. Maintained per channel on the receive * side; the resulting `byteWindow` is advertised to the peer via the existing * `WINDOW` frame so the sender stops blocking once the wire's BDP is reached. * * 1. On the first byte received after a previous sample completes, issue a * `BDP_PING` and snapshot `bytesReceived`. Only one ping is in flight at a time * so the cadence self-paces to ~1 ping per RTT during active traffic and zero * while idle. `BDP_PING_MIN_INTERVAL_MS` further caps the rate on loopback / * sub-ms RTT where unthrottled gRPC pacing would churn the event loop. * 2. The sender echoes `BDP_PING_ACK` immediately (queue-jumping any data) — the * gap between snapshot and ack is the in-flight byte count, which IS the BDP * sample for that round-trip. * 3. If the sample saturates ≥ 2/3 of the currently-advertised window, the window * was the bottleneck → `onPingAck` returns `true`; caller may call `grow()` to * double it (clamped to `CREDIT_WINDOW_MAX_BYTES`). The caller applies any * additional gates (e.g. runtime saturation in `FlowControl`) before committing. * Otherwise leave it; producer or wire is the limit, not us. * 4. Once `window` reaches the cap, probing stops entirely — no further growth * is possible, so the round-trips would be pure overhead. * * Scope: pure bytes/RTT (BDP). Cross-cutting policies — CPU saturation, congestion, * fairness — live above this layer (see `FlowControl`), which can refuse to commit * a `grow()` even when this estimator says the link has byte-room. * * Grow-only by design (same as gRPC). Oversized `W` costs nothing as long as the * sender doesn't fill it — receiver memory = unconsumed bytes, not `W`. Shrinking * adds oscillation risk and decay-tuning complexity for no real win; the only * downside of an oversized `W` is the worst-case admissible buffering, capped at MAX. * * Why a dedicated `BDP_PING` frame rather than piggybacking on the user-level ping * (`CHANNEL_PING_INTERVAL_MS`): the user-ping is configurable for connection health * (defaults to 5 s, often set to 30 s+); BDP needs RTT-scale cadence to adapt within * a handful of round-trips. */ declare class BdpEstimator { private _byteWindow; private _bytesAtPingSent; private _bytesReceived; private _msgWindow; private _msgsAtPingSent; private _msgsReceived; private _pingInFlight; private _lastPingAt; /** Adaptive probe interval: snaps to `MIN` on grow, doubles up to `MAX` on * non-grow. Slows but never freezes — a real rate change rediscovers. */ private _probeIntervalMs; /** Currently advertised byte-credit window. */ get byteWindow(): number; /** Currently advertised message-count window. */ get msgWindow(): number; /** Record one received frame (pre-app-processing). Returns true iff a `BDP_PING` * should be emitted: caller fires `sendBdpPing()` synchronously. A single probe * collects samples for both axes — `onPingAck` then derives independent * byte-sample / msg-sample saturation decisions. */ onReceive(bytes: number): boolean; /** Settle an outstanding `BDP_PING` against its `BDP_PING_ACK`. Returns per-axis * grow suggestions: each is `true` iff that axis's sample saturated ≥ 2/3 of * its current window. Caller decides whether to actually `growBytes()` / * `growMsgs()` (e.g. after applying the CPU-lag gate). */ onPingAck(): GrowDecision; /** Commit a byte-window doubling. Idempotent at the cap. */ growBytes(): void; /** Grow-only bump of the byte window (clamped to MAX). */ bumpInitialByteWindow(bytes: number): void; /** Commit a message-window doubling. Idempotent at the cap. */ growMsgs(): void; /** Drop the in-flight ping (its ack rode the prior wire). Preserves window AND * cadence — both are link properties; a real rate change rediscovers. */ reset(): void; }