camusdb 0.1.0

package/dist/config.js

@@ -0,0 +1,315 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { NO_CREDENTIALS, credentialsFromPassword, credentialsFromToken, hasCredentials, } from './auth/credentials.js';
+import { parseConnectionString, redactConnectionString } from './connection-string.js';
+import { CamusEndpointPool } from './endpoint-pool.js';
+import { CamusError } from './errors.js';
+import { CamusErrorCode } from './error-codes.js';
+import { CamusIsolationLevel, CamusLocking, CamusTransactionMode } from './options.js';
+/** The wire protocol a client speaks. */
+export const CamusProtocol = {
+    /** The REST and JSON HTTP API. This is the default. */
+    Rest: 'rest',
+    /** The gRPC API. The endpoint must address the server's gRPC port. */
+    Grpc: 'grpc',
+};
+/** How a client uses learned statement routing. */
+export const CamusRoutingMode = {
+    /** Rotate over the configured endpoints. Never negotiate, never learn. */
+    Off: 'off',
+    /** Negotiate routing metadata and prefer a learned destination for an unpinned statement. */
+    Learned: 'learned',
+    /**
+     * Behave as `learned` when `routingNodes` maps at least two distinct configured endpoints, and
+     * as `off` otherwise. One destination is not a routing decision, and a single load-balancer URL
+     * is not a set of routable database nodes. This is the default: the trust map is the opt-in, not
+     * a second switch.
+     */
+    Auto: 'auto',
+};
+export const DEFAULT_BATCH_OPTIONS = Object.freeze({
+    channelPoolSize: 2,
+    coalescingThreshold: 10,
+    coalescingDelayMs: 0,
+});
+/** How many statements a client keeps prepared, and how hot a statement must be first. */
+export const DEFAULT_MAX_AUTO_PREPARE = 128;
+export const DEFAULT_AUTO_PREPARE_MIN_USAGES = 2;
+/** Fallback token lifetime, comfortably inside the server's 15-minute default. */
+export const DEFAULT_TOKEN_LIFETIME_MS = 600_000;
+/** The backup admin API's own timeout. Taking a full backup routinely outlasts a statement. */
+export const DEFAULT_BACKUP_TIMEOUT_SECONDS = 300;
+/** The connection-string key that waives the refusal to send credentials in the clear. */
+export const ALLOW_INSECURE_CREDENTIALS_KEY = 'AllowInsecureCredentials';
+/** Resolves an options object. */
+export function resolveOptions(options) {
+    const endpointList = Array.isArray(options.endpoint)
+        ? options.endpoint.join(',')
+        : options.endpoint;
+    if (typeof endpointList !== 'string' || endpointList.trim().length === 0) {
+        throw new CamusError(CamusErrorCode.Generic, 'Endpoint is required.');
+    }
+    if (typeof options.database !== 'string' || options.database.trim().length === 0) {
+        throw new CamusError(CamusErrorCode.Generic, 'Database is required.');
+    }
+    const config = {
+        endpointList,
+        database: options.database,
+        timeoutSeconds: positiveOr(options.timeoutSeconds, 10),
+        protocol: options.protocol ?? CamusProtocol.Rest,
+        credentials: resolveCredentials(options),
+        tokenLifetimeMs: positiveOr(options.tokenLifetimeSeconds, 0) * 1000 || DEFAULT_TOKEN_LIFETIME_MS,
+        maxAutoPrepare: nonNegativeOr(options.maxAutoPrepare, DEFAULT_MAX_AUTO_PREPARE),
+        autoPrepareMinUsages: positiveOr(options.autoPrepareMinUsages, DEFAULT_AUTO_PREPARE_MIN_USAGES),
+        batch: {
+            channelPoolSize: atLeastOr(options.channelPoolSize, 1, DEFAULT_BATCH_OPTIONS.channelPoolSize),
+            coalescingThreshold: atLeastOr(options.coalescingThreshold, 1, DEFAULT_BATCH_OPTIONS.coalescingThreshold),
+            coalescingDelayMs: atLeastOr(options.coalescingDelayMs, 0, DEFAULT_BATCH_OPTIONS.coalescingDelayMs),
+        },
+        backupEndpoint: options.backupEndpoint,
+        backupTimeoutSeconds: positiveOr(options.backupTimeoutSeconds, DEFAULT_BACKUP_TIMEOUT_SECONDS),
+        allowInsecureCredentials: options.allowInsecureCredentials === true,
+        routingMode: options.routingMode ?? CamusRoutingMode.Auto,
+        routingNodes: resolveRoutingNodes(options.routingNodes, endpointList),
+        routingMaxHintAgeMs: atLeastOr(options.routingMaxHintAgeMs, 1, 5000),
+        defaultTransactionOptions: options.defaultTransactionOptions ?? {},
+        decode: { int64: options.int64 ?? 'auto' },
+        connectionString: undefined,
+    };
+    ensureCredentialsAreNotSentInClear(config);
+    return config;
+}
+/** Resolves a connection string. */
+export function resolveConnectionString(connectionString) {
+    const settings = parseConnectionString(connectionString);
+    const endpointList = settings.get('Endpoint');
+    if (endpointList === undefined || endpointList.trim().length === 0) {
+        throw new CamusError(CamusErrorCode.Generic, 'Endpoint is required.');
+    }
+    const database = settings.get('Database');
+    if (database === undefined) {
+        throw new CamusError(CamusErrorCode.Generic, 'Database is required.');
+    }
+    const config = {
+        endpointList,
+        database,
+        timeoutSeconds: parsePositiveInt(settings.get('Timeout'), 10),
+        protocol: parseEnum(settings.get('Protocol'), CamusProtocol, CamusProtocol.Rest),
+        credentials: credentialsFromSettings(settings),
+        tokenLifetimeMs: parsePositiveInt(settings.get('TokenLifetime'), 0) * 1000 || DEFAULT_TOKEN_LIFETIME_MS,
+        maxAutoPrepare: parseNonNegativeInt(settings.get('MaxAutoPrepare'), DEFAULT_MAX_AUTO_PREPARE),
+        autoPrepareMinUsages: parsePositiveInt(settings.get('AutoPrepareMinUsages'), DEFAULT_AUTO_PREPARE_MIN_USAGES),
+        batch: {
+            channelPoolSize: parseIntAtLeast(settings.get('ChannelPoolSize'), 1, DEFAULT_BATCH_OPTIONS.channelPoolSize),
+            coalescingThreshold: parseIntAtLeast(settings.get('CoalescingThreshold'), 1, DEFAULT_BATCH_OPTIONS.coalescingThreshold),
+            coalescingDelayMs: parseIntAtLeast(settings.get('CoalescingDelay'), 0, DEFAULT_BATCH_OPTIONS.coalescingDelayMs),
+        },
+        backupEndpoint: settings.first('BackupEndpoint'),
+        backupTimeoutSeconds: parsePositiveInt(settings.get('BackupTimeout'), DEFAULT_BACKUP_TIMEOUT_SECONDS),
+        allowInsecureCredentials: settings.get(ALLOW_INSECURE_CREDENTIALS_KEY)?.toLowerCase() === 'true',
+        routingMode: parseEnum(settings.get('RoutingMode'), CamusRoutingMode, CamusRoutingMode.Auto),
+        routingNodes: resolveRoutingNodes(settings.get('RoutingNodes'), endpointList),
+        routingMaxHintAgeMs: parseIntAtLeast(settings.get('RoutingMaxHintAge'), 1, 5000),
+        defaultTransactionOptions: {
+            isolationLevel: parseEnum(settings.get('IsolationLevel'), CamusIsolationLevel, undefined),
+            mode: parseEnum(settings.get('TransactionMode'), CamusTransactionMode, undefined),
+            locking: parseEnum(settings.get('Locking'), CamusLocking, undefined),
+        },
+        decode: { int64: parseInt64Mode(settings.get('Int64')) },
+        connectionString,
+    };
+    ensureCredentialsAreNotSentInClear(config);
+    return config;
+}
+/**
+ * Where the backup admin API lives.
+ *
+ * The backup routes are REST and JSON only — they have no SQL form and no gRPC service — so a gRPC
+ * client, whose endpoint addresses the gRPC port, must say where the HTTP port is. Rather than
+ * send HTTP at a gRPC port and fail obscurely, that case is refused with a message naming the
+ * setting to fill in.
+ *
+ * A configured backup endpoint is used as written, with no rotation: backups are node-level, and a
+ * coordinated backup must reach the coordinator specifically.
+ */
+export function resolveBackupEndpoint(config, pool) {
+    if (config.backupEndpoint !== undefined && config.backupEndpoint.trim().length > 0) {
+        return config.backupEndpoint;
+    }
+    if (config.protocol !== CamusProtocol.Rest) {
+        throw new CamusError(CamusErrorCode.Generic, 'The backup admin API is REST-only; a gRPC client must set backupEndpoint to the server’s HTTP endpoint.');
+    }
+    return pool.next();
+}
+/**
+ * Identifies the deployment when deciding which clients may share a token or a transport: the
+ * endpoint list plus the protocol. The same credentials against two different servers never share
+ * a token, and a REST client and a gRPC client each hold the token their own transport minted.
+ */
+export function deploymentKey(config) {
+    return `${config.endpointList}|${config.protocol}`;
+}
+/** The connection string with every secret masked, or a rebuilt summary for an options object. */
+export function describeConfig(config) {
+    if (config.connectionString !== undefined)
+        return redactConnectionString(config.connectionString);
+    const parts = [`Endpoint=${config.endpointList}`, `Database=${config.database}`];
+    if (config.protocol !== CamusProtocol.Rest)
+        parts.push(`Protocol=${config.protocol}`);
+    if (config.credentials.user !== undefined)
+        parts.push(`User=${config.credentials.user};Password=***`);
+    if (config.credentials.accessToken !== undefined)
+        parts.push('AccessToken=***');
+    return parts.join(';');
+}
+/**
+ * Refuses to carry credentials to an endpoint that cannot protect them.
+ *
+ * A password is posted to `/login` and a bearer token rides every later request. On an `http://`
+ * endpoint both cross the network in the clear, and the server's own `CADB0519` check — which a
+ * deployment can switch off — only fires after the password has already been sent. So the client
+ * refuses first, before anything leaves the process.
+ *
+ * A loopback endpoint is allowed: the traffic never reaches a network, and that is how the
+ * documented local examples and the test suite connect. Everything else must be `https://`, unless
+ * `allowInsecureCredentials` is set — for a deployment reached over a private link that terminates
+ * TLS elsewhere.
+ *
+ * The backup endpoint is held to the same rule, and deliberately: the token it receives is the
+ * client's own, which the backup admin API requires to be superuser-grade.
+ */
+export function ensureCredentialsAreNotSentInClear(config) {
+    if (!hasCredentials(config.credentials))
+        return;
+    if (config.allowInsecureCredentials)
+        return;
+    for (const endpoint of config.endpointList.split(',')) {
+        const trimmed = endpoint.trim();
+        if (trimmed.length > 0)
+            ensureEndpointIsSecure(trimmed, 'Endpoint');
+    }
+    if (config.backupEndpoint !== undefined && config.backupEndpoint.trim().length > 0) {
+        ensureEndpointIsSecure(config.backupEndpoint.trim(), 'BackupEndpoint');
+    }
+}
+function ensureEndpointIsSecure(endpoint, key) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new CamusError(CamusErrorCode.Generic, `The ${key} '${endpoint}' is not an absolute URL.`);
+    }
+    if (url.protocol === 'https:' || isLoopback(url.hostname))
+        return;
+    throw new CamusError(CamusErrorCode.InsecureTransport, `This configuration sends credentials to the ${key} '${endpoint}', which is neither https nor loopback. ` +
+        'The password and the bearer token would cross the network in the clear. Use https, or set ' +
+        `${ALLOW_INSECURE_CREDENTIALS_KEY} when the endpoint is reached over a link that protects them.`);
+}
+function isLoopback(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return host === 'localhost' || host === '::1' || host === '0:0:0:0:0:0:0:1' || /^127\./.test(host);
+}
+function resolveCredentials(options) {
+    if (options.accessToken !== undefined && options.accessToken.length > 0) {
+        return credentialsFromToken(options.accessToken);
+    }
+    if (options.user !== undefined && options.user.length > 0) {
+        return credentialsFromPassword(options.user, options.password ?? '');
+    }
+    return NO_CREDENTIALS;
+}
+function credentialsFromSettings(settings) {
+    const token = settings.first('AccessToken');
+    if (token !== undefined)
+        return credentialsFromToken(token);
+    const user = settings.first('User', 'UserId', 'Uid', 'Username');
+    if (user !== undefined) {
+        return credentialsFromPassword(user, settings.get('Password') ?? settings.get('Pwd') ?? '');
+    }
+    return NO_CREDENTIALS;
+}
+/**
+ * The trust map, filtered to addresses the endpoint pool actually lists.
+ *
+ * Advice becomes a destination only through this map, and only when the mapped address is a member
+ * of the endpoint pool. An entry naming any other address is dropped, so a response can never
+ * steer traffic at an address the operator did not list. Malformed entries are skipped rather than
+ * thrown on, the way the other tuning settings treat unusable input.
+ */
+function resolveRoutingNodes(nodes, endpointList) {
+    const map = new Map();
+    if (nodes === undefined)
+        return map;
+    const pool = CamusEndpointPool.forEndpoints(endpointList);
+    const pairs = [];
+    if (typeof nodes === 'string') {
+        for (const entry of nodes.split(',')) {
+            const trimmed = entry.trim();
+            if (trimmed.length === 0)
+                continue;
+            // The node identity is `host:port` and the address is a URL, so the first '=' is the only
+            // separator that is not ambiguous.
+            const separator = trimmed.indexOf('=');
+            if (separator <= 0 || separator === trimmed.length - 1)
+                continue;
+            pairs.push([trimmed.slice(0, separator).trim(), trimmed.slice(separator + 1).trim()]);
+        }
+    }
+    else {
+        for (const [nodeId, address] of Object.entries(nodes)) {
+            pairs.push([nodeId.trim(), address.trim()]);
+        }
+    }
+    for (const [nodeId, address] of pairs) {
+        if (nodeId.length > 0 && pool.contains(address))
+            map.set(nodeId, address);
+    }
+    return map;
+}
+function parseEnum(raw, members, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const wanted = raw.trim().toLowerCase();
+    for (const value of Object.values(members)) {
+        if (value.toLowerCase() === wanted)
+            return value;
+    }
+    return fallback;
+}
+function parseInt64Mode(raw) {
+    switch (raw?.trim().toLowerCase()) {
+        case 'number':
+            return 'number';
+        case 'bigint':
+            return 'bigint';
+        default:
+            return 'auto';
+    }
+}
+function parsePositiveInt(raw, fallback) {
+    const parsed = Number.parseInt(raw ?? '', 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function parseNonNegativeInt(raw, fallback) {
+    const parsed = Number.parseInt(raw ?? '', 10);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function parseIntAtLeast(raw, minimum, fallback) {
+    const parsed = Number.parseInt(raw ?? '', 10);
+    return Number.isInteger(parsed) && parsed >= minimum ? parsed : fallback;
+}
+function positiveOr(value, fallback) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function nonNegativeOr(value, fallback) {
+    return value !== undefined && Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+}
+function atLeastOr(value, minimum, fallback) {
+    return value !== undefined && Number.isFinite(value) && value >= minimum ? Math.floor(value) : fallback;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/connection-string.d.ts

@@ -0,0 +1,45 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * The parsed settings, keyed by lowercase key name. The original spelling of each key is kept so a
+ * diagnostic can name the key the way the caller wrote it.
+ */
+export declare class ConnectionStringSettings {
+    private readonly entries;
+    constructor(entries: Iterable<{
+        key: string;
+        value: string;
+    }>);
+    /** The value for a key, or `undefined`. Matching ignores case. */
+    get(key: string): string | undefined;
+    /** The first key of `keys` that has a value that is not blank. */
+    first(...keys: string[]): string | undefined;
+    /** True when the key is present, even with an empty value. */
+    has(key: string): boolean;
+    /** Replaces or adds a value. Used by `changeDatabase`. */
+    set(key: string, value: string): void;
+    /** Every key and value, in insertion order. */
+    [Symbol.iterator](): IterableIterator<{
+        key: string;
+        value: string;
+    }>;
+}
+/**
+ * Parses a connection string.
+ *
+ * @throws {CamusError} `CADB0000` when a key appears twice, or a quoted value is not closed.
+ */
+export declare function parseConnectionString(connectionString: string): ConnectionStringSettings;
+/**
+ * The connection string with every secret replaced by `***`. Everything else, including the
+ * original spelling and order of the keys, is left as written, so the result still identifies the
+ * connection.
+ *
+ * Use it for anything that is logged, printed, or reported as diagnostics.
+ */
+export declare function redactConnectionString(connectionString: string | undefined | null): string;
+//# sourceMappingURL=connection-string.d.ts.map

package/dist/connection-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-string.d.ts","sourceRoot":"","sources":["../src/connection-string.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH;;;GAGG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqD;gBAEjE,OAAO,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAM7D,kEAAkE;IAClE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpC,kEAAkE;IAClE,KAAK,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS;IAS5C,8DAA8D;IAC9D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,0DAA0D;IAC1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC,+CAA+C;IAC9C,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAGvE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,wBAAwB,CAoBxF;AAWD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CA4B1F"}

package/dist/connection-string.js

@@ -0,0 +1,170 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { CamusError } from './errors.js';
+import { CamusErrorCode } from './error-codes.js';
+/**
+ * The parsed settings, keyed by lowercase key name. The original spelling of each key is kept so a
+ * diagnostic can name the key the way the caller wrote it.
+ */
+export class ConnectionStringSettings {
+    entries = new Map();
+    constructor(entries) {
+        for (const entry of entries) {
+            this.entries.set(entry.key.toLowerCase(), entry);
+        }
+    }
+    /** The value for a key, or `undefined`. Matching ignores case. */
+    get(key) {
+        return this.entries.get(key.toLowerCase())?.value;
+    }
+    /** The first key of `keys` that has a value that is not blank. */
+    first(...keys) {
+        for (const key of keys) {
+            const value = this.get(key);
+            if (value !== undefined && value.trim().length > 0)
+                return value;
+        }
+        return undefined;
+    }
+    /** True when the key is present, even with an empty value. */
+    has(key) {
+        return this.entries.has(key.toLowerCase());
+    }
+    /** Replaces or adds a value. Used by `changeDatabase`. */
+    set(key, value) {
+        const existing = this.entries.get(key.toLowerCase());
+        this.entries.set(key.toLowerCase(), { key: existing?.key ?? key, value });
+    }
+    /** Every key and value, in insertion order. */
+    *[Symbol.iterator]() {
+        yield* this.entries.values();
+    }
+}
+/**
+ * Parses a connection string.
+ *
+ * @throws {CamusError} `CADB0000` when a key appears twice, or a quoted value is not closed.
+ */
+export function parseConnectionString(connectionString) {
+    const seen = new Set();
+    const entries = [];
+    for (const setting of enumerateSettings(connectionString)) {
+        const lowercase = setting.key.toLowerCase();
+        if (seen.has(lowercase)) {
+            throw new CamusError(CamusErrorCode.Generic, `The connection string sets '${setting.key}' more than once. Keys are matched without regard ` +
+                'to case; remove the duplicate.');
+        }
+        seen.add(lowercase);
+        entries.push({ key: setting.key, value: setting.value });
+    }
+    return new ConnectionStringSettings(entries);
+}
+/** The keys whose values a redacted string masks. */
+const SECRET_KEYS = new Set(['password', 'pwd', 'accesstoken']);
+/**
+ * What a masked secret is replaced with. Not the empty string: an empty value reads as "no
+ * password was configured", which is a different fact.
+ */
+const REDACTED = '***';
+/**
+ * The connection string with every secret replaced by `***`. Everything else, including the
+ * original spelling and order of the keys, is left as written, so the result still identifies the
+ * connection.
+ *
+ * Use it for anything that is logged, printed, or reported as diagnostics.
+ */
+export function redactConnectionString(connectionString) {
+    if (connectionString === undefined || connectionString === null || connectionString.trim().length === 0) {
+        return connectionString ?? '';
+    }
+    let settings;
+    try {
+        settings = enumerateSettings(connectionString);
+    }
+    catch {
+        // A string that cannot be parsed cannot be masked reliably, and printing it might disclose the
+        // secret it failed to parse. Report nothing rather than guess.
+        return REDACTED;
+    }
+    let out = '';
+    let copied = 0;
+    for (const setting of settings) {
+        if (!SECRET_KEYS.has(setting.key.toLowerCase()))
+            continue;
+        // The value's text is replaced in place, keeping any quotes around it, so the shape of the
+        // string does not change.
+        out += connectionString.slice(copied, setting.valueStart) + REDACTED;
+        copied = setting.valueStart + setting.valueLength;
+    }
+    return out + connectionString.slice(copied);
+}
+function enumerateSettings(source) {
+    const settings = [];
+    let position = 0;
+    while (position < source.length) {
+        // The key runs to the next '=' or ';'.
+        const keyStart = position;
+        while (position < source.length && source[position] !== '=' && source[position] !== ';') {
+            position++;
+        }
+        if (position >= source.length || source[position] === ';') {
+            // A segment with no '=' carries nothing to set. Skip it and take the next one.
+            position++;
+            continue;
+        }
+        const key = source.slice(keyStart, position).trim();
+        position++; // past the '='
+        while (position < source.length && (source[position] === ' ' || source[position] === '\t')) {
+            position++;
+        }
+        let valueStart;
+        let valueLength;
+        let value;
+        const quote = source[position];
+        if (quote === "'" || quote === '"') {
+            position++;
+            valueStart = position;
+            for (;;) {
+                if (position >= source.length) {
+                    throw new CamusError(CamusErrorCode.Generic, `The connection string has an unclosed ${quote} quoted value. Double the quote character ` +
+                        'to include one in a value.');
+                }
+                if (source[position] === quote) {
+                    // A doubled quote is one literal quote, not the end of the value.
+                    if (source[position + 1] === quote) {
+                        position += 2;
+                        continue;
+                    }
+                    break;
+                }
+                position++;
+            }
+            valueLength = position - valueStart;
+            value = source.slice(valueStart, position).replaceAll(quote + quote, quote);
+            position++; // past the closing quote
+            // Anything between the closing quote and the ';' is whitespace or a typo. Skip to the ';'.
+            while (position < source.length && source[position] !== ';')
+                position++;
+        }
+        else {
+            const rawStart = position;
+            while (position < source.length && source[position] !== ';')
+                position++;
+            const raw = source.slice(rawStart, position);
+            const leading = raw.length - raw.trimStart().length;
+            value = raw.trim();
+            valueStart = rawStart + leading;
+            valueLength = value.length;
+        }
+        position++; // past the ';'
+        if (key.length > 0) {
+            settings.push({ key, value, valueStart, valueLength });
+        }
+    }
+    return settings;
+}
+//# sourceMappingURL=connection-string.js.map

package/dist/connection-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-string.js","sourceRoot":"","sources":["../src/connection-string.ts"],"names":[],"mappings":"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"}

package/dist/endpoint-pool.d.ts

@@ -0,0 +1,70 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * The endpoints one deployment's clients rotate through, and which of them are set aside after
+ * failing to answer at all.
+ *
+ * A pool is shared per endpoint list rather than owned by one client. The rotation and the health
+ * it depends on are properties of the deployment; a per-client pool would restart its rotation at
+ * the first endpoint on every request.
+ *
+ * Quarantine expires. A pool that outlives the request that marked an endpoint cannot mark it
+ * forever: with a single endpoint configured — the common case — the first refused connection
+ * would otherwise end the process's ability to reach the database at all, long after the node came
+ * back. An endpoint is set aside for `QUARANTINE_PERIOD_MS` and then drawn again; a node that is
+ * still down is simply marked again by the request that draws it, at a cost of one failed request
+ * per period.
+ */
+export declare class CamusEndpointPool {
+    /** How long an endpoint that failed at the transport level is passed over. */
+    static readonly QUARANTINE_PERIOD_MS = 30000;
+    private static readonly shared;
+    /**
+     * The process-wide pool for an endpoint list, built on first use. Keyed by the list alone, so
+     * clients that differ only in database, credentials, or timeout share one rotation and one view
+     * of which nodes are answering.
+     */
+    static forEndpoints(endpointList: string): CamusEndpointPool;
+    /** @internal Test hook: drops every shared pool. */
+    static resetShared(): void;
+    private readonly endpoints;
+    /**
+     * Monotonic-clock deadlines, indexed alongside `endpoints`. Zero — the initial value — is in the
+     * past, so an endpoint that has never failed needs no special case.
+     */
+    private readonly quarantinedUntil;
+    private nextIndex;
+    /** @internal Test hook: the monotonic clock this pool reads. */
+    clock: () => number;
+    constructor(endpointList: string);
+    /** Every configured endpoint, in the order it was written. */
+    get members(): readonly string[];
+    /**
+     * The next endpoint to send to, skipping those in quarantine.
+     *
+     * When every endpoint is quarantined the one closest to leaving is returned rather than an
+     * error. The deployment is evidently down, and letting the request go and fail against the real
+     * node reports why, where a synthetic "no endpoints" would replace the server's diagnosis with
+     * the driver's bookkeeping.
+     */
+    next(): string;
+    /**
+     * Whether an endpoint is currently set aside. Learned routing reads it before preferring an
+     * endpoint, so a route pointing at a node that stopped answering falls back to rotation. An
+     * address the pool does not know reports as not quarantined.
+     */
+    isQuarantined(endpoint: string): boolean;
+    /**
+     * Whether an address is one of the configured endpoints. The routing trust map uses it to refuse
+     * mapping a node identity to any address the operator did not list.
+     */
+    contains(endpoint: string): boolean;
+    /** Sets an endpoint aside, so the endpoints that are answering carry the traffic meanwhile. */
+    markUnreachable(endpoint: string): void;
+    private indexOf;
+}
+//# sourceMappingURL=endpoint-pool.d.ts.map

package/dist/endpoint-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-pool.d.ts","sourceRoot":"","sources":["../src/endpoint-pool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAC5B,8EAA8E;IAC9E,MAAM,CAAC,QAAQ,CAAC,oBAAoB,SAAU;IAE9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAA2C;IAEzE;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,iBAAiB;IAI5D,oDAAoD;IACpD,MAAM,CAAC,WAAW,IAAI,IAAI;IAI1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IAErC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;IAE5C,OAAO,CAAC,SAAS,CAAK;IAEtB,gEAAgE;IAChE,KAAK,EAAE,MAAM,MAAM,CAA2B;gBAElC,YAAY,EAAE,MAAM;IAahC,8DAA8D;IAC9D,IAAI,OAAO,IAAI,SAAS,MAAM,EAAE,CAE/B;IAED;;;;;;;OAOG;IACH,IAAI,IAAI,MAAM;IAkBd;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAOxC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAInC,+FAA+F;IAC/F,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOvC,OAAO,CAAC,OAAO;CAShB"}