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

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

@@ -0,0 +1,90 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-require-imports, import/no-extraneous-dependencies */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pgProbeMultiHost = exports.pgProbe = exports.loadPgNative = void 0;
+let cachedPg = null;
+let cachedNative = null;
+const loadPg = () => {
+    if (cachedPg)
+        return cachedPg;
+    try {
+        cachedPg = require('pg');
+        return cachedPg;
+    }
+    catch (error) {
+        throw new Error('`pg` package is not installed. Install it as a runtime dependency to use postgres connectivity.', { cause: error });
+    }
+};
+/**
+ * Пробует загрузить `pg.native` (биндинги к libpq). Доступ к `pg.native`
+ * лениво требует пакет `pg-native`; если его нет, возвращаем `null`, чтобы
+ * вызывающая сторона могла переключиться на bootstrap-resolve вместо
+ * fatal-ошибки.
+ */
+const loadPgNative = () => {
+    if (cachedNative)
+        return cachedNative;
+    const pg = loadPg();
+    let nativeNs;
+    try {
+        nativeNs = pg.native;
+    }
+    catch {
+        return null;
+    }
+    if (!nativeNs?.Client) {
+        return null;
+    }
+    cachedNative = nativeNs;
+    return nativeNs;
+};
+exports.loadPgNative = loadPgNative;
+/**
+ * Bootstrap probe одного хоста: connects, runs `SELECT 1`, disconnects.
+ * Подходит как `bootstrapProbe` в {@link resolveDbConnection} для
+ * postgres-семейства драйверов.
+ */
+const pgProbe = async (candidate, ssl) => {
+    const Client = loadPg().Client;
+    const client = new Client({
+        connectionString: candidate.toString(),
+        ssl,
+        connectionTimeoutMillis: 5_000,
+    });
+    await client.connect();
+    try {
+        await client.query('SELECT 1');
+    }
+    finally {
+        await client.end().catch(() => {
+            /* swallow */
+        });
+    }
+};
+exports.pgProbe = pgProbe;
+/**
+ * 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` не используется.
+ */
+const pgProbeMultiHost = async (multiHostUrl, Client) => {
+    const client = new Client({
+        nativeConnectionString: multiHostUrl,
+    });
+    await client.connect();
+    try {
+        await client.query('SELECT 1');
+    }
+    finally {
+        await client.end().catch(() => {
+            /* swallow */
+        });
+    }
+};
+exports.pgProbeMultiHost = pgProbeMultiHost;
+//# sourceMappingURL=pg-native.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pg-native.js","sourceRoot":"","sources":["../../src/multi-host-url/pg-native.ts"],"names":[],"mappings":";AAAA,6FAA6F;;;AA0C7F,IAAI,QAAQ,GAAoB,IAAI,CAAC;AACrC,IAAI,YAAY,GAA0B,IAAI,CAAC;AAE/C,MAAM,MAAM,GAAG,GAAa,EAAE;IAC5B,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,CAAC;QACH,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAa,CAAC;QACrC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,iGAAiG,EACjG,EAAE,KAAK,EAAE,KAAc,EAAE,CAC1B,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACI,MAAM,YAAY,GAAG,GAA0B,EAAE;IACtD,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IAEtC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,IAAI,QAA2C,CAAC;IAEhD,IAAI,CAAC;QACH,QAAQ,GAAG,EAAE,CAAC,MAAM,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY,GAAG,QAAQ,CAAC;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAjBW,QAAA,YAAY,gBAiBvB;AAEF;;;;GAIG;AACI,MAAM,OAAO,GAAG,KAAK,EAAE,SAAc,EAAE,GAAY,EAAiB,EAAE;IAC3E,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,gBAAgB,EAAE,SAAS,CAAC,QAAQ,EAAE;QACtC,GAAG;QACH,uBAAuB,EAAE,KAAK;KAC/B,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;YAC5B,aAAa;QACf,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;AAhBW,QAAA,OAAO,WAgBlB;AAEF;;;;;;;;;GASG;AACI,MAAM,gBAAgB,GAAG,KAAK,EACnC,YAAoB,EACpB,MAAoB,EACL,EAAE;IACjB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,sBAAsB,EAAE,YAAY;KACrC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;YAC5B,aAAa;QACf,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;AAhBW,QAAA,gBAAgB,oBAgB3B"}

package/dist/multi-host-url/resolve-db-connection.d.ts

@@ -0,0 +1,64 @@
+import type { ILogger } from '@rsdk/logging';
+import type { MultiHostEntry, MultiHostUrl } from './multi-host-url';
+import type { MultiHostProbe } from './multi-host-url.resolver';
+import type { PgNativeModule } from './pg-native';
+/**
+ * Опции стратегии установки соединения для multi-host URL.
+ */
+export interface ResolveDbConnectionOptions {
+    url: MultiHostUrl;
+    logger: ILogger;
+    /**
+     * Включает попытку native-libpq пути. Должен быть `true` только для
+     * wire-совместимых с PostgreSQL драйверов (`postgres`, `aurora-postgres`,
+     * cockroachdb и т.п.). Для mysql/mssql/sqlite оставлять `false`.
+     */
+    isPostgresFamily: boolean;
+    /**
+     * Probe для bootstrap-resolve пути (выбор живого хоста при старте).
+     * Передача probe одновременно служит **разрешением** на bootstrap-фолбэк:
+     * если хостов несколько, postgres-семейство и `pg-native` не установлен —
+     * resolver упадёт с {@link MultiHostNativeRequired}, если probe не задан,
+     * либо выберет живой хост через probe, если задан. Так что не передавайте
+     * probe, если хотите fail-fast при отсутствии libpq runtime failover.
+     * Для single-host URL probe не вызывается.
+     */
+    bootstrapProbe?: MultiHostProbe;
+}
+/**
+ * Результат выбора стратегии: либо native-libpq (runtime failover через
+ * libpq), либо single-host (bootstrap-выбор живого хоста, без runtime
+ * failover). Плагины разворачивают этот union в свой driver-специфичный
+ * config.
+ */
+export type ResolvedDbConnection = {
+    kind: 'native-libpq';
+    /** Оригинальная multi-host строка для libpq. */
+    multiHostUrl: string;
+    /**
+     * Первый хост из списка. Используется как «косметический» host/port
+     * для тех мест в драйверах, что обращаются к этим полям (логи,
+     * метрики); реальный коннект libpq собирает из `multiHostUrl`.
+     */
+    firstHostEntry: MultiHostEntry;
+    username?: string;
+    password?: string;
+    database?: string;
+    driver: PgNativeModule;
+} | {
+    kind: 'single-host';
+    url: URL;
+};
+/**
+ * Выбирает стратегию подключения к БД для multi-host URL.
+ *
+ * - Один хост → возвращаем его без probe.
+ * - Несколько хостов + postgres-семейство + `pg-native` установлен →
+ *   native-libpq путь с runtime failover.
+ * - Несколько хостов + postgres-семейство + НЕТ `pg-native`:
+ *   - `bootstrapProbe` передан → warn + bootstrap-resolve.
+ *   - `bootstrapProbe` НЕ передан → бросаем {@link MultiHostNativeRequired}.
+ * - Несколько хостов + не postgres → bootstrap-resolve через `bootstrapProbe`
+ *   (если probe не передан, берётся первый хост без проверки доступности).
+ */
+export declare const resolveDbConnection: (options: ResolveDbConnectionOptions) => Promise<ResolvedDbConnection>;

package/dist/multi-host-url/resolve-db-connection.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDbConnection = void 0;
+const exception_1 = require("./exception");
+const multi_host_url_resolver_1 = require("./multi-host-url.resolver");
+const pg_native_1 = require("./pg-native");
+/**
+ * Выбирает стратегию подключения к БД для multi-host URL.
+ *
+ * - Один хост → возвращаем его без probe.
+ * - Несколько хостов + postgres-семейство + `pg-native` установлен →
+ *   native-libpq путь с runtime failover.
+ * - Несколько хостов + postgres-семейство + НЕТ `pg-native`:
+ *   - `bootstrapProbe` передан → warn + bootstrap-resolve.
+ *   - `bootstrapProbe` НЕ передан → бросаем {@link MultiHostNativeRequired}.
+ * - Несколько хостов + не postgres → bootstrap-resolve через `bootstrapProbe`
+ *   (если probe не передан, берётся первый хост без проверки доступности).
+ */
+const resolveDbConnection = async (options) => {
+    const isMultiHost = options.url.hosts.length > 1;
+    const native = isMultiHost && options.isPostgresFamily ? (0, pg_native_1.loadPgNative)() : null;
+    if (native) {
+        const multiHostUrl = options.url.toString();
+        await (0, pg_native_1.pgProbeMultiHost)(multiHostUrl, native.Client);
+        options.logger.warn(`multi-host db: switched to libpq failover via pg.native across ${options.url.hosts.length} hosts. ` +
+            'Caveat: SSL options from config (DB_SSL_MODE / DB_TLS_*) are NOT applied in native mode — ' +
+            'pass `sslmode=`/`sslrootcert=`/`sslcert=`/`sslkey=` in the connection string instead. ' +
+            'See docs/md/DATABASES.md for details.');
+        return {
+            kind: 'native-libpq',
+            multiHostUrl,
+            firstHostEntry: options.url.hosts[0],
+            ...(options.url.username && { username: options.url.username }),
+            ...(options.url.password && { password: options.url.password }),
+            ...(options.url.database && { database: options.url.database }),
+            driver: native,
+        };
+    }
+    if (isMultiHost && options.isPostgresFamily) {
+        if (!options.bootstrapProbe) {
+            throw new exception_1.MultiHostNativeRequired(options.url.hosts.length);
+        }
+        options.logger.warn(`multi-host db: \`pg-native\` is not installed — falling back to bootstrap-resolve across ${options.url.hosts.length} hosts. ` +
+            'Runtime failover after a connection drop will NOT work; only the host picked at startup is used. ' +
+            'Install `pg-native` (and a system libpq) for libpq-driven runtime failover.');
+    }
+    /**
+     * Single-host: пробу не вызываем; для multi-host без probe мы уже
+     * упали выше, поэтому здесь probe гарантированно есть либо хост один.
+     */
+    const probe = options.bootstrapProbe ?? (() => Promise.resolve());
+    const resolver = new multi_host_url_resolver_1.MultiHostResolver(options.logger);
+    const resolved = await resolver.resolve(options.url, probe);
+    return { kind: 'single-host', url: resolved };
+};
+exports.resolveDbConnection = resolveDbConnection;
+//# sourceMappingURL=resolve-db-connection.js.map

package/dist/multi-host-url/resolve-db-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-db-connection.js","sourceRoot":"","sources":["../../src/multi-host-url/resolve-db-connection.ts"],"names":[],"mappings":";;;AAEA,2CAAsD;AAGtD,uEAA8D;AAE9D,2CAA6D;AAyD7D;;;;;;;;;;;GAWG;AACI,MAAM,mBAAmB,GAAG,KAAK,EACtC,OAAmC,EACJ,EAAE;IACjC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACjD,MAAM,MAAM,GACV,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAA,wBAAY,GAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAElE,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAE5C,MAAM,IAAA,4BAAgB,EAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACpD,OAAO,CAAC,MAAM,CAAC,IAAI,CACjB,kEAAkE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,UAAU;YAClG,4FAA4F;YAC5F,wFAAwF;YACxF,uCAAuC,CAC1C,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,YAAY;YACZ,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YACpC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/D,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/D,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/D,MAAM,EAAE,MAAM;SACf,CAAC;IACJ,CAAC;IAED,IAAI,WAAW,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC5C,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;YAC5B,MAAM,IAAI,mCAAuB,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,IAAI,CACjB,4FAA4F,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,UAAU;YAC5H,mGAAmG;YACnG,6EAA6E,CAChF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,KAAK,GACT,OAAO,CAAC,cAAc,IAAI,CAAC,GAAkB,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,MAAM,QAAQ,GAAG,IAAI,2CAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAE5D,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAChD,CAAC,CAAC;AAlDW,QAAA,mBAAmB,uBAkD9B"}

package/jest.config.unit.js

@@ -0,0 +1 @@
+module.exports = require('@rsdk/jest/jest.config.unit');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdk/db",
-  "version": "5.12.0-next.7",
+  "version": "5.12.0-next.9",
   "description": "Common functionality and interfaces for relational database plugins",
   "main": "dist/index.js",
   "publishConfig": {
@@ -16,7 +16,8 @@
     "@rsdk/common": "*",
     "@rsdk/core": "*",
     "@rsdk/decorators": "*",
+    "@rsdk/logging": "*",
     "reflect-metadata": "^0.1.12 || ^0.2.0"
   },
-  "gitHead": "8ba4df5208a29cbaaca6eb9c58bf3a3e6d008056"
+  "gitHead": "43bfe38011bd365e92e35b8d159ab6e47a42c284"
 }

package/src/index.ts

@@ -11,3 +11,21 @@ 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/src/multi-host-url/exception.ts

@@ -0,0 +1,48 @@
+import { BootstrapException } from '@rsdk/core';
+
+/**
+ * Заменяет `userinfo` (`user:pass@`) в URL-подобной строке на `***:***@`,
+ * чтобы пароль из `DB_URL` не попадал в логи через message/details ошибки.
+ */
+const maskUrlCredentials = (str: string): string =>
+  str.replace(/(:\/\/)[^/@\s]+@/u, '$1***:***@');
+
+export class InvalidMultiHostUrl extends BootstrapException {
+  constructor(str: string, cause?: unknown) {
+    super(`Invalid multi-host url string: <${maskUrlCredentials(str)}>`, {
+      cause,
+    });
+  }
+}
+
+export class InvalidMultiHostProtocol extends BootstrapException {
+  constructor(expectedProtocols: string[], protocol: string, url: string) {
+    super(`Invalid protocol: <${protocol}>, expected: ${expectedProtocols}`, {
+      details: {
+        protocol,
+        url: maskUrlCredentials(url),
+        expected: expectedProtocols,
+      },
+    });
+  }
+}
+
+/**
+ * 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 class MultiHostNativeRequired extends BootstrapException {
+  constructor(hostsCount: number) {
+    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.',
+    );
+  }
+}

package/src/multi-host-url/index.ts

@@ -0,0 +1,17 @@
+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/src/multi-host-url/multi-host-url.parser.spec.ts

@@ -0,0 +1,131 @@
+import { InvalidMultiHostProtocol, InvalidMultiHostUrl } from './exception';
+import { MultiHostUrl } from './multi-host-url';
+import { MultiHostUrlParser } from './multi-host-url.parser';
+
+describe('MultiHostUrlParser', () => {
+  const parser = new MultiHostUrlParser();
+
+  describe('single-host URL (backward compat)', () => {
+    it('parses postgres://user:pass@host:5432/db', () => {
+      const url = parser.parse('postgres://app:secret@db.local:5432/myapp');
+
+      expect(url).toBeInstanceOf(MultiHostUrl);
+      expect(url.protocol).toBe('postgres:');
+      expect(url.username).toBe('app');
+      expect(url.password).toBe('secret');
+      expect(url.hosts).toEqual([{ host: 'db.local', port: 5432 }]);
+      expect(url.database).toBe('myapp');
+    });
+
+    it('omits port from MultiHostEntry when not in URL', () => {
+      const url = parser.parse('postgres://u:p@db.local/myapp');
+
+      expect(url.hosts).toEqual([{ host: 'db.local' }]);
+    });
+  });
+
+  describe('multi-host URL', () => {
+    it('parses two hosts with explicit ports', () => {
+      const url = parser.parse('postgres://app:secret@h1:5432,h2:5433/myapp');
+
+      expect(url.hosts).toEqual([
+        { host: 'h1', port: 5432 },
+        { host: 'h2', port: 5433 },
+      ]);
+      expect(url.database).toBe('myapp');
+    });
+
+    it('omits port for hosts that do not specify it (mixed)', () => {
+      const url = parser.parse('postgres://u:p@h1,h2:5433,h3/myapp');
+
+      expect(url.hosts).toEqual([
+        { host: 'h1' },
+        { host: 'h2', port: 5433 },
+        { host: 'h3' },
+      ]);
+    });
+
+    it('preserves searchParams', () => {
+      const url = parser.parse(
+        'postgres://u:p@h1:5432,h2:5432/db?sslmode=require&application_name=foo',
+      );
+
+      expect(url.searchParams.get('sslmode')).toBe('require');
+      expect(url.searchParams.get('application_name')).toBe('foo');
+    });
+
+    it('singleHostUrl produces a valid single-host URL', () => {
+      const url = parser.parse(
+        'postgres://app:secret@h1:5432,h2:5433/myapp?sslmode=require',
+      );
+
+      const single0 = url.getHostAt(0);
+
+      expect(single0.hostname).toBe('h1');
+      expect(single0.port).toBe('5432');
+      expect(single0.username).toBe('app');
+      expect(single0.password).toBe('secret');
+      expect(single0.pathname).toBe('/myapp');
+      expect(single0.searchParams.get('sslmode')).toBe('require');
+
+      const single1 = url.getHostAt(1);
+
+      expect(single1.hostname).toBe('h2');
+      expect(single1.port).toBe('5433');
+    });
+
+    it('toString returns multi-host form', () => {
+      const url = parser.parse('postgres://u:p@h1:5432,h2:5433/db');
+
+      expect(url.toString()).toBe('postgres://u:p@h1:5432,h2:5433/db');
+    });
+
+    it('toString preserves searchParams', () => {
+      const url = parser.parse(
+        'postgres://u:p@h1:5432,h2:5433/db?sslmode=require',
+      );
+
+      expect(url.toString()).toBe(
+        'postgres://u:p@h1:5432,h2:5433/db?sslmode=require',
+      );
+    });
+  });
+
+  describe('protocol validation', () => {
+    it('accepts URL when protocol matches one of allowed', () => {
+      const restricted = new MultiHostUrlParser('postgres:', 'postgresql:');
+
+      expect(() =>
+        restricted.parse('postgres://u:p@h1:5432,h2:5432/db'),
+      ).not.toThrow();
+    });
+
+    it('rejects URL when protocol is not in allowed list', () => {
+      const restricted = new MultiHostUrlParser('postgres:');
+
+      expect(() => restricted.parse('mysql://u:p@h1:5432,h2:5432/db')).toThrow(
+        InvalidMultiHostProtocol,
+      );
+    });
+  });
+
+  describe('invalid input', () => {
+    it.each([
+      ['empty hosts', 'postgres://u:p@/db'],
+      ['empty entry between commas', 'postgres://u:p@h1,,h2/db'],
+      ['port out of range', 'postgres://u:p@h1:99999/db'],
+      ['non-numeric port', 'postgres://u:p@h1:abc/db'],
+      ['missing scheme', 'h1:5432,h2:5432/db'],
+      ['non-string input (number)', 42],
+    ])('rejects %s', (_, input) => {
+      expect(() => parser.parse(input)).toThrow(InvalidMultiHostUrl);
+    });
+  });
+
+  describe('parser metadata', () => {
+    it('exposes type and description', () => {
+      expect(parser.type()).toBe('MultiHostUrl');
+      expect(parser.description()).toContain('MultiHostUrl');
+    });
+  });
+});

package/src/multi-host-url/multi-host-url.parser.ts

@@ -0,0 +1,182 @@
+import { Assert } from '@rsdk/common';
+import type { PropertyParser } from '@rsdk/core';
+
+import { InvalidMultiHostProtocol, InvalidMultiHostUrl } from './exception';
+import type { MultiHostEntry } from './multi-host-url';
+import { MultiHostUrl } from './multi-host-url';
+
+const PLACEHOLDER_HOST = '__rsdk_multihost_placeholder__';
+
+export class MultiHostUrlParser implements PropertyParser<MultiHostUrl> {
+  private readonly protocols: string[];
+
+  constructor(...protocols: string[]) {
+    this.protocols = protocols;
+  }
+
+  type(): string {
+    return 'MultiHostUrl';
+  }
+
+  description(): string {
+    return 'Parses string into MultiHostUrl supporting <scheme>://user:pass@host1:port1,host2:port2/db?... syntax';
+  }
+
+  parse(value: unknown): MultiHostUrl {
+    try {
+      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 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 InvalidMultiHostUrl ||
+        error instanceof InvalidMultiHostProtocol
+      ) {
+        throw error;
+      }
+      throw new InvalidMultiHostUrl(String(value), error);
+    }
+  }
+
+  /**
+   * Разбивает строку на три части: то, что слева от списка хостов
+   * (`scheme://[userinfo@]`), сам список (`h1:5432,h2:5432,...`) и то,
+   * что справа (`/db?params`). Делается вручную, потому что multi-host
+   * URI ломает `new URL()` ещё до того, как мы дойдём до парсинга хостов.
+   * Дальше вызывающая сторона подставляет в `hostsSegment` placeholder и
+   * скармливает результат `new URL()` уже как валидный single-host URI.
+   */
+  private getSplittedOnHosts(value: string): {
+    beforeHosts: string;
+    hostsSegment: string;
+    afterHosts: string;
+  } {
+    // scheme заканчивается на `://`. Без него это не URI.
+    const schemeEnd = value.indexOf('://');
+    if (schemeEnd === -1) {
+      throw new 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 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 не задан».
+   */
+  private extractDatabase(url: URL): string {
+    return url.pathname.replace(/^\//, '');
+  }
+
+  private findPathStart(value: string, from: number): number {
+    for (let i = from; i < value.length; i++) {
+      const ch = value[i];
+      if (ch === '/' || ch === '?' || ch === '#') {
+        return i;
+      }
+    }
+    return value.length;
+  }
+
+  private parseHosts(segment: string, original: string): MultiHostEntry[] {
+    const parts = segment.split(',');
+    const hosts: MultiHostEntry[] = [];
+
+    for (const part of parts) {
+      const trimmed = part.trim();
+      if (!trimmed) {
+        throw new InvalidMultiHostUrl(original);
+      }
+
+      const colonIdx = trimmed.lastIndexOf(':');
+      let host: string;
+      let port: number | undefined;
+
+      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 InvalidMultiHostUrl(original);
+        }
+        port = parsed;
+      }
+
+      if (!host) {
+        throw new InvalidMultiHostUrl(original);
+      }
+
+      hosts.push(port === undefined ? { host } : { host, port });
+    }
+
+    if (hosts.length === 0) {
+      throw new InvalidMultiHostUrl(original);
+    }
+
+    return hosts;
+  }
+
+  private assertProtocol(protocol: string, original: string): void {
+    if (this.protocols.length === 0) {
+      return;
+    }
+
+    if (!this.protocols.includes(protocol)) {
+      throw new InvalidMultiHostProtocol(this.protocols, protocol, original);
+    }
+  }
+}