@winkjs/composer 0.6.0 → 0.7.0

package/src/core/storage-manager/questdb/address-policy.js

@@ -0,0 +1,264 @@
+// core/storage-manager/questdb/address-policy.js
+
+/**
+ * @fileoverview The setup-time address policy of the QuestDB adapter
+ * (ADR-030), and the classification of a connect failure.
+ *
+ * Every check here runs once, at setup, before the adapter opens a
+ * socket. Nothing here runs on the per-row path. The checks exist
+ * because the run-5 soak lost its write path for four hours to one
+ * name: `localhost` resolved to `::1` while QuestDB listened on
+ * `127.0.0.1` only. The policy that came out of that incident:
+ *
+ * - `localhost` is refused for both endpoints, at the schema (flow
+ *   definition) and again here (the environment fallback and direct
+ *   callers). The message names the literal to set.
+ * - An IPv6 literal is refused for `ilpUrl`. The client (4.2.0) splits
+ *   the address on its first colon and cannot read one. `pgUrl`
+ *   accepts `[::1]:8812`, because the PostgreSQL client takes a bare
+ *   host.
+ * - A name other than `localhost` is allowed, with one `ADDRESS_IS_NAME`
+ *   warning per field. Only a literal address is immune to a resolver
+ *   that changes its answer under a running process.
+ * - Before any client is built, each endpoint is probed with one TCP
+ *   connect per address it resolves to. Every address must answer, or
+ *   setup fails with `TRANSPORT_UNREACHABLE` and a per-address report.
+ *
+ * The last two functions classify a failure to connect. The ADR-018
+ * error vocabulary mandates one split. An endpoint that does not
+ * answer is `TRANSPORT_UNREACHABLE`: check the network, the firewall,
+ * whether QuestDB is running. Everything else is `INVALID_CONFIG`: fix
+ * the supplied config. `NETWORK_ERROR_CODES` is the list of Node
+ * syscall codes that mean "did not answer".
+ *
+ * The adapter's `index.js` header carries the full `err.code`
+ * vocabulary and the operator remediation per code.
+ *
+ * @see ADR-018
+ * @see ADR-030
+ */
+
+import { logger } from '../../logger/index.js';
+import { validators } from '../../utils/validate/index.js';
+import {
+    classifyAddress,
+    formatAddress,
+    suggestLiteral,
+    localhostRefusalMessage,
+    nameWarningMessage
+} from '../../utils/address/index.js';
+import { describeProbe } from '../../utils/address/probe.js';
+
+// ============================================================================
+// ADDRESS POLICY (ADR-030)
+// ============================================================================
+
+/**
+ * Builds a setup-time INVALID_CONFIG error in this adapter's message
+ * family.
+ *
+ * @param {string} message - The message clause, already in ADR-028 form
+ * @returns {Error} The classified error
+ */
+const invalidConfig = function ( message ) {
+    const err = new Error( `winkComposer/questdb: ${message}` );
+    err.code = 'INVALID_CONFIG';
+    return err;
+}; // invalidConfig()
+
+/**
+ * Schema validator for `ilpUrl`: non-empty, never `localhost`, and
+ * never an IPv6 literal, because the client (4.2.0) splits the address
+ * on its first colon and cannot read one. A value the grammar cannot
+ * read passes; the client reports its own error for it.
+ *
+ * @param {*} value - The configured value
+ * @returns {boolean} Whether the value is allowed
+ */
+const isAllowedIlpUrl = function ( value ) {
+    if ( !validators.nonEmptyString( value ) ) {
+        return false;
+    }
+    const address = classifyAddress( value, 'hostPort' );
+    return ( address.kind !== 'localhost' ) && ( address.family !== 6 );
+}; // isAllowedIlpUrl()
+
+/**
+ * Schema validator for `pgUrl`: non-empty and never `localhost`. An
+ * IPv6 literal is fine here; the PostgreSQL client takes a bare host.
+ *
+ * @param {*} value - The configured value
+ * @returns {boolean} Whether the value is allowed
+ */
+const isAllowedPgUrl = function ( value ) {
+    if ( !validators.nonEmptyString( value ) ) {
+        return false;
+    }
+    return classifyAddress( value, 'hostPort' ).kind !== 'localhost';
+}; // isAllowedPgUrl()
+
+/**
+ * Classifies one address and refuses `localhost`. The schema already
+ * refused it at flow definition; this call covers the environment
+ * fallback and direct callers, and carries the classified code.
+ *
+ * @param {string} field - The config key, for the message
+ * @param {string} value - The address as configured
+ * @param {string} envVar - The environment variable that also sets it
+ * @returns {Object} The classified address
+ * @throws {Error} INVALID_CONFIG when the host is `localhost`
+ */
+const assertNotLocalhost = function ( field, value, envVar ) {
+    const address = classifyAddress( value, 'hostPort' );
+    if ( address.kind === 'localhost' ) {
+        throw invalidConfig( localhostRefusalMessage( { field, address, envVar } ) );
+    }
+    return address;
+}; // assertNotLocalhost()
+
+/**
+ * Refuses an IPv6 literal for `ilpUrl`, naming the client limitation.
+ *
+ * @param {Object} address - The classified `ilpUrl`
+ * @throws {Error} INVALID_CONFIG when the host is an IPv6 literal
+ */
+const assertIlpNotIPv6 = function ( address ) {
+    if ( address.family === 6 ) {
+        throw invalidConfig(
+            `ilpUrl '${formatAddress( address )}' is refused [INVALID_CONFIG]: the QuestDB client (4.2.0) ` +
+            'splits the address on its first colon and cannot read an IPv6 literal; use an IPv4 ' +
+            `literal such as ${suggestLiteral( address )}`
+        );
+    }
+}; // assertIlpNotIPv6()
+
+/**
+ * Prints the one ADDRESS_IS_NAME line for a host that is a name.
+ *
+ * @param {string} field - The config key, for the message
+ * @param {Object} address - The classified address
+ */
+const warnIfName = function ( field, address ) {
+    if ( address.kind === 'name' ) {
+        logger.warn( `winkComposer/questdb: ${nameWarningMessage( { field, host: address.host } )}` );
+    }
+}; // warnIfName()
+
+/**
+ * Runs the setup probe for one endpoint and fails setup unless every
+ * resolved address answers (ADR-030 item 4). A value the grammar could
+ * not read, or one without a port, is not probed: the client owns
+ * that error.
+ *
+ * @param {string} field - The config key, for the message
+ * @param {Object} address - The classified address
+ * @param {function} probeFn - The probe (injectable; `probeAddress` in production)
+ * @returns {Promise<void>} Resolves when every resolved address answered
+ * @throws {Error} TRANSPORT_UNREACHABLE with the per-address detail
+ */
+const assertReachable = async function ( field, address, probeFn ) {
+    if ( ( address.kind === 'unparsed' ) || ( address.port === undefined ) ) {
+        return;
+    }
+    const outcome = await probeFn( address );
+    if ( outcome.ok ) {
+        return;
+    }
+    const err = new Error(
+        `winkComposer/questdb: ${field} '${formatAddress( address )}' is unreachable [TRANSPORT_UNREACHABLE]: ` +
+        describeProbe( outcome, field, address )
+    );
+    err.code = 'TRANSPORT_UNREACHABLE';
+    throw err;
+}; // assertReachable()
+
+/**
+ * The host and port handed to the PostgreSQL client. The parsed
+ * address is used when the grammar read it with a port, which is what
+ * lets `[::1]:8812` through. Otherwise the previous first-colon split
+ * stays, so pg reports its own error for a value composer cannot read.
+ *
+ * @param {string} pgUrl - The address as configured
+ * @param {Object} address - Its classification
+ * @returns {{host: string, port: number}} The connection target
+ */
+const pgConnectionTarget = function ( pgUrl, address ) {
+    if ( ( address.kind !== 'unparsed' ) && ( address.port !== undefined ) ) {
+        return { host: address.host, port: address.port };
+    }
+    const [ host, port ] = pgUrl.split( ':' );
+    return { host, port: parseInt( port, 10 ) };
+}; // pgConnectionTarget()
+
+// ============================================================================
+// CONNECT-FAILURE CLASSIFICATION
+// ============================================================================
+
+/**
+ * Node syscall codes that mean an endpoint did not answer. Used at
+ * setup to classify a connect failure as TRANSPORT_UNREACHABLE (the
+ * one split the ADR-018 error vocabulary mandates).
+ * Module-level Set: allocated once at load, membership check at setup.
+ *
+ * @type {Set<string>}
+ */
+const NETWORK_ERROR_CODES = new Set( [
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'ETIMEDOUT',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ECONNRESET',
+    'EAI_AGAIN',
+    'EPIPE'
+] );
+
+/**
+ * Builds the ILP sender and classifies a failure. `fromConfig` may
+ * itself reach the endpoint (a `/settings` fetch for protocol
+ * negotiation), so a network code becomes `TRANSPORT_UNREACHABLE` and
+ * anything else `INVALID_CONFIG`, the same split as the PostgreSQL
+ * connect wrap in the factory. The client's error stays on `err.cause`.
+ *
+ * The agent goes to the client as its `extraOptions.agent` when one is
+ * given (the standard-library transport, ADR-029). With `null` the
+ * client keeps its own agent, which is the undici case.
+ *
+ * @param {Object} SenderClass - The client's Sender class
+ * @param {string} senderConfig - The sender configuration string
+ * @param {string} ilpUrl - The configured `ilpUrl`, for the message
+ * @param {Object|null} agent - The `http.Agent` the adapter owns, or null
+ * @returns {Promise<Object>} The connected sender
+ * @throws {Error} TRANSPORT_UNREACHABLE or INVALID_CONFIG, cause attached
+ */
+const buildSender = async function ( SenderClass, senderConfig, ilpUrl, agent ) {
+    try {
+        return ( agent === null ) ?
+            await SenderClass.fromConfig( senderConfig ) :
+            await SenderClass.fromConfig( senderConfig, { agent } );
+    } catch ( buildErr ) {
+        const code = NETWORK_ERROR_CODES.has( buildErr.code ) ? 'TRANSPORT_UNREACHABLE' : 'INVALID_CONFIG';
+        const err = new Error(
+            `winkComposer/questdb: could not build the ILP sender for ilpUrl '${ilpUrl}' [${code}]: ${buildErr.message}`
+        );
+        err.code = code;
+        err.cause = buildErr;
+        throw err;
+    }
+}; // buildSender()
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export {
+    isAllowedIlpUrl,
+    isAllowedPgUrl,
+    assertNotLocalhost,
+    assertIlpNotIPv6,
+    warnIfName,
+    assertReachable,
+    pgConnectionTarget,
+    NETWORK_ERROR_CODES,
+    buildSender
+};

package/src/core/storage-manager/questdb/delivery-gate.js

@@ -0,0 +1,218 @@
+// core/storage-manager/questdb/delivery-gate.js
+
+/**
+ * @fileoverview Hold and probe: the gate that pauses QuestDB delivery
+ * while the endpoint is unreachable (ADR-029, amendment of 2026-09-05).
+ *
+ * Why it exists. Before this gate, a QuestDB restart of 30 seconds cost
+ * every row written during it. Each interval tick started a flush into
+ * the dead endpoint, each flush failed or hung, and each failure lost
+ * its batch. The gate stops that. After a failed or abandoned engine
+ * flush it runs the ADR-030 probe against `ilpUrl`: one TCP connect
+ * per resolved address, off the hot path. A failing probe pauses
+ * delivery. While paused, the engine starts no flush and rows collect
+ * in the client's buffer up to the ceiling. Each interval tick runs one
+ * probe. When a probe passes, delivery resumes and the engine sends
+ * everything held in one flush. A restart then costs only the batch
+ * that was on the wire when the port closed.
+ *
+ * What the probe finding is for. The loss report carries it, so an
+ * operator reads which address refused and which answered, the same
+ * text the setup probe prints. A passing probe after a failure changes
+ * nothing: the server answered the request and refused it, so the
+ * failure is reported and delivery goes on.
+ *
+ * The three cases after a failure:
+ * - Shutdown is running. Shutdown owns the outcome and reports it in
+ *   its own rejection, so the gate only releases the engine's guard.
+ * - Delivery is paused, or a probe is already running. The loss is
+ *   reported without a finding. The tick, or the running probe,
+ *   decides what happens next.
+ * - Otherwise the probe runs. The engine's guard stays up meanwhile,
+ *   so no new engine flush starts into an endpoint that may be dead.
+ *   When the probe answers, the guard is released, the loss is
+ *   reported with the finding, and a failing probe pauses delivery.
+ *   The release comes first. The report runs user-facing code, and a
+ *   report that threw before the release would leave the guard up for
+ *   good, with no flush able to start again.
+ *
+ * Console lines (ADR-028 grammar, token `CIRCUIT_OPEN` from ADR-018
+ * §9). One `logger.warn` line on pause, with the held row count and
+ * the finding. One `logger.warn` line on resume, with the pause
+ * length and the held count. The resume line is warn, not info, so a
+ * log transport that keeps only warn and above still carries the end
+ * of the episode. Nothing per tick. A probe that itself
+ * throws or rejects counts as a failed probe: the gate must not depend
+ * on the probe's own robustness to decide whether to pause.
+ *
+ * The gate never calls back into the engine. `tick()` resolves to true
+ * when it resumed delivery, and the engine starts the catch-up flush.
+ * `isPaused()` feeds the engine's triggers. One probe runs at a time.
+ *
+ * The gate does tell the flush tracker's ledger about each pause and
+ * resume, through `onPause` and `onResume`. The ledger's ladder, the one
+ * function behind `getHealth()` and the edge lines, reads red while
+ * delivery is paused. So the red edge prints at the pause, before the
+ * `CIRCUIT_OPEN` line, and a later failed flush adds no second red line.
+ *
+ * @see ADR-029
+ * @see ADR-030
+ */
+
+import { logger } from '../../logger/index.js';
+import { monotonicNow } from '../../utils/clock/index.js';
+
+/**
+ * Builds the gate.
+ *
+ * @param {Object} parts - What the gate runs on
+ * @param {Object} parts.probe - The ADR-030 probe bound to `ilpUrl`
+ * @param {function} parts.probe.run - `() => Promise<outcome>`
+ * @param {function} parts.probe.describe - `( outcome ) => string`, the finding for an operator
+ * @param {function} parts.heldRows - `() => number`, rows the engine holds in the buffer now
+ * @param {function} parts.isShuttingDown - `() => boolean`
+ * @param {function} parts.onPause - `( pausedSince, finding ) => void`, tells the ledger delivery paused
+ * @param {function} parts.onResume - `() => void`, tells the ledger delivery resumed, after the resumed line
+ * @returns {{afterFailure: function, tick: function, isPaused: function}}
+ */
+const createDeliveryGate = function ( { probe, heldRows, isShuttingDown, onPause, onResume } ) {
+    // `paused` stops the engine's row and timer triggers. `pausedSince`
+    // is the wall-clock time the pause began, for health, where it
+    // leaves the process. `pausedAt` is the same instant on the
+    // stopwatch, for the resume line's length, so a step in the wall
+    // clock cannot change it (ADR-018). `probing` keeps one probe in
+    // flight at a time.
+    let paused = false;
+    let pausedSince = null;
+    let pausedAt = 0;
+    let probing = false;
+
+    /**
+     * Describes an outcome and never throws. The gate must not depend
+     * on the probe's robustness. A describer that threw would reject
+     * the chain in `runProbe`, and then `afterFailure` would never
+     * report the loss or release the engine's guard: no flush could
+     * start again, and nothing would say so.
+     *
+     * @param {Object} outcome - What `probe.run` resolved with
+     * @returns {string} The operator text, or a fallback naming the throw
+     */
+    const describeSafely = function ( outcome ) {
+        try {
+            return probe.describe( outcome );
+        } catch ( err ) {
+            return `the probe's description failed: ${err.message}`;
+        }
+    }; // describeSafely()
+
+    /**
+     * Runs the probe once and never rejects.
+     *
+     * @returns {Promise<{outcome: Object, finding: string}>} The outcome and its operator text
+     */
+    const runProbe = function () {
+        return Promise.resolve().then( probe.run ).then(
+            function ( outcome ) {
+                return { outcome, finding: describeSafely( outcome ) };
+            },
+            function ( err ) {
+                return { outcome: { ok: false, error: err.message }, finding: `the probe itself failed: ${err.message}` };
+            }
+        );
+    }; // runProbe()
+
+    /**
+     * Pauses delivery after a failing probe. The held count is what the
+     * buffer holds now; it grows until the resume flush carries it.
+     *
+     * @param {string} finding - The probe's operator text
+     */
+    const pause = function ( finding ) {
+        paused = true;
+        pausedSince = Date.now();
+        pausedAt = monotonicNow();
+        // The ledger's ladder turns red on the pause and prints its red
+        // edge first, so the log reads red, then paused.
+        onPause( pausedSince, finding );
+        logger.warn( `winkComposer/questdb: delivery paused, ${heldRows()} row(s) held [CIRCUIT_OPEN]: ${finding}` );
+    }; // pause()
+
+    /**
+     * Resumes delivery after a passing tick probe. The ledger hears it
+     * after the resumed line, so a restored line, when the ladder lands
+     * on green, reads after resumed.
+     *
+     * @param {string} finding - The probe's operator text
+     */
+    const resume = function ( finding ) {
+        const seconds = Math.round( ( monotonicNow() - pausedAt ) / 1000 );
+        paused = false;
+        pausedSince = null;
+        logger.warn(
+            `winkComposer/questdb: delivery resumed after ${seconds} s, ${heldRows()} row(s) held [CIRCUIT_OPEN]: ${finding}`
+        );
+        onResume();
+    }; // resume()
+
+    /**
+     * Routes a failed or abandoned engine flush (the three cases in the
+     * file header). `release()` is called exactly once, when the engine
+     * may start flushes again, and always before `report( probed )`,
+     * which is called exactly once with the probe result or null.
+     *
+     * @param {function} report - `( probed|null ) => void`, reports the loss
+     * @param {function} release - `() => void`, lowers the engine's guard
+     */
+    const afterFailure = function ( report, release ) {
+        if ( isShuttingDown() ) {
+            release();
+            return;
+        }
+        if ( paused || probing ) {
+            release();
+            report( null );
+            return;
+        }
+        probing = true;
+        runProbe().then( function ( probed ) {
+            probing = false;
+            // Release before the report: nothing runs between the two,
+            // and a report that throws must not leave the guard up.
+            release();
+            report( probed );
+            if ( !isShuttingDown() && !probed.outcome.ok ) {
+                pause( probed.finding );
+            }
+        } );
+    }; // afterFailure()
+
+    /**
+     * The tick while paused: one probe at a time, nothing printed.
+     *
+     * @returns {Promise<boolean>} True when this tick resumed delivery
+     */
+    const tick = function () {
+        if ( probing ) {
+            return Promise.resolve( false );
+        }
+        probing = true;
+        return runProbe().then( function ( probed ) {
+            probing = false;
+            if ( isShuttingDown() || !probed.outcome.ok ) {
+                return false;
+            }
+            resume( probed.finding );
+            return true;
+        } );
+    }; // tick()
+
+    return {
+        afterFailure,
+        tick,
+        isPaused: function () {
+            return paused;
+        }
+    };
+}; // createDeliveryGate()
+
+export { createDeliveryGate };