@astralyn/sash 0.1.0

package/dist/http.js

@@ -0,0 +1,282 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { Agent, EnvHttpProxyAgent, interceptors, request } from "undici";
+export const USER_AGENT = "sash-cli (https://github.com/ming-kang/Sash)";
+export const ERROR_BODY_LIMIT = 32 * 1024;
+let baseProxyDispatcher;
+let redirectProxyDispatcher;
+let baseDirectDispatcher;
+let redirectDirectDispatcher;
+function getBaseProxyDispatcher() {
+    if (!baseProxyDispatcher) {
+        const allProxyRaw = process.env.ALL_PROXY ?? process.env.all_proxy;
+        const allProxy = allProxyRaw && /^https?:\/\//i.test(allProxyRaw) ? allProxyRaw : undefined;
+        const httpProxy = process.env.HTTP_PROXY ?? process.env.http_proxy ?? allProxy;
+        const httpsProxy = process.env.HTTPS_PROXY ?? process.env.https_proxy ?? allProxy;
+        baseProxyDispatcher = new EnvHttpProxyAgent({
+            ...(httpProxy ? { httpProxy } : {}),
+            ...(httpsProxy ? { httpsProxy } : {}),
+        });
+    }
+    return baseProxyDispatcher;
+}
+function getBaseDirectDispatcher() {
+    if (!baseDirectDispatcher)
+        baseDirectDispatcher = new Agent();
+    return baseDirectDispatcher;
+}
+export function proxyAwareDispatcher() {
+    return getBaseProxyDispatcher();
+}
+export function directDispatcherForLoopback() {
+    return getBaseDirectDispatcher();
+}
+function pickDispatcher(opts) {
+    const base = opts.direct ? getBaseDirectDispatcher() : getBaseProxyDispatcher();
+    if (opts.manualRedirect)
+        return base;
+    if (opts.direct) {
+        if (!redirectDirectDispatcher) {
+            redirectDirectDispatcher = base.compose(interceptors.redirect({ maxRedirections: 5 }));
+        }
+        return redirectDirectDispatcher;
+    }
+    if (!redirectProxyDispatcher) {
+        redirectProxyDispatcher = base.compose(interceptors.redirect({ maxRedirections: 5 }));
+    }
+    return redirectProxyDispatcher;
+}
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const RETRYABLE_METHODS = new Set(["GET", "HEAD"]);
+function sleep(ms, signal) {
+    if (signal.aborted) {
+        return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error("HTTP request aborted"));
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            reject(signal.reason instanceof Error ? signal.reason : new Error("HTTP request aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function positiveTimeout(value, fallback, name) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return resolved;
+}
+function defaultAttempts(method) {
+    return RETRYABLE_METHODS.has(method.toUpperCase()) ? 4 : 1;
+}
+export async function fetchWithRetry(url, opts = {}) {
+    const method = (opts.method ?? "GET").toUpperCase();
+    const attempts = opts.attempts ?? defaultAttempts(method);
+    if (!Number.isSafeInteger(attempts) || attempts < 1) {
+        throw new Error("attempts must be a positive integer");
+    }
+    const headersTimeoutMs = positiveTimeout(opts.headersTimeoutMs, 30_000, "headersTimeoutMs");
+    const bodyInactivityTimeoutMs = positiveTimeout(opts.bodyInactivityTimeoutMs, 30_000, "bodyInactivityTimeoutMs");
+    const deadlineMs = positiveTimeout(opts.deadlineMs, 60_000, "deadlineMs");
+    const deadline = new AbortController();
+    const deadlineTimer = setTimeout(() => {
+        deadline.abort(new Error(`HTTP request deadline exceeded after ${deadlineMs}ms`));
+    }, deadlineMs);
+    let settled = false;
+    let responseReturned = false;
+    const clearDeadline = () => {
+        if (!settled) {
+            settled = true;
+            clearTimeout(deadlineTimer);
+        }
+    };
+    let lastErr;
+    try {
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                const res = await request(url, {
+                    method: method,
+                    headers: { "user-agent": USER_AGENT, ...opts.headers },
+                    body: opts.body,
+                    headersTimeout: headersTimeoutMs,
+                    bodyTimeout: bodyInactivityTimeoutMs,
+                    signal: deadline.signal,
+                    dispatcher: pickDispatcher(opts),
+                });
+                if (RETRYABLE_STATUS.has(res.statusCode) && attempt < attempts) {
+                    await res.body.dump();
+                    throw new Error(`HTTP ${res.statusCode}`);
+                }
+                const body = res.body;
+                let claimed = false;
+                const claimBody = () => {
+                    if (claimed)
+                        throw new Error("Response body has already been consumed or discarded");
+                    claimed = true;
+                };
+                const consume = async (maxBytes) => {
+                    claimBody();
+                    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+                        body.destroy();
+                        clearDeadline();
+                        throw new Error("maxBytes must be a non-negative safe integer");
+                    }
+                    const chunks = [];
+                    let total = 0;
+                    try {
+                        for await (const chunk of body) {
+                            const data = Buffer.from(chunk);
+                            total += data.length;
+                            if (total > maxBytes) {
+                                body.destroy();
+                                throw new Error(`Response body exceeds ${maxBytes} byte limit`);
+                            }
+                            chunks.push(data);
+                        }
+                        return Buffer.concat(chunks, total);
+                    }
+                    finally {
+                        clearDeadline();
+                    }
+                };
+                responseReturned = true;
+                return {
+                    statusCode: res.statusCode,
+                    headers: res.headers,
+                    text: async (maxBytes) => (await consume(maxBytes)).toString("utf8"),
+                    buffer: consume,
+                    discard: async () => {
+                        claimBody();
+                        try {
+                            await body.dump();
+                        }
+                        finally {
+                            clearDeadline();
+                        }
+                    },
+                };
+            }
+            catch (err) {
+                lastErr = err;
+                if (deadline.signal.aborted || attempt === attempts)
+                    break;
+                await sleep(Math.min(4_000, 300 * 2 ** (attempt - 1)) + Math.random() * 200, deadline.signal);
+                if (deadline.signal.aborted)
+                    break;
+            }
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    finally {
+        if (!responseReturned)
+            clearDeadline();
+    }
+}
+function abortResponseBody(body) {
+    body.on("error", () => undefined);
+    body.destroy();
+}
+function validateRedirectTarget(location, currentUrl, allowedHosts, requireHttps = false) {
+    const target = new URL(location, currentUrl);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+        throw new Error(`Refusing redirect to non-http(s) URL: ${target.href}`);
+    }
+    if (requireHttps && target.protocol !== "https:") {
+        throw new Error(`Refusing non-HTTPS download URL: ${target.href}`);
+    }
+    if (!allowedHosts.has(target.hostname.toLowerCase())) {
+        throw new Error(`Refusing redirect to untrusted host: ${target.hostname}`);
+    }
+    return target.href;
+}
+export async function downloadToFile(url, dest, opts) {
+    const stallMs = positiveTimeout(opts.stallMs, 60_000, "stallMs");
+    const deadlineMs = positiveTimeout(opts.deadlineMs, 15 * 60_000, "deadlineMs");
+    const maxRedirects = 5;
+    const deadline = new AbortController();
+    const deadlineTimer = setTimeout(() => {
+        deadline.abort(new Error(`Download deadline exceeded after ${deadlineMs}ms`));
+    }, deadlineMs);
+    const dispatcher = pickDispatcher({ direct: false, manualRedirect: true });
+    let outputStarted = false;
+    let res;
+    try {
+        let currentUrl = validateRedirectTarget(url, url, opts.allowedHosts, opts.requireHttps);
+        let hops = 0;
+        for (;;) {
+            res = await request(currentUrl, {
+                method: "GET",
+                headers: { "user-agent": USER_AGENT, ...opts.headers },
+                headersTimeout: 30_000,
+                bodyTimeout: stallMs,
+                signal: deadline.signal,
+                dispatcher,
+            });
+            const isRedirect = res.statusCode >= 300 && res.statusCode < 400 && Boolean(res.headers.location);
+            if (!isRedirect)
+                break;
+            const locationHeader = res.headers.location;
+            const location = Array.isArray(locationHeader) ? locationHeader[0] : locationHeader;
+            await res.body.dump();
+            if (!location)
+                throw new Error(`Redirect without Location header from ${currentUrl}`);
+            hops += 1;
+            if (hops > maxRedirects) {
+                throw new Error(`Too many redirects (>${maxRedirects}) downloading ${url}`);
+            }
+            currentUrl = validateRedirectTarget(location, currentUrl, opts.allowedHosts, opts.requireHttps);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            await res.body.dump();
+            throw new Error(`HTTP ${res.statusCode} for ${currentUrl}`);
+        }
+        const totalHeader = res.headers["content-length"];
+        const parsedTotal = typeof totalHeader === "string" ? Number.parseInt(totalHeader, 10) : Number.NaN;
+        const total = Number.isFinite(parsedTotal) && parsedTotal >= 0 ? parsedTotal : undefined;
+        const maxBytes = opts.maxBytes;
+        if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)) {
+            abortResponseBody(res.body);
+            throw new Error(`Invalid download size limit: ${maxBytes}`);
+        }
+        if (maxBytes !== undefined && total !== undefined && total > maxBytes) {
+            abortResponseBody(res.body);
+            throw new Error(`Download exceeds ${maxBytes} byte safety limit: ${currentUrl}`);
+        }
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        let downloaded = 0;
+        const limiter = new Transform({
+            transform(chunk, _encoding, callback) {
+                downloaded += chunk.length;
+                if (maxBytes !== undefined && downloaded > maxBytes) {
+                    callback(new Error(`Download exceeds ${maxBytes} byte safety limit: ${currentUrl}`));
+                    return;
+                }
+                opts.onProgress?.(downloaded, total);
+                callback(null, chunk);
+            },
+        });
+        outputStarted = true;
+        await pipeline(res.body, limiter, fs.createWriteStream(dest, { mode: 0o755 }));
+        if (downloaded === 0)
+            throw new Error(`Empty download from ${currentUrl}`);
+        return downloaded;
+    }
+    catch (err) {
+        if (res)
+            abortResponseBody(res.body);
+        if (outputStarted)
+            fs.rmSync(dest, { force: true });
+        throw err;
+    }
+    finally {
+        clearTimeout(deadlineTimer);
+    }
+}

package/dist/json-shape.js

@@ -0,0 +1,17 @@
+export function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+export function hasExactOwnKeys(value, expectedKeys) {
+    const actualKeys = Object.keys(value);
+    return (actualKeys.length === expectedKeys.length &&
+        expectedKeys.every((key) => Object.hasOwn(value, key)));
+}
+export function isCanonicalIsoTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const milliseconds = Date.parse(value);
+    return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value;
+}

package/dist/log-follow.js

@@ -0,0 +1,280 @@
+import fs from "node:fs";
+import path from "node:path";
+export const LOG_FOLLOW_CHUNK_BYTES = 64 * 1024;
+export function normalizeLines(input, fallback = 50) {
+    return typeof input === "number" && Number.isSafeInteger(input) && input > 0 ? input : fallback;
+}
+export function parseLogLineCount(value) {
+    if (!/^[1-9]\d*$/.test(value))
+        throw new Error("must be a positive integer");
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        throw new Error("must be a positive safe integer");
+    return parsed;
+}
+function fileIdentity(stat) {
+    return `${stat.dev}:${stat.ino}:${stat.birthtimeMs}`;
+}
+function validateChunkBytes(chunkBytes) {
+    if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) {
+        throw new Error("chunkBytes must be a positive safe integer");
+    }
+}
+function missingGrowth() {
+    return {
+        chunks: [],
+        cursor: { identity: null, offset: 0 },
+        hasMore: false,
+        missing: true,
+    };
+}
+export function logCursorAtEnd(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error(`Log path is not a regular file: ${file}`);
+        if (!Number.isSafeInteger(stat.size) || stat.size < 0) {
+            throw new Error(`Log file size is not safely readable: ${file}`);
+        }
+        return { identity: fileIdentity(stat), offset: stat.size };
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { identity: null, offset: 0 };
+        }
+        throw err;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+export function readLogGrowth(file, cursor, chunkBytes = LOG_FOLLOW_CHUNK_BYTES) {
+    validateChunkBytes(chunkBytes);
+    const safeOffset = Number.isSafeInteger(cursor.offset) && cursor.offset >= 0 ? cursor.offset : 0;
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error(`Log path is not a regular file: ${file}`);
+        if (!Number.isSafeInteger(stat.size) || stat.size < 0) {
+            throw new Error(`Log file size is not safely readable: ${file}`);
+        }
+        const identity = fileIdentity(stat);
+        const position = cursor.identity === identity && stat.size >= safeOffset ? safeOffset : 0;
+        if (position >= stat.size) {
+            return {
+                chunks: [],
+                cursor: { identity, offset: position },
+                hasMore: false,
+                missing: false,
+            };
+        }
+        const length = Math.min(chunkBytes, stat.size - position);
+        const chunk = Buffer.allocUnsafe(length);
+        const bytesRead = fs.readSync(fd, chunk, 0, length, position);
+        const nextOffset = position + Math.max(0, bytesRead);
+        return {
+            chunks: bytesRead > 0 ? [chunk.subarray(0, bytesRead)] : [],
+            cursor: { identity, offset: nextOffset },
+            hasMore: nextOffset < stat.size,
+            missing: false,
+        };
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return missingGrowth();
+        throw err;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+export function logTailCursor(file) {
+    try {
+        return logCursorAtEnd(file);
+    }
+    catch {
+        return { identity: "unreadable", offset: 0 };
+    }
+}
+export function boundedLogTailSince(file, cursor, options = {}) {
+    const maxBytes = options.maxBytes ?? LOG_FOLLOW_CHUNK_BYTES;
+    const maxLines = options.maxLines ?? 20;
+    if (!Number.isSafeInteger(maxBytes) ||
+        maxBytes <= 0 ||
+        !Number.isSafeInteger(maxLines) ||
+        maxLines <= 0) {
+        return "";
+    }
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || !Number.isSafeInteger(stat.size) || stat.size < 0)
+            return "";
+        const identity = fileIdentity(stat);
+        const offset = Number.isSafeInteger(cursor.offset) && cursor.offset >= 0 ? cursor.offset : 0;
+        if (cursor.identity !== null && cursor.identity !== identity)
+            return "";
+        if (stat.size < offset || stat.size === offset)
+            return "";
+        const position = Math.max(offset, stat.size - maxBytes);
+        const length = stat.size - position;
+        const buffer = Buffer.allocUnsafe(length);
+        const bytesRead = fs.readSync(fd, buffer, 0, length, position);
+        let start = 0;
+        while (start < bytesRead && ((buffer[start] ?? 0) & 0xc0) === 0x80)
+            start++;
+        const lines = buffer
+            .subarray(start, bytesRead)
+            .toString("utf8")
+            .split(/\r?\n/)
+            .filter((line) => line.trim().length > 0);
+        return lines.slice(-maxLines).join("\n");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+            }
+        }
+    }
+}
+export function followLogFile(file, options) {
+    const chunkBytes = options.chunkBytes ?? LOG_FOLLOW_CHUNK_BYTES;
+    const pollMs = options.pollMs ?? 500;
+    validateChunkBytes(chunkBytes);
+    if (!Number.isSafeInteger(pollMs) || pollMs <= 0) {
+        throw new Error("pollMs must be a positive safe integer");
+    }
+    return new Promise((resolve, reject) => {
+        let cursor = options.cursor ?? { identity: null, offset: 0 };
+        let watcher;
+        let timer;
+        let draining = false;
+        let queued = false;
+        let stopped = false;
+        const closeWatcher = () => {
+            try {
+                watcher?.close();
+            }
+            catch {
+            }
+            watcher = undefined;
+        };
+        const cleanup = () => {
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            closeWatcher();
+            options.signal.removeEventListener("abort", onAbort);
+        };
+        const finish = (err) => {
+            if (stopped)
+                return;
+            stopped = true;
+            cleanup();
+            if (err === undefined)
+                resolve();
+            else
+                reject(err);
+        };
+        const installWatcher = () => {
+            if (watcher || stopped)
+                return;
+            try {
+                const watched = fs.watch(path.dirname(file), (_event, filename) => {
+                    if (filename === null || filename.toString() === path.basename(file))
+                        scheduleDrain();
+                });
+                watched.on("error", () => {
+                    if (watcher === watched)
+                        watcher = undefined;
+                    try {
+                        watched.close();
+                    }
+                    catch {
+                    }
+                });
+                watched.on("close", () => {
+                    if (watcher === watched)
+                        watcher = undefined;
+                });
+                watcher = watched;
+            }
+            catch {
+            }
+        };
+        const drain = async () => {
+            if (stopped || draining) {
+                queued = !stopped;
+                return;
+            }
+            draining = true;
+            try {
+                let chunksThisTurn = 0;
+                do {
+                    queued = false;
+                    let growth;
+                    try {
+                        growth = readLogGrowth(file, cursor, chunkBytes);
+                    }
+                    catch {
+                        break;
+                    }
+                    cursor = growth.cursor;
+                    if (stopped)
+                        break;
+                    for (const chunk of growth.chunks) {
+                        await options.onChunk(chunk);
+                        if (stopped)
+                            break;
+                    }
+                    queued = !stopped && (queued || growth.hasMore);
+                    chunksThisTurn += growth.chunks.length;
+                    if (queued && chunksThisTurn >= 16)
+                        break;
+                } while (queued && !stopped);
+            }
+            catch (err) {
+                finish(err);
+            }
+            finally {
+                draining = false;
+                if (queued && !stopped)
+                    setImmediate(scheduleDrain);
+            }
+        };
+        const scheduleDrain = () => {
+            if (stopped)
+                return;
+            if (draining) {
+                queued = true;
+                return;
+            }
+            void drain();
+        };
+        const onAbort = () => finish();
+        if (options.signal.aborted) {
+            finish();
+            return;
+        }
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        installWatcher();
+        timer = setInterval(() => {
+            installWatcher();
+            scheduleDrain();
+        }, pollMs);
+        scheduleDrain();
+    });
+}

package/dist/log.js

@@ -0,0 +1,17 @@
+export const log = {
+    info(msg) {
+        console.log(`[sash] ${msg}`);
+    },
+    ok(msg) {
+        console.log(`[sash] ✓ ${msg}`);
+    },
+    warn(msg) {
+        console.warn(`[sash] ! ${msg}`);
+    },
+    error(msg) {
+        console.error(`[sash] ✗ ${msg}`);
+    },
+    kv(key, value) {
+        console.log(`  ${key.padEnd(16)}${value}`);
+    },
+};