hive-am 1.0.0 → 1.2.0

package/server/dist/objects/http.js

@@ -0,0 +1,735 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { randomInt, randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { runScript } from './http-script.js';
+import { ObjectError } from './model.js';
+/**
+ * HTTP requests as an object: a folder of `.http` / `.rest` files in the format of the IntelliJ and VS Code REST clients. hive-am lists the
+ * requests of every file, picks an environment from `http-client.env.json` (and the private one next to it) and runs a request with `fetch`,
+ * answering with the status, headers, body and time. No JDK and no extra package.
+ *
+ * Format that is understood: `###` separates requests (the text after it is the name; `# @name x` too); `@name = value` defines a variable;
+ * `{{name}}` uses one (and `{{$uuid}}`, `{{$timestamp}}`, `{{$isoTimestamp}}`, `{{$randomInt}}`); the request line is `METHOD URL [HTTP/1.1]`
+ * (lines that start with `?` or `&` continue the URL); header lines follow until the first blank line; the rest is the body (`< ./file`
+ * inserts a file); `> {% … %}` response handlers are ignored.
+ */
+const MAX_DEPTH = 4, MAX_FILES = 300, MAX_REQUESTS = 2000;
+const MAX_RESPONSE = 2 * 1024 * 1024, TIMEOUT_MS = 60_000, MAX_INCLUDE = 1024 * 1024, MAX_FILE_EDIT = 1024 * 1024;
+const SKIP = new Set(['node_modules', '.git', 'target', 'dist', 'build', '.idea', '.vscode']);
+const METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']);
+const ENV_FILES = ['http-client.env.json', 'http-client.private.env.json'];
+const VAR = /\{\{\s*([$A-Za-z0-9_.\[\]-]+)\s*\}\}/g;
+const REF = /^([\w-]+)\.response\.(body|headers|status)(?:\.(.*))?$/;
+const variablesIn = (...texts) => { const out = new Set(); for (const t of texts)
+    for (const m of (t ?? '').matchAll(VAR))
+        if (!REF.test(m[1]))
+            out.add(m[1]); return [...out]; };
+const refsIn = (...texts) => { const out = new Set(); for (const t of texts)
+    for (const m of (t ?? '').matchAll(VAR)) {
+        const r = REF.exec(m[1]);
+        if (r)
+            out.add(r[1]);
+    } return [...out]; };
+/** One `.http` file → its requests. */
+export function parseHttpFile(content, relFile) {
+    const lines = content.split(/\r?\n/);
+    const fileVariables = {};
+    const requests = [];
+    let name;
+    let cur = null;
+    const finish = () => {
+        if (!cur)
+            return;
+        const body = [];
+        let inHandler = false;
+        const scripts = [];
+        let current = [];
+        let scriptFile;
+        for (const l of cur.body) {
+            const t = l.trim();
+            if (!inHandler && (t.startsWith('> {%') || t.startsWith('>! {%'))) {
+                const rest = t.replace(/^>!?\s*\{%/, '');
+                if (rest.includes('%}')) {
+                    scripts.push(rest.slice(0, rest.lastIndexOf('%}')));
+                    continue;
+                } // all in one line
+                inHandler = true;
+                current = rest.trim() ? [rest] : [];
+                continue;
+            }
+            if (inHandler) {
+                if (t.endsWith('%}')) {
+                    current.push(l.slice(0, l.lastIndexOf('%}')));
+                    scripts.push(current.join('\n'));
+                    inHandler = false;
+                }
+                else
+                    current.push(l);
+                continue;
+            }
+            if (t.startsWith('<> '))
+                continue; // a saved response
+            if (t.startsWith('> ')) {
+                scriptFile = t.slice(2).trim();
+                continue;
+            } // a handler file
+            body.push(l);
+        }
+        while (body.length && !body[body.length - 1].trim())
+            body.pop();
+        while (body.length && !body[0].trim())
+            body.shift();
+        const text = body.length ? body.join('\n') : undefined;
+        const index = requests.length;
+        requests.push({ id: `${relFile}#${index}`, index, name: cur.name || `${cur.method} ${cur.url.replace(/^(https?:\/\/[^/]+|\{\{[^}]+\}\})/, '').split('?')[0] || '/'}`, method: cur.method, url: cur.url, headers: cur.headers, body: text, line: cur.line, variables: variablesIn(cur.url, text, ...cur.headers.map((h) => h.value)), refs: refsIn(cur.url, text, ...cur.headers.map((h) => h.value)), named: /^[\w-]+$/.test(cur.name ?? '') ? cur.name : undefined, script: scripts.length ? scripts.join('\n') : undefined, scriptFile });
+        cur = null;
+    };
+    lines.forEach((raw, i) => {
+        const line = raw.trimEnd(), t = line.trim();
+        if (/^#{3,}/.test(t)) {
+            finish();
+            name = t.replace(/^#+\s*/, '').trim() || undefined;
+            return;
+        }
+        if (cur?.inBody) {
+            cur.body.push(raw);
+            return;
+        }
+        const tag = /^(?:#|\/\/)\s*@name\s+(\S.*)$/.exec(t);
+        if (tag) {
+            name = tag[1].trim();
+            return;
+        }
+        if (!cur) {
+            if (!t || t.startsWith('#') || t.startsWith('//'))
+                return;
+            const v = /^@([\w.-]+)\s*=\s*(.*)$/.exec(t);
+            if (v) {
+                fileVariables[v[1]] = v[2].trim();
+                return;
+            }
+            const m = /^([A-Za-z]+)\s+(\S.*?)(?:\s+HTTP\/[\d.]+)?$/.exec(t);
+            if (m && METHODS.has(m[1].toUpperCase())) {
+                cur = { method: m[1].toUpperCase(), url: m[2].trim(), headers: [], body: [], line: i + 1, inBody: false, name };
+                name = undefined;
+                return;
+            }
+            if (/^https?:\/\//i.test(t)) {
+                cur = { method: 'GET', url: t.replace(/\s+HTTP\/[\d.]+$/, ''), headers: [], body: [], line: i + 1, inBody: false, name };
+                name = undefined;
+            }
+            return;
+        }
+        if (!t) {
+            cur.inBody = true;
+            return;
+        } // the blank line that ends the headers
+        if (!cur.headers.length && /^\s+[?&]/.test(line)) {
+            cur.url += t;
+            return;
+        } // an indented line continues the URL
+        if (t.startsWith('#') || t.startsWith('//'))
+            return;
+        const h = /^([^\s:]+)\s*:\s*(.*)$/.exec(t);
+        if (h)
+            cur.headers.push({ name: h[1], value: h[2] });
+        else
+            cur.body.push(raw), cur.inBody = true;
+    });
+    finish();
+    return { relFile, requests, fileVariables };
+}
+/** The folder, as a real path (so a link cannot lead outside of it). */
+function realFolder(folder) {
+    if (!isAbsolute(folder))
+        throw new ObjectError('The folder must be an absolute path');
+    if (!existsSync(folder) || !statSync(folder).isDirectory())
+        throw new ObjectError(`The folder ${folder} does not exist`);
+    return realpathSync(folder);
+}
+/** A path inside the folder, or an error. */
+function inside(root, rel) {
+    const abs = resolve(root, rel);
+    const r = relative(root, abs);
+    if (r.startsWith('..') || isAbsolute(r))
+        throw new ObjectError('That path is outside the folder');
+    try {
+        const real = realpathSync(abs);
+        const rr = relative(root, real);
+        if (rr.startsWith('..') || isAbsolute(rr))
+            throw new ObjectError('That path is outside the folder');
+        return real;
+    }
+    catch (e) {
+        if (e instanceof ObjectError)
+            throw e;
+        return abs;
+    }
+}
+const readJson = (file) => {
+    try {
+        const j = JSON.parse(readFileSync(file, 'utf8'));
+        return j && typeof j === 'object' && !Array.isArray(j) ? j : null;
+    }
+    catch {
+        return null;
+    }
+};
+const SECRET_NAME = /(pass(word|wd)?|secret|token|api[-_]?key|auth|credential|private)/i;
+export const looksSecret = (name) => SECRET_NAME.test(name);
+function envVars(root, fileAbs, env, hive) {
+    const dirs = [];
+    for (let d = dirname(fileAbs);; d = dirname(d)) {
+        dirs.push(d);
+        if (d === root || !d.startsWith(root))
+            break;
+    }
+    const merged = {};
+    const priv = {};
+    const files = [];
+    for (const d of dirs.reverse())
+        for (const f of ENV_FILES) {
+            const p = join(d, f);
+            if (!existsSync(p))
+                continue;
+            const j = readJson(p);
+            if (!j)
+                continue;
+            files.push(relative(root, p));
+            for (const [k, v] of Object.entries(j))
+                if (v && typeof v === 'object') {
+                    merged[k] = { ...(merged[k] ?? {}), ...v };
+                    if (f.includes('private')) {
+                        const s = (priv[k] ??= new Set());
+                        for (const n of Object.keys(v))
+                            s.add(n);
+                    }
+                }
+        }
+    const names = [...new Set([...Object.keys(merged), ...Object.keys(hive ?? {})])].filter((k) => k !== '$shared').sort();
+    // The levels, from the weakest to the strongest: hive-am's shared values, hive-am's values of the environment, then the same two from the env files.
+    const layers = [];
+    const fromHive = (scope) => ({ source: 'hive', from: scope, vars: Object.fromEntries(Object.entries(hive?.[scope] ?? {}).map(([k, v]) => [k, { value: v.value, secret: !!v.secret, hidden: !!v.secret }])) });
+    const fromFiles = (scope) => ({ source: 'envfile', from: scope, vars: Object.fromEntries(Object.entries(merged[scope] ?? {}).map(([k, v]) => [k, { value: typeof v === 'string' ? v : JSON.stringify(v), secret: !!priv[scope]?.has(k), hidden: false }])) });
+    layers.push(fromHive('$shared'));
+    if (env)
+        layers.push(fromHive(env));
+    layers.push(fromFiles('$shared'));
+    if (env)
+        layers.push(fromFiles(env));
+    const vars = {};
+    for (const l of layers)
+        for (const [k, v] of Object.entries(l.vars))
+            vars[k] = v.value;
+    return { vars, names, files, layers };
+}
+export function scanHttp(folder, hive) {
+    const root = realFolder(folder);
+    const files = [];
+    const envNames = new Set(Object.keys(hive ?? {}).filter((k) => k !== '$shared'));
+    const envFiles = new Set();
+    const fileVars = {};
+    let truncated = false, total = 0;
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            const abs = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (depth < MAX_DEPTH && !SKIP.has(e.name) && !e.name.startsWith('.'))
+                    walk(abs, depth + 1);
+                continue;
+            }
+            if (ENV_FILES.includes(e.name)) {
+                envFiles.add(relative(root, abs));
+                for (const [k, vars] of Object.entries(readJson(abs) ?? {})) {
+                    if (k !== '$shared')
+                        envNames.add(k);
+                    const set = (fileVars[k] ??= new Set());
+                    for (const name of Object.keys(vars ?? {}))
+                        set.add(name);
+                }
+                continue;
+            }
+            if (!/\.(http|rest)$/i.test(e.name))
+                continue;
+            if (files.length >= MAX_FILES || total >= MAX_REQUESTS) {
+                truncated = true;
+                return;
+            }
+            try {
+                const f = parseHttpFile(readFileSync(abs, 'utf8'), relative(root, abs));
+                if (f.requests.length) {
+                    files.push(f);
+                    total += f.requests.length;
+                }
+            }
+            catch { /* unreadable file */ }
+        }
+    };
+    walk(root, 0);
+    const count = new Map();
+    for (const f of files)
+        for (const r of f.requests)
+            for (const v of r.variables)
+                if (!v.startsWith('$'))
+                    count.set(v, (count.get(v) ?? 0) + 1);
+    const fileDefined = [...new Set(files.flatMap((f) => Object.keys(f.fileVariables)))].sort();
+    // The variables that response handlers keep, found by reading the handlers (not by running them).
+    const setBy = {};
+    for (const f of files)
+        for (const r of f.requests)
+            for (const m of (r.script ?? '').matchAll(/client\.global\.set\(\s*["'`]([\w.-]+)["'`]/g))
+                (setBy[m[1]] ??= []).push(r.named ?? r.name);
+    return { folder: root, setBy, files, environments: [...envNames].sort(), envFiles: [...envFiles].sort(), used: [...count].map(([name, n]) => ({ name, count: n })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)), fileDefined, fileVars: Object.fromEntries(Object.entries(fileVars).map(([k, v]) => [k, [...v].sort()])), truncated };
+}
+const MASK = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|api-key|x-auth-token|x-access-token)$/i;
+const mask = (name, value) => (MASK.test(name) ? `${value.slice(0, Math.min(6, Math.floor(value.length / 3)))}••••` : value);
+/** `Authorization: Basic user password` (or `user:password`) as the encoded header; an already encoded one is left alone. */
+const basicAuth = (name, value) => {
+    if (name.toLowerCase() !== 'authorization')
+        return value;
+    const m = /^Basic\s+(\S+?)(?:\s+|:)(.+)$/i.exec(value.trim());
+    return m ? `Basic ${Buffer.from(`${m[1]}:${m[2]}`).toString('base64')}` : value;
+};
+const dynamic = (key) => {
+    if (key === '$uuid' || key === '$guid')
+        return randomUUID();
+    if (key === '$timestamp')
+        return String(Math.floor(Date.now() / 1000));
+    if (key === '$isoTimestamp')
+        return new Date().toISOString();
+    if (key === '$randomInt')
+        return String(randomInt(0, 1000));
+    return undefined;
+};
+const sessions = new Map();
+export const sessionOf = (objectId) => { let s = sessions.get(objectId); if (!s)
+    sessions.set(objectId, s = { globals: {}, responses: new Map() }); return s; };
+export const dropSession = (objectId) => { sessions.delete(objectId); };
+export function sessionView(objectId) {
+    const s = sessionOf(objectId);
+    return { globals: { ...s.globals }, responses: [...s.responses].map(([name, r]) => ({ name, status: r.status, at: r.at, headers: r.headers, body: r.text.slice(0, 200_000) })) };
+}
+export function sessionSet(objectId, name, value) {
+    if (!/^[A-Za-z_][\w.-]{0,80}$/.test(name))
+        throw new ObjectError(`"${name}" is not a valid variable name`);
+    if (value.length > 8000)
+        throw new ObjectError('The value is too long');
+    sessionOf(objectId).globals[name] = value;
+}
+/** Forgets one value, or (without a name) every value and every stored answer. */
+export function sessionClear(objectId, name) {
+    const s = sessionOf(objectId);
+    if (name)
+        delete s.globals[name];
+    else {
+        s.globals = {};
+        s.responses.clear();
+    }
+}
+/** `{{login.response.body.$.token}}`, `{{login.response.headers.X-Token}}`, `{{login.response.status}}`: a piece of the last answer of a named request. */
+function fromResponse(s, key) {
+    const m = REF.exec(key);
+    if (!m)
+        return undefined;
+    const r = s?.responses.get(m[1]);
+    if (!r)
+        return undefined;
+    if (m[2] === 'status')
+        return String(r.status);
+    if (m[2] === 'headers')
+        return r.headers[(m[3] ?? '').toLowerCase()];
+    const path = (m[3] ?? '*').replace(/^\$\.?/, '');
+    if (path === '*' || path === '')
+        return r.text;
+    let cur = r.body;
+    for (const part of path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean)) {
+        if (cur === null || typeof cur !== 'object' || ['__proto__', 'constructor', 'prototype'].includes(part))
+            return undefined;
+        cur = cur[part];
+    }
+    return cur === undefined ? undefined : typeof cur === 'string' ? cur : JSON.stringify(cur);
+}
+const substitute = (text, vars, unresolved, session) => {
+    let out = text;
+    for (let pass = 0; pass < 5 && VAR.test(out); pass++) {
+        VAR.lastIndex = 0;
+        out = out.replace(VAR, (whole, k) => dynamic(k) ?? vars[k] ?? fromResponse(session, k) ?? whole);
+    }
+    VAR.lastIndex = 0;
+    for (const m of out.matchAll(VAR))
+        unresolved.add(m[1]);
+    return out;
+};
+/** The variables a request needs and where each one stands, so the interface can show what is missing before running it. */
+export function describeHttp(folder, relFile, index, env, hive, session) {
+    const root = realFolder(folder);
+    const abs = inside(root, relFile);
+    const file = parseHttpFile(readFileSync(abs, 'utf8'), relFile);
+    const item = file.requests[index];
+    if (!item)
+        throw new ObjectError(`Request #${index} is not in ${relFile}`);
+    const e = envVars(root, abs, env, hive);
+    const vars = { ...file.fileVariables, ...e.vars, ...(session?.globals ?? {}) };
+    // Answers of other requests this one uses: a reference to a request that has not been run in this session is missing too.
+    const refMissing = [...(item.url + (item.body ?? '') + item.headers.map((x) => x.value).join('\n')).matchAll(VAR)].map((m) => m[1]).filter((k) => REF.test(k) && fromResponse(session, k) === undefined);
+    const missing = [...item.variables.filter((v) => dynamic(v) === undefined && !(v in vars)), ...new Set(refMissing)];
+    return { item, missing, needsRun: [...new Set(refMissing.map((k) => REF.exec(k)[1]))], environments: e.names };
+}
+export function inspectHttp(folder, relFile, index, env, hive, session) {
+    const root = realFolder(folder);
+    const abs = relFile ? inside(root, relFile) : join(root, '_.http');
+    const files = [];
+    if (relFile)
+        files.push(parseHttpFile(readFileSync(abs, 'utf8'), relFile));
+    else
+        for (const f of scanHttp(folder, hive).files)
+            files.push(f);
+    const item = relFile && index !== undefined ? files[0].requests[index] : undefined;
+    if (relFile && index !== undefined && !item)
+        throw new ObjectError(`Request #${index} is not in ${relFile}`);
+    const e = envVars(root, abs, env, hive);
+    // The names to show, and how many requests use each.
+    const used = new Map();
+    const bump = (n) => used.set(n, (used.get(n) ?? 0) + 1);
+    const reqs = item ? [item] : files.flatMap((f) => f.requests);
+    for (const r of reqs) {
+        for (const v of r.variables)
+            bump(v);
+        for (const m of (r.url + (r.body ?? '') + r.headers.map((x) => x.value).join('\n')).matchAll(VAR))
+            if (REF.test(m[1]))
+                bump(m[1]);
+    }
+    const names = new Set(used.keys());
+    if (!item) {
+        for (const f of files)
+            for (const k of Object.keys(f.fileVariables))
+                names.add(k);
+        for (const l of e.layers)
+            for (const k of Object.keys(l.vars))
+                names.add(k);
+        for (const k of Object.keys(session?.globals ?? {}))
+            names.add(k);
+    }
+    const infoOf = (name) => {
+        const usedBy = used.get(name) ?? 0;
+        if (REF.test(name)) {
+            const v = fromResponse(session, name), ref = REF.exec(name);
+            return v === undefined
+                ? { name, value: null, source: 'missing', from: ref[1], secret: false, hidden: false, overridden: [], usedBy, hint: `run:${ref[1]}` }
+                : { name, value: v, source: 'response', from: ref[1], secret: looksSecret(name), hidden: false, overridden: [], usedBy };
+        }
+        if (dynamic(name) !== undefined)
+            return { name, value: null, source: 'dynamic', from: name, secret: false, hidden: false, overridden: [], usedBy };
+        // every source that defines it, strongest first
+        const found = [];
+        if (session && name in session.globals)
+            found.push({ source: 'session', from: '', value: session.globals[name], secret: looksSecret(name), hidden: false });
+        for (const l of [...e.layers].reverse())
+            if (name in l.vars)
+                found.push({ source: l.source, from: l.from === '$shared' ? '$shared' : l.from, value: l.vars[name].value, secret: l.vars[name].secret || looksSecret(name), hidden: l.vars[name].hidden });
+        for (const f of files)
+            if (name in f.fileVariables)
+                found.push({ source: 'file', from: f.relFile, value: f.fileVariables[name], secret: looksSecret(name), hidden: false });
+        if (!found.length)
+            return { name, value: null, source: 'missing', from: '', secret: looksSecret(name), hidden: false, overridden: [], usedBy };
+        const [w, ...rest] = found;
+        return { name, value: w.hidden ? null : w.value, source: w.source, from: w.from, secret: w.secret, hidden: w.hidden, overridden: rest.map((x) => ({ source: x.source, from: x.from, value: x.hidden || x.secret ? null : x.value })), usedBy };
+    };
+    const vars = [...names].map(infoOf).sort((a, b) => (a.source === 'missing' ? 0 : 1) - (b.source === 'missing' ? 0 : 1) || a.name.localeCompare(b.name));
+    let preview;
+    if (item) {
+        const unresolved = new Set();
+        const byName = new Map(vars.map((v) => [v.name, v]));
+        const fill = (text) => text.replace(VAR, (whole, k) => { const v = byName.get(k); if (!v)
+            return whole; if (v.source === 'missing') {
+            unresolved.add(k);
+            return whole;
+        } if (v.source === 'dynamic')
+            return whole; return v.hidden ? '••••' : v.value ?? whole; });
+        preview = { method: item.method, url: fill(item.url), headers: item.headers.map((x) => ({ name: x.name, value: mask(x.name, fill(x.value)) })), body: item.body === undefined ? undefined : fill(item.body), unresolved: [...unresolved] };
+    }
+    return { env: env ?? null, environments: e.names, vars, preview };
+}
+/** The text of a .http file (to show and edit it). */
+export function readHttpFile(folder, relFile) {
+    const root = realFolder(folder);
+    const abs = inside(root, relFile);
+    if (!/\.(http|rest)$/i.test(abs))
+        throw new ObjectError('That is not a .http file');
+    const st = statSync(abs);
+    if (!st.isFile())
+        throw new ObjectError('That is not a file');
+    if (st.size > MAX_FILE_EDIT)
+        throw new ObjectError('The file is too large to open here');
+    return readFileSync(abs, 'utf8');
+}
+/** Creates a new .http / .rest file inside the folder (it never overwrites one). */
+export function createHttpFile(folder, relFile, content) {
+    const root = realFolder(folder);
+    if (!/^[\w .@()+/-]+\.(http|rest)$/i.test(relFile) || relFile.split('/').some((p) => p.startsWith('.') || !p))
+        throw new ObjectError('Use a name that ends in .http or .rest, with letters, numbers, spaces, - _ . and folders inside the project');
+    const abs = resolve(root, relFile);
+    const r = relative(root, abs);
+    if (r.startsWith('..') || isAbsolute(r))
+        throw new ObjectError('That path is outside the folder');
+    if (existsSync(abs))
+        throw new ObjectError('A file with that name already exists');
+    if (Buffer.byteLength(content) > MAX_FILE_EDIT)
+        throw new ObjectError('The file is too large');
+    // the deepest folder that exists must be inside the project once links are resolved (a link could lead out)
+    let anc = dirname(abs);
+    while (!existsSync(anc))
+        anc = dirname(anc);
+    const real = relative(root, realpathSync(anc));
+    if (real.startsWith('..') || isAbsolute(real))
+        throw new ObjectError('That path is outside the folder');
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content, { encoding: 'utf8', flag: 'wx' });
+    return r;
+}
+export function writeHttpFile(folder, relFile, content) {
+    const root = realFolder(folder);
+    const abs = inside(root, relFile);
+    if (!/\.(http|rest)$/i.test(abs))
+        throw new ObjectError('Only .http and .rest files can be saved here');
+    if (!existsSync(abs) || !statSync(abs).isFile())
+        throw new ObjectError('The file does not exist: this saves changes to a file, it does not create one');
+    if (Buffer.byteLength(content) > MAX_FILE_EDIT)
+        throw new ObjectError('The file is too large');
+    writeFileSync(abs, content, 'utf8');
+}
+export const EXPORT_FORMATS = ['curl', 'wget', 'httpie', 'powershell', 'fetch', 'axios', 'python', 'go', 'php', 'java', 'csharp', 'ruby', 'rust', 'http'];
+const sq = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
+const js = (v) => JSON.stringify(v);
+/**
+ * A request as text to paste somewhere else (cURL, fetch, Python requests, HTTPie, or the raw HTTP message), with the values the runner
+ * would use now. What has no value stays as {{name}}; credential headers can be masked.
+ */
+export function exportHttp(folder, relFile, index, format, env, hive, session, redact = false) {
+    if (!EXPORT_FORMATS.includes(format))
+        throw new ObjectError(`Unknown format "${format}"`);
+    const root = realFolder(folder);
+    const abs = inside(root, relFile);
+    if (!/\.(http|rest)$/i.test(abs))
+        throw new ObjectError('That is not a .http file');
+    const file = parseHttpFile(readFileSync(abs, 'utf8'), relFile);
+    const item = file.requests[index];
+    if (!item)
+        throw new ObjectError(`Request #${index} is not in ${relFile}`);
+    const e = envVars(root, abs, env, hive);
+    const vars = { ...file.fileVariables, ...e.vars, ...(session?.globals ?? {}) };
+    const unresolved = new Set();
+    const sess = session ?? { globals: {}, responses: new Map() };
+    const url = substitute(item.url, vars, unresolved, sess);
+    const headers = item.headers.map((h) => { const v = basicAuth(h.name, substitute(h.value, vars, unresolved, sess)); return { name: h.name, value: redact ? mask(h.name, v) : v }; });
+    let body = item.body === undefined ? undefined : substitute(item.body, vars, unresolved, sess);
+    const inc = body && /^<\s+(\S+)\s*$/.exec(body.trim());
+    if (inc) {
+        try {
+            const pth = inside(root, join(relative(root, dirname(abs)), inc[1]));
+            if (statSync(pth).size <= MAX_INCLUDE)
+                body = readFileSync(pth, 'utf8');
+        }
+        catch { /* left as written */ }
+    }
+    const hasBody = body !== undefined && body !== '' && !['GET', 'HEAD'].includes(item.method);
+    const m = item.method;
+    let text;
+    if (format === 'curl') {
+        text = `curl ${m === 'GET' ? '' : `-X ${m} `}${sq(url)}` + headers.map((h) => ` \\\n  -H ${sq(`${h.name}: ${h.value}`)}`).join('') + (hasBody ? ` \\\n  --data-raw ${sq(body)}` : '');
+    }
+    else if (format === 'fetch') {
+        const opts = [`  method: ${js(m)}`, ...(headers.length ? [`  headers: {\n${headers.map((h) => `    ${js(h.name)}: ${js(h.value)}`).join(',\n')}\n  }`] : []), ...(hasBody ? [`  body: ${js(body)}`] : [])];
+        text = `const res = await fetch(${js(url)}, {\n${opts.join(',\n')}\n});\nconsole.log(res.status, await res.text());`;
+    }
+    else if (format === 'python') {
+        text = `import requests\n\nres = requests.request(\n    ${js(m)},\n    ${js(url)},\n` + (headers.length ? `    headers={\n${headers.map((h) => `        ${js(h.name)}: ${js(h.value)},`).join('\n')}\n    },\n` : '') + (hasBody ? `    data=${js(body)}.encode(),\n` : '') + `)\nprint(res.status_code, res.text)`;
+    }
+    else if (format === 'wget') {
+        text = `wget --quiet --method ${m} ${sq(url)}` + headers.map((h) => ` \\\n  --header ${sq(`${h.name}: ${h.value}`)}`).join('') + (hasBody ? ` \\\n  --body-data ${sq(body)}` : '') + ' \\\n  -O -';
+    }
+    else if (format === 'powershell') {
+        const ps = (v) => `'${v.replace(/'/g, "''")}'`;
+        text = (headers.length ? `$headers = @{\n${headers.map((h) => `  ${ps(h.name)} = ${ps(h.value)}`).join('\n')}\n}\n` : '') + `Invoke-RestMethod -Method ${m} -Uri ${ps(url)}` + (headers.length ? ' -Headers $headers' : '') + (hasBody ? ` -Body ${ps(body)}` : '');
+    }
+    else if (format === 'axios') {
+        const opts = [`  method: ${js(m.toLowerCase())}`, `  url: ${js(url)}`, ...(headers.length ? [`  headers: {\n${headers.map((h) => `    ${js(h.name)}: ${js(h.value)}`).join(',\n')}\n  }`] : []), ...(hasBody ? [`  data: ${js(body)}`] : [])];
+        text = `import axios from 'axios';\n\nconst res = await axios.request({\n${opts.join(',\n')}\n});\nconsole.log(res.status, res.data);`;
+    }
+    else if (format === 'go') {
+        const gs = (v) => '`' + v.replace(/`/g, '` + "`" + `') + '`';
+        text = `package main\n\nimport (\n\t"fmt"\n\t"io"\n\t"net/http"\n${hasBody ? '\t"strings"\n' : ''})\n\nfunc main() {\n\treq, _ := http.NewRequest(${js(m)}, ${js(url)}, ${hasBody ? `strings.NewReader(${gs(body)})` : 'nil'})\n` + headers.map((h) => `\treq.Header.Set(${js(h.name)}, ${js(h.value)})\n`).join('') + `\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(out))\n}`;
+    }
+    else if (format === 'php') {
+        const ph = (v) => `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+        text = `<?php\n$ch = curl_init(${ph(url)});\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => ${ph(m)},\n  CURLOPT_RETURNTRANSFER => true,\n` + (headers.length ? `  CURLOPT_HTTPHEADER => [\n${headers.map((h) => `    ${ph(`${h.name}: ${h.value}`)},`).join('\n')}\n  ],\n` : '') + (hasBody ? `  CURLOPT_POSTFIELDS => ${ph(body)},\n` : '') + `]);\n$out = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $out;`;
+    }
+    else if (format === 'java') {
+        text = `import java.net.URI;\nimport java.net.http.*;\n\nvar request = HttpRequest.newBuilder(URI.create(${js(url)}))\n` + headers.filter((h) => !/^(host|content-length|connection)$/i.test(h.name)).map((h) => `    .header(${js(h.name)}, ${js(h.value)})\n`).join('') + `    .method(${js(m)}, ${hasBody ? `HttpRequest.BodyPublishers.ofString(${js(body)})` : 'HttpRequest.BodyPublishers.noBody()'})\n    .build();\nvar response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\nSystem.out.println(response.statusCode() + " " + response.body());`;
+    }
+    else if (format === 'csharp') {
+        const cs = (v) => '@"' + v.replace(/"/g, '""') + '"';
+        const ct = headers.find((h) => h.name.toLowerCase() === 'content-type')?.value.split(';')[0].trim();
+        text = `using var client = new HttpClient();\nvar request = new HttpRequestMessage(new HttpMethod(${js(m)}), ${cs(url)});\n` + headers.filter((h) => h.name.toLowerCase() !== 'content-type').map((h) => `request.Headers.TryAddWithoutValidation(${js(h.name)}, ${cs(h.value)});\n`).join('') + (hasBody ? `request.Content = new StringContent(${cs(body)}, System.Text.Encoding.UTF8${ct ? `, ${js(ct)}` : ''});\n` : '') + `var response = await client.SendAsync(request);\nConsole.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");`;
+    }
+    else if (format === 'ruby') {
+        const rb = (v) => `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+        text = `require 'net/http'\nrequire 'uri'\n\nuri = URI(${rb(url)})\nrequest = Net::HTTP::${m[0] + m.slice(1).toLowerCase()}.new(uri)\n` + headers.map((h) => `request[${rb(h.name)}] = ${rb(h.value)}\n`).join('') + (hasBody ? `request.body = ${rb(body)}\n` : '') + `response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(request) }\nputs "#{response.code} #{response.body}"`;
+    }
+    else if (format === 'rust') {
+        text = `let client = reqwest::Client::new();\nlet res = client\n    .request(reqwest::Method::from_bytes(b${js(m)}).unwrap(), ${js(url)})\n` + headers.map((h) => `    .header(${js(h.name)}, ${js(h.value)})\n`).join('') + (hasBody ? `    .body(${js(body)})\n` : '') + `    .send()\n    .await?;\nprintln!("{} {}", res.status(), res.text().await?);`;
+    }
+    else if (format === 'httpie') {
+        text = `http${hasBody ? ` --raw ${sq(body)}` : ''} ${m} ${sq(url)}` + headers.map((h) => ` ${sq(`${h.name}:${h.value}`)}`).join('');
+    }
+    else {
+        let host = '';
+        try {
+            host = new URL(url).host;
+        }
+        catch { /* not a full URL */ }
+        const hs = headers.some((h) => h.name.toLowerCase() === 'host') || !host ? headers : [{ name: 'Host', value: host }, ...headers];
+        text = `${m} ${url} HTTP/1.1\n${hs.map((h) => `${h.name}: ${h.value}`).join('\n')}${hasBody ? `\n\n${body}` : ''}`;
+    }
+    return { text, unresolved: [...unresolved] };
+}
+/** The requests of a file (or of all the files) as documentation (Markdown) or as a Postman collection (v2.1). Values stay as {{variables}}. */
+export function exportCollection(folder, name, format, relFile, lastRuns) {
+    const sc = scanHttp(folder, undefined);
+    const files = sc.files.filter((f) => !relFile || f.relFile === relFile);
+    if (relFile && !files.length)
+        throw new ObjectError(`${relFile} is not one of the .http files`);
+    const slug = (relFile ? relFile.replace(/\.(http|rest)$/i, '') : name).replace(/[^\w.-]+/g, '-').replace(/^-+|-+$/g, '') || 'requests';
+    if (format === 'postman') {
+        const vars = [...new Map(files.flatMap((f) => Object.entries(f.fileVariables)).map(([key, value]) => [key, { key, value }])).values()];
+        const item = (f) => f.requests.map((r) => {
+            const hasBody = r.body !== undefined && !['GET', 'HEAD'].includes(r.method);
+            const ct = r.headers.find((h) => h.name.toLowerCase() === 'content-type')?.value ?? '';
+            return { name: r.name, request: { method: r.method, header: r.headers.map((h) => ({ key: h.name, value: h.value })), url: { raw: r.url }, ...(hasBody ? { body: { mode: 'raw', raw: r.body, options: { raw: { language: /json/i.test(ct) ? 'json' : /xml/i.test(ct) ? 'xml' : 'text' } } } } : {}) } };
+        });
+        const items = files.length === 1 ? item(files[0]) : files.map((f) => ({ name: f.relFile, item: item(f) }));
+        return { filename: `${slug}.postman_collection.json`, mime: 'application/json', content: JSON.stringify({ info: { name: relFile ?? name, schema: 'https://schema.getpostman.com/json/collection/v2.1.0/collection.json' }, item: items, variable: vars }, null, 2) };
+    }
+    const out = [`# ${relFile ?? name}`, ''];
+    for (const f of files) {
+        if (!relFile)
+            out.push(`## ${f.relFile}`, '');
+        const vs = Object.entries(f.fileVariables);
+        if (vs.length)
+            out.push('Variables of the file:', '', ...vs.map(([k, v]) => `- \`${k}\` = \`${v}\``), '');
+        for (const r of f.requests) {
+            out.push(`${relFile ? '##' : '###'} ${r.name}`, '', '```http', `${r.method} ${r.url}`, ...r.headers.map((h) => `${h.name}: ${h.value}`), '```', '');
+            if (r.body)
+                out.push('Body:', '', '```' + (/^\s*[[{]/.test(r.body) ? 'json' : ''), r.body, '```', '');
+            if (r.refs.length)
+                out.push(`Uses the answer of: ${r.refs.map((n) => `\`${n}\``).join(', ')}.`, '');
+            const last = lastRuns?.(f.relFile, r.index);
+            if (last) {
+                let b = last.body;
+                try {
+                    b = JSON.stringify(JSON.parse(b), null, 2);
+                }
+                catch { /* as it came */ }
+                out.push(`Example answer (${last.status}):`, '', '```' + (/json/i.test(last.contentType) ? 'json' : ''), b.length > 4000 ? `${b.slice(0, 4000)}\n…` : b, '```', '');
+            }
+        }
+    }
+    return { filename: `${slug}.md`, mime: 'text/markdown', content: out.join('\n') };
+}
+export async function runHttp(folder, relFile, index, env, hive, session = { globals: {}, responses: new Map() }) {
+    const root = realFolder(folder);
+    const abs = inside(root, relFile);
+    if (!/\.(http|rest)$/i.test(abs))
+        throw new ObjectError('That is not a .http file');
+    const file = parseHttpFile(readFileSync(abs, 'utf8'), relFile);
+    const item = file.requests[index];
+    if (!item)
+        throw new ObjectError(`Request #${index} is not in ${relFile}`);
+    const e = envVars(root, abs, env, hive);
+    if (env && !e.names.includes(env))
+        throw new ObjectError(`The environment "${env}" is not in the env files`);
+    const vars = { ...file.fileVariables, ...e.vars, ...session.globals };
+    const unresolved = new Set();
+    const url = substitute(item.url, vars, unresolved, session);
+    const headers = item.headers.map((h) => ({ name: h.name, value: substitute(h.value, vars, unresolved, session) }));
+    for (const h of headers)
+        h.value = basicAuth(h.name, h.value);
+    let body = item.body === undefined ? undefined : substitute(item.body, vars, unresolved, session);
+    const needRun = [...new Set([...unresolved].filter((k) => REF.test(k)).map((k) => REF.exec(k)[1]))];
+    if (needRun.length)
+        throw new ObjectError(`This request uses the answer of ${needRun.map((n) => `“${n}”`).join(', ')}, which has not been run in this session: run ${needRun.length > 1 ? 'them' : 'it'} first (or the whole file, in order).`);
+    if (unresolved.size)
+        throw new ObjectError(`Missing values for: ${[...unresolved].map((v) => `{{${v}}}`).join(', ')}${e.names.length ? '. Pick an environment that defines them.' : '. Define them in the file (@name = value), in an http-client.env.json, or in the Variables of this object.'}`);
+    // `< ./file` as the whole body: the content of a file next to the .http file (inside the folder).
+    const inc = body && /^<\s+(\S+)\s*$/.exec(body.trim());
+    if (inc) {
+        const p = inside(root, join(relative(root, dirname(abs)), inc[1]));
+        if (statSync(p).size > MAX_INCLUDE)
+            throw new ObjectError('The included file is too large');
+        body = readFileSync(p, 'utf8');
+    }
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        throw new ObjectError(`"${url}" is not a full URL: use http:// or https://, or define a {{host}} variable`);
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:')
+        throw new ObjectError('Only http and https URLs can be requested');
+    const hasBody = body !== undefined && !['GET', 'HEAD'].includes(item.method);
+    const started = Date.now(), ctl = new AbortController(), timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(target, { method: item.method, headers: Object.fromEntries(headers.map((h) => [h.name, h.value])), body: hasBody ? body : undefined, signal: ctl.signal, redirect: 'follow' });
+        const buf = Buffer.from(await res.arrayBuffer());
+        const durationMs = Date.now() - started;
+        const contentType = res.headers.get('content-type') ?? '';
+        const binary = buf.subarray(0, 4000).includes(0) || /^(image|audio|video)\//.test(contentType) || /octet-stream|zip|pdf/.test(contentType);
+        const truncated = buf.length > MAX_RESPONSE;
+        const text = binary ? '' : buf.subarray(0, MAX_RESPONSE).toString('utf8');
+        // The answer, as the handlers and the other requests see it: JSON when it is JSON.
+        let parsed = text;
+        if (!binary && (/json/i.test(contentType) || /^\s*[[{]/.test(text))) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        const lower = Object.fromEntries([...res.headers.entries()].map(([k, v]) => [k.toLowerCase(), v]));
+        if (item.named)
+            session.responses.set(item.named, { status: res.status, headers: lower, body: parsed, text, at: Date.now() });
+        const handled = item.script ? runScript(item.script, { status: res.status, headers: lower, body: parsed, text, contentType, time: durationMs }, session.globals) : null;
+        return {
+            tests: handled?.tests ?? [], logs: handled?.logs ?? [], set: handled?.set ?? [], scriptError: handled?.error, scriptFile: item.scriptFile,
+            request: { method: item.method, url: target.toString(), headers: headers.map((h) => ({ name: h.name, value: mask(h.name, h.value) })), body: hasBody ? body : undefined },
+            status: res.status, statusText: res.statusText, durationMs, size: buf.length,
+            headers: [...res.headers.entries()].map(([name, value]) => ({ name, value })),
+            body: text, truncated, binary, contentType,
+        };
+    }
+    catch (err) {
+        if (err.name === 'AbortError')
+            throw new ObjectError(`The request took more than ${TIMEOUT_MS / 1000} s and was cancelled`);
+        const cause = err.cause;
+        throw new ObjectError(`The request failed: ${cause?.code ? `${cause.code} (${cause.message ?? ''})` : err.message}`.slice(0, 300));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const httpCount = (folder) => { try {
+    return scanHttp(folder).files.reduce((n, f) => n + f.requests.length, 0);
+}
+catch {
+    return 0;
+} };