@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/connectionBudget.js

@@ -0,0 +1,128 @@
+/**
+ * How many connections this process can hold against each PostgreSQL
+ * database, and whether the server would let it.
+ *
+ * Every pool is sized for the process it lives in and knows nothing of the
+ * others: the read and write pools (`--read-pool`, `--write-pool`), the
+ * background writer, a LISTEN connection, the auth store's pool. A second
+ * replica multiplies all of them, and the server's limit (the role's, or
+ * `max_connections`) is the first anyone hears of the product — as a 53300
+ * under load. So each holder says what it may open when it is made
+ * (`holdConnections`), the totals are read by database, and a start compares
+ * them with what the server says it allows (`adviseConnectionLimits`).
+ * `mistri check --deploy` does the same sum before anything runs
+ * (`processConnections`), for as many replicas as the operator names.
+ *
+ * Counted: pools at their `max`, whether or not they have opened yet — a
+ * ceiling, not a reading. Not counted: the short-lived client that cancels a
+ * statement (pg_cancel_backend) and the one-shot clients of migrations and
+ * maintenance, which run beside a stopped or starting server.
+ */
+/** The connections a manager of PostgreSQL pools may hold: its readers, its writers and the one background writer. */
+export const managerConnections = (readers, writers) => readers + writers + 1;
+/**
+ * What a short-lived store manager asks for (a retention prune's, a command line's): one reader and one writer.
+ */
+export const SMALL_STORE_POOL = Object.freeze({ readers: 1, writers: 1 });
+/**
+ * The one manager the server's own stores share on a database (postgresPool.ts sharedPgConnections): the jobs host
+ * with its workflow and event-delivery stores, the effects host, the mail outbox, the integrations store, the
+ * decisions, assistant and API event stores. Two readers and two writers, whatever the App's pools, sized for their
+ * short statements and kept apart from the pools a person's reads and saves use, where a burst of job claims could
+ * otherwise queue ahead of a save. Not all of them are background: the assistant store, a tenant's decision
+ * suggestions and the API event feed answer a person, and share the two readers and two writers with job claims
+ * and completions, the mail outbox and the integrations. That is deliberate (no connection is added for them) and
+ * bounded by the pool's own queue, which answers busy. A job's own command and every delivery run as background
+ * work, on the one background writer, whose line is bounded the same way (postgresPool.ts). `mistri check --deploy`
+ * counts the same size (servedHosts.ts), so they cannot drift.
+ */
+export const RUNTIME_STORE_POOL = Object.freeze({ readers: 2, writers: 2 });
+/** `host:port/database` of a connection string, without its credentials: what two URLs share when they name one database. */
+export function databaseOf(url) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.hostname}:${parsed.port || '5432'}${parsed.pathname.replace(/\/+$/, '') || '/'}`;
+    }
+    catch {
+        return url;
+    }
+}
+const holds = new Set();
+/**
+ * Record that this process may now hold up to `count` connections to `url`'s database. Returns the release, called
+ * when the holder closes; calling it twice is harmless.
+ */
+export function holdConnections(url, count, ask) {
+    const hold = { database: databaseOf(url), count, ...(ask ? { ask } : {}) };
+    holds.add(hold);
+    return () => void holds.delete(hold);
+}
+/** Up to how many connections this process holds now, by database. */
+export function heldConnections() {
+    const totals = new Map();
+    for (const hold of holds)
+        totals.set(hold.database, (totals.get(hold.database) ?? 0) + hold.count);
+    return totals;
+}
+/** The connections one process may hold on the primary: its manager, plus the LISTEN connection. */
+export const primaryConnections = (shape) => managerConnections(shape.readers, shape.writers) + (shape.listen === false ? 0 : 1);
+/** One database's line for `mistri check --deploy`: "3 processes × 41 connections = 123". */
+export function sayBudget(budget) {
+    const times = `${budget.processes} process${budget.processes === 1 ? '' : 'es'} × ${budget.perProcess} connections = ${budget.total}`;
+    const limit = budget.limit === undefined ? '' : ` (limit ${budget.limit})`;
+    const cpus = budget.cpus === undefined ? '' : ` (at ${budget.cpus} cpus; pass --cpus for the deployment's)`;
+    const parts = budget.parts?.length ? `; a process: ${budget.parts.map((part) => `${part.host} ${part.connections}`).join(' + ')}` : '';
+    return `${budget.database}: ${times}${limit}${cpus}${parts}`;
+}
+/** The smaller of the limits that apply to this role, or undefined when neither is set. */
+export function effectiveLimit(roleLimit, usable) {
+    const limits = [roleLimit, usable].filter((limit) => limit !== undefined && limit >= 0);
+    return limits.length ? Math.min(...limits) : undefined;
+}
+const LIMITS = `SELECT r.rolconnlimit AS role_limit,
+  current_setting('max_connections')::int - current_setting('superuser_reserved_connections')::int AS usable
+  FROM pg_roles r WHERE r.rolname = current_user`;
+/**
+ * One line a database whose holders may open more connections than its server allows this role, naming both
+ * numbers and the flags that lower them. Never refuses and never throws: one round trip per database, started
+ * after the first connection is open, whose failure (a pooler that answers no catalog, a role that may not read
+ * it) is silent.
+ */
+export async function adviseConnectionLimits(say) {
+    const totals = heldConnections();
+    const asked = new Set();
+    for (const hold of [...holds]) {
+        if (!hold.ask || asked.has(hold.database) || !totals.has(hold.database))
+            continue;
+        asked.add(hold.database);
+        try {
+            const line = await limitAdvice(hold.database, totals.get(hold.database), await hold.ask());
+            if (line)
+                say(line);
+        }
+        catch {
+            /* The advice is a courtesy: a start never depends on it. */
+        }
+    }
+}
+/** The warning for one database given a connection to ask, or undefined when it fits. Exported for tests. */
+export async function limitAdvice(database, held, connection) {
+    const row = (await connection.query(LIMITS)).rows[0];
+    if (!row)
+        return undefined;
+    const whole = (value) => {
+        const number = Number(value);
+        return value === null || value === undefined || !Number.isInteger(number) ? undefined : number;
+    };
+    const roleLimit = whole(row.role_limit);
+    const usable = whole(row.usable);
+    const limit = effectiveLimit(roleLimit, usable);
+    if (limit === undefined || held <= limit)
+        return undefined;
+    const source = roleLimit !== undefined && roleLimit >= 0 && roleLimit <= (usable ?? Infinity)
+        ? `the role's limit`
+        : `the server's max_connections less its reserved ones`;
+    return (`this process may open ${held} connections to ${database}, and ${source} allows ${limit}. ` +
+        `Lower --read-pool and --write-pool (or a connection's "pool"), and MISTRI_AUTH_POOL for the sign-in store, or raise the limit; ` +
+        `with several replicas the sum of all of them counts.`);
+}

package/dist/adapters/dbLatency.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A remote database's distance, felt on a laptop: `--db-latency <ms>` (or
+ * `MISTRI_DEV_DB_LATENCY`) makes every round trip wait that long before it is
+ * sent, so an App that asks the database eleven questions in a row feels it in
+ * development, where the database is a millisecond away, rather than in
+ * production, where it is twenty.
+ *
+ * A round trip is a flight: on PostgreSQL the message a client writes to its
+ * socket, so a pipelined batch leaves in one write and pays once, the way a
+ * remote database charges. On SQLite it is the statement call, which has no
+ * network to be pipelined on.
+ *
+ * Development only. Production would pay the wait for nothing, so it is
+ * refused there (NODE_ENV=production), and by the serve of a build
+ * (`refuseForBuild`): a build is what is deployed.
+ */
+/** The wait before each flight, in milliseconds; 0 is none. */
+export declare const dbLatency: () => number;
+/** Set the wait: read once at start by `configureDbLatency`; tests set it directly. */
+export declare function setDbLatency(value: number): void;
+/**
+ * The wait the flag or the environment asks for, validated and set. The flag wins over the variable. Throws a
+ * message fit for the terminal when the value is not a number of milliseconds, or the process is a production one.
+ */
+export declare function configureDbLatency(flag: string | undefined, env?: NodeJS.ProcessEnv): number;
+/** A build is what is deployed: the wait is refused with it, and cleared. */
+export declare function refuseForBuild(): void;
+/** Wait one round trip, for an engine with no network of its own (SQLite's statement call). Nothing when off. */
+export declare function roundTrip(): Promise<void>;
+/**
+ * Hold each message `client` writes to its socket for the wait before it leaves. Timers of one duration fire in
+ * the order they were set, so the messages still leave in order; two written in the same tick leave together, which
+ * is what a pipeline is. A no-op when the wait is off, for a client without a socket, and for one already held.
+ */
+export declare function delayFlights(client: object): void;

package/dist/adapters/dbLatency.js

@@ -0,0 +1,79 @@
+/**
+ * A remote database's distance, felt on a laptop: `--db-latency <ms>` (or
+ * `MISTRI_DEV_DB_LATENCY`) makes every round trip wait that long before it is
+ * sent, so an App that asks the database eleven questions in a row feels it in
+ * development, where the database is a millisecond away, rather than in
+ * production, where it is twenty.
+ *
+ * A round trip is a flight: on PostgreSQL the message a client writes to its
+ * socket, so a pipelined batch leaves in one write and pays once, the way a
+ * remote database charges. On SQLite it is the statement call, which has no
+ * network to be pipelined on.
+ *
+ * Development only. Production would pay the wait for nothing, so it is
+ * refused there (NODE_ENV=production), and by the serve of a build
+ * (`refuseForBuild`): a build is what is deployed.
+ */
+let ms = 0;
+/** The wait before each flight, in milliseconds; 0 is none. */
+export const dbLatency = () => ms;
+/** Set the wait: read once at start by `configureDbLatency`; tests set it directly. */
+export function setDbLatency(value) {
+    ms = value;
+}
+/**
+ * The wait the flag or the environment asks for, validated and set. The flag wins over the variable. Throws a
+ * message fit for the terminal when the value is not a number of milliseconds, or the process is a production one.
+ */
+export function configureDbLatency(flag, env = process.env) {
+    const given = flag ?? env.MISTRI_DEV_DB_LATENCY;
+    if (given === undefined || (flag === undefined && given.trim() === ''))
+        return ms;
+    const source = flag !== undefined ? '--db-latency' : 'MISTRI_DEV_DB_LATENCY';
+    if (!/^\d{1,4}(\.\d+)?$/.test(given.trim()) || Number(given) > 5000)
+        throw new Error(`${source} takes the milliseconds each database round trip should wait, like 20 (0 to 5000); it got "${given}".`);
+    if (env.NODE_ENV === 'production')
+        throw new Error(`${source} slows every database round trip on purpose to feel a remote database in development, and NODE_ENV is production.`);
+    ms = Number(given);
+    return ms;
+}
+/** A build is what is deployed: the wait is refused with it, and cleared. */
+export function refuseForBuild() {
+    if (ms === 0)
+        return;
+    ms = 0;
+    throw new Error('--db-latency (or MISTRI_DEV_DB_LATENCY) is for development and is refused when serving a build, which is what is deployed.');
+}
+/** Wait one round trip, for an engine with no network of its own (SQLite's statement call). Nothing when off. */
+export async function roundTrip() {
+    if (ms > 0)
+        await new Promise((done) => setTimeout(done, ms));
+}
+const delayed = new WeakSet();
+/**
+ * Hold each message `client` writes to its socket for the wait before it leaves. Timers of one duration fire in
+ * the order they were set, so the messages still leave in order; two written in the same tick leave together, which
+ * is what a pipeline is. A no-op when the wait is off, for a client without a socket, and for one already held.
+ */
+export function delayFlights(client) {
+    if (ms <= 0 || delayed.has(client))
+        return;
+    const stream = client.connection?.stream;
+    if (!stream?.write)
+        return;
+    delayed.add(client);
+    const write = stream.write.bind(stream);
+    stream.write = (chunk, ...rest) => {
+        if (ms <= 0)
+            return write(chunk, ...rest);
+        setTimeout(() => {
+            try {
+                write(chunk, ...rest);
+            }
+            catch {
+                // The socket went away while the message waited: the client hears it close.
+            }
+        }, ms);
+        return true;
+    };
+}

package/dist/adapters/epochCache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A cache that is never wrong, because it is never trusted on its own.
+ *
+ * Every entry is kept under the version of the thing it was derived from —
+ * the catalog's epoch (postgresSchemaEpoch.ts, SQLite's `schema_version`),
+ * an App's version, a role set — and is served only to a caller that holds
+ * the current version, read cheaply inside the transaction that will use the
+ * entry. An entry under any other version is a miss, never an answer: a
+ * stale cache is only a slower one. So nothing here expires by time, and
+ * nothing needs invalidating; a new version simply stops matching.
+ *
+ * The version is read BEFORE what is derived from it, never after: a change
+ * committing between the two leaves an entry filed under a version no later
+ * read can match, so it is derived again rather than trusted on a version it
+ * postdates.
+ *
+ * Generic on purpose: the catalog caches here, the command metadata in the
+ * journal and the plans compiled per (App, roles, epoch) all keep their
+ * entries through one of these, and so can a composed read that wants to.
+ */
+export declare class EpochCache<V> {
+    private readonly max;
+    private readonly entries;
+    private counts;
+    /** At most `max` keys; the least recently set goes first. Bounded, because a key can carry a caller's role set. */
+    constructor(max?: number);
+    /** The value kept for `key` under exactly `version`; anything else is a miss. */
+    get(version: string | undefined, key: string): V | undefined;
+    /** What is kept for `key`, whatever its version: for work that must happen before the version is read (a lock). Never an answer. */
+    peek(key: string): {
+        version: string;
+        value: V;
+    } | undefined;
+    /** Keep `value` under `version`, the one read before `value` was derived. Returns the value. */
+    set<T extends V>(version: string | undefined, key: string, value: T): T;
+    /** Read through: the kept value under `version`, or `derive()` kept under it. */
+    through<T extends V>(version: string | undefined, key: string, derive: () => Promise<T>): Promise<T>;
+    /** Synchronous read through, for SQLite. */
+    throughSync<T extends V>(version: string | undefined, key: string, derive: () => T): T;
+    clear(): void;
+    /** Drop what is kept for `key`, whatever its version. */
+    forget(key: string): void;
+    get size(): number;
+    /** Hits and misses since the process started, for the operator and the budget tests. */
+    stats(): Readonly<{
+        hits: number;
+        misses: number;
+        size: number;
+    }>;
+}

package/dist/adapters/epochCache.js

@@ -0,0 +1,85 @@
+/**
+ * A cache that is never wrong, because it is never trusted on its own.
+ *
+ * Every entry is kept under the version of the thing it was derived from —
+ * the catalog's epoch (postgresSchemaEpoch.ts, SQLite's `schema_version`),
+ * an App's version, a role set — and is served only to a caller that holds
+ * the current version, read cheaply inside the transaction that will use the
+ * entry. An entry under any other version is a miss, never an answer: a
+ * stale cache is only a slower one. So nothing here expires by time, and
+ * nothing needs invalidating; a new version simply stops matching.
+ *
+ * The version is read BEFORE what is derived from it, never after: a change
+ * committing between the two leaves an entry filed under a version no later
+ * read can match, so it is derived again rather than trusted on a version it
+ * postdates.
+ *
+ * Generic on purpose: the catalog caches here, the command metadata in the
+ * journal and the plans compiled per (App, roles, epoch) all keep their
+ * entries through one of these, and so can a composed read that wants to.
+ */
+export class EpochCache {
+    max;
+    entries = new Map();
+    counts = { hits: 0, misses: 0 };
+    /** At most `max` keys; the least recently set goes first. Bounded, because a key can carry a caller's role set. */
+    constructor(max = 512) {
+        this.max = max;
+    }
+    /** The value kept for `key` under exactly `version`; anything else is a miss. */
+    get(version, key) {
+        if (version === undefined) {
+            this.counts.misses++;
+            return undefined;
+        }
+        const entry = this.entries.get(key);
+        if (entry?.version === version) {
+            this.counts.hits++;
+            return entry.value;
+        }
+        this.counts.misses++;
+        return undefined;
+    }
+    /** What is kept for `key`, whatever its version: for work that must happen before the version is read (a lock). Never an answer. */
+    peek(key) {
+        return this.entries.get(key);
+    }
+    /** Keep `value` under `version`, the one read before `value` was derived. Returns the value. */
+    set(version, key, value) {
+        if (version === undefined)
+            return value;
+        this.entries.delete(key);
+        this.entries.set(key, { version, value });
+        while (this.entries.size > this.max)
+            this.entries.delete(this.entries.keys().next().value);
+        return value;
+    }
+    /** Read through: the kept value under `version`, or `derive()` kept under it. */
+    async through(version, key, derive) {
+        const kept = this.get(version, key);
+        if (kept !== undefined)
+            return kept;
+        return this.set(version, key, await derive());
+    }
+    /** Synchronous read through, for SQLite. */
+    throughSync(version, key, derive) {
+        const kept = this.get(version, key);
+        if (kept !== undefined)
+            return kept;
+        return this.set(version, key, derive());
+    }
+    clear() {
+        this.entries.clear();
+    }
+    /** Drop what is kept for `key`, whatever its version. */
+    forget(key) {
+        this.entries.delete(key);
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /** Hits and misses since the process started, for the operator and the budget tests. */
+    stats() {
+        return { ...this.counts, size: this.entries.size };
+    }
+}

package/dist/adapters/http/egress.d.ts

@@ -0,0 +1,48 @@
+import { type NetworkPolicy, type Resolver } from '../net/networkPolicy.js';
+export type { Resolver } from '../net/networkPolicy.js';
+export interface EgressPolicy extends NetworkPolicy {
+    /** Plain `http:`; for an API on a trusted network or a test, never the default. */
+    insecure: boolean;
+    connectTimeoutMs: number;
+    /** The whole request, from the first byte sent to the last one read. */
+    timeoutMs: number;
+    maxBytes: number;
+    resolver?: Resolver;
+}
+export declare const DEFAULT_POLICY: EgressPolicy;
+/** Why a request failed, as a reason the App's error mapping can rely on; the message is for the operator. */
+export declare class HttpSourceError extends Error {
+    readonly reason: 'refused' | 'timeout' | 'redirect' | 'too_large' | 'not_json' | 'status' | 'shape' | 'network';
+    readonly status?: number | undefined;
+    constructor(reason: 'refused' | 'timeout' | 'redirect' | 'too_large' | 'not_json' | 'status' | 'shape' | 'network', message: string, status?: number | undefined);
+}
+export interface EgressReply {
+    status: number;
+    json: unknown;
+}
+interface EgressRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers: Record<string, string>;
+    /** Sent as JSON. A service's own client builds it; never anything a browser sent verbatim. */
+    body?: unknown;
+    /** Sent as it is, with its own media type, in place of a JSON body: a warehouse's NDJSON. */
+    text?: {
+        readonly type: string;
+        readonly body: string;
+    };
+    /** The answer's body is never read, whatever its status: the reply is the status alone. A webhook's POST. */
+    discard?: true;
+    /** What the call is, for its span: a webhook, an HTTP source, a search service. */
+    kind?: 'webhook' | 'http' | 'search' | 'analytics';
+}
+/**
+ * One GET. A 2xx answers its parsed JSON; any other status answers the status
+ * alone — its body is never read into anything a caller could forward.
+ */
+export declare function send(url: URL, headers: Record<string, string>, policy: EgressPolicy): Promise<EgressReply>;
+/**
+ * One request of any method, under the same rules as a GET: a JSON body out,
+ * a JSON body back from a 2xx and nothing read from anything else. For the
+ * services a config names (search), which write as well as read.
+ */
+export declare function request(url: URL, asked: EgressRequest, policy: EgressPolicy): Promise<EgressReply>;

package/dist/adapters/http/egress.js

@@ -0,0 +1,175 @@
+/**
+ * The one place a request to an API leaves the process.
+ *
+ * Every HTTP connection's traffic goes through `request`, so the rules that
+ * make it safe to point tablewalk at someone else's server live here once:
+ *
+ *   - the address a name resolves to is checked, and that exact address is
+ *     the one connected to (the shared network policy, networkPolicy.ts);
+ *   - a redirect is refused, not followed — following one is how a trusted
+ *     name hands the request to an address nobody checked;
+ *   - a response is JSON, arrives within a deadline, and is read under a byte
+ *     cap — and a webhook's (`discard`) is not read at all: its status is the
+ *     whole reply, and its body is drained unread;
+ *   - a failure is an `HttpSourceError` carrying a reason, never the response
+ *     body, a header or the credential.
+ *
+ * Private networks are reachable by default: internal APIs are the common
+ * case, and an HTTP connection only ever comes from the operator's config,
+ * never from a browser. Cloud metadata and link-local addresses are not,
+ * unless the connection says so, because they hand out credentials to
+ * whoever asks.
+ */
+import { errorCode, inSpan, injectTrace, tracing } from '../telemetry/trace.js';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { checkedLookup, refusedLiteral } from '../net/networkPolicy.js';
+export const DEFAULT_POLICY = Object.freeze({
+    allowPrivate: true,
+    allowLinkLocal: false,
+    insecure: false,
+    connectTimeoutMs: 5_000,
+    timeoutMs: 15_000,
+    maxBytes: 5 * 1024 * 1024,
+});
+/** Why a request failed, as a reason the App's error mapping can rely on; the message is for the operator. */
+export class HttpSourceError extends Error {
+    reason;
+    status;
+    constructor(reason, message, status) {
+        super(message);
+        this.reason = reason;
+        this.status = status;
+        this.name = 'HttpSourceError';
+    }
+}
+const refused = (host, addresses) => new HttpSourceError('refused', `${host} resolves only to addresses this connection may not reach (${addresses.join(', ')}).`);
+/* JSON with its big integers kept: a number past 2^53 comes back as the digits
+   it arrived with, which every display path keeps whole, rather than as the
+   nearest double. The reviver's third argument is the value's source text. */
+function parseJson(text) {
+    const reviver = (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && context?.source && /^-?\d+$/.test(context.source) ? context.source : value;
+    return JSON.parse(text, reviver);
+}
+/**
+ * One GET. A 2xx answers its parsed JSON; any other status answers the status
+ * alone — its body is never read into anything a caller could forward.
+ */
+export function send(url, headers, policy) {
+    return request(url, { method: 'GET', headers }, policy);
+}
+/**
+ * One request of any method, under the same rules as a GET: a JSON body out,
+ * a JSON body back from a 2xx and nothing read from anything else. For the
+ * services a config names (search), which write as well as read.
+ */
+export function request(url, asked, policy) {
+    if (!tracing())
+        return requestUntraced(url, asked, policy);
+    /* An outbound call's span: its method, host and status travel, and the
+       caller's trace goes with it as `traceparent`. The URL's path and query,
+       the headers and the bodies stay local (adapters/telemetry/trace.ts). */
+    return inSpan(asked.method, {
+        kind: 'client',
+        attributes: {
+            'http.request.method': asked.method,
+            'server.address': url.hostname,
+            'server.port': url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80,
+            'mistri.outbound.kind': asked.kind ?? 'http',
+        },
+    }, async (span) => {
+        span.detail(() => ({
+            request: {
+                method: asked.method,
+                url: url.href,
+                headers: asked.headers,
+                ...(asked.text !== undefined ? { body: asked.text.body } : asked.body !== undefined ? { body: JSON.stringify(asked.body) } : {}),
+            },
+        }));
+        const reply = await requestUntraced(url, { ...asked, headers: injectTrace(asked.headers) }, policy);
+        span.setAttribute('http.response.status_code', reply.status);
+        if (reply.status >= 400)
+            span.fail(String(reply.status));
+        span.detail(() => ({
+            response: { status: reply.status, ...(reply.json !== undefined ? { body: JSON.stringify(reply.json).slice(0, 64 * 1024) } : {}) },
+        }));
+        return reply;
+    }, (error) => (error instanceof HttpSourceError ? error.reason : errorCode(error)));
+}
+function requestUntraced(url, asked, policy) {
+    const host = url.host;
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && policy.insecure)) {
+        return Promise.reject(new HttpSourceError('refused', `${url.protocol}// is not allowed; use https, or set "insecure": true for an API on a trusted network.`));
+    }
+    if (url.username || url.password) {
+        return Promise.reject(new HttpSourceError('refused', 'A credential belongs in the connection\'s "auth", not in its URL.'));
+    }
+    // An address written into the URL is never looked up, so it is checked here, before any socket opens.
+    const literal = refusedLiteral(url.hostname, policy);
+    if (literal)
+        return Promise.reject(refused(host, [literal]));
+    const payload = asked.text !== undefined
+        ? Buffer.from(asked.text.body, 'utf8')
+        : asked.body === undefined
+            ? undefined
+            : Buffer.from(JSON.stringify(asked.body), 'utf8');
+    const headers = payload
+        ? { ...asked.headers, 'content-type': asked.text?.type ?? 'application/json', 'content-length': String(payload.byteLength) }
+        : asked.headers;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error, reply) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            if (error) {
+                outgoing.destroy();
+                reject(error);
+            }
+            else
+                resolve(reply);
+        };
+        const deadline = setTimeout(() => finish(new HttpSourceError('timeout', `${host} did not answer within ${policy.timeoutMs / 1000} s.`)), policy.timeoutMs);
+        const open = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const outgoing = open(url, {
+            method: asked.method,
+            headers,
+            lookup: checkedLookup(policy, refused),
+            timeout: policy.connectTimeoutMs,
+        }, (response) => {
+            const status = response.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                return finish(new HttpSourceError('redirect', `${host} redirected (${status}); redirects are not followed. Point the connection at the final address.`, status));
+            }
+            if (asked.discard || status < 200 || status > 299) {
+                response.resume();
+                return finish(null, { status, json: undefined });
+            }
+            const type = String(response.headers['content-type'] ?? '');
+            if (!/^application\/([\w.+-]*\+)?json\b/i.test(type)) {
+                return finish(new HttpSourceError('not_json', `${host} answered ${type || 'without a content type'}, not JSON.`));
+            }
+            const chunks = [];
+            let size = 0;
+            response.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > policy.maxBytes)
+                    return finish(new HttpSourceError('too_large', `${host} answered more than ${Math.round(policy.maxBytes / 1024 / 1024)} MB.`));
+                chunks.push(chunk);
+            });
+            response.on('end', () => {
+                try {
+                    finish(null, { status, json: parseJson(Buffer.concat(chunks).toString('utf8')) });
+                }
+                catch {
+                    finish(new HttpSourceError('not_json', `${host} answered text that is not JSON.`));
+                }
+            });
+            response.on('error', () => finish(new HttpSourceError('network', `${host} closed the connection mid-answer.`)));
+        });
+        outgoing.on('timeout', () => finish(new HttpSourceError('timeout', `${host} did not accept a connection within ${policy.connectTimeoutMs / 1000} s.`)));
+        outgoing.on('error', (error) => finish(error instanceof HttpSourceError ? error : new HttpSourceError('network', `${host}: ${error.code ?? 'the connection failed'}.`)));
+        outgoing.end(payload);
+    });
+}