@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/files/media/media.js

@@ -0,0 +1,325 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { keys, string, integer, validateRequest } from '../../tools/validation.js';
+import { MediaScheduler, MediaConsumerExpiredError } from './scheduler.js';
+import { decoderCommand } from './encoding.js';
+/** The successful-result marker consumers match (`FileMediaStreamingGateway` maps it to FileMediaResourceExpired). */
+export const MEDIA_CONSUMER_EXPIRED = 'media-consumer-expired';
+const RECIPE = 'preview-v2-720p-h264-aac128-png2048-mp3128';
+const STREAM_RECIPE = 'preview-v4-720p30-closedgop120-aac128-mp3128-noreservoir-globalpts';
+const MAX_OUTPUT = 512 * 1024 * 1024;
+const CACHE_LIMIT = 2 * 1024 * 1024 * 1024;
+const TTL = 24 * 60 * 60_000;
+const formats = 'mov,matroska,webm,mp3,wav,flac,ogg,aac,avi,aiff,png_pipe,jpeg_pipe,webp_pipe,bmp_pipe,tiff_pipe,gif';
+const extensions = new Set('mp4 m4v mov mkv webm avi mp3 wav flac ogg opus aac m4a aif aiff png jpg jpeg webp bmp tif tiff gif heic heif avif'.split(' '));
+async function snapshot(handle) {
+    const s = await handle.stat({ bigint: true });
+    if (!s.isFile() || s.size > 32n * 1024n * 1024n * 1024n)
+        throw new Error('Not a supported regular media file');
+    return { dev: String(s.dev), ino: String(s.ino), size: String(s.size), mtime: String(s.mtimeNs), ctime: String(s.ctimeNs) };
+}
+const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function tool(command, args, input, signal) {
+    return new Promise((resolve, reject) => {
+        // Restrict decoding to local self-contained containers; never accept playlist/concat/network inputs.
+        // An explicit cwd: the files host changes its own cwd inside pinned() sections, which a child would otherwise inherit.
+        const child = spawn(command, args, { cwd: '/', stdio: ['ignore', 'pipe', 'pipe', input.fd], env: process.env });
+        let output = '';
+        let failure;
+        const stop = () => { failure ??= new Error('Media preparation cancelled or timed out'); child.kill('SIGTERM'); };
+        const timeout = setTimeout(() => cancel(), 5 * 60_000);
+        timeout.unref();
+        let kill;
+        const cancel = () => { stop(); kill = setTimeout(() => child.kill('SIGKILL'), 2000); kill.unref(); };
+        signal.addEventListener('abort', cancel, { once: true });
+        if (signal.aborted)
+            cancel();
+        child.stdout.on('data', chunk => { output += chunk.toString(); if (output.length > 1024 * 1024) {
+            failure = new Error('Media metadata exceeds limit');
+            cancel();
+        } });
+        child.stderr.resume(); // Diagnostics may contain local paths; keep public errors bounded and generic.
+        child.on('error', e => { failure = new Error(e.code === 'ENOENT' ? 'Install FFmpeg and ffprobe on this workstation (or set AXOM_FFMPEG / AXOM_FFPROBE).' : 'Unable to start workstation media decoder'); });
+        child.on('close', code => {
+            clearTimeout(timeout);
+            if (kill)
+                clearTimeout(kill);
+            signal.removeEventListener('abort', cancel);
+            if (failure)
+                reject(failure);
+            else if (code !== 0)
+                reject(new Error('Unable to prepare this media file. It may be damaged or unsupported.'));
+            else
+                resolve(output);
+        });
+    });
+}
+/** Separate finite jobs: tools queue never waits for FFmpeg. Cache paths are derived, not client supplied. */
+export class WorkstationMedia {
+    files;
+    cache;
+    jobs = new Map();
+    queue = Promise.resolve();
+    closed = false;
+    initialized;
+    scheduler;
+    constructor(files, cache) {
+        this.files = files;
+        this.cache = cache;
+    }
+    init() {
+        return this.initialized ??= (async () => {
+            await fs.mkdir(this.cache, { recursive: true, mode: 0o700 });
+            const stat = await fs.lstat(this.cache);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+                throw new Error('Unsafe media cache');
+            await fs.chmod(this.cache, 0o700);
+            this.scheduler = await MediaScheduler.create(this.cache);
+            await this.trim();
+        })();
+    }
+    async trim() { await this.scheduler.trimCache(); }
+    async dispatch(method, p) {
+        if (this.closed)
+            throw new Error('Workstation media stopped');
+        if (!['files.media.prepare', 'files.media.read', 'files.media.cancel'].includes(method))
+            return this.streaming(method, p);
+        keys(p, [...(method === 'files.media.prepare' ? ['path'] : method === 'files.media.cancel' ? ['path', 'version'] : ['path', 'version', 'offset', 'length']), 'readOnly']);
+        if (p.readOnly !== undefined && typeof p.readOnly !== 'boolean')
+            throw new Error('Invalid readOnly');
+        const source = string(p, 'path');
+        if (!extensions.has(path.extname(source).slice(1).toLowerCase()))
+            throw new Error('Unsupported media format');
+        const input = await this.files.openMediaSource(source, p.readOnly === true);
+        let retained = false;
+        try {
+            const stamp = await snapshot(input);
+            const version = createHash('sha256').update(JSON.stringify([source, stamp, RECIPE])).digest('hex');
+            if (method !== 'files.media.prepare' && string(p, 'version', 64) !== version)
+                throw new Error('Media source changed; reopen its preview');
+            await this.init();
+            // The files host runs requests concurrently (the legacy keeper serialized them): one version's check-then-create
+            // of its job must not interleave with another request for the same version, or two conversions would start.
+            return await this.exclusive(version, async () => {
+                await this.scheduler.pinLegacy(version);
+                let job = this.jobs.get(version);
+                if (method === 'files.media.cancel') {
+                    job?.abort.abort();
+                    return { ok: true };
+                }
+                if (method === 'files.media.read') {
+                    const offset = integer(p, 'offset', 0, Number.MAX_SAFE_INTEGER);
+                    const length = integer(p, 'length', 1, 256 * 1024);
+                    const media = job?.media ?? await this.cached(version);
+                    if (!media)
+                        throw new Error('Media preview is not ready');
+                    const handle = await fs.open(path.join(this.cache, `${version}.${media.extension}`), constants.O_RDONLY | constants.O_NOFOLLOW);
+                    try {
+                        const stat = await handle.stat();
+                        if (!stat.isFile() || stat.size !== media.size)
+                            throw new Error('Media preview cache changed');
+                        const bytes = Buffer.alloc(Math.min(length, Math.max(0, stat.size - offset)));
+                        const { bytesRead } = await handle.read(bytes, 0, bytes.length, offset);
+                        return { data: bytes.subarray(0, bytesRead).toString('base64'), size: stat.size, eof: offset + bytesRead >= stat.size };
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                }
+                if (job?.state === 'ready' && !await this.cached(version)) {
+                    this.jobs.delete(version);
+                    job = undefined;
+                }
+                if (!job) {
+                    const cached = await this.cached(version);
+                    if (cached)
+                        return cached;
+                    for (const [key, item] of this.jobs)
+                        if (item.state !== 'preparing')
+                            this.jobs.delete(key);
+                    if (this.jobs.size >= 8)
+                        throw new Error('Workstation media queue is full; try again shortly');
+                    job = { version, snapshot: stamp, state: 'preparing', abort: new AbortController(), done: Promise.resolve() };
+                    this.jobs.set(version, job);
+                    retained = true;
+                    const current = job;
+                    current.done = this.scheduler.runFinite(signal => this.convert(version, input, stamp, signal), current.abort.signal)
+                        .then(media => { current.media = media; current.state = 'ready'; }, error => { current.state = 'failed'; current.error = error.message; })
+                        .finally(() => input.close());
+                    this.queue = Promise.all([this.queue, current.done]).then(() => { });
+                }
+                // Report the failed attempt once, then allow a fresh user retry (e.g. after installing FFmpeg).
+                if (job.state === 'failed')
+                    this.jobs.delete(version);
+                return job.media ?? { state: job.state, version, ...(job.error ? { error: job.error } : {}) };
+            });
+        }
+        finally {
+            if (!retained)
+                await input.close();
+        }
+    }
+    async streaming(method, p) {
+        validateRequest(method, p);
+        const source = string(p, 'path');
+        if (!extensions.has(path.extname(source).slice(1).toLowerCase()))
+            throw new Error('Unsupported media format');
+        if (method === 'files.media.release') {
+            await this.init();
+            await this.scheduler.releaseIdentity(string(p, 'version', 64), string(p, 'consumerId', 128));
+            return { ok: true };
+        }
+        const input = await this.files.openMediaSource(source, p.readOnly === true);
+        let transferred = false;
+        try {
+            const stamp = await snapshot(input);
+            const version = createHash('sha256').update(JSON.stringify([source, stamp, STREAM_RECIPE])).digest('hex');
+            const legacyVersion = createHash('sha256').update(JSON.stringify([source, stamp, RECIPE])).digest('hex');
+            if (method !== 'files.media.open' && string(p, 'version', 64) !== version)
+                throw new Error('Media source changed; reopen its preview');
+            await this.init();
+            const scheduler = this.scheduler;
+            const key = { version, sourcePath: source, snapshot: JSON.stringify(stamp), recipe: STREAM_RECIPE, legacyVersion };
+            const consumerId = string(p, 'consumerId', 128);
+            if (method === 'files.media.open') {
+                transferred = true;
+                return { ...await scheduler.open(input, key, consumerId, p.hls === true) };
+            }
+            if (method === 'files.media.status')
+                return { ...await scheduler.status(key, consumerId) };
+            if (method === 'files.media.seek')
+                return { ...await scheduler.seek(key, consumerId, integer(p, 'positionMs', 0, 21600000), integer(p, 'revision', 0, Number.MAX_SAFE_INTEGER)) };
+            if (method === 'files.media.interest') {
+                await scheduler.interest(key, consumerId, integer(p, 'positionMs', 0, 21600000), p.playing === true);
+                return { ok: true };
+            }
+            if (method === 'files.media.object')
+                return { ...await scheduler.object(key, consumerId, string(p, 'objectId', 128), integer(p, 'offset', 0, Number.MAX_SAFE_INTEGER), integer(p, 'length', 1, 256 * 1024)) };
+            if (method === 'files.media.release') {
+                await scheduler.release(key, consumerId);
+                return { ok: true };
+            }
+            throw new Error('Unsupported workstation tool');
+        }
+        catch (error) {
+            if (error instanceof MediaConsumerExpiredError)
+                return { errorCode: MEDIA_CONSUMER_EXPIRED };
+            throw error;
+        }
+        finally {
+            if (!transferred)
+                await input.close();
+        }
+    }
+    /** Media encodes running or queued (sampled by the daemon as activity). */
+    get activeEncodes() { return this.scheduler?.runningEncodes ?? 0; }
+    versionLocks = new Map();
+    /** Runs `action` after every earlier action for the same version has settled. */
+    async exclusive(version, action) {
+        const previous = this.versionLocks.get(version) ?? Promise.resolve();
+        const mine = previous.catch(() => { }).then(action);
+        const tail = mine.catch(() => { });
+        this.versionLocks.set(version, tail);
+        try {
+            return await mine;
+        }
+        finally {
+            if (this.versionLocks.get(version) === tail)
+                this.versionLocks.delete(version);
+        }
+    }
+    async cached(version) {
+        await this.scheduler.pinLegacy(version);
+        try {
+            const meta = path.join(this.cache, `${version}.json`);
+            const handle = await fs.open(meta, constants.O_RDONLY | constants.O_NOFOLLOW);
+            let media;
+            try {
+                if ((await handle.stat()).size > 4096)
+                    return;
+                media = JSON.parse(await handle.readFile('utf8'));
+            }
+            finally {
+                await handle.close();
+            }
+            if (media.version !== version || media.state !== 'ready' || !['mp3', 'mp4', 'png'].includes(media.extension) || !Number.isSafeInteger(media.size) || media.size <= 0 || media.size >= MAX_OUTPUT)
+                return;
+            const stat = await fs.lstat(path.join(this.cache, `${version}.${media.extension}`));
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== media.size)
+                return;
+            return media;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async convert(version, input, stamp, signal) {
+        if (process.platform === 'win32')
+            throw new Error('Workstation media preparation currently requires macOS or Linux FFmpeg');
+        await this.trim();
+        const free = await fs.statfs(this.cache);
+        if (free.bavail * free.bsize < MAX_OUTPUT)
+            throw new Error('Not enough free disk space for a media preview');
+        const base = ['-v', 'error', '-max_alloc', '134217728', '-protocol_whitelist', 'file', '-format_whitelist', formats];
+        const raw = await tool(decoderCommand('AXOM_FFPROBE', 'ffprobe'), [...base, '-show_format', '-show_streams', '-of', 'json', '/dev/fd/3'], input, signal);
+        const probe = JSON.parse(raw);
+        const video = probe.streams.find(s => s.codec_type === 'video' && !s.disposition?.attached_pic);
+        const audio = probe.streams.find(s => s.codec_type === 'audio');
+        const duration = Number(probe.format.duration ?? video?.duration ?? audio?.duration ?? 0);
+        const image = !!video && !audio && duration === 0;
+        const kind = image ? 'image' : video ? 'video' : audio ? 'audio' : undefined;
+        if (!kind || !Number.isFinite(duration) || duration < 0 || duration > 6 * 60 * 60)
+            throw new Error('Unsupported media or duration exceeds six hours');
+        if (video && ((!video.width || !video.height) || video.width * video.height > 40_000_000))
+            throw new Error('Image/video dimensions exceed preview limits');
+        const extension = kind === 'video' ? 'mp4' : kind === 'audio' ? 'mp3' : 'png';
+        const output = path.join(this.cache, `.part-${randomUUID()}.${extension}`);
+        const destination = path.join(this.cache, `${version}.${extension}`);
+        let args = ['-nostdin', '-v', 'error', '-max_alloc', '134217728', '-threads', '2', '-protocol_whitelist', 'file', '-format_whitelist', formats, '-i', '/dev/fd/3', '-map_metadata', '-1'];
+        if (kind === 'image')
+            args.push('-map', '0:v:0', '-frames:v', '1', '-vf', "scale=w='min(2048,iw)':h='min(2048,ih)':force_original_aspect_ratio=decrease", '-c:v', 'png', '-threads', '1');
+        else if (kind === 'audio')
+            args.push('-map', '0:a:0', '-vn', '-c:a', 'libmp3lame', '-b:a', '128k', '-ac', '2', '-ar', '44100');
+        else {
+            args.push('-map', '0:v:0', '-map', '0:a:0?');
+            if (video.codec_name === 'h264' && video.pix_fmt === 'yuv420p' && video.width <= 1280 && video.height <= 720 && Number(probe.format.bit_rate) <= 2_000_000)
+                args.push('-c:v', 'copy');
+            else
+                args.push('-vf', "scale=w='min(1280,iw)':h='min(720,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2", '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '26', '-maxrate', '1800k', '-bufsize', '3600k', '-pix_fmt', 'yuv420p', '-threads', '2');
+            args.push('-c:a', 'aac', '-b:a', '128k', '-ac', '2', '-movflags', '+faststart');
+        }
+        args.push('-fs', String(MAX_OUTPUT), '-y', output);
+        await this.scheduler.pinLegacy(version);
+        const releaseReservation = await this.scheduler.reserveLegacy(output, MAX_OUTPUT + 4096);
+        try {
+            await tool(decoderCommand('AXOM_FFMPEG', 'ffmpeg'), args, input, signal);
+            if (signal.aborted || !equal(stamp, await snapshot(input)))
+                throw new Error('Media source changed or preparation cancelled');
+            const stat = await fs.stat(output);
+            if (!stat.size || stat.size >= MAX_OUTPUT)
+                throw new Error('Media preview exceeds 512 MiB');
+            const factor = video ? Math.min(1, (image ? 2048 : 1280) / video.width, (image ? 2048 : 720) / video.height) : 0;
+            const media = { state: 'ready', version, kind, mimeType: kind === 'video' ? 'video/mp4' : kind === 'audio' ? 'audio/mpeg' : 'image/png', extension, size: stat.size, durationSeconds: duration, width: video ? Math.floor(video.width * factor) : 0, height: video ? Math.floor(video.height * factor) : 0 };
+            await this.scheduler.pinLegacy(version);
+            await fs.rename(output, destination);
+            const metaTemp = path.join(this.cache, `.part-${randomUUID()}.json`);
+            try {
+                await fs.writeFile(metaTemp, JSON.stringify(media), { mode: 0o600, flag: 'wx' });
+                await fs.rename(metaTemp, path.join(this.cache, `${version}.json`));
+            }
+            finally {
+                await fs.unlink(metaTemp).catch(() => { });
+            }
+            return media;
+        }
+        finally {
+            await fs.unlink(output).catch(() => { });
+            await releaseReservation();
+        }
+    }
+    async dispose() { this.closed = true; for (const job of this.jobs.values())
+        job.abort.abort(); await this.scheduler?.dispose(); await this.queue; this.jobs.clear(); }
+}

package/dist/workstation/files/media/packedAudio.js

@@ -0,0 +1,23 @@
+/** RFC 8216 §3.4: one PRIV frame with an unsigned 33-bit MPEG timestamp. */
+export function stampPackedAudio(mp3, transportTimestamp90k) {
+    if (transportTimestamp90k < 0n || transportTimestamp90k >= 1n << 33n)
+        throw new Error('Invalid packed audio timestamp');
+    const owner = Buffer.from('com.apple.streaming.transportStreamTimestamp\0');
+    const payload = Buffer.alloc(owner.length + 8);
+    owner.copy(payload);
+    payload.writeBigUInt64BE(transportTimestamp90k, owner.length);
+    const frame = Buffer.alloc(10);
+    frame.write('PRIV');
+    writeSynchsafe(frame, 4, payload.length);
+    const tag = Buffer.alloc(10);
+    tag.write('ID3');
+    tag[3] = 4;
+    writeSynchsafe(tag, 6, frame.length + payload.length);
+    return Buffer.concat([tag, frame, payload, mp3]);
+}
+function writeSynchsafe(buffer, offset, size) {
+    for (let i = 3; i >= 0; i--) {
+        buffer[offset + i] = size & 127;
+        size >>>= 7;
+    }
+}