@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/core/domain/contract.js

@@ -0,0 +1,102 @@
+export const STOP_CODES = [
+    'host_token_invalid',
+    'no_subscription',
+    'quota_exhausted',
+    'cli_outdated'
+];
+export const TASK_CODES = ['task_not_found', 'task_terminal', 'lease_superseded'];
+export const OTHER_CODES = [
+    'poll_too_soon',
+    'invalid_request',
+    'worker_not_found',
+    'payload_too_large',
+    'unsupported_media_type',
+    'service_unavailable'
+];
+export function isStopCode(code) {
+    return typeof code === 'string' && STOP_CODES.includes(code);
+}
+export const SYNC_REJECT_CODES = [
+    'invalid_worker_name',
+    'description_too_long',
+    'worker_name_taken'
+];
+export const HOST_TOKEN_PREFIX = 'tm_host_';
+export const PULL_MAX_DEFAULT = 10;
+export const PULL_MAX_LIMIT = 50;
+export const POLL_MIN_INTERVAL_MS = 5_000;
+export const LEASE_MS = 60_000;
+export const MAX_DELIVERIES = 6;
+export const REPORT_MAX_BYTES = 100 * 1024;
+export const STATUS_MESSAGE_MAX_CHARS = 256;
+export const LEASE_EXPIRED_REASON = 'lease expired without acknowledgement';
+export const TASK_ERROR_CODE = -32000;
+export const RECEIVE_MODES = ['live', 'poll'];
+export const LIVE_TOPICS = ['workers', 'host'];
+export const LIVE_RESERVED_TOPICS = ['update', 'config'];
+export function isLiveTopic(topic) {
+    return typeof topic === 'string' && LIVE_TOPICS.includes(topic);
+}
+export const LIVE_PING = 'ping';
+export const LIVE_PONG = 'pong';
+export const LIVE_PING_INTERVAL_MS = 30_000;
+export const LIVE_PONG_TIMEOUT_MS = 10_000;
+export const LIVE_CLOSE = {
+    REPLACED: 4000,
+    CHECK_HOST: 4001
+};
+export const LIVE_CLOSE_REASON = {
+    [LIVE_CLOSE.REPLACED]: 'replaced',
+    [LIVE_CLOSE.CHECK_HOST]: 'check_host'
+};
+export const LIVE_RECONNECT_FIRST_JITTER_MS = 30_000;
+export const LIVE_RECONNECT_MAX_MS = 300_000;
+export const LIVE_RECONNECT_STABLE_MS = 60_000;
+export const LIVE_RETRY_MS = 60_000;
+export const LIVE_URL_REFRESH_AFTER_MS = 30 * 60_000;
+const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '[::1]'];
+export function isTrustedLiveUrl(liveUrl, apiUrl) {
+    let live;
+    let api;
+    try {
+        live = new URL(liveUrl);
+        api = new URL(apiUrl);
+    }
+    catch {
+        return false;
+    }
+    const secure = api.protocol === 'https:' && live.protocol === 'wss:';
+    const loopback = api.protocol === 'http:' &&
+        live.protocol === 'ws:' &&
+        LOOPBACK_HOSTNAMES.includes(api.hostname);
+    if (!secure && !loopback)
+        return false;
+    return (live.hostname === api.hostname &&
+        live.port === api.port &&
+        live.username === '' &&
+        live.password === '');
+}
+export const SYNC_WORKERS_MAX = 200;
+export const WORKER_DESCRIPTION_MAX_CHARS = 500;
+export const PULL_WORKER_NAME = /^[a-z0-9_-]{1,50}$/;
+export const WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/;
+export function isPullWorkerName(name) {
+    return (typeof name === 'string' && PULL_WORKER_NAME.test(name) && !WINDOWS_RESERVED_NAME.test(name));
+}
+export const RESERVED_NAME_PREFIX = '_';
+export const BUILTIN_RESULTS_PREFIX = '_results_';
+export const BUILTIN_HOST_SUFFIX_CHARS = 8;
+export function builtinResultsName(hostId) {
+    return (BUILTIN_RESULTS_PREFIX +
+        hostId.replace(/-/g, '').toLowerCase().slice(-BUILTIN_HOST_SUFFIX_CHARS));
+}
+export function isReservedWorkerName(name) {
+    return name.startsWith(RESERVED_NAME_PREFIX);
+}
+export function isSyncableWorkerName(name, hostId) {
+    if (!isPullWorkerName(name))
+        return false;
+    return !isReservedWorkerName(name) || name === builtinResultsName(hostId);
+}
+export const REPEAT_INTERVAL_MIN_S = 10;
+export const REPEAT_INTERVAL_MAX_S = 604_800;

package/dist/core/domain/errors.js

@@ -0,0 +1,57 @@
+export const ExitCode = {
+    Ok: 0,
+    Failure: 1,
+    Usage: 2,
+    Environment: 3,
+    AuthStopped: 4,
+    QuotaStopped: 5,
+    UpdateRequired: 6,
+    Interrupted: 130
+};
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = ExitCode.Failure) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, ExitCode.Usage);
+        this.name = 'UsageError';
+    }
+}
+export class ConfigError extends CliError {
+    constructor(message) {
+        super(message, ExitCode.Environment);
+        this.name = 'ConfigError';
+    }
+}
+export class NewerSchemaError extends ConfigError {
+    constructor(file, found, known) {
+        super(`${file} was created by a newer version of 3minapi (schema ${found}, this CLI knows ${known}). ` +
+            'Update 3minapi.');
+        this.name = 'NewerSchemaError';
+    }
+}
+function stopExitCode(reason) {
+    switch (reason) {
+        case 'quota_exhausted':
+            return ExitCode.QuotaStopped;
+        case 'cli_outdated':
+            return ExitCode.UpdateRequired;
+        default:
+            return ExitCode.AuthStopped;
+    }
+}
+export class StopError extends CliError {
+    reason;
+    resetAt;
+    constructor(reason, message, resetAt) {
+        super(message, stopExitCode(reason));
+        this.name = 'StopError';
+        this.reason = reason;
+        this.resetAt = resetAt;
+    }
+}

package/dist/core/domain/index.js

@@ -0,0 +1,3 @@
+export * from "./constants.js";
+export * from "./contract.js";
+export * from "./errors.js";

package/dist/core/domain/types.js

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

package/dist/core/error-report.js

@@ -0,0 +1,103 @@
+import { ApiError } from "./api.js";
+import { BIN, CliError, ConfigError, ExitCode, StopError, UsageError } from "./domain/index.js";
+const NETWORK_HINT = `Check the network, or run '${BIN} doctor' (it checks the API URL and proxy settings).`;
+export function describeError(err) {
+    if (err instanceof StopError) {
+        return {
+            kind: 'stop',
+            message: err.message,
+            exitCode: err.exitCode,
+            code: err.reason,
+            ...(err.resetAt ? { resetAt: err.resetAt } : {})
+        };
+    }
+    if (err instanceof ApiError) {
+        if (err.status === null) {
+            return {
+                kind: 'network',
+                message: `${err.message}\n${NETWORK_HINT}`,
+                exitCode: err.exitCode
+            };
+        }
+        return {
+            kind: 'server',
+            message: err.message,
+            exitCode: err.exitCode,
+            ...(err.code ? { code: err.code } : {})
+        };
+    }
+    if (err instanceof UsageError)
+        return { kind: 'usage', message: err.message, exitCode: err.exitCode };
+    if (err instanceof ConfigError)
+        return { kind: 'config', message: err.message, exitCode: err.exitCode };
+    if (err instanceof CliError)
+        return { kind: 'failure', message: err.message, exitCode: err.exitCode };
+    const fs = fsFailure(err);
+    if (fs)
+        return fs;
+    const e = err;
+    return {
+        kind: 'bug',
+        message: `unexpected error: ${firstLine(e?.message ?? String(err))}`,
+        exitCode: ExitCode.Failure,
+        stack: e?.stack ?? String(err)
+    };
+}
+const ERRNO = {
+    EACCES: 'permission denied — check the owner and permissions of that folder or file',
+    EPERM: 'operation not permitted — check the permissions, or close a program holding it (antivirus, indexer)',
+    EROFS: 'the file system is read-only — run it in a folder you can write to',
+    ENOSPC: `the disk is full — free some space (logs: logMaxBytes, results: '${BIN} worker results prune', history: '${BIN} tasks prune')`,
+    EDQUOT: 'the disk quota is used up — free some space',
+    EBUSY: 'it is in use by another program — close it and try again',
+    EMFILE: 'too many open files — close some programs and try again',
+    ENFILE: 'too many open files — close some programs and try again',
+    ENOTDIR: 'a part of the path is a file, not a folder — check the path',
+    EISDIR: 'it is a folder, not a file — check the path',
+    ENOENT: 'it does not exist — check the path',
+    EEXIST: 'it already exists — check the path'
+};
+const SQLITE = {
+    5: ['SQLITE_BUSY', 'the database is locked by another program — close it and try again'],
+    8: ['SQLITE_READONLY', 'the database file is read-only — check its permissions'],
+    13: ['SQLITE_FULL', 'the disk is full — free some space'],
+    14: [
+        'SQLITE_CANTOPEN',
+        'the database file cannot be opened — check the folder and its permissions'
+    ]
+};
+function fsFailure(err) {
+    const e = err;
+    if (!e || typeof e !== 'object')
+        return null;
+    if (e.code === 'ERR_SQLITE_ERROR' && typeof e.errcode === 'number') {
+        const known = SQLITE[e.errcode & 0xff];
+        if (!known)
+            return null;
+        return {
+            kind: 'fs',
+            message: `${firstLine(e.message)}: ${known[1]}`,
+            exitCode: ExitCode.Environment,
+            code: known[0]
+        };
+    }
+    if (typeof e.code !== 'string' || typeof e.path !== 'string')
+        return null;
+    const reason = ERRNO[e.code];
+    if (!reason)
+        return null;
+    const action = typeof e.syscall === 'string' ? e.syscall : 'use';
+    return {
+        kind: 'fs',
+        message: `cannot ${action} ${e.path}: ${reason}`,
+        exitCode: ExitCode.Environment,
+        code: e.code
+    };
+}
+function firstLine(text) {
+    return text.split('\n')[0];
+}
+export function errorDocument(report) {
+    const { stack: _stack, ...error } = report;
+    return { error };
+}

package/dist/core/host/detach.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+import { closeSync, openSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ENV, OUT_FILE_MAX_BYTES, SECRET_FILE_MODE } from "../domain/index.js";
+import { ensurePrivateDir } from "../secure-fs.js";
+export function spawnDetached(opts) {
+    ensurePrivateDir(path.dirname(opts.outFile));
+    rotateIfLarge(opts.outFile);
+    const fd = openSync(opts.outFile, 'a', SECRET_FILE_MODE);
+    try {
+        return spawn(process.execPath, [...proxyNodeArgs(), binPath(), ...opts.args], {
+            cwd: opts.cwd,
+            env: { ...opts.env, [ENV.detached]: '1' },
+            detached: true,
+            stdio: ['ignore', fd, fd],
+            windowsHide: true
+        });
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function rotateIfLarge(file) {
+    try {
+        const size = statSync(file, { throwIfNoEntry: false })?.size ?? 0;
+        if (size <= OUT_FILE_MAX_BYTES)
+            return;
+        rmSync(`${file}.1`, { force: true });
+        renameSync(file, `${file}.1`);
+    }
+    catch {
+    }
+}
+function binPath() {
+    return fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../../bin.ts' : '../../bin.js', import.meta.url));
+}
+export function outputTail(file) {
+    try {
+        const text = readFileSync(file, 'utf8').trimEnd().split('\n').slice(-10).join('\n');
+        return text ? `Last output (${file}):\n${text}` : `See ${file}`;
+    }
+    catch {
+        return `See ${file}`;
+    }
+}
+function proxyNodeArgs() {
+    return process.execArgv.filter((a) => a === '--use-env-proxy');
+}

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

@@ -0,0 +1,270 @@
+import { LIVE_CLOSE, LIVE_CONNECT_TIMEOUT_MS, LIVE_PING, LIVE_PING_INTERVAL_MS, LIVE_PONG, LIVE_PONG_TIMEOUT_MS, LIVE_RECONNECT_FIRST_JITTER_MS, LIVE_RECONNECT_MAX_MS, LIVE_RECONNECT_STABLE_MS, LIVE_URL_REFRESH_AFTER_MS } from "../domain/index.js";
+import { stripControl } from "../text.js";
+export const LIVE_TIMING = {
+    pingIntervalMs: LIVE_PING_INTERVAL_MS,
+    pongTimeoutMs: LIVE_PONG_TIMEOUT_MS,
+    connectTimeoutMs: LIVE_CONNECT_TIMEOUT_MS,
+    firstJitterMs: LIVE_RECONNECT_FIRST_JITTER_MS,
+    maxBackoffMs: LIVE_RECONNECT_MAX_MS,
+    stableMs: LIVE_RECONNECT_STABLE_MS,
+    refreshAfterMs: LIVE_URL_REFRESH_AFTER_MS
+};
+const WebSocketWithHeaders = WebSocket;
+export class LiveConnection {
+    opts;
+    timing;
+    now;
+    random;
+    url;
+    ws = null;
+    gen = 0;
+    closed = false;
+    attempt = 0;
+    attempts = 0;
+    openedAt = null;
+    failingSince = null;
+    lastRefreshAt = Number.NEGATIVE_INFINITY;
+    pingTimer = null;
+    pongTimer = null;
+    connectTimer = null;
+    reconnectTimer = null;
+    state = {
+        connected: false,
+        since: null,
+        reconnects: 0,
+        everConnected: false,
+        lastError: null
+    };
+    constructor(opts) {
+        this.opts = opts;
+        this.timing = { ...LIVE_TIMING, ...opts.timing };
+        this.now = opts.now ?? Date.now;
+        this.random = opts.random ?? Math.random;
+        this.url = opts.url;
+    }
+    get connected() {
+        return this.state.connected;
+    }
+    get liveState() {
+        return { ...this.state };
+    }
+    start() {
+        this.connect();
+    }
+    setUrl(url) {
+        if (url === this.url)
+            return;
+        this.url = url;
+        this.opts.logger.info('live url updated');
+    }
+    close() {
+        this.closed = true;
+        this.gen++;
+        this.clearTimers();
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.abandon(1000);
+    }
+    connect() {
+        if (this.closed)
+            return;
+        const gen = ++this.gen;
+        if (this.attempts++ > 0)
+            this.setState({ reconnects: this.state.reconnects + 1 });
+        let ws;
+        try {
+            ws = new WebSocketWithHeaders(this.url, {
+                headers: { authorization: `Bearer ${this.opts.token}` }
+            });
+        }
+        catch (err) {
+            this.opts.logger.warn('cannot open the live connection', { message: err.message });
+            void this.lost('not_opened', 'invalid live url');
+            return;
+        }
+        ws.binaryType = 'arraybuffer';
+        this.ws = ws;
+        let opened = false;
+        this.connectTimer = setTimeout(() => {
+            if (gen !== this.gen || opened)
+                return;
+            this.abandon();
+            void this.lost('not_opened', 'timed out');
+        }, this.timing.connectTimeoutMs);
+        ws.addEventListener('open', () => {
+            if (gen !== this.gen)
+                return;
+            opened = true;
+            this.clearTimer('connectTimer');
+            this.openedAt = this.now();
+            this.failingSince = null;
+            this.setState({
+                connected: true,
+                since: new Date(this.openedAt).toISOString(),
+                everConnected: true,
+                lastError: null
+            });
+            this.opts.logger.info('live connected');
+            this.pingTimer = setInterval(() => this.ping(gen), this.timing.pingIntervalMs);
+            this.pingTimer.unref();
+            this.opts.onOpen();
+        });
+        ws.addEventListener('message', (ev) => {
+            if (gen === this.gen)
+                this.onMessage(ev.data);
+        });
+        ws.addEventListener('error', () => {
+            if (gen === this.gen)
+                this.opts.logger.debug('live socket error');
+        });
+        ws.addEventListener('close', (ev) => {
+            if (gen !== this.gen)
+                return;
+            this.ws = null;
+            if (!opened)
+                return void this.lost('not_opened', null);
+            const reason = stripControl(String(ev.reason ?? '')).slice(0, 123);
+            this.opts.logger.info('live disconnected', { code: ev.code, reason });
+            if (ev.code === LIVE_CLOSE.REPLACED)
+                return void this.lost('replaced', null);
+            if (ev.code === LIVE_CLOSE.CHECK_HOST)
+                return void this.lost('check_host', null);
+            void this.lost('dropped', `closed (${ev.code})`);
+        });
+    }
+    ping(gen) {
+        if (gen !== this.gen || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(LIVE_PING);
+        if (this.pongTimer)
+            return;
+        this.pongTimer = setTimeout(() => {
+            if (gen !== this.gen)
+                return;
+            this.opts.logger.warn('no pong from the live connection; reconnecting');
+            this.abandon();
+            void this.lost('no_pong', null);
+        }, this.timing.pongTimeoutMs);
+        this.pongTimer.unref();
+    }
+    onMessage(data) {
+        if (typeof data !== 'string') {
+            this.opts.logger.debug('ignored a non-text live frame');
+            return;
+        }
+        if (data === LIVE_PONG) {
+            this.clearTimer('pongTimer');
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            this.opts.logger.debug('ignored a live frame that is not JSON');
+            return;
+        }
+        const topic = parsed?.topic;
+        if (typeof parsed !== 'object' || Array.isArray(parsed) || typeof topic !== 'string') {
+            this.opts.logger.debug('ignored a live frame without a topic');
+            return;
+        }
+        this.opts.logger.debug('live signal', { topic: stripControl(topic).slice(0, 32) });
+        this.opts.onSignal(topic);
+    }
+    async lost(kind, detail) {
+        this.clearTimers();
+        const now = this.now();
+        const upFor = this.openedAt === null ? 0 : now - this.openedAt;
+        this.openedAt = null;
+        this.setState({
+            connected: false,
+            since: this.state.connected || this.state.since === null
+                ? new Date(now).toISOString()
+                : this.state.since,
+            lastError: describe(kind, detail)
+        });
+        if (this.closed)
+            return;
+        if (upFor >= this.timing.stableMs && kind !== 'check_host')
+            this.attempt = 0;
+        if (kind === 'not_opened' && this.state.everConnected) {
+            this.failingSince ??= now;
+            if (now - this.failingSince >= this.timing.refreshAfterMs &&
+                now - this.lastRefreshAt >= this.timing.refreshAfterMs) {
+                this.lastRefreshAt = now;
+                await this.call(() => this.opts.onRefreshUrl());
+            }
+        }
+        if (kind === 'check_host')
+            await this.call(() => this.opts.onCheckHost());
+        if (this.closed)
+            return;
+        const delay = kind === 'replaced'
+            ? this.timing.maxBackoffMs
+            : this.random() *
+                Math.min(this.timing.maxBackoffMs, this.timing.firstJitterMs * 2 ** this.attempt);
+        this.attempt++;
+        this.opts.logger.info('live reconnecting', { in_ms: Math.round(delay), kind });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    async call(fn) {
+        try {
+            await fn();
+        }
+        catch (err) {
+            this.opts.logger.warn('live callback failed', { message: err.message });
+        }
+    }
+    abandon(code) {
+        const ws = this.ws;
+        this.ws = null;
+        this.gen++;
+        if (!ws)
+            return;
+        try {
+            ws.close(code);
+        }
+        catch {
+        }
+    }
+    clearTimers() {
+        this.clearTimer('pingTimer');
+        this.clearTimer('pongTimer');
+        this.clearTimer('connectTimer');
+    }
+    clearTimer(name) {
+        const t = this[name];
+        if (!t)
+            return;
+        clearTimeout(t);
+        this[name] = null;
+    }
+    setState(patch) {
+        const next = { ...this.state, ...patch };
+        if (JSON.stringify(next) === JSON.stringify(this.state))
+            return;
+        this.state = next;
+        this.opts.onState?.({ ...next });
+    }
+}
+function describe(kind, detail) {
+    switch (kind) {
+        case 'replaced':
+            return 'replaced by a newer connection for this host (another 3minapi start?)';
+        case 'check_host':
+            return 'closed by the server to check this host';
+        case 'no_pong':
+            return 'no reply to keepalive (connection lost or buffered by a proxy)';
+        case 'not_opened':
+            return detail === 'timed out'
+                ? 'could not connect: timed out'
+                : 'could not connect (network, proxy, firewall or server — the cause is not visible)';
+        case 'dropped':
+            return `connection lost: ${detail ?? 'closed'}`;
+    }
+}