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

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

@@ -0,0 +1,57 @@
+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 class MultiHostResolver {
+  constructor(private readonly logger: ILogger) {}
+
+  async resolve(url: MultiHostUrl, probe: MultiHostProbe): Promise<URL> {
+    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];
+
+      try {
+        await probe(candidate);
+        if (i > 0) {
+          this.logger.info(
+            `multi-host db: connected to host #${i + 1} (${entry.host}:${entry.port}) after previous hosts failed`,
+          );
+        }
+        return candidate;
+      } catch (error) {
+        this.logger.warn(
+          `multi-host db: host ${entry.host}:${entry.port} not reachable, trying next`,
+          error as 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);
+  }
+}

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

@@ -0,0 +1,85 @@
+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 class MultiHostUrl {
+  readonly protocol: string;
+  readonly username?: string;
+  readonly password?: string;
+  readonly hosts: readonly MultiHostEntry[];
+  readonly database?: string;
+  readonly searchParams: URLSearchParams;
+
+  constructor(init: MultiHostUrlInit) {
+    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: number): URL {
+    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(): string {
+    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}`;
+  }
+}

package/src/multi-host-url/pg-native.ts

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

package/src/multi-host-url/resolve-db-connection.ts

@@ -0,0 +1,127 @@
+import type { ILogger } from '@rsdk/logging';
+
+import { MultiHostNativeRequired } from './exception';
+import type { MultiHostEntry, MultiHostUrl } from './multi-host-url';
+import type { MultiHostProbe } from './multi-host-url.resolver';
+import { MultiHostResolver } from './multi-host-url.resolver';
+import type { PgNativeModule } from './pg-native';
+import { loadPgNative, pgProbeMultiHost } 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 const resolveDbConnection = async (
+  options: ResolveDbConnectionOptions,
+): Promise<ResolvedDbConnection> => {
+  const isMultiHost = options.url.hosts.length > 1;
+  const native =
+    isMultiHost && options.isPostgresFamily ? loadPgNative() : null;
+
+  if (native) {
+    const multiHostUrl = options.url.toString();
+
+    await 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 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: MultiHostProbe =
+    options.bootstrapProbe ?? ((): Promise<void> => Promise.resolve());
+  const resolver = new MultiHostResolver(options.logger);
+  const resolved = await resolver.resolve(options.url, probe);
+
+  return { kind: 'single-host', url: resolved };
+};