@3minapi/cli 0.0.0-stage → 0.22.1

package/dist/core/host/runner-lock.js

@@ -0,0 +1,245 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { uptime } from 'node:os';
+import path from 'node:path';
+import { BIN, CliError, HEARTBEAT_INTERVAL_MS, HEARTBEAT_STALE_MS, RUNNER_LOCK_FILE, RUNNER_DELETED_FILE, RUNNER_RELOADED_FILE, RUNNER_RELOAD_FILE, RUNNER_STOP_FILE, SECRET_FILE_MODE } from "../domain/index.js";
+import { ensurePrivateDir, writeSecretFile } from "../secure-fs.js";
+import { sleep } from "../time.js";
+const STARTING_GRACE_MS = 10_000;
+const BOOT_TOLERANCE_MS = 60_000;
+export function bootTime(now = Date.now()) {
+    return now - uptime() * 1000;
+}
+export function runnerMode(info) {
+    return info.mode ?? 'poll';
+}
+export function lockPath(dataDir) {
+    return path.join(dataDir, RUNNER_LOCK_FILE);
+}
+export function stopPath(dataDir) {
+    return path.join(dataDir, RUNNER_STOP_FILE);
+}
+function reloadPath(dataDir) {
+    return path.join(dataDir, RUNNER_RELOAD_FILE);
+}
+function reloadedPath(dataDir) {
+    return path.join(dataDir, RUNNER_RELOADED_FILE);
+}
+function deletedPath(dataDir) {
+    return path.join(dataDir, RUNNER_DELETED_FILE);
+}
+function readDeleted(file) {
+    try {
+        const v = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof v?.nonce === 'string' && Array.isArray(v.names) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+export function readRunner(dataDir) {
+    return readLockFile(lockPath(dataDir));
+}
+export function readLockFile(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { state: 'stopped' };
+        throw err;
+    }
+    if (text.trim() === '') {
+        const age = Date.now() - statSync(file, { throwIfNoEntry: false }).mtimeMs;
+        return age < STARTING_GRACE_MS ? { state: 'starting' } : { state: 'stopped' };
+    }
+    let info;
+    try {
+        info = JSON.parse(text);
+    }
+    catch {
+        return { state: 'stopped' };
+    }
+    if (!Number.isInteger(info.pid) || !isAlive(info.pid))
+        return { state: 'stopped' };
+    if (!Number.isFinite(info.startedAt) || info.startedAt < bootTime() - BOOT_TOLERANCE_MS) {
+        return { state: 'stopped' };
+    }
+    return { state: 'running', info };
+}
+export function claimLockFile(file, info, busy) {
+    ensurePrivateDir(path.dirname(file));
+    for (let attempt = 0;; attempt++) {
+        try {
+            writeFileSync(file, '', { flag: 'wx', mode: SECRET_FILE_MODE });
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST' || attempt > 0)
+                throw busy(err);
+            if (readLockFile(file).state !== 'stopped')
+                throw busy(err);
+            rmSync(file, { force: true });
+        }
+    }
+    writeFileSync(file, JSON.stringify(info), { mode: SECRET_FILE_MODE });
+}
+export function releaseLockFile(file, nonce) {
+    try {
+        const current = JSON.parse(readFileSync(file, 'utf8'));
+        if (current.nonce === nonce)
+            rmSync(file, { force: true });
+    }
+    catch {
+    }
+}
+export function touchLockFile(file) {
+    try {
+        const now = new Date();
+        utimesSync(file, now, now);
+    }
+    catch {
+    }
+}
+export function heartbeatStopped(file, info, now = Date.now()) {
+    if (info.heartbeat !== true)
+        return false;
+    const stat = statSync(file, { throwIfNoEntry: false });
+    return stat !== undefined && now - stat.mtimeMs > HEARTBEAT_STALE_MS;
+}
+export function heartbeater(file) {
+    let last = Date.now();
+    return () => {
+        const now = Date.now();
+        if (now - last < HEARTBEAT_INTERVAL_MS)
+            return;
+        last = now;
+        touchLockFile(file);
+    };
+}
+export function stopFileMatches(file, nonce) {
+    try {
+        return readFileSync(file, 'utf8').trim() === nonce;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readSettled(read) {
+    const current = read();
+    if (current.state !== 'starting')
+        return current;
+    await sleep(2_000);
+    return read();
+}
+export function acquireRunnerLock(dataDir, fields, now) {
+    const file = lockPath(dataDir);
+    const info = {
+        pid: process.pid,
+        nonce: randomBytes(8).toString('hex'),
+        startedAt: now,
+        heartbeat: true,
+        ...fields
+    };
+    claimLockFile(file, info, (cause) => alreadyRunning(dataDir, cause));
+    const beat = heartbeater(file);
+    rmSync(stopPath(dataDir), { force: true });
+    rmSync(reloadPath(dataDir), { force: true });
+    rmSync(reloadedPath(dataDir), { force: true });
+    rmSync(deletedPath(dataDir), { force: true });
+    let released = false;
+    return {
+        info,
+        stopRequested() {
+            return stopFileMatches(stopPath(dataDir), info.nonce);
+        },
+        heartbeat: beat,
+        takeReload() {
+            let text;
+            try {
+                text = readFileSync(reloadPath(dataDir), 'utf8');
+            }
+            catch {
+                return false;
+            }
+            rmSync(reloadPath(dataDir), { force: true });
+            return text.trim() === info.nonce;
+        },
+        takeDeleted() {
+            if (!existsSync(deletedPath(dataDir)))
+                return [];
+            const taken = `${deletedPath(dataDir)}.${randomBytes(6).toString('hex')}.taking`;
+            try {
+                renameSync(deletedPath(dataDir), taken);
+            }
+            catch {
+                return [];
+            }
+            const record = readDeleted(taken);
+            rmSync(taken, { force: true });
+            return record?.nonce === info.nonce ? record.names.filter((n) => typeof n === 'string') : [];
+        },
+        writeReload(record) {
+            writeFileSync(reloadedPath(dataDir), JSON.stringify({ nonce: info.nonce, ...record }), {
+                mode: SECRET_FILE_MODE
+            });
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            releaseLockFile(file, info.nonce);
+            rmSync(stopPath(dataDir), { force: true });
+            rmSync(reloadPath(dataDir), { force: true });
+            rmSync(deletedPath(dataDir), { force: true });
+        }
+    };
+}
+export function requestReload(dataDir, info, now = Date.now()) {
+    writeFileSync(reloadPath(dataDir), info.nonce, { mode: SECRET_FILE_MODE });
+    return now;
+}
+export function notifyDeleted(dataDir, info, names) {
+    const prev = readDeleted(deletedPath(dataDir));
+    const merged = new Set(prev?.nonce === info.nonce ? prev.names : []);
+    for (const n of names)
+        merged.add(n);
+    writeSecretFile(deletedPath(dataDir), JSON.stringify({ nonce: info.nonce, names: [...merged] }));
+}
+export function readReload(dataDir, info) {
+    try {
+        const record = JSON.parse(readFileSync(reloadedPath(dataDir), 'utf8'));
+        return record.nonce === info.nonce ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readRunnerSettled(dataDir) {
+    return readSettled(() => readRunner(dataDir));
+}
+export function requestStop(dataDir, info) {
+    writeFileSync(stopPath(dataDir), info.nonce, { mode: SECRET_FILE_MODE });
+}
+function alreadyRunning(dataDir, cause) {
+    const current = readRunner(dataDir);
+    if (current.state === 'running') {
+        const where = current.info.detached ? 'in the background' : 'in another terminal';
+        return new CliError(`3minapi is already running ${where} (pid ${current.info.pid}). Only one can run per host.\n` +
+            `Stop it with '${BIN} stop' first.`);
+    }
+    if (current.state === 'starting') {
+        return new CliError(`another '${BIN} start' is starting right now. Check with '${BIN} status'.`);
+    }
+    return new CliError(`cannot create ${lockPath(dataDir)}: ${cause.message}`);
+}

package/dist/core/host/session.js

@@ -0,0 +1,84 @@
+import { ControlDb } from "../control-db.js";
+import { Logger, pruneLogs } from "../logger.js";
+import { updateCommand, updateNote } from "../update-notice.js";
+export function openSession(ctx) {
+    const config = ctx.loadConfig();
+    const db = ControlDb.open(ctx.dirs.data);
+    try {
+        const { logRetentionDays, logMaxBytes } = config.values;
+        const logger = new Logger({
+            dir: ctx.dirs.logs,
+            now: ctx.now,
+            onMaintenance(now) {
+                pruneLogs({
+                    dir: ctx.dirs.logs,
+                    now,
+                    retentionDays: logRetentionDays,
+                    maxBytes: logMaxBytes
+                });
+            },
+            onError: (message) => ctx.out.warn(message)
+        });
+        return { config, out: ctx.out, db, logger, close: () => db.close() };
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
+}
+export function recordStop(session, err, now) {
+    try {
+        session.db.recordStop(err.reason, now, err.resetAt);
+    }
+    catch (e) {
+        session.out.warn(`could not record the stop in ${session.db.file}: ${e.message}`);
+    }
+    session.logger.warn('stopped all API calls', { reason: err.reason, message: err.message });
+}
+export function clearStop(session) {
+    try {
+        session.db.clearStop();
+    }
+    catch (e) {
+        session.out.warn(`could not clear the previous stop record in ${session.db.file}: ${e.message}`);
+    }
+}
+export function recordEnd(session, reason, deletedWorkers, now) {
+    try {
+        session.db.recordEnd(reason, now, deletedWorkers);
+    }
+    catch (e) {
+        session.out.warn(`could not record why it ended in ${session.db.file}: ${e.message}`);
+    }
+    session.logger.warn('runner ended: no active workers', { deleted_workers: deletedWorkers });
+}
+export function clearRunnerRecords(session) {
+    clearStop(session);
+    try {
+        session.db.clearEnd();
+    }
+    catch (e) {
+        session.out.warn(`could not clear the previous end record in ${session.db.file}: ${e.message}`);
+    }
+}
+export function rememberQuota(session, quota, now) {
+    if (!quota)
+        return;
+    try {
+        session.db.recordQuota(quota, now);
+    }
+    catch {
+    }
+}
+export function stopHint(reason) {
+    switch (reason) {
+        case 'host_token_invalid':
+            return "The host token was revoked or the host was deleted. Issue a new token on the dashboard and run '3minapi login'.";
+        case 'no_subscription':
+            return 'There is no active subscription for this account. Subscribe on the dashboard, then run the command again.';
+        case 'quota_exhausted':
+            return 'All API calls are stopped. After the quota resets or the plan is upgraded, run the command again.';
+        case 'cli_outdated':
+            return `All API calls are stopped until this CLI is updated. Run: ${updateCommand()}\n${updateNote(null)}`;
+    }
+}

package/dist/core/host/usage.js

@@ -0,0 +1,20 @@
+import { listAllLogFiles } from "../logger.js";
+export function hostUsage(db, logsDir) {
+    let controlDb = null;
+    try {
+        const { total, unfinished } = db.taskCounts();
+        controlDb = { file: db.file, bytes: db.fileBytes(), tasks: total, unfinished };
+    }
+    catch {
+    }
+    let files = [];
+    try {
+        files = listAllLogFiles(logsDir);
+    }
+    catch {
+    }
+    return {
+        controlDb,
+        logs: { dir: logsDir, bytes: files.reduce((n, f) => n + f.size, 0), files: files.length }
+    };
+}

package/dist/core/log-read.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { listChannelFiles } from "./logger.js";
+export function tailLines(dir, count) {
+    const collected = [];
+    for (const f of listChannelFiles(dir).reverse()) {
+        const text = readIfExists(f.file);
+        if (text === null)
+            continue;
+        const lines = text.split('\n').filter((l) => l !== '');
+        collected.unshift(...lines);
+        if (collected.length >= count)
+            break;
+    }
+    return collected.slice(-count);
+}
+export function findLastRecord(dir, match, opts) {
+    let scanned = 0;
+    for (const f of listChannelFiles(dir).reverse()) {
+        if (scanned >= opts.maxBytes)
+            return null;
+        const text = readIfExists(f.file);
+        if (text === null)
+            continue;
+        scanned += f.size;
+        const lines = text.split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (opts.contains !== undefined && !lines[i].includes(opts.contains))
+                continue;
+            const record = parseRecord(lines[i]);
+            if (record && match(record))
+                return record;
+        }
+    }
+    return null;
+}
+export function parseRecord(line) {
+    if (line === '')
+        return null;
+    try {
+        const record = JSON.parse(line);
+        return record !== null && typeof record === 'object' && typeof record.timestamp === 'string'
+            ? record
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readIfExists(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export { stripControl } from "./text.js";

package/dist/core/logger.js

@@ -0,0 +1,206 @@
+import { appendFileSync, readdirSync, rmdirSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { APP_LOG_DIR, LOG_FILE_EXTENSION, LOG_FILE_MAX_BYTES, LOG_STRING_MAX_CHARS, SECRET_FILE_MODE, WORKER_LOG_DIR } from "./domain/index.js";
+import { redact, redactAndTruncate } from "./redact.js";
+import { ensurePrivateDir } from "./secure-fs.js";
+import { daysToMs, toIsoUtc, utcDate } from "./time.js";
+const LOG_FILE = /^(\d{4}-\d{2}-\d{2})(?:\.(\d+))?\.jsonl$/;
+export function channelDir(logsDir, worker) {
+    return worker === null
+        ? path.join(logsDir, APP_LOG_DIR)
+        : path.join(logsDir, WORKER_LOG_DIR, worker);
+}
+export class Logger {
+    opts;
+    fileMaxBytes;
+    current = new Map();
+    lastMaintenanceDate = null;
+    reported = new Set();
+    constructor(opts) {
+        this.opts = opts;
+        this.fileMaxBytes = opts.fileMaxBytes ?? LOG_FILE_MAX_BYTES;
+        this.maintain(opts.now());
+    }
+    debug(body, attributes) {
+        this.write(null, 'debug', body, attributes);
+    }
+    info(body, attributes) {
+        this.write(null, 'info', body, attributes);
+    }
+    warn(body, attributes) {
+        this.write(null, 'warn', body, attributes);
+    }
+    error(body, attributes) {
+        this.write(null, 'error', body, attributes);
+    }
+    worker(name, level, body, attributes) {
+        this.write(name, level, body, attributes);
+    }
+    write(channel, level, body, attributes) {
+        const now = this.opts.now();
+        this.maintain(now);
+        const record = {
+            timestamp: toIsoUtc(now),
+            severity_text: level,
+            body: redactAndTruncate(body, LOG_STRING_MAX_CHARS)
+        };
+        if (attributes && Object.keys(attributes).length > 0) {
+            record.attributes = truncateStrings(redact(attributes));
+        }
+        const line = JSON.stringify(record) + '\n';
+        try {
+            const { file, rotated } = this.fileFor(channel, utcDate(now), Buffer.byteLength(line));
+            appendFileSync(file, line, { mode: SECRET_FILE_MODE });
+            if (rotated)
+                this.maintain(now, true);
+        }
+        catch (err) {
+            this.report('write', `could not write to the log in ${this.opts.dir}: ${message(err)}`);
+        }
+    }
+    fileFor(channel, date, bytes) {
+        const dir = channelDir(this.opts.dir, channel);
+        const key = channel ?? '';
+        let cur = this.current.get(key);
+        if (!cur || cur.date !== date) {
+            ensurePrivateDir(dir);
+            const latest = listChannelFiles(dir)
+                .filter((f) => f.date === date)
+                .at(-1);
+            cur = { date, index: latest?.index ?? 0, size: latest?.size ?? 0 };
+            this.current.set(key, cur);
+        }
+        let rotated = false;
+        if (cur.size > 0 && cur.size + bytes > this.fileMaxBytes) {
+            cur.index++;
+            cur.size = 0;
+            rotated = true;
+        }
+        cur.size += bytes;
+        return { file: path.join(dir, fileName(date, cur.index)), rotated };
+    }
+    maintain(now, force = false) {
+        const date = utcDate(now);
+        if (!force && date === this.lastMaintenanceDate)
+            return;
+        this.lastMaintenanceDate = date;
+        try {
+            this.opts.onMaintenance?.(now);
+        }
+        catch (err) {
+            this.report('maintenance', `log cleanup failed in ${this.opts.dir}: ${message(err)}`);
+        }
+    }
+    report(kind, text) {
+        if (this.reported.has(kind))
+            return;
+        this.reported.add(kind);
+        this.opts.onError?.(text);
+    }
+}
+export function fileName(date, index) {
+    return index === 0 ? `${date}${LOG_FILE_EXTENSION}` : `${date}.${index}${LOG_FILE_EXTENSION}`;
+}
+export function listChannelFiles(dir) {
+    const files = [];
+    for (const name of readdirOrEmpty(dir)) {
+        const m = LOG_FILE.exec(name);
+        if (!m)
+            continue;
+        const file = path.join(dir, name);
+        const st = statSync(file, { throwIfNoEntry: false });
+        if (!st?.isFile())
+            continue;
+        files.push({ file, dir, date: m[1], index: m[2] ? Number(m[2]) : 0, size: st.size });
+    }
+    return files.sort((a, b) => (a.date === b.date ? a.index - b.index : a.date < b.date ? -1 : 1));
+}
+export function listAllLogFiles(logsDir) {
+    const dirs = [channelDir(logsDir, null)];
+    const workersRoot = path.join(logsDir, WORKER_LOG_DIR);
+    for (const entry of readdirOrEmpty(workersRoot, true)) {
+        if (entry.isDirectory())
+            dirs.push(path.join(workersRoot, entry.name));
+    }
+    return dirs.flatMap(listChannelFiles);
+}
+export function pruneLogs({ dir, now, retentionDays, maxBytes }) {
+    const deleted = [];
+    const cutoffDate = utcDate(now - daysToMs(retentionDays));
+    const today = utcDate(now);
+    let files = listAllLogFiles(dir);
+    for (const f of files) {
+        if (f.date < cutoffDate)
+            remove(f, deleted);
+    }
+    files = files.filter((f) => f.date >= cutoffDate);
+    const active = new Set();
+    const byChannel = new Map();
+    for (const f of files)
+        if (f.date === today)
+            byChannel.set(f.dir, f);
+    for (const f of byChannel.values())
+        active.add(f.file);
+    let total = files.reduce((sum, f) => sum + f.size, 0);
+    const oldestFirst = [...files].sort((a, b) => a.date === b.date ? a.index - b.index : a.date < b.date ? -1 : 1);
+    for (const f of oldestFirst) {
+        if (total <= maxBytes)
+            break;
+        if (active.has(f.file))
+            continue;
+        remove(f, deleted);
+        total -= f.size;
+    }
+    removeEmptyWorkerDirs(dir);
+    return deleted;
+}
+function remove(f, deleted) {
+    rmSync(f.file, { force: true });
+    deleted.push(f.file);
+}
+function removeEmptyWorkerDirs(logsDir) {
+    const root = path.join(logsDir, WORKER_LOG_DIR);
+    for (const entry of readdirOrEmpty(root, true)) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        if (readdirOrEmpty(dir).length > 0)
+            continue;
+        try {
+            rmdirSync(dir);
+        }
+        catch (err) {
+            if (!['ENOTEMPTY', 'ENOENT', 'EEXIST'].includes(errno(err)))
+                throw err;
+        }
+    }
+}
+function readdirOrEmpty(dir, withFileTypes) {
+    try {
+        return withFileTypes ? readdirSync(dir, { withFileTypes: true }) : readdirSync(dir);
+    }
+    catch (err) {
+        if (errno(err) === 'ENOENT' || errno(err) === 'ENOTDIR')
+            return [];
+        throw err;
+    }
+}
+function errno(err) {
+    return err?.code ?? '';
+}
+function message(err) {
+    return err?.message ?? String(err);
+}
+function truncateStrings(value) {
+    if (typeof value === 'string') {
+        return value.length > LOG_STRING_MAX_CHARS
+            ? value.slice(0, LOG_STRING_MAX_CHARS - 1) + '…'
+            : value;
+    }
+    if (Array.isArray(value))
+        return value.map(truncateStrings);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, truncateStrings(v)]));
+    }
+    return value;
+}

package/dist/core/names.js

@@ -0,0 +1,27 @@
+import { PULL_WORKER_NAME, RESERVED_NAME_PREFIX, UsageError, WINDOWS_RESERVED_NAME, isReservedWorkerName } from "./domain/index.js";
+export function checkWorkerName(name) {
+    if (!PULL_WORKER_NAME.test(name)) {
+        return {
+            ok: false,
+            reason: 'use 1-50 characters of lowercase letters, digits, "_" or "-"'
+        };
+    }
+    if (WINDOWS_RESERVED_NAME.test(name)) {
+        return { ok: false, reason: `"${name}" is a reserved device name on Windows` };
+    }
+    if (isReservedWorkerName(name)) {
+        return {
+            ok: false,
+            reason: `names starting with "${RESERVED_NAME_PREFIX}" are reserved for built-in workers`
+        };
+    }
+    return { ok: true };
+}
+export function invalidNameMessage(name, reason) {
+    return `invalid worker name "${name}": ${reason}`;
+}
+export function assertWorkerName(name) {
+    const check = checkWorkerName(name);
+    if (!check.ok)
+        throw new UsageError(invalidNameMessage(name, check.reason));
+}

package/dist/core/network.js

@@ -0,0 +1,10 @@
+import { getDefaultAutoSelectFamilyAttemptTimeout, setDefaultAutoSelectFamilyAttemptTimeout } from 'node:net';
+import { NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS } from "./domain/constants.js";
+const FLAG = '--network-family-autoselection-attempt-timeout';
+export function raiseConnectAttemptTimeout({ execArgv, nodeOptions }, target = NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS) {
+    const userSet = execArgv.some((a) => a.startsWith(FLAG)) || (nodeOptions ?? '').includes(FLAG);
+    if (!userSet && getDefaultAutoSelectFamilyAttemptTimeout() < target) {
+        setDefaultAutoSelectFamilyAttemptTimeout(target);
+    }
+    return getDefaultAutoSelectFamilyAttemptTimeout();
+}

package/dist/core/open-browser.js

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+export function openBrowser(url, platform) {
+    const [command, args] = platform === 'darwin'
+        ? ['open', [url]]
+        : platform === 'win32'
+            ?
+                ['cmd', ['/c', 'start', '""', `"${url}"`]]
+            : ['xdg-open', [url]];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, {
+                detached: true,
+                stdio: 'ignore',
+                windowsVerbatimArguments: platform === 'win32'
+            });
+            child.once('error', () => resolve(false));
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}