@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/desktopControl/rateController.js

@@ -0,0 +1,226 @@
+import { DesktopNetworkEvidence } from './networkEvidence.js';
+export class DesktopRateController {
+    min;
+    max;
+    maxFps;
+    networkEvidence = new DesktopNetworkEvidence();
+    target;
+    fps;
+    lastNow = -Infinity;
+    lastWindow = -Infinity;
+    lastRateChange = -Infinity;
+    lastFpsChange = -Infinity;
+    lastReopen = -Infinity;
+    cooldown = -Infinity;
+    reopens = [];
+    networkPressure = 0;
+    processingPressure = 0;
+    networkHealthy = 0;
+    headroom = 0;
+    recoveryWindows = 0;
+    recoveryFps;
+    fpsTrialUntil = -Infinity;
+    fpsRecoveryAfter = -Infinity;
+    paused = false;
+    demandBps = 0;
+    demandKnown = false;
+    windowHadActivity = false;
+    windowHadProgress = false;
+    windowHadProbeEvidence = false;
+    processingSamples = [];
+    encodeSamples = [];
+    lastEncodeObservation = -Infinity;
+    lastDecodeObservation = -Infinity;
+    lastNetworkPolicySample;
+    lastPath;
+    snapshot = { networkState: 'unknown',
+        networkQueueMs: 0, observedPayloadBps: 0, processingP95Ms: 0, encodeP95Ms: 0, receiverBudgetMs: 0, reasons: [] };
+    constructor(options = {}) {
+        const min = options.minBps ?? 500_000, max = options.maxBps ?? 20_000_000;
+        if (![min, max, options.targetBps ?? 4_000_000].every(Number.isFinite) || min < 500_000 || max > 20_000_000)
+            throw new Error('invalid rate bounds');
+        this.min = Math.ceil(min / 4000) * 4000;
+        this.max = Math.floor(max / 4000) * 4000;
+        if (this.min > this.max)
+            throw new Error('unrepresentable rate bounds');
+        this.target = this.quantize(options.targetBps ?? 4_000_000);
+        this.maxFps = options.maxFps ?? options.fpsCeiling ?? 60;
+        this.fps = options.fpsCeiling ?? this.maxFps;
+        this.recoveryFps = this.fps;
+        if (![15, 30, 60].includes(this.fps) || ![15, 30, 60].includes(this.maxFps) || this.fps > this.maxFps)
+            throw new Error('invalid fps bounds');
+    }
+    get diagnostics() { return { ...this.snapshot, reasons: [...this.snapshot.reasons] }; }
+    quantize(rate) {
+        return Math.max(this.min, Math.min(this.max, Math.floor(rate / 4000) * 4000));
+    }
+    sample(s, runtimeRateReconfigure = false) {
+        const optional = [s.rttBaselineMs, s.deliveryDelayMs, s.deliveryObservedAtMs, s.encodeObservedAtMs, s.decodeObservedAtMs];
+        if (![s.nowMs, s.activeBytes, s.excessRttMs, s.queueAgeMs, s.queuedSendMs, s.encodeMs, s.decodeMs]
+            .every(value => Number.isFinite(value) && value >= 0) ||
+            optional.some(value => value !== undefined && (!Number.isFinite(value) || value < 0)) ||
+            s.nowMs < this.lastNow)
+            throw new Error('invalid rate sample');
+        const elapsed = Number.isFinite(this.lastNow) ? s.nowMs - this.lastNow : 1000;
+        if (elapsed > 0) {
+            const observed = Math.min(this.max * 4, s.activeBytes * 8000 / elapsed);
+            const weight = -Math.expm1(-elapsed / 1000);
+            this.demandBps = this.demandKnown ? this.demandBps + (observed - this.demandBps) * weight : observed;
+            this.demandKnown = true;
+        }
+        this.lastNow = s.nowMs;
+        const window = Math.floor(s.nowMs / 1000);
+        const contiguous = window === this.lastWindow + 1;
+        const activeWindow = s.activeBytes > 0 || (contiguous && this.windowHadActivity);
+        const freshnessMs = Math.max(1500, (s.rttBaselineMs ?? 0) * 3);
+        const progress = s.deliveryObservedAtMs !== undefined
+            ? s.deliveryObservedAtMs <= s.nowMs && s.nowMs - s.deliveryObservedAtMs <= freshnessMs
+            : s.deliveryDelayMs !== undefined && s.deliveryDelayMs <= 40;
+        const progressWindow = progress || contiguous && this.windowHadProgress;
+        this.windowHadActivity = window === this.lastWindow ? this.windowHadActivity || s.activeBytes > 0 : s.activeBytes > 0;
+        this.windowHadProgress = window === this.lastWindow ? this.windowHadProgress || progress : progress;
+        if (s.queuedSendMs > 100)
+            this.paused = true;
+        else if (s.queuedSendMs === 0)
+            this.paused = false;
+        const evidence = this.networkEvidence.sample(s.nowMs, s.network, this.demandBps);
+        const probeEvidence = progress && (evidence.state === 'usable' || evidence.state === 'unknown' &&
+            s.deliveryDelayMs !== undefined && s.deliveryDelayMs <= 40);
+        const probeWindow = probeEvidence || contiguous && this.windowHadProbeEvidence;
+        this.windowHadProbeEvidence = window === this.lastWindow ? this.windowHadProbeEvidence || probeEvidence : probeEvidence;
+        const path = s.network ? `${s.network.id}:${s.network.pathGeneration}` : undefined;
+        if (path !== this.lastPath) {
+            this.networkPressure = this.networkHealthy = 0;
+            this.lastNetworkPolicySample = undefined;
+            this.lastPath = path;
+        }
+        const sampleKey = s.network ? `${path}:${s.network.sequence}` : undefined;
+        const freshNetworkWindow = sampleKey !== undefined && sampleKey !== this.lastNetworkPolicySample;
+        if (window !== this.lastWindow && !contiguous) {
+            this.processingSamples = [];
+            this.encodeSamples = [];
+        }
+        const encodeAt = s.encodeObservedAtMs ?? (s.encodeMs > 0 ? s.nowMs : undefined);
+        const decodeAt = s.decodeObservedAtMs ?? (s.decodeMs > 0 ? s.nowMs : undefined);
+        const costs = [];
+        if (encodeAt !== undefined && encodeAt > this.lastEncodeObservation && encodeAt <= s.nowMs && s.nowMs - encodeAt <= freshnessMs) {
+            this.lastEncodeObservation = encodeAt;
+            costs.push(s.encodeMs);
+            this.encodeSamples.push(s.encodeMs);
+        }
+        if (decodeAt !== undefined && decodeAt > this.lastDecodeObservation && decodeAt <= s.nowMs && s.nowMs - decodeAt <= freshnessMs) {
+            this.lastDecodeObservation = decodeAt;
+            costs.push(s.decodeMs);
+        }
+        if (costs.length)
+            this.processingSamples.push(Math.max(...costs));
+        if (this.processingSamples.length > 128)
+            this.processingSamples.shift();
+        if (this.encodeSamples.length > 128)
+            this.encodeSamples.shift();
+        this.snapshot = { ...this.snapshot, networkState: evidence.state, networkQueueMs: evidence.queueMs,
+            observedPayloadBps: Math.round(this.demandBps), reasons: this.paused ? ['sender-backpressure'] : [] };
+        const decision = (reopenEpoch = false) => ({ targetBps: this.target,
+            fpsCeiling: this.fps, pauseCapture: this.paused, reopenEpoch });
+        if (window === this.lastWindow)
+            return decision();
+        this.lastWindow = window;
+        if (!contiguous)
+            this.networkPressure = this.processingPressure = this.networkHealthy = this.headroom = this.recoveryWindows = 0;
+        const costsInWindow = this.processingSamples.sort((left, right) => left - right);
+        this.processingSamples = [];
+        const cost = costsInWindow[Math.max(0, Math.ceil(costsInWindow.length * 0.95) - 1)] ?? 0;
+        this.snapshot.processingP95Ms = cost;
+        const encodeCosts = this.encodeSamples.sort((left, right) => left - right);
+        this.encodeSamples = [];
+        const encodeCost = encodeCosts[Math.max(0, Math.ceil(encodeCosts.length * 0.95) - 1)] ?? 0;
+        const receiverBudget = Math.max(80, 3000 / this.fps);
+        this.snapshot.encodeP95Ms = encodeCost;
+        this.snapshot.receiverBudgetMs = receiverBudget;
+        if (!activeWindow) {
+            this.networkPressure = this.processingPressure = this.networkHealthy = this.headroom = this.recoveryWindows = 0;
+            this.snapshot.reasons.push('content-idle');
+            return decision();
+        }
+        const net = evidence.state === 'congested' && freshNetworkWindow;
+        this.lastNetworkPolicySample = sampleKey;
+        const receiverPressure = costsInWindow.length > 0 && cost > 0.8 * 1000 / this.fps && s.queueAgeMs > receiverBudget;
+        const sourcePressure = encodeCosts.length > 0 && encodeCost > 0.8 * 1000 / this.fps;
+        const processing = sourcePressure || receiverPressure;
+        this.networkPressure = net ? this.networkPressure + 1 : 0;
+        this.processingPressure = processing ? this.processingPressure + 1 : 0;
+        this.networkHealthy = !net && probeWindow && progressWindow && !this.paused ? this.networkHealthy + 1 : 0;
+        const nextFps = Math.min(this.maxFps, this.fps === 15 ? 30 : 60);
+        this.headroom = encodeCosts.length > 0 && !processing && s.queueAgeMs <= 40 && !this.paused &&
+            encodeCost < 0.6 * 1000 / nextFps ? this.headroom + 1 : 0;
+        this.recoveryWindows = nextFps > this.fps && nextFps <= this.recoveryFps && encodeCosts.length > 0 &&
+            progressWindow && !net && s.queueAgeMs <= 40 && !this.paused && encodeCost < 0.8 * 1000 / nextFps
+            ? this.recoveryWindows + 1 : 0;
+        if (net)
+            this.snapshot.reasons.push('sender-path-congestion');
+        if (processing)
+            this.snapshot.reasons.push('processing-pressure');
+        if (sourcePressure)
+            this.snapshot.reasons.push('source-encode-pressure');
+        if (receiverPressure)
+            this.snapshot.reasons.push('receiver-backlog');
+        if (evidence.state === 'unknown')
+            this.snapshot.reasons.push('network-unknown');
+        if (this.fps < this.recoveryFps && s.nowMs < this.fpsRecoveryAfter)
+            this.snapshot.reasons.push('fps-recovery-backoff');
+        if (s.nowMs < this.cooldown)
+            return decision();
+        let target = this.target, fps = this.fps;
+        if (this.networkPressure >= 2 && s.nowMs - this.lastRateChange >= 2000) {
+            target = this.quantize(Math.min(target * 0.85, evidence.bandwidthBps ? evidence.bandwidthBps * 0.9 : target));
+        }
+        else if (this.networkHealthy >= 3 && s.nowMs - this.lastRateChange >= (runtimeRateReconfigure ? 2000 : 10000) &&
+            this.demandBps >= target * 0.25) {
+            target = this.quantize(target * (runtimeRateReconfigure ? evidence.state === 'usable' ? 1.5 : 1.2 : 1.1));
+            if (target > this.target)
+                this.snapshot.reasons.push('bandwidth-probe');
+        }
+        if (this.processingPressure >= 2 && s.nowMs - this.lastFpsChange >= 2000)
+            fps = fps === 60 ? 30 : 15;
+        else if ((this.headroom >= 3 || this.recoveryWindows >= 5) && s.nowMs >= this.fpsRecoveryAfter &&
+            s.nowMs - this.lastFpsChange >= (runtimeRateReconfigure ? 2000 : 10000)) {
+            fps = nextFps;
+            if (fps > this.fps && this.headroom < 3)
+                this.snapshot.reasons.push('fps-recovery-probe');
+        }
+        if (target === this.max)
+            this.snapshot.reasons.push('policy-limit');
+        if (target === this.target && fps === this.fps)
+            return decision();
+        if (!runtimeRateReconfigure && s.nowMs - this.lastReopen < 2000)
+            return decision();
+        this.reopens = this.reopens.filter(at => s.nowMs - at < 10000);
+        if (!runtimeRateReconfigure && this.reopens.length === 2) {
+            fps = 15;
+            this.cooldown = s.nowMs + 10000;
+        }
+        if (target !== this.target) {
+            this.lastRateChange = s.nowMs;
+            this.networkPressure = this.networkHealthy = 0;
+        }
+        if (fps !== this.fps) {
+            if (fps < this.fps) {
+                this.recoveryFps = Math.max(this.recoveryFps, this.fps);
+                if (s.nowMs <= this.fpsTrialUntil)
+                    this.fpsRecoveryAfter = s.nowMs + 30000;
+                this.fpsTrialUntil = -Infinity;
+            }
+            else
+                this.fpsTrialUntil = s.nowMs + 10000;
+            this.lastFpsChange = s.nowMs;
+            this.processingPressure = this.headroom = this.recoveryWindows = 0;
+        }
+        this.target = target;
+        this.fps = fps;
+        if (!runtimeRateReconfigure) {
+            this.reopens.push(s.nowMs);
+            this.lastReopen = s.nowMs;
+        }
+        return decision(!runtimeRateReconfigure);
+    }
+}