@rsdk/db 5.12.0-next.7 → 5.12.0-next.9

package/dist/index.d.ts

@@ -7,3 +7,5 @@ export { Propagation } from './propagation.enum';
 export { HEALTH_CHECK_QUERY } from './constants';
 export { getSecureContextOptions } from './tls';
 export { SslModeEnum } from './ssl-mode.enum';
+export { MultiHostUrl, MultiHostUrlParser, MultiHostResolver, InvalidMultiHostUrl, InvalidMultiHostProtocol, MultiHostNativeRequired, pgProbe, resolveDbConnection, } from './multi-host-url';
+export type { MultiHostEntry, MultiHostUrlInit, MultiHostProbe, PgNativeModule, ResolveDbConnectionOptions, ResolvedDbConnection, } from './multi-host-url';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SslModeEnum = exports.getSecureContextOptions = exports.HEALTH_CHECK_QUERY = exports.Propagation = exports.TransactionRunner = exports.IncompatibleIsolationLevels = exports.CallOutOfContextWithMandatory = exports.NeverRunningInTransaction = exports.BaseContext = exports.ContextStorage = void 0;
+exports.resolveDbConnection = exports.pgProbe = exports.MultiHostNativeRequired = exports.InvalidMultiHostProtocol = exports.InvalidMultiHostUrl = exports.MultiHostResolver = exports.MultiHostUrlParser = exports.MultiHostUrl = exports.SslModeEnum = exports.getSecureContextOptions = exports.HEALTH_CHECK_QUERY = exports.Propagation = exports.TransactionRunner = exports.IncompatibleIsolationLevels = exports.CallOutOfContextWithMandatory = exports.NeverRunningInTransaction = exports.BaseContext = exports.ContextStorage = void 0;
 var context_storage_1 = require("./context.storage");
 Object.defineProperty(exports, "ContextStorage", { enumerable: true, get: function () { return context_storage_1.ContextStorage; } });
 var context_base_1 = require("./context.base");
@@ -19,4 +19,13 @@ var tls_1 = require("./tls");
 Object.defineProperty(exports, "getSecureContextOptions", { enumerable: true, get: function () { return tls_1.getSecureContextOptions; } });
 var ssl_mode_enum_1 = require("./ssl-mode.enum");
 Object.defineProperty(exports, "SslModeEnum", { enumerable: true, get: function () { return ssl_mode_enum_1.SslModeEnum; } });
+var multi_host_url_1 = require("./multi-host-url");
+Object.defineProperty(exports, "MultiHostUrl", { enumerable: true, get: function () { return multi_host_url_1.MultiHostUrl; } });
+Object.defineProperty(exports, "MultiHostUrlParser", { enumerable: true, get: function () { return multi_host_url_1.MultiHostUrlParser; } });
+Object.defineProperty(exports, "MultiHostResolver", { enumerable: true, get: function () { return multi_host_url_1.MultiHostResolver; } });
+Object.defineProperty(exports, "InvalidMultiHostUrl", { enumerable: true, get: function () { return multi_host_url_1.InvalidMultiHostUrl; } });
+Object.defineProperty(exports, "InvalidMultiHostProtocol", { enumerable: true, get: function () { return multi_host_url_1.InvalidMultiHostProtocol; } });
+Object.defineProperty(exports, "MultiHostNativeRequired", { enumerable: true, get: function () { return multi_host_url_1.MultiHostNativeRequired; } });
+Object.defineProperty(exports, "pgProbe", { enumerable: true, get: function () { return multi_host_url_1.pgProbe; } });
+Object.defineProperty(exports, "resolveDbConnection", { enumerable: true, get: function () { return multi_host_url_1.resolveDbConnection; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAmD;AAA1C,iHAAA,cAAc,OAAA;AACvB,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AAEpB,2CAIsB;AAHpB,uHAAA,yBAAyB,OAAA;AACzB,2HAAA,6BAA6B,OAAA;AAC7B,yHAAA,2BAA2B,OAAA;AAE7B,+DAA2D;AAAlD,yHAAA,iBAAiB,OAAA;AAC1B,uDAAiD;AAAxC,+GAAA,WAAW,OAAA;AACpB,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA;AAC3B,6BAAgD;AAAvC,8GAAA,uBAAuB,OAAA;AAChC,iDAA8C;AAArC,4GAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAmD;AAA1C,iHAAA,cAAc,OAAA;AACvB,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AAEpB,2CAIsB;AAHpB,uHAAA,yBAAyB,OAAA;AACzB,2HAAA,6BAA6B,OAAA;AAC7B,yHAAA,2BAA2B,OAAA;AAE7B,+DAA2D;AAAlD,yHAAA,iBAAiB,OAAA;AAC1B,uDAAiD;AAAxC,+GAAA,WAAW,OAAA;AACpB,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA;AAC3B,6BAAgD;AAAvC,8GAAA,uBAAuB,OAAA;AAChC,iDAA8C;AAArC,4GAAA,WAAW,OAAA;AACpB,mDAS0B;AARxB,8GAAA,YAAY,OAAA;AACZ,oHAAA,kBAAkB,OAAA;AAClB,mHAAA,iBAAiB,OAAA;AACjB,qHAAA,mBAAmB,OAAA;AACnB,0HAAA,wBAAwB,OAAA;AACxB,yHAAA,uBAAuB,OAAA;AACvB,yGAAA,OAAO,OAAA;AACP,qHAAA,mBAAmB,OAAA"}

package/dist/multi-host-url/exception.d.ts

@@ -0,0 +1,18 @@
+import { BootstrapException } from '@rsdk/core';
+export declare class InvalidMultiHostUrl extends BootstrapException {
+    constructor(str: string, cause?: unknown);
+}
+export declare class InvalidMultiHostProtocol extends BootstrapException {
+    constructor(expectedProtocols: string[], protocol: string, url: string);
+}
+/**
+ * Multi-host URL задан, но `pg-native` не установлен — runtime failover
+ * через libpq невозможен. По умолчанию `resolveDbConnection` падает на
+ * старте, чтобы single-host pool не выдавался под обещание failover,
+ * которого не будет. Чтобы разрешить тихий фолбэк на bootstrap-resolve,
+ * передайте в `resolveDbConnection` поле `bootstrapProbe` — в плагинах
+ * `@rsdk/db.*` это управляется env-переменной `DB_MULTIHOST_BOOTSTRAP_FALLBACK`.
+ */
+export declare class MultiHostNativeRequired extends BootstrapException {
+    constructor(hostsCount: number);
+}

package/dist/multi-host-url/exception.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiHostNativeRequired = exports.InvalidMultiHostProtocol = exports.InvalidMultiHostUrl = void 0;
+const core_1 = require("@rsdk/core");
+/**
+ * Заменяет `userinfo` (`user:pass@`) в URL-подобной строке на `***:***@`,
+ * чтобы пароль из `DB_URL` не попадал в логи через message/details ошибки.
+ */
+const maskUrlCredentials = (str) => str.replace(/(:\/\/)[^/@\s]+@/u, '$1***:***@');
+class InvalidMultiHostUrl extends core_1.BootstrapException {
+    constructor(str, cause) {
+        super(`Invalid multi-host url string: <${maskUrlCredentials(str)}>`, {
+            cause,
+        });
+    }
+}
+exports.InvalidMultiHostUrl = InvalidMultiHostUrl;
+class InvalidMultiHostProtocol extends core_1.BootstrapException {
+    constructor(expectedProtocols, protocol, url) {
+        super(`Invalid protocol: <${protocol}>, expected: ${expectedProtocols}`, {
+            details: {
+                protocol,
+                url: maskUrlCredentials(url),
+                expected: expectedProtocols,
+            },
+        });
+    }
+}
+exports.InvalidMultiHostProtocol = InvalidMultiHostProtocol;
+/**
+ * Multi-host URL задан, но `pg-native` не установлен — runtime failover
+ * через libpq невозможен. По умолчанию `resolveDbConnection` падает на
+ * старте, чтобы single-host pool не выдавался под обещание failover,
+ * которого не будет. Чтобы разрешить тихий фолбэк на bootstrap-resolve,
+ * передайте в `resolveDbConnection` поле `bootstrapProbe` — в плагинах
+ * `@rsdk/db.*` это управляется env-переменной `DB_MULTIHOST_BOOTSTRAP_FALLBACK`.
+ */
+class MultiHostNativeRequired extends core_1.BootstrapException {
+    constructor(hostsCount) {
+        super(`multi-host db: \`pg-native\` is not installed but URL has ${hostsCount} hosts. ` +
+            'Install `pg-native` (and a system libpq) for libpq runtime failover, ' +
+            'or pass `bootstrapProbe` to resolveDbConnection to allow falling back ' +
+            'to bootstrap-resolve (no runtime failover). In @rsdk/db.* plugins this ' +
+            'is controlled by DB_MULTIHOST_BOOTSTRAP_FALLBACK=true.');
+    }
+}
+exports.MultiHostNativeRequired = MultiHostNativeRequired;
+//# sourceMappingURL=exception.js.map

package/dist/multi-host-url/exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exception.js","sourceRoot":"","sources":["../../src/multi-host-url/exception.ts"],"names":[],"mappings":";;;AAAA,qCAAgD;AAEhD;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAU,EAAE,CACjD,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,YAAY,CAAC,CAAC;AAEjD,MAAa,mBAAoB,SAAQ,yBAAkB;IACzD,YAAY,GAAW,EAAE,KAAe;QACtC,KAAK,CAAC,mCAAmC,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE;YACnE,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAND,kDAMC;AAED,MAAa,wBAAyB,SAAQ,yBAAkB;IAC9D,YAAY,iBAA2B,EAAE,QAAgB,EAAE,GAAW;QACpE,KAAK,CAAC,sBAAsB,QAAQ,gBAAgB,iBAAiB,EAAE,EAAE;YACvE,OAAO,EAAE;gBACP,QAAQ;gBACR,GAAG,EAAE,kBAAkB,CAAC,GAAG,CAAC;gBAC5B,QAAQ,EAAE,iBAAiB;aAC5B;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAVD,4DAUC;AAED;;;;;;;GAOG;AACH,MAAa,uBAAwB,SAAQ,yBAAkB;IAC7D,YAAY,UAAkB;QAC5B,KAAK,CACH,6DAA6D,UAAU,UAAU;YAC/E,uEAAuE;YACvE,wEAAwE;YACxE,yEAAyE;YACzE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;CACF;AAVD,0DAUC"}

package/dist/multi-host-url/index.d.ts

@@ -0,0 +1,10 @@
+export { MultiHostUrl } from './multi-host-url';
+export type { MultiHostEntry, MultiHostUrlInit } from './multi-host-url';
+export { MultiHostUrlParser } from './multi-host-url.parser';
+export { MultiHostResolver } from './multi-host-url.resolver';
+export type { MultiHostProbe } from './multi-host-url.resolver';
+export { InvalidMultiHostUrl, InvalidMultiHostProtocol, MultiHostNativeRequired, } from './exception';
+export { pgProbe } from './pg-native';
+export type { PgNativeModule } from './pg-native';
+export { resolveDbConnection } from './resolve-db-connection';
+export type { ResolveDbConnectionOptions, ResolvedDbConnection, } from './resolve-db-connection';

package/dist/multi-host-url/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDbConnection = exports.pgProbe = exports.MultiHostNativeRequired = exports.InvalidMultiHostProtocol = exports.InvalidMultiHostUrl = exports.MultiHostResolver = exports.MultiHostUrlParser = exports.MultiHostUrl = void 0;
+var multi_host_url_1 = require("./multi-host-url");
+Object.defineProperty(exports, "MultiHostUrl", { enumerable: true, get: function () { return multi_host_url_1.MultiHostUrl; } });
+var multi_host_url_parser_1 = require("./multi-host-url.parser");
+Object.defineProperty(exports, "MultiHostUrlParser", { enumerable: true, get: function () { return multi_host_url_parser_1.MultiHostUrlParser; } });
+var multi_host_url_resolver_1 = require("./multi-host-url.resolver");
+Object.defineProperty(exports, "MultiHostResolver", { enumerable: true, get: function () { return multi_host_url_resolver_1.MultiHostResolver; } });
+var exception_1 = require("./exception");
+Object.defineProperty(exports, "InvalidMultiHostUrl", { enumerable: true, get: function () { return exception_1.InvalidMultiHostUrl; } });
+Object.defineProperty(exports, "InvalidMultiHostProtocol", { enumerable: true, get: function () { return exception_1.InvalidMultiHostProtocol; } });
+Object.defineProperty(exports, "MultiHostNativeRequired", { enumerable: true, get: function () { return exception_1.MultiHostNativeRequired; } });
+var pg_native_1 = require("./pg-native");
+Object.defineProperty(exports, "pgProbe", { enumerable: true, get: function () { return pg_native_1.pgProbe; } });
+var resolve_db_connection_1 = require("./resolve-db-connection");
+Object.defineProperty(exports, "resolveDbConnection", { enumerable: true, get: function () { return resolve_db_connection_1.resolveDbConnection; } });
+//# sourceMappingURL=index.js.map

package/dist/multi-host-url/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/multi-host-url/index.ts"],"names":[],"mappings":";;;AAAA,mDAAgD;AAAvC,8GAAA,YAAY,OAAA;AAErB,iEAA6D;AAApD,2HAAA,kBAAkB,OAAA;AAC3B,qEAA8D;AAArD,4HAAA,iBAAiB,OAAA;AAE1B,yCAIqB;AAHnB,gHAAA,mBAAmB,OAAA;AACnB,qHAAA,wBAAwB,OAAA;AACxB,oHAAA,uBAAuB,OAAA;AAEzB,yCAAsC;AAA7B,oGAAA,OAAO,OAAA;AAEhB,iEAA8D;AAArD,4HAAA,mBAAmB,OAAA"}

package/dist/multi-host-url/multi-host-url.d.ts

@@ -0,0 +1,37 @@
+export interface MultiHostEntry {
+    host: string;
+    /**
+     * Порт хоста, если он явно указан в URL. Если `undefined` — порт в
+     * исходном URL отсутствует; вызывающая сторона (ORM-плагин / драйвер) сама
+     * подставляет дефолтное значение для своей СУБД (`5432` для PG,
+     * `3306` для MySQL и т.п.).
+     */
+    port?: number;
+}
+export interface MultiHostUrlInit {
+    protocol: string;
+    username?: string;
+    password?: string;
+    hosts: MultiHostEntry[];
+    database?: string;
+    searchParams: URLSearchParams;
+}
+export declare class MultiHostUrl {
+    readonly protocol: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly hosts: readonly MultiHostEntry[];
+    readonly database?: string;
+    readonly searchParams: URLSearchParams;
+    constructor(init: MultiHostUrlInit);
+    /**
+     * Single-host URL для передачи в драйвер БД (pg, knex, typeorm, mikro-orm).
+     * Драйверы не понимают multihost-синтаксис в connection string, поэтому
+     * перед бутстрапом нужно выбрать один живой хост из списка.
+     */
+    getHostAt(index: number): URL;
+    /**
+     * Возвращает оригинальный multi-host URL (или single-host, если хост один).
+     */
+    toString(): string;
+}

package/dist/multi-host-url/multi-host-url.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiHostUrl = void 0;
+class MultiHostUrl {
+    protocol;
+    username;
+    password;
+    hosts;
+    database;
+    searchParams;
+    constructor(init) {
+        this.protocol = init.protocol;
+        this.hosts = init.hosts;
+        this.searchParams = init.searchParams;
+        if (init.username !== undefined)
+            this.username = init.username;
+        if (init.password !== undefined)
+            this.password = init.password;
+        if (init.database !== undefined)
+            this.database = init.database;
+    }
+    /**
+     * Single-host URL для передачи в драйвер БД (pg, knex, typeorm, mikro-orm).
+     * Драйверы не понимают multihost-синтаксис в connection string, поэтому
+     * перед бутстрапом нужно выбрать один живой хост из списка.
+     */
+    getHostAt(index) {
+        const entry = this.hosts[index];
+        if (!entry) {
+            throw new RangeError(`host index ${index} out of bounds (hosts.length=${this.hosts.length})`);
+        }
+        const auth = this.username
+            ? `${encodeURIComponent(this.username)}${this.password ? `:${encodeURIComponent(this.password)}` : ''}@`
+            : '';
+        const search = this.searchParams.toString();
+        const query = search ? `?${search}` : '';
+        const database = this.database ? `/${this.database}` : '';
+        const port = entry.port === undefined ? '' : `:${entry.port}`;
+        return new URL(`${this.protocol}//${auth}${entry.host}${port}${database}${query}`);
+    }
+    /**
+     * Возвращает оригинальный multi-host URL (или single-host, если хост один).
+     */
+    toString() {
+        const auth = this.username
+            ? `${encodeURIComponent(this.username)}${this.password ? `:${encodeURIComponent(this.password)}` : ''}@`
+            : '';
+        const hosts = this.hosts
+            .map((entry) => entry.port === undefined ? entry.host : `${entry.host}:${entry.port}`)
+            .join(',');
+        const search = this.searchParams.toString();
+        const query = search ? `?${search}` : '';
+        const database = this.database ? `/${this.database}` : '';
+        return `${this.protocol}//${auth}${hosts}${database}${query}`;
+    }
+}
+exports.MultiHostUrl = MultiHostUrl;
+//# sourceMappingURL=multi-host-url.js.map

package/dist/multi-host-url/multi-host-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-host-url.js","sourceRoot":"","sources":["../../src/multi-host-url/multi-host-url.ts"],"names":[],"mappings":";;;AAqBA,MAAa,YAAY;IACd,QAAQ,CAAS;IACjB,QAAQ,CAAU;IAClB,QAAQ,CAAU;IAClB,KAAK,CAA4B;IACjC,QAAQ,CAAU;IAClB,YAAY,CAAkB;IAEvC,YAAY,IAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IACjE,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,KAAa;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAEhC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAClB,cAAc,KAAK,gCAAgC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CACxE,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ;YACxB,CAAC,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG;YACxG,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAE1D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAE9D,OAAO,IAAI,GAAG,CACZ,GAAG,IAAI,CAAC,QAAQ,KAAK,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI,GAAG,QAAQ,GAAG,KAAK,EAAE,CACnE,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ;YACxB,CAAC,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG;YACxG,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;aACrB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACb,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CACtE;aACA,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAE1D,OAAO,GAAG,IAAI,CAAC,QAAQ,KAAK,IAAI,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,EAAE,CAAC;IAChE,CAAC;CACF;AA/DD,oCA+DC"}

package/dist/multi-host-url/multi-host-url.parser.d.ts

@@ -0,0 +1,26 @@
+import type { PropertyParser } from '@rsdk/core';
+import { MultiHostUrl } from './multi-host-url';
+export declare class MultiHostUrlParser implements PropertyParser<MultiHostUrl> {
+    private readonly protocols;
+    constructor(...protocols: string[]);
+    type(): string;
+    description(): string;
+    parse(value: unknown): MultiHostUrl;
+    /**
+     * Разбивает строку на три части: то, что слева от списка хостов
+     * (`scheme://[userinfo@]`), сам список (`h1:5432,h2:5432,...`) и то,
+     * что справа (`/db?params`). Делается вручную, потому что multi-host
+     * URI ломает `new URL()` ещё до того, как мы дойдём до парсинга хостов.
+     * Дальше вызывающая сторона подставляет в `hostsSegment` placeholder и
+     * скармливает результат `new URL()` уже как валидный single-host URI.
+     */
+    private getSplittedOnHosts;
+    /**
+     * Возвращает имя БД из pathname (`/db` → `db`). Пустой pathname (URL без
+     * пути) даёт `''` — вызывающая сторона трактует это как «database не задан».
+     */
+    private extractDatabase;
+    private findPathStart;
+    private parseHosts;
+    private assertProtocol;
+}

package/dist/multi-host-url/multi-host-url.parser.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiHostUrlParser = void 0;
+const common_1 = require("@rsdk/common");
+const exception_1 = require("./exception");
+const multi_host_url_1 = require("./multi-host-url");
+const PLACEHOLDER_HOST = '__rsdk_multihost_placeholder__';
+class MultiHostUrlParser {
+    protocols;
+    constructor(...protocols) {
+        this.protocols = protocols;
+    }
+    type() {
+        return 'MultiHostUrl';
+    }
+    description() {
+        return 'Parses string into MultiHostUrl supporting <scheme>://user:pass@host1:port1,host2:port2/db?... syntax';
+    }
+    parse(value) {
+        try {
+            common_1.Assert.isString(value);
+            const splitted = this.getSplittedOnHosts(value);
+            const placeholder = `${splitted.beforeHosts}${PLACEHOLDER_HOST}${splitted.afterHosts}`;
+            const url = new URL(placeholder);
+            this.assertProtocol(url.protocol, value);
+            const hosts = this.parseHosts(splitted.hostsSegment, value);
+            const database = this.extractDatabase(url);
+            return new multi_host_url_1.MultiHostUrl({
+                protocol: url.protocol,
+                ...(url.username && {
+                    username: decodeURIComponent(url.username),
+                }),
+                ...(url.password && {
+                    password: decodeURIComponent(url.password),
+                }),
+                hosts,
+                ...(database && { database }),
+                searchParams: url.searchParams,
+            });
+        }
+        catch (error) {
+            if (error instanceof exception_1.InvalidMultiHostUrl ||
+                error instanceof exception_1.InvalidMultiHostProtocol) {
+                throw error;
+            }
+            throw new exception_1.InvalidMultiHostUrl(String(value), error);
+        }
+    }
+    /**
+     * Разбивает строку на три части: то, что слева от списка хостов
+     * (`scheme://[userinfo@]`), сам список (`h1:5432,h2:5432,...`) и то,
+     * что справа (`/db?params`). Делается вручную, потому что multi-host
+     * URI ломает `new URL()` ещё до того, как мы дойдём до парсинга хостов.
+     * Дальше вызывающая сторона подставляет в `hostsSegment` placeholder и
+     * скармливает результат `new URL()` уже как валидный single-host URI.
+     */
+    getSplittedOnHosts(value) {
+        // scheme заканчивается на `://`. Без него это не URI.
+        const schemeEnd = value.indexOf('://');
+        if (schemeEnd === -1) {
+            throw new exception_1.InvalidMultiHostUrl(value);
+        }
+        // Authority — всё между `://` и следующим `/`, `?` или `#`.
+        // Внутри authority может быть `userinfo@hosts`.
+        const authorityStart = schemeEnd + 3;
+        const pathStart = this.findPathStart(value, authorityStart);
+        const authority = value.slice(authorityStart, pathStart);
+        const after = value.slice(pathStart);
+        // `userinfo` отделяется от hosts последним `@`. `lastIndexOf` —
+        // на случай, если в пароле встретится сам символ `@` (хотя по
+        // спеке его положено percent-кодировать, на практике встречается).
+        const atIdx = authority.lastIndexOf('@');
+        const userInfo = atIdx === -1 ? '' : authority.slice(0, atIdx + 1);
+        const hostsSegment = atIdx === -1 ? authority : authority.slice(atIdx + 1);
+        if (!hostsSegment) {
+            throw new exception_1.InvalidMultiHostUrl(value);
+        }
+        // `beforeHosts` сохраняем вместе с userInfo — placeholder будет
+        // подставлен только вместо hosts, чтобы `new URL()` корректно
+        // распарсил scheme/userinfo/path/query.
+        return {
+            beforeHosts: value.slice(0, authorityStart) + userInfo,
+            hostsSegment,
+            afterHosts: after,
+        };
+    }
+    /**
+     * Возвращает имя БД из pathname (`/db` → `db`). Пустой pathname (URL без
+     * пути) даёт `''` — вызывающая сторона трактует это как «database не задан».
+     */
+    extractDatabase(url) {
+        return url.pathname.replace(/^\//, '');
+    }
+    findPathStart(value, from) {
+        for (let i = from; i < value.length; i++) {
+            const ch = value[i];
+            if (ch === '/' || ch === '?' || ch === '#') {
+                return i;
+            }
+        }
+        return value.length;
+    }
+    parseHosts(segment, original) {
+        const parts = segment.split(',');
+        const hosts = [];
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (!trimmed) {
+                throw new exception_1.InvalidMultiHostUrl(original);
+            }
+            const colonIdx = trimmed.lastIndexOf(':');
+            let host;
+            let port;
+            if (colonIdx === -1) {
+                // Порт отсутствует — оставляем undefined; default подставит вызывающая сторона.
+                host = trimmed;
+                port = undefined;
+            }
+            else {
+                host = trimmed.slice(0, colonIdx);
+                const portStr = trimmed.slice(colonIdx + 1);
+                const parsed = Number(portStr);
+                if (portStr.length === 0 ||
+                    !Number.isInteger(parsed) ||
+                    parsed < 1 ||
+                    parsed > 65535) {
+                    throw new exception_1.InvalidMultiHostUrl(original);
+                }
+                port = parsed;
+            }
+            if (!host) {
+                throw new exception_1.InvalidMultiHostUrl(original);
+            }
+            hosts.push(port === undefined ? { host } : { host, port });
+        }
+        if (hosts.length === 0) {
+            throw new exception_1.InvalidMultiHostUrl(original);
+        }
+        return hosts;
+    }
+    assertProtocol(protocol, original) {
+        if (this.protocols.length === 0) {
+            return;
+        }
+        if (!this.protocols.includes(protocol)) {
+            throw new exception_1.InvalidMultiHostProtocol(this.protocols, protocol, original);
+        }
+    }
+}
+exports.MultiHostUrlParser = MultiHostUrlParser;
+//# sourceMappingURL=multi-host-url.parser.js.map

package/dist/multi-host-url/multi-host-url.parser.js.map

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

package/dist/multi-host-url/multi-host-url.resolver.d.ts

@@ -0,0 +1,25 @@
+import type { ILogger } from '@rsdk/logging';
+import type { MultiHostUrl } from './multi-host-url';
+export type MultiHostProbe = (candidate: URL) => Promise<void>;
+/**
+ * Стратегия "resolve at bootstrap": перебирает хосты из multi-host URL и
+ * выбирает первый, на котором проба прошла успешно. Если ни один не отвечает,
+ * возвращается первый хост — далее у каждого ORM работает свой reconnect-цикл.
+ *
+ * **Bootstrap-only failover.** Чистый JS-драйвер `pg` не реализует
+ * libpq-style failover, поэтому при использовании этого resolver-а
+ * переключение между хостами происходит **только** в момент старта.
+ * Если уже выбранный хост упадёт в runtime, reconnect-цикл ORM продолжит
+ * подключаться к нему же — до перезапуска приложения.
+ *
+ * Для **runtime failover** (libpq-style) используйте {@link resolveDbConnection}
+ * — он автоматически переключается на native-libpq путь, когда хостов >1
+ * и доступен `pg-native`. `MultiHostResolver` остаётся низкоуровневым
+ * примитивом для случаев, где native путь невозможен (не-postgres драйверы)
+ * или нежелателен (например, чтобы не зависеть от системной libpq).
+ */
+export declare class MultiHostResolver {
+    private readonly logger;
+    constructor(logger: ILogger);
+    resolve(url: MultiHostUrl, probe: MultiHostProbe): Promise<URL>;
+}

package/dist/multi-host-url/multi-host-url.resolver.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiHostResolver = void 0;
+/**
+ * Стратегия "resolve at bootstrap": перебирает хосты из multi-host URL и
+ * выбирает первый, на котором проба прошла успешно. Если ни один не отвечает,
+ * возвращается первый хост — далее у каждого ORM работает свой reconnect-цикл.
+ *
+ * **Bootstrap-only failover.** Чистый JS-драйвер `pg` не реализует
+ * libpq-style failover, поэтому при использовании этого resolver-а
+ * переключение между хостами происходит **только** в момент старта.
+ * Если уже выбранный хост упадёт в runtime, reconnect-цикл ORM продолжит
+ * подключаться к нему же — до перезапуска приложения.
+ *
+ * Для **runtime failover** (libpq-style) используйте {@link resolveDbConnection}
+ * — он автоматически переключается на native-libpq путь, когда хостов >1
+ * и доступен `pg-native`. `MultiHostResolver` остаётся низкоуровневым
+ * примитивом для случаев, где native путь невозможен (не-postgres драйверы)
+ * или нежелателен (например, чтобы не зависеть от системной libpq).
+ */
+class MultiHostResolver {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async resolve(url, probe) {
+        if (url.hosts.length === 1) {
+            return url.getHostAt(0);
+        }
+        for (let i = 0; i < url.hosts.length; i++) {
+            const candidate = url.getHostAt(i);
+            const entry = url.hosts[i];
+            const hostLabel = entry.port === undefined ? entry.host : `${entry.host}:${entry.port}`;
+            try {
+                await probe(candidate);
+                if (i > 0) {
+                    this.logger.info(`multi-host db: connected to host #${i + 1} (${hostLabel}) after previous hosts failed`);
+                }
+                return candidate;
+            }
+            catch (error) {
+                this.logger.warn(`multi-host db: host ${hostLabel} not reachable, trying next`, error);
+            }
+        }
+        this.logger.warn('multi-host db: none of the configured hosts responded to the bootstrap probe; falling back to the first host and relying on reconnect cycle');
+        return url.getHostAt(0);
+    }
+}
+exports.MultiHostResolver = MultiHostResolver;
+//# sourceMappingURL=multi-host-url.resolver.js.map

package/dist/multi-host-url/multi-host-url.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-host-url.resolver.js","sourceRoot":"","sources":["../../src/multi-host-url/multi-host-url.resolver.ts"],"names":[],"mappings":";;;AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,iBAAiB;IACC;IAA7B,YAA6B,MAAe;QAAf,WAAM,GAAN,MAAM,CAAS;IAAG,CAAC;IAEhD,KAAK,CAAC,OAAO,CAAC,GAAiB,EAAE,KAAqB;QACpD,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YACnC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,SAAS,GACb,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAExE,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,SAAS,CAAC,CAAC;gBACvB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBACV,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,qCAAqC,CAAC,GAAG,CAAC,KAAK,SAAS,+BAA+B,CACxF,CAAC;gBACJ,CAAC;gBACD,OAAO,SAAS,CAAC;YACnB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,uBAAuB,SAAS,6BAA6B,EAC7D,KAAc,CACf,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,6IAA6I,CAC9I,CAAC;QACF,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;CACF;AAnCD,8CAmCC"}

package/dist/multi-host-url/pg-native.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Утилиты для работы с `pg` и `pg.native` (libpq) на стороне @rsdk/db.
+ * `pg` — peer-зависимость использующего пакета; здесь оборачиваем `require`
+ * в try/catch, чтобы пакет, не использующий postgres, не падал при загрузке.
+ */
+export type PgClient = {
+    connect(): Promise<void>;
+    query(text: string): Promise<unknown>;
+    end(): Promise<void>;
+};
+export type PgClientCtor = new (config: {
+    connectionString?: string;
+    /**
+     * Escape hatch у `pg.native`: строка идёт напрямую в libpq, минуя
+     * `pg-connection-string` (он парсит URL через `new URL()` и падает на
+     * multi-host синтаксис).
+     * @see node_modules/pg/lib/native/client.js
+     */
+    nativeConnectionString?: string;
+    ssl?: unknown;
+    connectionTimeoutMillis?: number;
+}) => PgClient;
+/**
+ * Объект-модуль `pg.native`. TypeORM/Knex/MikroORM принимают его как
+ * `driver`/`overrideConfig.driver`, поэтому signature намеренно широкий.
+ */
+export type PgNativeModule = {
+    Client: PgClientCtor;
+    [key: string]: unknown;
+};
+/**
+ * Пробует загрузить `pg.native` (биндинги к libpq). Доступ к `pg.native`
+ * лениво требует пакет `pg-native`; если его нет, возвращаем `null`, чтобы
+ * вызывающая сторона могла переключиться на bootstrap-resolve вместо
+ * fatal-ошибки.
+ */
+export declare const loadPgNative: () => PgNativeModule | null;
+/**
+ * Bootstrap probe одного хоста: connects, runs `SELECT 1`, disconnects.
+ * Подходит как `bootstrapProbe` в {@link resolveDbConnection} для
+ * postgres-семейства драйверов.
+ */
+export declare const pgProbe: (candidate: URL, ssl: unknown) => Promise<void>;
+/**
+ * Bootstrap probe для multi-host URL через нативный libpq-клиент.
+ * libpq сам перебирает хосты внутри connection-string, поэтому достаточно
+ * одного `SELECT 1`: если ни один хост не доступен — упадёт здесь, fail-fast.
+ *
+ * Multi-host строка передаётся через `nativeConnectionString`, чтобы
+ * обойти JS-парсер `pg-connection-string` (он падает на multi-host URI).
+ * SSL-опции в native-режиме задаются параметрами libpq в самой строке
+ * (`sslmode=`, `sslrootcert=`, ...), JS-объект `ssl` не используется.
+ */
+export declare const pgProbeMultiHost: (multiHostUrl: string, Client: PgClientCtor) => Promise<void>;