@3minapi/cli 0.0.0-stage → 0.22.1

package/dist/core/host/live-receiver.js

@@ -0,0 +1,264 @@
+import { LIVE_RETRY_MS, POLL_INTERVAL_MAX_MS, POLL_MIN_INTERVAL_MS, StopError, isTrustedLiveUrl } from "../domain/index.js";
+import { stripControl } from "../text.js";
+import { formatInterval, sleep } from "../time.js";
+import { LiveConnection } from "./live-connection.js";
+import { endReceive, pullStep } from "./pull-step.js";
+const HOST_CHECK_DEDUPE_MS = 30_000;
+export class LiveReceiver {
+    opts;
+    conn;
+    now;
+    minIntervalMs;
+    retryMs;
+    halted = new AbortController();
+    stopError = null;
+    lastQuota;
+    resyncState = 'idle';
+    napWake = null;
+    signalled = false;
+    signalSeq = 0;
+    more = false;
+    slotPending = false;
+    triggers = new Set();
+    notBefore = 0;
+    hostCheck = null;
+    drops = [];
+    url;
+    hostCheckedAt = Number.NEGATIVE_INFINITY;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? Date.now;
+        this.minIntervalMs = opts.minIntervalMs ?? POLL_MIN_INTERVAL_MS;
+        this.retryMs = opts.retryMs ?? LIVE_RETRY_MS;
+        this.lastQuota = opts.quota ?? null;
+        this.url = opts.url;
+        this.conn = new LiveConnection({
+            url: opts.url,
+            token: opts.token,
+            logger: opts.logger,
+            onOpen: () => this.pullSoon('catch_up'),
+            onSignal: (topic) => this.onSignal(topic),
+            onCheckHost: () => this.checkHost('close'),
+            onRefreshUrl: () => this.checkHost('refresh'),
+            onState: opts.onState,
+            timing: opts.timing,
+            now: opts.now,
+            random: opts.random
+        });
+        opts.module.onSlotFree(() => {
+            if (!this.slotPending)
+                return;
+            this.slotPending = false;
+            this.more = true;
+            this.triggers.add('slot_free');
+            this.wake();
+        });
+    }
+    get liveState() {
+        return this.conn.liveState;
+    }
+    stop(err) {
+        this.stopError ??= err;
+        this.halted.abort();
+        this.conn.close();
+        this.wake();
+    }
+    requestResync() {
+        if (this.resyncState !== 'idle')
+            return;
+        this.resyncState = 'pending';
+        this.wake();
+    }
+    requestDrop(names) {
+        this.drops.push(...names);
+        this.wake();
+    }
+    get resyncIdle() {
+        return this.resyncState === 'idle';
+    }
+    setUrl(url) {
+        if (url === this.url)
+            return;
+        if (!isTrustedLiveUrl(url, this.opts.apiUrl)) {
+            this.opts.logger.warn('ignored a live url that does not match the API host');
+            return;
+        }
+        this.url = url;
+        this.conn.setUrl(url);
+        this.opts.onLiveUrl?.(url);
+    }
+    async run() {
+        const { api, logger, module, signal } = this.opts;
+        const sleepSignal = AbortSignal.any([signal, this.halted.signal]);
+        const flushTimer = setInterval(() => void module.flushPending(), this.retryMs);
+        flushTimer.unref();
+        let noActive = false;
+        this.conn.start();
+        try {
+            while (!signal.aborted && this.stopError === null) {
+                if (this.drops.length > 0) {
+                    module.dropLocal(this.drops.splice(0));
+                    if (module.activeCount === 0) {
+                        noActive = true;
+                        break;
+                    }
+                }
+                if (this.resyncState === 'pending') {
+                    this.resyncState = 'running';
+                    try {
+                        await module.resync();
+                    }
+                    catch (err) {
+                        if (!(err instanceof StopError))
+                            throw err;
+                        this.stop(err);
+                        break;
+                    }
+                    finally {
+                        this.resyncState = 'idle';
+                    }
+                    if (module.activeCount === 0) {
+                        noActive = true;
+                        break;
+                    }
+                    continue;
+                }
+                let wait = POLL_INTERVAL_MAX_MS;
+                if ((this.signalled || this.more) && this.conn.connected) {
+                    const left = this.notBefore - this.now();
+                    if (left > 0) {
+                        wait = left;
+                    }
+                    else {
+                        const full = module.pullMax() === 0;
+                        if (full && !this.signalled) {
+                            this.more = false;
+                            this.slotPending = true;
+                            this.triggers.clear();
+                            continue;
+                        }
+                        const seq = this.signalSeq;
+                        const was = { signalled: this.signalled, more: this.more };
+                        const trigger = [...this.triggers];
+                        this.signalled = false;
+                        this.more = false;
+                        this.triggers.clear();
+                        const out = await pullStep({
+                            api,
+                            logger,
+                            module,
+                            isStopped: () => this.stopError !== null,
+                            onPull: this.opts.onPull,
+                            onError: this.opts.onError,
+                            retryHint: `in ${formatInterval(this.retryMs)}`,
+                            quietTooSoon: true,
+                            trigger
+                        });
+                        if (out.kind === 'skipped')
+                            break;
+                        if (out.kind === 'stopped') {
+                            this.stop(out.err);
+                            break;
+                        }
+                        if (out.kind === 'pulled') {
+                            this.lastQuota = out.res.quota;
+                            this.notBefore =
+                                this.now() +
+                                    Math.min(Math.max(this.minIntervalMs, out.res.poll.min_interval_ms), POLL_INTERVAL_MAX_MS);
+                            if (out.noActive) {
+                                noActive = true;
+                                break;
+                            }
+                            if (full || out.res.has_more) {
+                                if (module.pullMax() > 0) {
+                                    this.more = true;
+                                    this.triggers.add(full ? 'slot_free' : 'has_more');
+                                }
+                                else
+                                    this.slotPending = true;
+                            }
+                        }
+                        else {
+                            this.signalled ||= was.signalled;
+                            this.more ||= was.more;
+                            for (const t of trigger)
+                                this.triggers.add(t);
+                            this.triggers.add('retry');
+                            this.notBefore =
+                                this.now() +
+                                    (out.kind === 'too_soon'
+                                        ? Math.min(out.retryAfterMs, POLL_INTERVAL_MAX_MS)
+                                        : this.retryMs);
+                        }
+                        if (this.signalSeq !== seq)
+                            this.signalled = true;
+                        continue;
+                    }
+                }
+                this.napWake = new AbortController();
+                await sleep(wait, AbortSignal.any([sleepSignal, this.napWake.signal]));
+                this.napWake = null;
+            }
+        }
+        finally {
+            clearInterval(flushTimer);
+            this.conn.close();
+        }
+        await this.hostCheck;
+        if (this.stopError === null)
+            this.resyncState = 'idle';
+        return endReceive(module, this.stopError, this.lastQuota, noActive);
+    }
+    onSignal(topic) {
+        if (topic === 'host') {
+            void this.checkHost('signal');
+            return;
+        }
+        if (this.opts.module.topics.includes(topic)) {
+            this.pullSoon('signal');
+            return;
+        }
+        this.opts.logger.debug('ignored an unknown live topic', {
+            topic: stripControl(topic).slice(0, 32)
+        });
+    }
+    pullSoon(trigger) {
+        this.triggers.add(trigger);
+        this.signalled = true;
+        this.signalSeq++;
+        this.wake();
+    }
+    wake() {
+        this.napWake?.abort();
+    }
+    checkHost(why) {
+        if (this.hostCheck)
+            return this.hostCheck;
+        if (this.stopError !== null)
+            return Promise.resolve();
+        if (why === 'close' && this.now() - this.hostCheckedAt < HOST_CHECK_DEDUPE_MS) {
+            return Promise.resolve();
+        }
+        this.hostCheck = (async () => {
+            try {
+                const res = await this.opts.api.getHost();
+                this.hostCheckedAt = this.now();
+                this.lastQuota = res.quota;
+                if (res.live)
+                    this.setUrl(res.live.url);
+                this.opts.logger.info('host checked', { why });
+            }
+            catch (err) {
+                if (err instanceof StopError) {
+                    this.stop(err);
+                    return;
+                }
+                this.opts.logger.warn('host check failed', { why, message: err.message });
+            }
+            finally {
+                this.hostCheck = null;
+            }
+        })();
+        return this.hostCheck;
+    }
+}

package/dist/core/host/module.js

@@ -0,0 +1 @@
+export {};

package/dist/core/host/poller.js

@@ -0,0 +1,113 @@
+import { POLL_INTERVAL_MAX_MS, StopError } from "../domain/index.js";
+import { sleep } from "../time.js";
+import { endReceive, pullStep } from "./pull-step.js";
+const INTERVAL_TRIGGER = ['interval'];
+const RETRY_TRIGGER = ['retry'];
+export class Poller {
+    opts;
+    stopError = null;
+    wake = new AbortController();
+    lastQuota = null;
+    resyncState = 'idle';
+    napWake = null;
+    drops = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.lastQuota = opts.quota ?? null;
+    }
+    stop(err) {
+        this.stopError ??= err;
+        this.wake.abort();
+    }
+    requestResync() {
+        if (this.resyncState !== 'idle')
+            return;
+        this.resyncState = 'pending';
+        this.napWake?.abort();
+    }
+    requestDrop(names) {
+        this.drops.push(...names);
+        this.napWake?.abort();
+    }
+    get resyncIdle() {
+        return this.resyncState === 'idle';
+    }
+    async run() {
+        const { api, logger, signal, module } = this.opts;
+        const sleepSignal = AbortSignal.any([signal, this.wake.signal]);
+        let noActive = false;
+        let retrying = false;
+        while (!signal.aborted && this.stopError === null) {
+            let wait = this.opts.intervalMs;
+            const out = await pullStep({
+                api,
+                logger,
+                module,
+                isStopped: () => this.stopError !== null,
+                onPull: this.opts.onPull,
+                onError: this.opts.onError,
+                retryHint: 'at the next interval',
+                trigger: retrying ? RETRY_TRIGGER : INTERVAL_TRIGGER
+            });
+            retrying = out.kind === 'too_soon' || out.kind === 'failed';
+            if (out.kind === 'skipped')
+                break;
+            if (out.kind === 'stopped') {
+                this.stop(out.err);
+                break;
+            }
+            if (out.kind === 'pulled') {
+                this.lastQuota = out.res.quota;
+                wait = Math.min(Math.max(this.opts.intervalMs, out.res.poll.min_interval_ms), POLL_INTERVAL_MAX_MS);
+                if (out.noActive) {
+                    noActive = true;
+                    break;
+                }
+            }
+            else if (out.kind === 'too_soon') {
+                wait = Math.min(out.retryAfterMs, POLL_INTERVAL_MAX_MS);
+            }
+            if (await this.nap(wait, sleepSignal)) {
+                noActive = true;
+                break;
+            }
+        }
+        if (this.stopError === null)
+            this.resyncState = 'idle';
+        return endReceive(module, this.stopError, this.lastQuota, noActive);
+    }
+    async nap(wait, sleepSignal) {
+        const until = Date.now() + wait;
+        while (!this.opts.signal.aborted && this.stopError === null) {
+            if (this.drops.length > 0) {
+                this.opts.module.dropLocal(this.drops.splice(0));
+                if (this.opts.module.activeCount === 0)
+                    return true;
+            }
+            if (this.resyncState === 'pending') {
+                this.resyncState = 'running';
+                try {
+                    await this.opts.module.resync();
+                }
+                catch (err) {
+                    if (!(err instanceof StopError))
+                        throw err;
+                    this.stop(err);
+                    return false;
+                }
+                finally {
+                    this.resyncState = 'idle';
+                }
+                if (this.opts.module.activeCount === 0)
+                    return true;
+            }
+            const left = until - Date.now();
+            if (left <= 0)
+                return false;
+            this.napWake = new AbortController();
+            await sleep(left, AbortSignal.any([sleepSignal, this.napWake.signal]));
+            this.napWake = null;
+        }
+        return false;
+    }
+}

package/dist/core/host/pull-step.js

@@ -0,0 +1,54 @@
+import { ApiError } from "../api.js";
+import { StopError } from "../domain/index.js";
+export async function pullStep(opts) {
+    const { api, logger, module } = opts;
+    try {
+        await module.beforePull();
+        if (opts.isStopped())
+            return { kind: 'skipped' };
+        const res = await api.pullTasks(module.pullMax());
+        logger.debug('pulled', {
+            trigger: opts.trigger.join('+'),
+            tasks: res.tasks.length,
+            cancelled: res.cancelled.length,
+            has_more: res.has_more,
+            remaining: res.quota.remaining
+        });
+        opts.onPull?.(res);
+        module.onPull(res);
+        return { kind: 'pulled', res, noActive: module.activeCount === 0 };
+    }
+    catch (err) {
+        if (err instanceof StopError)
+            return { kind: 'stopped', err };
+        if (!(err instanceof ApiError))
+            throw err;
+        const tooSoon = err.code === 'poll_too_soon' && err.retryAfterMs !== null;
+        if (err.code === 'invalid_request') {
+            logger.error('the server rejected the pull request (a CLI bug)', {
+                trigger: opts.trigger.join('+'),
+                message: err.message
+            });
+        }
+        else if (!tooSoon) {
+            logger.warn(`pull failed; trying again ${opts.retryHint}`, {
+                trigger: opts.trigger.join('+'),
+                status: err.status,
+                message: err.message
+            });
+        }
+        if (!(tooSoon && opts.quietTooSoon))
+            opts.onError?.(err);
+        return tooSoon
+            ? { kind: 'too_soon', retryAfterMs: err.retryAfterMs }
+            : { kind: 'failed', err };
+    }
+}
+export async function endReceive(module, stopError, lastQuota, noActive) {
+    if (stopError !== null) {
+        await module.halt(stopError.reason);
+        return new StopError(stopError.reason, stopError.message, stopError.resetAt ?? lastQuota?.reset_at);
+    }
+    await module.shutdown();
+    return noActive ? module.ended() : null;
+}

package/dist/core/host/receiver.js

@@ -0,0 +1 @@
+export {};

package/dist/core/host/reload.js

@@ -0,0 +1,34 @@
+import { CliError, ExitCode, RELOAD_WAIT_MS, StopError } from "../domain/index.js";
+import { readReload, readRunner, requestReload } from "./runner-lock.js";
+import { stopHint } from "./session.js";
+import { sleep } from "../time.js";
+const POLL_MS = 200;
+export async function reloadRunner(ctx, info) {
+    if (!info.reload) {
+        throw new CliError(`the running start (pid ${info.pid}) is from an older 3minapi and cannot reload. Restart it: '3minapi stop' then '3minapi start'.`);
+    }
+    const requestedAt = requestReload(ctx.dirs.data, info);
+    const deadline = requestedAt + RELOAD_WAIT_MS;
+    for (;;) {
+        const record = readReload(ctx.dirs.data, info);
+        if (record?.state === 'done' && record.startedAt >= requestedAt && record.result) {
+            return record.result;
+        }
+        const runner = readRunner(ctx.dirs.data);
+        if (runner.state !== 'running' || runner.info.nonce !== info.nonce) {
+            throw new CliError("the running start ended before the reload finished. See '3minapi status' and '3minapi logs'.");
+        }
+        if (Date.now() >= deadline) {
+            throw new CliError(`no reload result after ${RELOAD_WAIT_MS / 1000}s — the start may still be loading worker files. See '3minapi logs'.`);
+        }
+        await sleep(POLL_MS, ctx.signal);
+        if (ctx.signal.aborted)
+            throw new CliError('cancelled — the running start may still reload.', ExitCode.Interrupted);
+    }
+}
+export function failReload(result) {
+    if (result.stopped) {
+        throw new StopError(result.stopped, `${result.error}\nThe running start stopped all calls. ${stopHint(result.stopped)}`);
+    }
+    throw new CliError(`reload failed: ${result.error} The running start keeps its current workers.`);
+}