@runinfra/cli 0.1.0

package/dist/downloader.js

@@ -0,0 +1,265 @@
+import { probeArtifact, requestLease } from "./catalog-api.js";
+import { CliError } from "./errors.js";
+import { streamRange, streamWhole } from "./http.js";
+import { leaseChangeReason, leaseExpiredStatus, leaseNeedsRefresh, } from "./lease.js";
+import { readProgress, renderProgress } from "./progress.js";
+import { normalizeRanges, planResume, rangeLength, totalBytes, } from "./range-plan.js";
+import { describeMismatch, sidecarMismatch } from "./sidecar.js";
+import { sleep, unrefTimer } from "./timers.js";
+const CHUNK_ATTEMPTS = 4;
+const MAX_LEASE_REFRESHES = 40;
+const RETRY_BASE_DELAY_MS = 500;
+const PROGRESS_INTERVAL_MS = 500;
+const TRANSFER_IDLE_TIMEOUT_MS = 60_000;
+class LeaseHolder {
+    inputs;
+    lease;
+    refreshes = 0;
+    pending = null;
+    constructor(lease, inputs) {
+        this.inputs = inputs;
+        this.lease = lease;
+    }
+    async url(nowMs = Date.now()) {
+        if (!leaseNeedsRefresh(this.lease, nowMs))
+            return this.lease.url;
+        return (await this.renew()).url;
+    }
+    async refresh() {
+        return (await this.renew()).url;
+    }
+    async renew() {
+        if (this.pending !== null)
+            return await this.pending;
+        this.pending = this.doRenew().finally(() => {
+            this.pending = null;
+        });
+        return await this.pending;
+    }
+    async doRenew() {
+        this.refreshes += 1;
+        if (this.refreshes > MAX_LEASE_REFRESHES) {
+            throw new CliError("server_error", "The download URL had to be renewed too many times.", "Run the same command again to resume from where this left off.");
+        }
+        const lease = await requestLease(this.inputs.endpoints, this.inputs.apiKey, this.inputs.slug, this.inputs.signal);
+        const changed = leaseChangeReason(this.inputs.sidecar, lease);
+        if (changed !== null)
+            throw artifactChanged(this.inputs.slug, changed);
+        const probe = await probeArtifact(lease.url, this.inputs.signal);
+        if (!probe.ok) {
+            throw new CliError("server_error", `The renewed download URL for ${this.inputs.slug} could not be used.`, "Run the same command again to resume.");
+        }
+        const mismatch = sidecarMismatch(this.inputs.sidecar, {
+            slug: this.inputs.slug,
+            packageVersion: lease.packageVersion,
+            sizeBytes: probe.probe.sizeBytes,
+            etag: probe.probe.etag,
+            checksumSha256: lease.checksumSha256,
+        });
+        if (mismatch !== null)
+            throw artifactChanged(this.inputs.slug, describeMismatch(mismatch));
+        this.lease = lease;
+        return lease;
+    }
+}
+function artifactChanged(slug, reason) {
+    return new CliError("artifact_changed", `The download was stopped because ${reason}.`, `Nothing on disk was mixed between versions. Run \`runinfra pull ${slug}\` again to start the new one.`);
+}
+function abortedError() {
+    return new CliError("interrupted", "Download interrupted.", "Run the same command again to resume from the bytes already on disk.");
+}
+export async function runDownload(inputs) {
+    const { sidecar, output } = inputs;
+    const holder = new LeaseHolder(inputs.lease, inputs);
+    const committed = normalizeRanges(sidecar.committedRanges, sidecar.sizeBytes) ?? [];
+    let committedBytes = totalBytes(committed);
+    let sessionBytes = 0;
+    const inFlight = new Map();
+    const startedAtMs = Date.now();
+    const snapshot = () => {
+        let partial = 0;
+        for (const bytes of inFlight.values())
+            partial += bytes;
+        const totals = {
+            totalBytes: sidecar.sizeBytes,
+            completedBytes: Math.min(sidecar.sizeBytes, committedBytes + partial),
+            sessionBytes,
+            elapsedMs: Date.now() - startedAtMs,
+        };
+        output.status(`  ${renderProgress(inputs.label, totals, readProgress(totals))}`);
+    };
+    const ticker = setInterval(snapshot, PROGRESS_INTERVAL_MS);
+    unrefTimer(ticker);
+    let commitChain = Promise.resolve();
+    const commit = async (range) => {
+        commitChain = commitChain.then(async () => {
+            await inputs.handle.datasync();
+            committed.push({ ...range });
+            const merged = normalizeRanges(committed, sidecar.sizeBytes) ?? committed;
+            committed.length = 0;
+            committed.push(...merged);
+            committedBytes = totalBytes(committed);
+            await inputs.onCommit(committed.map((entry) => ({ ...entry })));
+        });
+        await commitChain;
+    };
+    try {
+        if (!inputs.rangesSupported) {
+            await downloadSequentially(inputs, holder, (delta) => {
+                sessionBytes += delta;
+                inFlight.set(0, (inFlight.get(0) ?? 0) + delta);
+            });
+            inFlight.clear();
+            await commit({ start: 0, endInclusive: sidecar.sizeBytes - 1 });
+            snapshot();
+            return { sessionBytes };
+        }
+        const plan = planResume({
+            sizeBytes: sidecar.sizeBytes,
+            committed,
+            concurrency: inputs.concurrency,
+        });
+        const queue = plan.chunks;
+        let next = 0;
+        let failed = false;
+        const worker = async () => {
+            for (;;) {
+                if (failed)
+                    return;
+                if (inputs.signal.aborted)
+                    throw abortedError();
+                const index = next;
+                next += 1;
+                const chunk = queue[index];
+                if (chunk === undefined)
+                    return;
+                await fetchChunk({
+                    chunk,
+                    index,
+                    holder,
+                    inputs,
+                    onBytes: (delta) => {
+                        sessionBytes += delta;
+                        inFlight.set(index, (inFlight.get(index) ?? 0) + delta);
+                    },
+                    onReset: () => {
+                        sessionBytes -= inFlight.get(index) ?? 0;
+                        inFlight.set(index, 0);
+                    },
+                });
+                inFlight.delete(index);
+                await commit(chunk);
+            }
+        };
+        const workers = Array.from({ length: Math.min(inputs.concurrency, Math.max(1, queue.length)) }, () => worker().catch((error) => {
+            failed = true;
+            throw error;
+        }));
+        const settled = await Promise.allSettled(workers);
+        const firstFailure = settled.find((result) => result.status === "rejected");
+        if (firstFailure)
+            throw firstFailure.reason;
+        snapshot();
+        return { sessionBytes };
+    }
+    finally {
+        clearInterval(ticker);
+        await commitChain.catch(() => undefined);
+        output.endStatus();
+    }
+}
+async function fetchChunk(input) {
+    const { chunk, holder, inputs } = input;
+    let lastError = null;
+    for (let attempt = 0; attempt < CHUNK_ATTEMPTS; attempt += 1) {
+        if (inputs.signal.aborted)
+            throw abortedError();
+        input.onReset();
+        let received = 0;
+        try {
+            const url = await holder.url();
+            const result = await streamRange({
+                url,
+                start: chunk.start,
+                endInclusive: chunk.endInclusive,
+                idleTimeoutMs: TRANSFER_IDLE_TIMEOUT_MS,
+                signal: inputs.signal,
+                onChunk: async (buffer) => {
+                    const offset = received;
+                    received += buffer.length;
+                    await writeAt(inputs.handle, buffer, chunk.start + offset);
+                    input.onBytes(buffer.length);
+                },
+            });
+            if (result.status === 206) {
+                if (received !== rangeLength(chunk)) {
+                    lastError = new CliError("network", `The server sent ${received} of ${rangeLength(chunk)} bytes for one chunk.`);
+                }
+                else {
+                    return;
+                }
+            }
+            else if (leaseExpiredStatus(result.status)) {
+                await holder.refresh();
+                attempt -= 1;
+                continue;
+            }
+            else if (result.status === 200) {
+                throw new CliError("ranges_unsupported", "The storage origin stopped honouring byte ranges mid-download.", "Run the same command again; it will fall back to a single stream.");
+            }
+            else {
+                lastError = new CliError("server_error", `Downloading one chunk failed with HTTP ${result.status}.`);
+            }
+        }
+        catch (error) {
+            if (inputs.signal.aborted)
+                throw abortedError();
+            if (error instanceof CliError &&
+                (error.code === "artifact_changed" || error.code === "ranges_unsupported")) {
+                throw error;
+            }
+            lastError = error;
+        }
+        if (attempt < CHUNK_ATTEMPTS - 1) {
+            await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+        }
+    }
+    const detail = lastError instanceof Error ? lastError.message : String(lastError);
+    const code = lastError instanceof CliError && lastError.code !== "network"
+        ? lastError.code
+        : "network";
+    throw new CliError(code, `A chunk of the download failed ${CHUNK_ATTEMPTS} times: ${detail}`, "Run the same command again to resume from the bytes already on disk.");
+}
+async function downloadSequentially(inputs, holder, onBytes) {
+    inputs.output.warn("This storage origin does not support byte ranges, so the download runs as a single stream and cannot be resumed.");
+    let written = 0;
+    const url = await holder.url();
+    const result = await streamWhole({
+        url,
+        idleTimeoutMs: TRANSFER_IDLE_TIMEOUT_MS,
+        signal: inputs.signal,
+        onChunk: async (buffer) => {
+            const offset = written;
+            written += buffer.length;
+            await writeAt(inputs.handle, buffer, offset);
+            onBytes(buffer.length);
+        },
+    });
+    if (result.status !== 200) {
+        throw new CliError("server_error", `The download failed with HTTP ${result.status}.`, "Run the command again.");
+    }
+    if (written !== inputs.sidecar.sizeBytes) {
+        throw new CliError("network", `The download ended early: ${written} of ${inputs.sidecar.sizeBytes} bytes.`, "Run the command again.");
+    }
+    return written;
+}
+async function writeAt(handle, buffer, position) {
+    let offset = 0;
+    while (offset < buffer.length) {
+        const { bytesWritten } = await handle.write(buffer, offset, buffer.length - offset, position + offset);
+        if (bytesWritten <= 0) {
+            throw new CliError("storage_unwritable", "The filesystem stopped accepting writes for this download.", "Check free space and permissions on the destination, then run the command again.");
+        }
+        offset += bytesWritten;
+    }
+}

package/dist/endpoints.js

@@ -0,0 +1,58 @@
+export const DEFAULT_API_BASE = "https://runinfra.ai";
+export const API_BASE_ENV = "RUNINFRA_API_BASE";
+export function resolveApiBase(env) {
+    const raw = env[API_BASE_ENV]?.trim();
+    if (!raw)
+        return { ok: true, base: DEFAULT_API_BASE };
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, message: `${API_BASE_ENV} is not a valid URL: ${raw}` };
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        return {
+            ok: false,
+            message: `${API_BASE_ENV} must be an http or https URL, got ${url.protocol}`,
+        };
+    }
+    if (url.protocol === "http:" && !isLoopbackHostname(url.hostname)) {
+        return {
+            ok: false,
+            message: `${API_BASE_ENV} may only use http:// for a loopback host. ${url.hostname} would send your API key in plaintext.`,
+        };
+    }
+    if (url.search !== "" || url.hash !== "") {
+        return { ok: false, message: `${API_BASE_ENV} must not carry a query or fragment.` };
+    }
+    const base = `${url.origin}${url.pathname}`.replace(/\/+$/u, "");
+    return { ok: true, base };
+}
+function isLoopbackHostname(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "[::1]" ||
+        hostname === "::1");
+}
+export function endpointsFor(base) {
+    return {
+        loopbackInit: `${base}/api/cli/device/loopback-init`,
+        consentUrl: (requestId) => `${base}/cli/authorize?request=${encodeURIComponent(requestId)}`,
+        authorizePage: `${base}/cli/authorize`,
+        token: `${base}/api/cli/token`,
+        deviceInit: `${base}/api/cli/device/init`,
+        devicePoll: `${base}/api/cli/device/poll`,
+        download: (slug) => `${base}/api/catalog/${encodeURIComponent(slug)}/download`,
+    };
+}
+export function sanitizeDeviceLabel(raw) {
+    const cleaned = raw
+        .replace(/[^A-Za-z0-9._~@ -]+/gu, "-")
+        .replace(/\s+/gu, " ")
+        .replace(/-{2,}/gu, "-")
+        .trim()
+        .replace(/^-+|-+$/gu, "")
+        .slice(0, 80);
+    return cleaned.length > 0 ? cleaned : null;
+}

package/dist/env.js

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

package/dist/errors.js

@@ -0,0 +1,54 @@
+export const EXIT_CODES = {
+    usage: 2,
+    unsupported_runtime: 2,
+    not_authenticated: 3,
+    auth_denied: 3,
+    auth_expired: 3,
+    auth_timeout: 3,
+    auth_failed: 3,
+    not_found: 4,
+    not_entitled: 4,
+    artifact_not_ready: 4,
+    network: 5,
+    server_error: 5,
+    rate_limited: 5,
+    checksum_mismatch: 6,
+    artifact_changed: 6,
+    ranges_unsupported: 6,
+    disk_space: 7,
+    storage_unwritable: 7,
+    interrupted: 130,
+};
+export class CliError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint = null) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export function isCliError(value) {
+    return value instanceof CliError;
+}
+export function exitCodeFor(error) {
+    return isCliError(error) ? EXIT_CODES[error.code] : 1;
+}
+export function describeError(error) {
+    if (isCliError(error)) {
+        return { code: error.code, message: error.message, hint: error.hint };
+    }
+    if (error instanceof Error) {
+        return {
+            code: "unexpected",
+            message: error.message || "An unexpected error occurred.",
+            hint: null,
+        };
+    }
+    return {
+        code: "unexpected",
+        message: String(error),
+        hint: null,
+    };
+}

package/dist/help.js

@@ -0,0 +1,47 @@
+import { API_BASE_ENV } from "./endpoints.js";
+import { CONFIG_DIR_ENV } from "./paths.js";
+import { CLI_NAME, CLI_VERSION } from "./version.js";
+export function helpText() {
+    return [
+        `${CLI_NAME} ${CLI_VERSION}`,
+        "",
+        "Sign in from your terminal and pull the optimized model packages your",
+        "workspace owns.",
+        "",
+        "USAGE",
+        `  ${CLI_NAME} <command> [options]`,
+        "",
+        "COMMANDS",
+        "  login [--device]        Connect this terminal by approving it in a browser.",
+        "                          --device prints a code to type on another device,",
+        "                          which is what a headless GPU host needs.",
+        "  logout                  Delete this machine's stored key. To end its access",
+        "                          everywhere, revoke it in Settings, API keys.",
+        "  whoami                  Show the workspace and key this machine has stored,",
+        "                          and when that access expires.",
+        "  pull <slug>             Download a package this workspace owns. Resumable:",
+        "                          run the same command again to continue.",
+        "",
+        "PULL OPTIONS",
+        "  --out DIR               Where to write the file. Defaults to the current",
+        "                          directory.",
+        "  --concurrency N         Parallel connections, 1 to 16. Defaults to 8.",
+        "",
+        "ENVIRONMENT",
+        `  ${API_BASE_ENV}       Point the CLI at another deployment. Plaintext http is`,
+        "                          accepted only for a loopback host.",
+        `  ${CONFIG_DIR_ENV}     Where credentials are stored.`,
+        "",
+        "EXIT CODES",
+        "  0 success",
+        "  2 bad usage or unsupported runtime",
+        "  3 not signed in, denied, or expired",
+        "  4 the workspace does not own it",
+        "  5 network or server failure",
+        "  6 integrity failure (checksum, or the artifact changed mid-download)",
+        "  7 no space, or the destination is not writable",
+        "  130 interrupted",
+        "",
+        "Access can be revoked at any time from Settings, API keys on runinfra.ai.",
+    ].join("\n");
+}

package/dist/http.js

@@ -0,0 +1,204 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { CliError } from "./errors.js";
+import { userAgent } from "./version.js";
+export const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_BODY_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_REDIRECTS = 5;
+function normalizeHeaders(message) {
+    const out = {};
+    for (const [name, value] of Object.entries(message.headers)) {
+        if (value === undefined)
+            continue;
+        out[name.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return out;
+}
+function networkError(url, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    let host = url;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+    }
+    return new CliError("network", `Could not reach ${host}: ${detail}`, "Check your connection or proxy settings, then run the command again.");
+}
+async function dispatch(options) {
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    let currentUrl = options.url;
+    let method = options.method;
+    let body = options.json === undefined ? null : Buffer.from(JSON.stringify(options.json), "utf8");
+    for (let hop = 0; hop <= maxRedirects; hop += 1) {
+        const parsed = new URL(currentUrl);
+        const secure = parsed.protocol === "https:";
+        const send = secure ? httpsRequest : httpRequest;
+        const headers = {
+            accept: "application/json",
+            "user-agent": userAgent(),
+            ...(options.headers ?? {}),
+        };
+        if (body) {
+            headers["content-type"] = "application/json";
+            headers["content-length"] = String(body.length);
+        }
+        const message = await new Promise((resolve, reject) => {
+            const req = send({
+                protocol: parsed.protocol,
+                hostname: parsed.hostname,
+                port: parsed.port,
+                path: `${parsed.pathname}${parsed.search}`,
+                method,
+                headers,
+                ...(options.signal ? { signal: options.signal } : {}),
+            }, resolve);
+            req.setTimeout(options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS, () => {
+                req.destroy(new Error("timed out waiting for the server"));
+            });
+            req.on("error", reject);
+            if (body)
+                req.write(body);
+            req.end();
+        }).catch((cause) => {
+            throw networkError(currentUrl, cause);
+        });
+        const status = message.statusCode ?? 0;
+        const location = message.headers.location;
+        const isRedirect = (status === 301 || status === 302 || status === 303 || status === 307 || status === 308) &&
+            typeof location === "string";
+        if (!isRedirect) {
+            return { message, finalUrl: currentUrl };
+        }
+        message.resume();
+        const next = new URL(location, currentUrl);
+        if (parsed.protocol === "https:" && next.protocol !== "https:") {
+            throw new CliError("network", `${parsed.host} redirected to an insecure URL (${next.protocol}//${next.host}).`, "This is not something the CLI can safely follow. Report it to support.");
+        }
+        if (status === 303 || ((status === 301 || status === 302) && method !== "HEAD")) {
+            method = "GET";
+            body = null;
+        }
+        currentUrl = next.toString();
+    }
+    throw new CliError("network", `Too many redirects while requesting ${options.url}.`, null);
+}
+async function bufferBody(message, url, maxBytes) {
+    return await new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        message.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                message.destroy();
+                reject(new CliError("server_error", `${url} returned an unexpectedly large response.`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        message.on("end", () => resolve(Buffer.concat(chunks)));
+        message.on("error", (cause) => reject(networkError(url, cause)));
+    });
+}
+export async function requestRaw(options) {
+    const { message, finalUrl } = await dispatch(options);
+    const body = await bufferBody(message, finalUrl, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES);
+    return { status: message.statusCode ?? 0, headers: normalizeHeaders(message), body };
+}
+export async function requestJson(options) {
+    const raw = await requestRaw(options);
+    if (raw.body.length === 0) {
+        return { status: raw.status, headers: raw.headers, body: null };
+    }
+    try {
+        return {
+            status: raw.status,
+            headers: raw.headers,
+            body: JSON.parse(raw.body.toString("utf8")),
+        };
+    }
+    catch {
+        return { status: raw.status, headers: raw.headers, body: null };
+    }
+}
+export async function headResource(url, options = {}) {
+    const { message } = await dispatch({
+        method: "HEAD",
+        url,
+        ...(options.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: options.idleTimeoutMs }),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    message.resume();
+    return { status: message.statusCode ?? 0, headers: normalizeHeaders(message) };
+}
+export async function streamRange(request) {
+    const { message, finalUrl } = await dispatch({
+        method: "GET",
+        url: request.url,
+        headers: { range: `bytes=${request.start}-${request.endInclusive}` },
+        ...(request.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: request.idleTimeoutMs }),
+        ...(request.signal ? { signal: request.signal } : {}),
+    });
+    const status = message.statusCode ?? 0;
+    const headers = normalizeHeaders(message);
+    if (status !== 206) {
+        await drain(message);
+        return { status, headers, bytes: 0 };
+    }
+    const bytes = await consumeBody(message, finalUrl, request.onChunk);
+    return { status, headers, bytes };
+}
+export async function streamWhole(request) {
+    const { message, finalUrl } = await dispatch({
+        method: "GET",
+        url: request.url,
+        ...(request.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: request.idleTimeoutMs }),
+        ...(request.signal ? { signal: request.signal } : {}),
+    });
+    const status = message.statusCode ?? 0;
+    const headers = normalizeHeaders(message);
+    if (status !== 200) {
+        await drain(message);
+        return { status, headers, bytes: 0 };
+    }
+    const bytes = await consumeBody(message, finalUrl, request.onChunk);
+    return { status, headers, bytes };
+}
+async function drain(message) {
+    message.resume();
+    await new Promise((resolve) => {
+        message.on("end", resolve);
+        message.on("close", resolve);
+        message.on("error", () => resolve());
+    });
+}
+async function consumeBody(message, finalUrl, onChunk) {
+    let bytes = 0;
+    await new Promise((resolve, reject) => {
+        let failed = false;
+        let pendingWrite = Promise.resolve();
+        const fail = (cause) => {
+            if (failed)
+                return;
+            failed = true;
+            message.destroy();
+            reject(cause instanceof CliError ? cause : networkError(finalUrl, cause));
+        };
+        message.on("data", (chunk) => {
+            bytes += chunk.length;
+            const outcome = onChunk(chunk);
+            if (outcome instanceof Promise) {
+                message.pause();
+                pendingWrite = outcome;
+                outcome.then(() => message.resume(), (cause) => fail(cause));
+            }
+        });
+        message.on("end", () => {
+            pendingWrite.then(() => {
+                if (!failed)
+                    resolve();
+            }, fail);
+        });
+        message.on("error", fail);
+    });
+    return bytes;
+}