@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/desktopControl/media.js

@@ -0,0 +1,331 @@
+import { z } from 'zod';
+import { DesktopProtocolError, parseDesktopJson } from './protocol.js';
+export function mediaRequire(value) {
+    if (!value)
+        throw new DesktopProtocolError('Invalid desktop media');
+}
+const integer = (n, min = 0, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(n) && n >= min && n <= max;
+const axis = z.number().int().min(2).max(4096).refine(n => n % 2 === 0);
+const label = z.string().min(1).refine(s => Buffer.byteLength(s) <= 128 && !/[\x00-\x1f\x7f]/.test(s));
+const codecSchema = z.strictObject({ codec: z.literal('h264'), representation: z.literal(1),
+    width: axis, height: axis, fpsCeiling: z.union([z.literal(15), z.literal(30), z.literal(60)]),
+    profile: label, level: label, colorMatrix: z.literal('bt709'), colorRange: z.literal('limited'), parameterSets: z.array(z.string()) });
+function checked(read) {
+    try {
+        return read();
+    }
+    catch {
+        throw new DesktopProtocolError('Invalid desktop media');
+    }
+}
+export function decodeConfig(bytes) {
+    return checked(() => {
+        const c = codecSchema.parse(parseDesktopJson(bytes, 16384));
+        mediaRequire(c.parameterSets.length === 2);
+        c.parameterSets.forEach((encoded, i) => {
+            mediaRequire(encoded.length <= 2732);
+            const nal = Buffer.from(encoded, 'base64');
+            mediaRequire(nal.length >= 1 && nal.length <= 2048 && nal.toString('base64') === encoded &&
+                (nal[0] & 128) === 0 && (nal[0] & 31) === (i % 2 === 0 ? 7 : 8));
+        });
+        return c;
+    });
+}
+function validateUnit(p, bytes) {
+    if (p.type === 1)
+        mediaRequire(decodeConfig(bytes).representation === p.representation);
+    else if (p.type === 3) {
+        const w = bytes.readUInt16BE(), h = bytes.readUInt16BE(2);
+        mediaRequire(w >= 1 && w <= 256 && h >= 1 && h <= 256 && bytes.readUInt16BE(4) < w &&
+            bytes.readUInt16BE(6) < h && w * h * 4 + 8 === p.unitLength);
+    }
+    else if (p.type === 5) {
+        mediaRequire(bytes.length >= 95 && bytes.subarray(0, 16).equals(Buffer.from('28b4619e8e524cf29ae8415852473034', 'hex')) && bytes[16] === 4 && bytes[37] === 1 && bytes.readUInt32BE(38) === 0 && bytes.readUInt16BE(42) > 0 && bytes.readUInt16BE(42) <= 1024);
+        const focusRevision = bytes.readBigUInt64BE(44), [x, y, w, h, sw, sh] = [52, 56, 60, 64, 68, 72].map(o => bytes.readUInt32BE(o));
+        mediaRequire(focusRevision > 0n && focusRevision <= BigInt(Number.MAX_SAFE_INTEGER) && w > 0 && h > 0 && sw >= 2 && sh >= 2 && sw <= 4096 && sh <= 4096 && x + w <= sw && y + h <= sh);
+        mediaRequire(axis.safeParse(bytes.readUInt16BE(17)).success && axis.safeParse(bytes.readUInt16BE(19)).success && bytes.readBigUInt64BE(21) > 0n && bytes.readBigUInt64BE(21) <= BigInt(Number.MAX_SAFE_INTEGER) && bytes.readBigUInt64BE(29) > 0n && bytes.readBigUInt64BE(29) <= BigInt(Number.MAX_SAFE_INTEGER));
+    }
+    else if (p.type === 4)
+        cursor(bytes);
+}
+function cursor(bytes) {
+    return checked(() => z.strictObject({ x: z.number().int().min(0).max(4095),
+        y: z.number().int().min(0).max(4095), visible: z.boolean() }).parse(parseDesktopJson(bytes, 1024)));
+}
+/** Validates the header and current identity before retaining/reassembling payload. */
+export function decodeMedia(bytes, fence = () => { }) {
+    return checked(() => {
+        mediaRequire(bytes.length >= 65 && bytes.length <= 65600 && bytes.subarray(0, 5).equals(Buffer.from('AXDS\x01')) &&
+            bytes.readUInt16BE(8) === 64 && bytes.readUInt16BE(10) === 0 && bytes.readUIntBE(61, 3) === 0);
+        const u64 = (offset) => { const n = bytes.readBigUInt64BE(offset); mediaRequire(n <= BigInt(Number.MAX_SAFE_INTEGER)); return Number(n); };
+        const length = bytes.readUInt32BE(48);
+        const p = { type: bytes[5], flags: bytes.readUInt16BE(6), epoch: bytes.readUInt32BE(12),
+            displayRevision: bytes.readUInt32BE(16), sequence: bytes.readUInt32BE(20), frameId: u64(24), timestampUs: u64(32),
+            lastInputSequence: u64(40), unitLength: bytes.readUInt32BE(52), fragmentIndex: bytes.readUInt16BE(56),
+            fragmentCount: bytes.readUInt16BE(58), representation: bytes[60], payload: Buffer.alloc(0) };
+        mediaRequire(p.type >= 1 && p.type <= 5 && p.representation === 1 && p.flags <= 1 &&
+            (p.type === 2 || p.flags === 0) && p.epoch > 0 && p.displayRevision > 0 && p.sequence > 0 &&
+            ((p.type === 2 || p.type === 5) ? p.frameId > 0 : p.frameId === 0 && p.timestampUs === 0));
+        mediaRequire(length > 0 && length <= 65536 && bytes.length === 64 + length && p.unitLength > 0 && p.unitLength <= 8388608);
+        const count = Math.ceil(p.unitLength / 65536);
+        mediaRequire(p.fragmentCount === count && p.fragmentIndex < count &&
+            length === (p.fragmentIndex === count - 1 ? p.unitLength - p.fragmentIndex * 65536 : 65536));
+        if (p.type === 1)
+            mediaRequire(count === 1 && p.unitLength <= 16384);
+        if (p.type === 3)
+            mediaRequire(p.unitLength >= 12 && p.unitLength <= 262152);
+        if (p.type === 5)
+            mediaRequire(count === 1 && p.unitLength >= 95 && p.unitLength <= 24576);
+        if (p.type === 4)
+            mediaRequire(count === 1 && p.unitLength <= 1024);
+        fence(p);
+        p.payload = bytes.subarray(64);
+        if (count === 1)
+            validateUnit(p, p.payload);
+        return p;
+    });
+}
+export class DesktopMediaStream {
+    sourceDimensions;
+    constructor(sourceDimensions = () => undefined) {
+        this.sourceDimensions = sourceDimensions;
+    }
+    configuration = null;
+    epoch = 0;
+    revision = 0;
+    picture = { sequence: 0, lastFrame: 0, pending: undefined, storage: undefined, next: 0 };
+    cursorLane = { sequence: 0, lastFrame: 0, pending: undefined, storage: undefined, next: 0 };
+    exactLane = { sequence: 0, lastFrame: 0, pending: undefined, storage: undefined, next: 0 };
+    lane(type) { return type === 3 || type === 4 ? this.cursorLane : type === 5 ? this.exactLane : this.picture; }
+    exactSequence = 0;
+    recentFrames = [];
+    needsIdr = true;
+    failed = false;
+    accept(bytes) {
+        mediaRequire(!this.failed);
+        try {
+            const p = decodeMedia(bytes, packet => this.validate(packet));
+            const lane = this.lane(p.type);
+            lane.sequence = p.sequence;
+            if (p.type === 1) {
+                this.configuration = decodeConfig(p.payload);
+                this.epoch = p.epoch;
+                this.revision = p.displayRevision;
+                this.needsIdr = true;
+                this.exactSequence = 0;
+                this.exactLane.sequence = 0;
+                this.exactLane.pending = undefined;
+                this.exactLane.storage = undefined;
+                this.exactLane.next = 0;
+                this.cursorLane.sequence = 0;
+                this.cursorLane.pending = undefined;
+                this.cursorLane.storage = undefined;
+                this.cursorLane.next = 0;
+                return null;
+            }
+            if (p.fragmentCount === 1)
+                return this.complete(p, p.payload);
+            if (!lane.pending) {
+                lane.pending = { ...p, payload: Buffer.alloc(0) };
+                lane.storage = Buffer.alloc(p.unitLength);
+                lane.next = 0;
+            }
+            p.payload.copy(lane.storage, lane.next++ * 65536);
+            if (lane.next !== p.fragmentCount)
+                return null;
+            const first = lane.pending, unit = lane.storage;
+            lane.pending = undefined;
+            lane.storage = undefined;
+            validateUnit(first, unit);
+            return this.complete(first, unit);
+        }
+        catch {
+            this.failed = true;
+            this.picture.pending = this.cursorLane.pending = this.exactLane.pending = undefined;
+            this.picture.storage = this.cursorLane.storage = this.exactLane.storage = undefined;
+            throw new DesktopProtocolError('Invalid desktop stream');
+        }
+    }
+    applyMotionCut(pictureThrough, frameThrough) {
+        mediaRequire(!this.failed && this.configuration && integer(pictureThrough, this.picture.sequence, 0xffffffff) && integer(frameThrough, this.picture.lastFrame));
+        this.picture.sequence = pictureThrough;
+        this.picture.lastFrame = frameThrough;
+        this.picture.pending = undefined;
+        this.picture.storage = undefined;
+        this.picture.next = 0;
+        this.needsIdr = true;
+    }
+    validate(p) {
+        const lane = this.lane(p.type);
+        if (p.type === 1) {
+            mediaRequire(!this.picture.pending && p.epoch > this.epoch && p.sequence === 1);
+            return;
+        }
+        mediaRequire(this.configuration && p.epoch === this.epoch && p.displayRevision === this.revision &&
+            p.representation === this.configuration.representation && p.sequence === lane.sequence + 1);
+        if (!lane.pending) {
+            mediaRequire(p.fragmentIndex === 0);
+            if (p.type === 2 || p.type === 5)
+                mediaRequire(p.frameId > lane.lastFrame && !this.recentFrames.includes(p.frameId) && p.frameId !== this.picture.pending?.frameId && (!this.needsIdr || p.type === 2 && p.flags === 1));
+        }
+        else {
+            const first = lane.pending;
+            mediaRequire(['type', 'flags', 'frameId', 'timestampUs', 'lastInputSequence', 'unitLength', 'fragmentCount']
+                .every(k => p[k] === first[k]) && p.fragmentIndex === lane.next);
+        }
+    }
+    complete(p, bytes) {
+        if (p.type === 4) {
+            const c = cursor(bytes), source = this.sourceDimensions() ?? this.configuration;
+            mediaRequire(c.x < source.width && c.y < source.height);
+        }
+        if (p.type !== 2 && p.type !== 5)
+            return null;
+        const exactSequence = p.type === 5 ? Number(bytes.readBigUInt64BE(29)) : 0;
+        if (p.type === 5) {
+            mediaRequire(exactSequence === this.exactSequence + 1 && bytes.readUInt16BE(17) === this.configuration.width && bytes.readUInt16BE(19) === this.configuration.height);
+            this.exactSequence = exactSequence;
+        }
+        else
+            this.needsIdr = false;
+        this.lane(p.type).lastFrame = p.frameId;
+        this.recentFrames.push(p.frameId);
+        if (this.recentFrames.length > 128)
+            this.recentFrames.shift();
+        return { ...p, payload: bytes, mainAU: bytes, exactSequence };
+    }
+}
+const lanes = ['motion', 'cursor', 'exact'];
+const consumedKey = { motion: 'motionConsumedBytes', cursor: 'cursorConsumedBytes', exact: 'exactConsumedBytes' };
+const freshTotals = () => ({ motion: 0, cursor: 0, exact: 0 });
+export function desktopMediaLane(type) {
+    mediaRequire(integer(type, 1, 5));
+    return type <= 2 ? 'motion' : type <= 4 ? 'cursor' : 'exact';
+}
+/** One epoch's bounded reservations and actual transport admissions. Pipe writes never commit. */
+export class DesktopMediaFlowWindow {
+    window;
+    records = new Map();
+    committed = freshTotals();
+    reserved = freshTotals();
+    observed = freshTotals();
+    consumed = freshTotals();
+    lastId = 0;
+    constructor(window = 0) {
+        this.window = window;
+        mediaRequire(window === 0 || integer(window, 196608, 524288));
+    }
+    get inFlightBytes() { return lanes.reduce((n, l) => n + this.debt(l), 0); }
+    get recordCount() { return this.records.size; }
+    get hasCredit() { return this.window > 0; }
+    get appliedCredit() { return { motionConsumedBytes: this.consumed.motion, cursorConsumedBytes: this.consumed.cursor, exactConsumedBytes: this.consumed.exact, windowBytes: this.window }; }
+    debt(lane) { return this.committed[lane] + this.reserved[lane] - this.consumed[lane]; }
+    laneRecords(lane) { return [...this.records.values()].filter(r => r.lane === lane).length; }
+    admit(lane, bytes) {
+        mediaRequire(lanes.includes(lane) && integer(bytes, 1, lane === 'exact' ? 24576 : 65536));
+        const others = lanes.filter(l => l !== lane && l !== 'motion');
+        const protectedBytes = others.reduce((n, l) => n + Math.max(0, (l === 'cursor' ? 65536 : 24576) - this.debt(l)), 0);
+        const protectedRecords = others.reduce((n, l) => n + (this.laneRecords(l) === 0 ? 1 : 0), 0);
+        return this.records.size + 1 <= 128 - protectedRecords && this.inFlightBytes + bytes <= this.window - protectedBytes;
+    }
+    /** IDs are fresh monotonically increasing local admission attempts, including failed attempts. */
+    reserve(id, lane, bytes) {
+        mediaRequire(integer(id, this.lastId + 1));
+        this.lastId = id;
+        if (!this.admit(lane, bytes))
+            return false;
+        mediaRequire(this.committed[lane] <= Number.MAX_SAFE_INTEGER - this.reserved[lane] - bytes);
+        this.reserved[lane] += bytes;
+        this.records.set(id, { lane, bytes, remaining: bytes, committed: false });
+        return true;
+    }
+    commit(id) {
+        const r = this.records.get(id);
+        mediaRequire(r && !r.committed);
+        this.reserved[r.lane] -= r.bytes;
+        this.committed[r.lane] += r.bytes;
+        r.committed = true;
+        this.applyPending();
+    }
+    cancel(id) {
+        const r = this.records.get(id);
+        mediaRequire(r && !r.committed);
+        mediaRequire(this.observed[r.lane] <= this.committed[r.lane] + this.reserved[r.lane] - r.bytes);
+        this.reserved[r.lane] -= r.bytes;
+        this.records.delete(id);
+    }
+    credit(value) {
+        mediaRequire(integer(value.windowBytes, 196608, 524288) && Number.isSafeInteger(value.motionConsumedBytes + value.cursorConsumedBytes + value.exactConsumedBytes));
+        for (const l of lanes)
+            mediaRequire(integer(value[consumedKey[l]], this.observed[l], this.committed[l] + this.reserved[l]));
+        for (const l of lanes)
+            this.observed[l] = value[consumedKey[l]];
+        this.window = value.windowBytes;
+        this.applyPending();
+    }
+    applyPending() {
+        for (const lane of lanes) {
+            if (this.observed[lane] > this.committed[lane])
+                continue;
+            let delta = this.observed[lane] - this.consumed[lane];
+            this.consumed[lane] = this.observed[lane];
+            for (const [id, r] of this.records)
+                if (delta && r.lane === lane && r.committed) {
+                    const used = Math.min(delta, r.remaining);
+                    r.remaining -= used;
+                    delta -= used;
+                    if (!r.remaining)
+                        this.records.delete(id);
+                }
+            mediaRequire(delta === 0);
+        }
+    }
+}
+/** Sender-clock complete-frame send -> feedback. Feedback scheduling is not network delay. */
+export class DesktopDeliveryDelay {
+    frames = new Map();
+    samples = [];
+    observation = 0;
+    sampled = 0;
+    sent(frame, at) {
+        this.frames.set(frame, at);
+        if (this.frames.size > 512)
+            this.frames.delete(this.frames.keys().next().value);
+    }
+    received(frame, at) {
+        const sent = this.frames.get(frame);
+        if (sent === undefined)
+            return;
+        this.samples.push({ at, delay: Math.max(0, at - sent), observation: ++this.observation });
+        if (this.samples.length > 500)
+            this.samples.shift();
+        // Independent exact/motion completion may insert IDs out of numeric order.
+        for (const id of this.frames.keys())
+            if (id <= frame)
+                this.frames.delete(id);
+    }
+    excess(now) {
+        this.samples = this.samples.filter(s => now - s.at <= 90000);
+        const recent = this.samples.filter(s => now - s.at <= 1250);
+        if (!recent.length)
+            return 0;
+        return Math.max(0, Math.min(...recent.map(s => s.delay)) - Math.min(...this.samples.map(s => s.delay)));
+    }
+    sample(now) {
+        const raw = this.excess(now);
+        const fresh = this.samples.filter(s => s.observation > this.sampled && now - s.at <= 1250);
+        this.sampled = this.observation;
+        if (!fresh.length)
+            return { excessMs: raw, observations: 0, delayMs: undefined };
+        const excessMs = Math.max(0, Math.min(...fresh.map(s => s.delay)) - Math.min(...this.samples.map(s => s.delay)));
+        // The active feedback cadence allows 200ms of scheduling uncertainty. Only
+        // the excess beyond that can establish >40ms congestion; ambiguity must hold.
+        const delayMs = excessMs <= 40 ? excessMs : excessMs > 240 ? excessMs - 200 : undefined;
+        return { excessMs, observations: fresh.length, delayMs };
+    }
+    reset() {
+        this.frames.clear();
+        this.samples = [];
+        this.sampled = this.observation;
+    }
+}