@winkjs/composer 0.5.1 → 0.7.0

package/src/core/utils/address/index.js

@@ -0,0 +1,362 @@
+// core/utils/address/index.js
+
+/**
+ * @fileoverview The shared address helper: parse, classify, and describe
+ * the addresses adapters connect to.
+ *
+ * Every adapter takes an address. QuestDB takes `ilpUrl` and `pgUrl`
+ * in the `host:port` grammar. The two MQTT adapters take `brokerUrl`
+ * in the URL grammar (`mqtt://host:port`). This module is the one
+ * place that reads those strings, so the three refusal layers (the
+ * adapter schema, the adapter factory, and `env-vars.js`) and the
+ * three adapters all reach the same verdict about one value.
+ *
+ * Why it exists (ADR-030): `localhost` is a name, not an address. On
+ * most systems it resolves to two addresses, `::1` and `127.0.0.1`,
+ * and a service may listen on only one. The run-5 soak lost its write
+ * path for four hours that way. So `localhost` is refused wherever an
+ * adapter address is read, and any other name gets one warning. This
+ * module supplies the classification and the two message strings; it
+ * never prints and never opens a socket. The setup probe that does open
+ * a socket lives beside it in `probe.js` (ADR-030 item 4), so this file
+ * stays pure.
+ *
+ * Classification rules:
+ * - An IP literal (`net.isIP` returns 4 or 6) is `ip`.
+ * - `localhost` in any letter case, with or without a trailing dot, is
+ *   `localhost`. So is any name under the reserved `.localhost`
+ *   top-level domain (RFC 6761 §6.3 reserves it for loopback).
+ * - Everything else is `name`.
+ * - A value the grammar cannot read is `unparsed`. It is neither
+ *   refused nor warned here; the transport library owns that error.
+ *
+ * The functions never throw on an address value. `classifyAddress`
+ * throws only on an unknown grammar, which is a programming error.
+ *
+ * Setup path only. Nothing here runs per message.
+ */
+
+import net from 'node:net';
+
+const LOOPBACK_LITERAL = '127.0.0.1';
+const MAX_PORT = 65535;
+const LOCALHOST = 'localhost';
+const LOCALHOST_SUFFIX = '.localhost';
+const GRAMMARS = new Set( [ 'hostPort', 'url' ] );
+
+// A host in the plain form has no colon, slash, or whitespace. The
+// port is digits only. Both patterns are single-quantifier on purpose:
+// the security lint rejects a nested quantifier, so the host and the
+// port are split by hand on the first colon and each part is tested
+// alone.
+const HOST_CHARS = /^[^:\/\s]+$/;
+const DIGITS = /^\d+$/;
+
+const MULTI_ADDRESS_REASON = 'can resolve to more than one address, and the service may answer on only one';
+
+/**
+ * The result every parser returns for a value it cannot read.
+ *
+ * @param {*} value - The original value, echoed for the caller's message
+ * @returns {{unparsed: true, value: *}} The unparsed marker
+ */
+const unparsed = function ( value ) {
+    return { unparsed: true, value };
+}; // unparsed()
+
+/**
+ * Completes a host:port parse once the host and the port text are
+ * known. The port must be digits only and at most 65535; otherwise the
+ * whole value is unparsed.
+ *
+ * @param {*} value - The original value, for the unparsed marker
+ * @param {string} host - The host text, brackets already removed
+ * @param {string|undefined} portText - The text after the colon, or undefined
+ * @param {boolean} bracketed - Whether the host was written in brackets
+ * @returns {Object} `{ host, port, bracketed }` or the unparsed marker
+ */
+const finishHostPort = function ( value, host, portText, bracketed ) {
+    if ( portText === undefined ) {
+        return { host, port: undefined, bracketed };
+    }
+    if ( !DIGITS.test( portText ) ) {
+        return unparsed( value );
+    }
+    const port = Number( portText );
+    if ( port > MAX_PORT ) {
+        return unparsed( value );
+    }
+    return { host, port, bracketed };
+}; // finishHostPort()
+
+/**
+ * Parses the bracketed form: `[v6]` or `[v6]:port`. The brackets must
+ * hold an IPv6 literal, and only `:port` may follow them.
+ *
+ * @param {*} value - The original value, for the unparsed marker
+ * @param {string} text - The trimmed value, known to start with `[`
+ * @returns {Object} `{ host, port, bracketed }` or the unparsed marker
+ */
+const parseBracketed = function ( value, text ) {
+    const close = text.indexOf( ']' );
+    if ( close === -1 ) {
+        return unparsed( value );
+    }
+    const host = text.slice( 1, close );
+    if ( net.isIP( host ) !== 6 ) {
+        return unparsed( value );
+    }
+    const rest = text.slice( close + 1 );
+    if ( rest === '' ) {
+        return { host, port: undefined, bracketed: true };
+    }
+    if ( !rest.startsWith( ':' ) ) {
+        return unparsed( value );
+    }
+    return finishHostPort( value, host, rest.slice( 1 ), true );
+}; // parseBracketed()
+
+/**
+ * Parses the `host:port` grammar. Accepts `host:port`, `[v6]:port`,
+ * a bare host, a bare bracketed IPv6 literal, and a bare unbracketed
+ * IPv6 literal. The port is optional in every form.
+ *
+ * @param {*} value - The configured value
+ * @returns {Object} `{ host, port, bracketed }` or `{ unparsed: true, value }`
+ */
+const parseHostPort = function ( value ) {
+    if ( typeof value !== 'string' ) {
+        return unparsed( value );
+    }
+    const text = value.trim();
+    if ( text === '' ) {
+        return unparsed( value );
+    }
+    if ( text.startsWith( '[' ) ) {
+        return parseBracketed( value, text );
+    }
+
+    // A bare IPv6 literal has colons of its own, so it cannot carry a
+    // port in this grammar. Write `[v6]:port` for that.
+    if ( net.isIP( text ) === 6 ) {
+        return { host: text, port: undefined, bracketed: false };
+    }
+
+    // The plain form splits on the first colon. A second colon then
+    // lands in the port text, where the digits test rejects it.
+    const at = text.indexOf( ':' );
+    const host = ( at === -1 ) ? text : text.slice( 0, at );
+    const portText = ( at === -1 ) ? undefined : text.slice( at + 1 );
+    if ( !HOST_CHARS.test( host ) ) {
+        return unparsed( value );
+    }
+    return finishHostPort( value, host, portText, false );
+}; // parseHostPort()
+
+/**
+ * Parses the broker URL grammar with the platform URL parser. The
+ * brackets around an IPv6 host are removed. Userinfo (a user name or
+ * password in the URL) is reported as a flag and never copied out, so
+ * a password cannot travel into a message.
+ *
+ * @param {*} value - The configured value
+ * @returns {Object} `{ protocol, host, port, bracketed, hasUserinfo }` or `{ unparsed: true, value }`
+ */
+const parseBrokerUrl = function ( value ) {
+    if ( typeof value !== 'string' ) {
+        return unparsed( value );
+    }
+    let url;
+    try {
+        url = new URL( value.trim() );
+    } catch {
+        return unparsed( value );
+    }
+    if ( url.hostname === '' ) {
+        return unparsed( value );
+    }
+
+    const bracketed = url.hostname.startsWith( '[' );
+    const host = bracketed ? url.hostname.slice( 1, -1 ) : url.hostname;
+    const port = ( url.port === '' ) ? undefined : Number( url.port );
+    const hasUserinfo = ( url.username !== '' ) || ( url.password !== '' );
+    return { protocol: url.protocol, host, port, bracketed, hasUserinfo };
+}; // parseBrokerUrl()
+
+/**
+ * Classifies one host as an IP literal, `localhost`, or a name.
+ *
+ * @param {string} host - A parsed host, brackets already removed
+ * @returns {'ip'|'localhost'|'name'} The classification
+ */
+const classifyHost = function ( host ) {
+    if ( net.isIP( host ) !== 0 ) {
+        return 'ip';
+    }
+    const lowered = host.toLowerCase();
+    const normalised = lowered.endsWith( '.' ) ? lowered.slice( 0, -1 ) : lowered;
+    if ( ( normalised === LOCALHOST ) || normalised.endsWith( LOCALHOST_SUFFIX ) ) {
+        return 'localhost';
+    }
+    return 'name';
+}; // classifyHost()
+
+/**
+ * Parses and classifies one configured address in one call. This is
+ * the one check the three refusal layers share.
+ *
+ * @param {*} value - The configured value
+ * @param {'hostPort'|'url'} grammar - Which grammar the field uses
+ * @returns {Object} `{ kind, grammar, host, port, family, bracketed }`,
+ *   plus `protocol` and `hasUserinfo` for the URL grammar. A value the
+ *   grammar cannot read returns `{ kind: 'unparsed', grammar, value }`.
+ * @throws {TypeError} On an unknown grammar (a programming error)
+ */
+const classifyAddress = function ( value, grammar ) {
+    if ( !GRAMMARS.has( grammar ) ) {
+        throw new TypeError( `winkComposer/address: unknown grammar '${grammar}' (expected hostPort or url)` );
+    }
+    const parsed = ( grammar === 'url' ) ? parseBrokerUrl( value ) : parseHostPort( value );
+    if ( parsed.unparsed ) {
+        return { kind: 'unparsed', grammar, value };
+    }
+    const address = {
+        kind: classifyHost( parsed.host ),
+        grammar,
+        host: parsed.host,
+        port: parsed.port,
+        family: net.isIP( parsed.host ),
+        bracketed: parsed.bracketed
+    };
+    if ( grammar === 'url' ) {
+        address.protocol = parsed.protocol;
+        address.hasUserinfo = parsed.hasUserinfo;
+    }
+    return address;
+}; // classifyAddress()
+
+/**
+ * Writes a host the way a config value would: an IPv6 literal in
+ * brackets, anything else as is.
+ *
+ * @param {string} host - The host text
+ * @returns {string} The host, bracketed when it is an IPv6 literal
+ */
+const bracketIfIPv6 = function ( host ) {
+    return ( net.isIP( host ) === 6 ) ? `[${host}]` : host;
+}; // bracketIfIPv6()
+
+/**
+ * Joins a host text and an optional port.
+ *
+ * @param {string} hostText - The host, already bracketed if needed
+ * @param {number|undefined} port - The port, or undefined for none
+ * @returns {string} `host` or `host:port`
+ */
+const withPort = function ( hostText, port ) {
+    return ( port === undefined ) ? hostText : `${hostText}:${port}`;
+}; // withPort()
+
+/**
+ * Writes a host and an optional port the way a config value would:
+ * an IPv6 host in brackets, `host:port` when a port is given.
+ *
+ * @param {string} host - The host text
+ * @param {number|undefined} port - The port, or undefined for none
+ * @returns {string} `host`, `host:port`, or `[v6]:port`
+ */
+const formatHostPort = function ( host, port ) {
+    return withPort( bracketIfIPv6( host ), port );
+}; // formatHostPort()
+
+/**
+ * Renders a classified address for a message. Userinfo in a URL is
+ * shown as `***@`, never as written.
+ *
+ * @param {Object} address - A `classifyAddress` result (not unparsed)
+ * @returns {string} The address as an operator would write it
+ */
+const formatAddress = function ( address ) {
+    const hostPort = formatHostPort( address.host, address.port );
+    if ( address.grammar === 'url' ) {
+        const userinfo = address.hasUserinfo ? '***@' : '';
+        return `${address.protocol}//${userinfo}${hostPort}`;
+    }
+    return hostPort;
+}; // formatAddress()
+
+/**
+ * Suggests the same address with a literal host in place of the one
+ * configured. A URL suggestion drops userinfo, so a password never
+ * lands in a message.
+ *
+ * @param {Object} address - A `classifyAddress` result (not unparsed)
+ * @param {string} [literalHost='127.0.0.1'] - The literal to suggest
+ * @returns {string} The address to set
+ */
+const suggestLiteral = function ( address, literalHost = LOOPBACK_LITERAL ) {
+    const hostPort = formatHostPort( literalHost, address.port );
+    if ( address.grammar === 'url' ) {
+        return `${address.protocol}//${hostPort}`;
+    }
+    return hostPort;
+}; // suggestLiteral()
+
+/**
+ * The message clause for a refused `localhost` address, in the ADR-028
+ * form `<message> [INVALID_CONFIG]: <detail>`. The caller prefixes its
+ * module token. Names the field, the literal to set, and the env var
+ * when the field has one.
+ *
+ * @param {Object} args - Message inputs
+ * @param {string} args.field - The config key (`ilpUrl`, `brokerUrl`)
+ * @param {Object} args.address - The classified address being refused
+ * @param {string} [args.envVar] - The environment variable that also sets it
+ * @returns {string} The message clause
+ */
+const localhostRefusalMessage = function ( { field, address, envVar } ) {
+    const literal = suggestLiteral( address );
+    const where = ( envVar === undefined ) ? '' : ` (or ${envVar}=${literal})`;
+    return `${field} '${formatAddress( address )}' is refused [INVALID_CONFIG]: ` +
+        `'localhost' ${MULTI_ADDRESS_REASON}; set ${field} to ${literal}${where}`;
+}; // localhostRefusalMessage()
+
+/**
+ * The detail for `env-vars.js`, whose runner prefixes the variable
+ * name itself.
+ *
+ * @param {Object} address - The classified address being refused
+ * @returns {string} The detail sentence
+ */
+const localhostRefusalDetail = function ( address ) {
+    return `'localhost' ${MULTI_ADDRESS_REASON}; use ${suggestLiteral( address )}`;
+}; // localhostRefusalDetail()
+
+/**
+ * The warning clause for a host that is a name. `ADDRESS_IS_NAME` is a
+ * console classification token, like `CALLBACK_FAILED`, not an
+ * `err.code` (ADR-030). The caller prefixes its module token.
+ *
+ * @param {Object} args - Message inputs
+ * @param {string} args.field - The config key
+ * @param {string} args.host - The name that was configured
+ * @returns {string} The warning clause
+ */
+const nameWarningMessage = function ( { field, host } ) {
+    return `${field} host '${host}' is a name, not an address [ADDRESS_IS_NAME]: ` +
+        `a name ${MULTI_ADDRESS_REASON}; prefer the literal address`;
+}; // nameWarningMessage()
+
+export {
+    parseHostPort,
+    parseBrokerUrl,
+    classifyHost,
+    classifyAddress,
+    formatHostPort,
+    formatAddress,
+    suggestLiteral,
+    localhostRefusalMessage,
+    localhostRefusalDetail,
+    nameWarningMessage,
+    LOOPBACK_LITERAL
+};

package/src/core/utils/address/probe.js

@@ -0,0 +1,210 @@
+// core/utils/address/probe.js
+
+/**
+ * @fileoverview The setup probe: does the configured address answer on
+ * every address it resolves to?
+ *
+ * Why it exists (ADR-030 item 4): a name such as `db.plant.local` can
+ * resolve to two addresses, `::1` and `127.0.0.1`, and a service may
+ * listen on only one. Node connects to the first address the resolver
+ * returns. On the run-5 rig the first address refused while the
+ * second answered, the flow ran on the second for 32 hours, and then
+ * the name stopped working with no change composer could see. So the
+ * QuestDB adapter probes both of its endpoints at setup, before any
+ * client is built, and fails setup unless every resolved address
+ * answers. The message names each address and its result and, when
+ * one answered, the literal to set.
+ *
+ * How it probes:
+ * - An IP literal is probed once. A name is resolved with Node's
+ *   default lookup, all addresses, no family or order forced. That is
+ *   the same resolve path the QuestDB client takes, so the probe sees
+ *   what the client will see. A shell tool cannot stand in for it:
+ *   `curl` and `nc` resolve and fall back differently from Node.
+ * - The lookup has the same time limit as a connect. A resolver pool
+ *   that stalls is a real failure mode: on the run-5 rig one held
+ *   every flush open for minutes. A lookup that does not answer in
+ *   time fails the probe as `timeout`, and no address is dialled.
+ * - Every address is probed in resolver order, one at a time, with a
+ *   time limit each. A probe is one TCP connect; the socket is
+ *   destroyed the moment it answers, fails, or times out. The socket
+ *   is not `unref`'d: an unref'd socket would let the process exit
+ *   with the probe still pending when nothing else holds the event
+ *   loop open, which is the case for a headless flow at setup. The
+ *   time limit bounds the wait instead.
+ * - A late event after the first (an error after a connect) changes
+ *   nothing; each attempt settles once.
+ * - Results are `answers`, `refused` (ECONNREFUSED), `timeout`
+ *   (ETIMEDOUT or the time limit), or the Node error code as is.
+ *
+ * The lookup and the connect are injectable so the adapter specs run
+ * against scripted sockets. ADR-029's adapter calls the same probe
+ * once when a flush fails to connect, off the hot path, to attach a
+ * diagnosis to the report. Setup path only; nothing here runs per
+ * message.
+ */
+
+import dns from 'node:dns';
+import net from 'node:net';
+
+import { formatHostPort, suggestLiteral } from './index.js';
+
+const DEFAULT_PROBE_TIMEOUT_MS = 2000;
+
+/**
+ * Names the outcome of a failed connect.
+ *
+ * @param {Error} err - The socket error
+ * @returns {string} `refused`, `timeout`, the Node code, or `error`
+ */
+const resultForError = function ( err ) {
+    if ( err.code === 'ECONNREFUSED' ) {
+        return 'refused';
+    }
+    if ( err.code === 'ETIMEDOUT' ) {
+        return 'timeout';
+    }
+    return err.code || 'error';
+}; // resultForError()
+
+/**
+ * Builds the one-address dialler over the injected connect.
+ *
+ * @param {function} connectFn - `net.connect`-shaped: `( { host, port } ) => socket`
+ * @param {number} timeoutMs - The time limit per attempt
+ * @returns {function} `( address, port ) => Promise<string>` resolving to the result name
+ */
+const makeDial = function ( connectFn, timeoutMs ) {
+    return function ( address, port ) {
+        return new Promise( ( resolve ) => {
+            const socket = connectFn( { host: address, port } );
+            let settled = false;
+            const finish = function ( result ) {
+                if ( settled ) {
+                    return;
+                }
+                settled = true;
+                socket.destroy();
+                resolve( result );
+            };
+            socket.once( 'connect', () => finish( 'answers' ) );
+            socket.once( 'error', ( err ) => finish( resultForError( err ) ) );
+            socket.setTimeout( timeoutMs, () => finish( 'timeout' ) );
+        } );
+    };
+}; // makeDial()
+
+/**
+ * Resolves a name within the time limit. The timer is cleared the
+ * moment the lookup settles, so a normal lookup leaves nothing behind.
+ * The timer is not `unref`'d, for the same reason as the socket above.
+ *
+ * @param {function} lookupFn - The resolver, `( host, { all: true } ) => Promise<targets>`
+ * @param {string} host - The name to resolve
+ * @param {number} timeoutMs - The time limit
+ * @returns {Promise<Array>} The resolved targets; rejects with code `timeout` at the limit
+ */
+const lookupWithin = function ( lookupFn, host, timeoutMs ) {
+    return new Promise( ( resolve, reject ) => {
+        const pending = lookupFn( host, { all: true } );
+        const timer = setTimeout( () => {
+            const err = new Error( `lookup of '${host}' did not answer within ${timeoutMs} ms` );
+            err.code = 'timeout';
+            reject( err );
+        }, timeoutMs );
+        pending.then(
+            ( targets ) => {
+                clearTimeout( timer );
+                resolve( targets );
+            },
+            ( err ) => {
+                clearTimeout( timer );
+                reject( err );
+            }
+        );
+    } );
+}; // lookupWithin()
+
+/**
+ * Probes the targets one at a time, in order. Written as a recursion
+ * rather than a loop so no `await` sits inside a loop body; the depth
+ * is the number of resolved addresses, two or three in practice.
+ *
+ * @param {Array<{address: string, family: number}>} targets - Resolved addresses
+ * @param {number} port - The port to probe
+ * @param {function} dial - The dialler from `makeDial`
+ * @param {Array} attempts - The results so far
+ * @returns {Promise<Array>} One `{ address, family, result }` per target
+ */
+const probeEach = async function ( targets, port, dial, attempts ) {
+    if ( attempts.length === targets.length ) {
+        return attempts;
+    }
+    const target = targets[ attempts.length ];
+    const result = await dial( target.address, port );
+    attempts.push( { address: target.address, family: target.family, result } );
+    return probeEach( targets, port, dial, attempts );
+}; // probeEach()
+
+/**
+ * Probes one classified address. Passes only when every resolved
+ * address answers.
+ *
+ * @param {Object} address - A `classifyAddress` result of kind `ip` or `name`, with a port
+ * @param {Object} [options] - Injection points
+ * @param {function} [options.lookupFn=dns.promises.lookup] - The resolver
+ * @param {function} [options.connectFn=net.connect] - The connect
+ * @param {number} [options.timeoutMs=2000] - The time limit per address, and for the lookup
+ * @returns {Promise<Object>} `{ ok, host, port, attempts }`, or
+ *   `{ ok: false, host, port, lookupError, attempts: [] }` when the name did not resolve in time
+ */
+const probeAddress = async function ( address, options = {} ) {
+    const {
+        lookupFn = dns.promises.lookup,
+        connectFn = net.connect,
+        timeoutMs = DEFAULT_PROBE_TIMEOUT_MS
+    } = options;
+    const dial = makeDial( connectFn, timeoutMs );
+
+    let targets;
+    if ( address.kind === 'ip' ) {
+        targets = [ { address: address.host, family: address.family } ];
+    } else {
+        try {
+            targets = await lookupWithin( lookupFn, address.host, timeoutMs );
+        } catch ( err ) {
+            return { ok: false, host: address.host, port: address.port, lookupError: err.code || err.message, attempts: [] };
+        }
+    }
+
+    const attempts = await probeEach( targets, address.port, dial, [] );
+    const ok = attempts.every( ( attempt ) => attempt.result === 'answers' );
+    return { ok, host: address.host, port: address.port, attempts };
+}; // probeAddress()
+
+/**
+ * Renders a probe outcome for an operator: each address with its
+ * result and, when one answered but another did not, the literal to
+ * set. The rig's own case reads
+ * `[::1]:9000 refused, 127.0.0.1:9000 answers; set ilpUrl to 127.0.0.1:9000`.
+ *
+ * @param {Object} outcome - A `probeAddress` result
+ * @param {string} field - The config key, for the suggestion
+ * @param {Object} address - The classified address that was probed
+ * @returns {string} The detail sentence
+ */
+const describeProbe = function ( outcome, field, address ) {
+    if ( outcome.lookupError !== undefined ) {
+        return `'${outcome.host}' did not resolve (${outcome.lookupError})`;
+    }
+    const listed = outcome.attempts
+        .map( ( attempt ) => `${formatHostPort( attempt.address, outcome.port )} ${attempt.result}` )
+        .join( ', ' );
+    const answering = outcome.attempts.find( ( attempt ) => attempt.result === 'answers' );
+    if ( outcome.ok || ( answering === undefined ) ) {
+        return listed;
+    }
+    return `${listed}; set ${field} to ${suggestLiteral( address, answering.address )}`;
+}; // describeProbe()
+
+export { probeAddress, describeProbe, DEFAULT_PROBE_TIMEOUT_MS };