npaw-plugin-nwf
Version:
NPAW's Plugin
65 lines (64 loc) • 3.13 kB
TypeScript
/**
* @file Dynamic trial-call timeout. Mirrors the Android
* `TrialDeadlineEventListener` (plugin-android@video-balancer-24-2-on-main).
*
* When a candidate CDN is picked as a trial, a `TrialTag` is attached to the
* segment so the XHR layer can recompute a tighter call deadline at
* HEADERS_RECEIVED based on the announced Content-Length, the *current* good
* CDN's bandwidth, and that CDN's idle ratio (L0). The new deadline replaces
* the existing per-attempt total timer ONLY when it is stricter than the
* baseline already armed by the network interceptor — the trial never gets
* MORE time than the call would naturally have.
*/
/** Lower bound for the computed trial timeout, in milliseconds. */
export declare const MIN_TRIAL_TIMEOUT_MS = 500;
/**
* Default safety factor on the "time given to the trial" side of the formula
* (Android `TrialTag.safetyFactor = 0.75`). Values < 1 give the trial less
* time than the current CDN would itself take to deliver the same chunk.
*/
export declare const DEFAULT_TRIAL_SAFETY_FACTOR = 0.75;
/**
* Carrier attached to a VideoSegment that has been selected as a trial fetch
* (a deliberate probe of an idle CDN). Provides everything the dynamic-deadline
* recompute needs once response headers land.
*/
export interface TrialTag {
/** Existing call-timeout when the trial was scheduled (ms). The deadline is
* shortened ONLY when the recompute is stricter than this value. */
baselineCallTimeoutMs: number;
/** Current (good) CDN's bandwidth in bits/sec, or null when the current CDN
* has no usable history yet — the recompute is skipped in that case. */
currentCdnBandwidthBps: number | null;
/** Current CDN's name (for diagnostics only). */
currentCdnName: string | null;
/** Per-trial safety factor; defaults to DEFAULT_TRIAL_SAFETY_FACTOR. */
safetyFactor: number;
}
/**
* Trial call-timeout in milliseconds.
*
* tFallback = sizeBytes * 8 / bandwidthBps (seconds on the current CDN)
* tTrial = tFallback / (1 - l0) * l0 * sf (slack offered by idle ratio)
* result = max(min(tTrial, tFallback) * 1000, MIN_TRIAL_TIMEOUT_MS)
*
* Returns `-1` when the formula has no usable signal:
* - `sizeBytes <= 0` (no announced Content-Length, or zero-length response),
* - `bandwidthBps <= 0` (current CDN never produced a measurement), or
* - `l0 >= 1` (no concurrency samples yet — the EMA fold has nothing to compare).
*
* Android parity: TrialDeadlineEventListener.computeTrialTimeoutMs.
*/
export declare function computeTrialTimeoutMs(sizeBytes: number, bandwidthBps: number, l0: number, safetyFactor: number): number;
/**
* Single-trial-slot guard. Mirrors Android's `TrialDeadlineRegistry.activeTrialCall`
* — at most one trial in flight per balancer instance. Callers acquire the slot
* before sending the trial XHR and release it on call end / abort.
*/
export declare class TrialSlot {
private active;
tryAcquire(xhr: XMLHttpRequest): boolean;
release(xhr: XMLHttpRequest): void;
isHeldBy(xhr: XMLHttpRequest): boolean;
isActive(): boolean;
}