@itphx/synth-storage-postgres 0.0.0-stage → 0.12.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/LICENSE +18 -0
  2. package/LICENSE.ru.md +31 -0
  3. package/dist/errors.d.ts +71 -0
  4. package/dist/errors.js +126 -0
  5. package/dist/index.d.ts +51 -0
  6. package/dist/index.js +56 -0
  7. package/dist/json-param.d.ts +14 -0
  8. package/dist/json-param.js +22 -0
  9. package/dist/locks.d.ts +104 -0
  10. package/dist/locks.js +201 -0
  11. package/dist/migrate.d.ts +58 -0
  12. package/dist/migrate.js +125 -0
  13. package/dist/migrations/001-init.d.ts +15 -0
  14. package/dist/migrations/001-init.js +457 -0
  15. package/dist/migrations/002-egress-audit.d.ts +12 -0
  16. package/dist/migrations/002-egress-audit.js +52 -0
  17. package/dist/migrations/003-analytics-rollups.d.ts +12 -0
  18. package/dist/migrations/003-analytics-rollups.js +21 -0
  19. package/dist/migrations/004-pipeline-engine.d.ts +19 -0
  20. package/dist/migrations/004-pipeline-engine.js +74 -0
  21. package/dist/migrations/005-pipeline-provenance.d.ts +12 -0
  22. package/dist/migrations/005-pipeline-provenance.js +15 -0
  23. package/dist/migrations/006-plugin-audit.d.ts +13 -0
  24. package/dist/migrations/006-plugin-audit.js +34 -0
  25. package/dist/migrations/007-plugin-lock.d.ts +10 -0
  26. package/dist/migrations/007-plugin-lock.js +25 -0
  27. package/dist/migrations/008-plugin-audit-scan.d.ts +11 -0
  28. package/dist/migrations/008-plugin-audit-scan.js +15 -0
  29. package/dist/migrations/009-plugin-lock-previous.d.ts +13 -0
  30. package/dist/migrations/009-plugin-lock-previous.js +16 -0
  31. package/dist/migrations/010-plugin-lock-mode.d.ts +16 -0
  32. package/dist/migrations/010-plugin-lock-mode.js +20 -0
  33. package/dist/migrations/011-session-steer-inbox.d.ts +11 -0
  34. package/dist/migrations/011-session-steer-inbox.js +14 -0
  35. package/dist/migrations/012-external-credentials.d.ts +15 -0
  36. package/dist/migrations/012-external-credentials.js +40 -0
  37. package/dist/migrations/013-service-key-plugin-id.d.ts +17 -0
  38. package/dist/migrations/013-service-key-plugin-id.js +20 -0
  39. package/dist/migrations/014-session-mode-by-principal.d.ts +12 -0
  40. package/dist/migrations/014-session-mode-by-principal.js +15 -0
  41. package/dist/migrations/015-authority.d.ts +17 -0
  42. package/dist/migrations/015-authority.js +43 -0
  43. package/dist/migrations/016-credential-audit.d.ts +17 -0
  44. package/dist/migrations/016-credential-audit.js +32 -0
  45. package/dist/migrations/017-memory.d.ts +29 -0
  46. package/dist/migrations/017-memory.js +95 -0
  47. package/dist/migrations/018-memory-index-scope.d.ts +14 -0
  48. package/dist/migrations/018-memory-index-scope.js +18 -0
  49. package/dist/migrations/019-memory-index-enabled.d.ts +11 -0
  50. package/dist/migrations/019-memory-index-enabled.js +14 -0
  51. package/dist/migrations/020-project-memory.d.ts +11 -0
  52. package/dist/migrations/020-project-memory.js +13 -0
  53. package/dist/migrations/021-background-runs.d.ts +17 -0
  54. package/dist/migrations/021-background-runs.js +67 -0
  55. package/dist/migrations/022-background-run-process-id.d.ts +14 -0
  56. package/dist/migrations/022-background-run-process-id.js +18 -0
  57. package/dist/migrations/023-session-worktree.d.ts +12 -0
  58. package/dist/migrations/023-session-worktree.js +16 -0
  59. package/dist/migrations/024-blob-refs.d.ts +15 -0
  60. package/dist/migrations/024-blob-refs.js +26 -0
  61. package/dist/migrations/025-packs-pipelines.d.ts +28 -0
  62. package/dist/migrations/025-packs-pipelines.js +82 -0
  63. package/dist/migrations/026-instance-skills.d.ts +17 -0
  64. package/dist/migrations/026-instance-skills.js +25 -0
  65. package/dist/migrations/027-context-files.d.ts +20 -0
  66. package/dist/migrations/027-context-files.js +30 -0
  67. package/dist/migrations/index.d.ts +23 -0
  68. package/dist/migrations/index.js +71 -0
  69. package/dist/pool.d.ts +178 -0
  70. package/dist/pool.js +382 -0
  71. package/dist/ports/analytics.d.ts +26 -0
  72. package/dist/ports/analytics.js +243 -0
  73. package/dist/ports/audit.d.ts +15 -0
  74. package/dist/ports/audit.js +192 -0
  75. package/dist/ports/authority.d.ts +27 -0
  76. package/dist/ports/authority.js +148 -0
  77. package/dist/ports/background-runs.d.ts +41 -0
  78. package/dist/ports/background-runs.js +179 -0
  79. package/dist/ports/blob-refs.d.ts +36 -0
  80. package/dist/ports/blob-refs.js +55 -0
  81. package/dist/ports/content.d.ts +41 -0
  82. package/dist/ports/content.js +1553 -0
  83. package/dist/ports/context-files.d.ts +145 -0
  84. package/dist/ports/context-files.js +279 -0
  85. package/dist/ports/core-sync.d.ts +31 -0
  86. package/dist/ports/core-sync.js +34 -0
  87. package/dist/ports/credential-audit.d.ts +19 -0
  88. package/dist/ports/credential-audit.js +96 -0
  89. package/dist/ports/deps.d.ts +63 -0
  90. package/dist/ports/deps.js +19 -0
  91. package/dist/ports/events-bindings.d.ts +77 -0
  92. package/dist/ports/events-bindings.js +356 -0
  93. package/dist/ports/events-core.d.ts +35 -0
  94. package/dist/ports/events-core.js +71 -0
  95. package/dist/ports/events-journal.d.ts +68 -0
  96. package/dist/ports/events-journal.js +211 -0
  97. package/dist/ports/events-scheduler.d.ts +49 -0
  98. package/dist/ports/events-scheduler.js +231 -0
  99. package/dist/ports/events-webhooks.d.ts +64 -0
  100. package/dist/ports/events-webhooks.js +268 -0
  101. package/dist/ports/events.d.ts +20 -0
  102. package/dist/ports/events.js +27 -0
  103. package/dist/ports/external-credentials.d.ts +6 -0
  104. package/dist/ports/external-credentials.js +363 -0
  105. package/dist/ports/legacy-pipelines.d.ts +50 -0
  106. package/dist/ports/legacy-pipelines.js +202 -0
  107. package/dist/ports/memory.d.ts +65 -0
  108. package/dist/ports/memory.js +471 -0
  109. package/dist/ports/packs.d.ts +32 -0
  110. package/dist/ports/packs.js +117 -0
  111. package/dist/ports/pipelines.d.ts +67 -0
  112. package/dist/ports/pipelines.js +297 -0
  113. package/dist/ports/plugin-audit.d.ts +14 -0
  114. package/dist/ports/plugin-audit.js +110 -0
  115. package/dist/ports/plugin-lock.d.ts +27 -0
  116. package/dist/ports/plugin-lock.js +145 -0
  117. package/dist/ports/principals-defaults.d.ts +21 -0
  118. package/dist/ports/principals-defaults.js +68 -0
  119. package/dist/ports/principals-documents.d.ts +23 -0
  120. package/dist/ports/principals-documents.js +38 -0
  121. package/dist/ports/principals-profiles.d.ts +21 -0
  122. package/dist/ports/principals-profiles.js +263 -0
  123. package/dist/ports/principals-projects.d.ts +19 -0
  124. package/dist/ports/principals-projects.js +161 -0
  125. package/dist/ports/principals-settings.d.ts +25 -0
  126. package/dist/ports/principals-settings.js +295 -0
  127. package/dist/ports/principals-shared.d.ts +33 -0
  128. package/dist/ports/principals-shared.js +44 -0
  129. package/dist/ports/principals.d.ts +27 -0
  130. package/dist/ports/principals.js +39 -0
  131. package/dist/ports/questions.d.ts +40 -0
  132. package/dist/ports/questions.js +135 -0
  133. package/dist/ports/sessions-mapping.d.ts +254 -0
  134. package/dist/ports/sessions-mapping.js +449 -0
  135. package/dist/ports/sessions.d.ts +143 -0
  136. package/dist/ports/sessions.js +517 -0
  137. package/dist/ports/skills.d.ts +59 -0
  138. package/dist/ports/skills.js +205 -0
  139. package/dist/ports/stub.d.ts +14 -0
  140. package/dist/ports/stub.js +32 -0
  141. package/dist/ports/worktrees.d.ts +41 -0
  142. package/dist/ports/worktrees.js +85 -0
  143. package/dist/postgres-storage.d.ts +58 -0
  144. package/dist/postgres-storage.js +110 -0
  145. package/dist/schema.d.ts +13 -0
  146. package/dist/schema.js +22 -0
  147. package/dist/storage-context.d.ts +80 -0
  148. package/dist/storage-context.js +238 -0
  149. package/package.json +40 -3
  150. package/README.md +0 -3
package/dist/pool.d.ts ADDED
@@ -0,0 +1,178 @@
1
+ /**
2
+ * Пул соединений и низкоуровневые хелперы PostgreSQL-драйвера (ADR-097, волна 3a).
3
+ *
4
+ * Модуль **не требует** установленного `pg` на импорте: `pg` подключается лениво,
5
+ * внутри `createPostgresConnection`/при первом обращении к пулу (типы `pg` приходят
6
+ * из `@types/pg` и стираются на этапе компиляции). Это требование формы поставки
7
+ * (`pg` — `optionalDependencies`, ADR-097).
8
+ *
9
+ * Публичные примитивы следующей волны (портов):
10
+ * - `query(text, params)` — запрос через пул (с маппингом ошибок);
11
+ * - `withTransaction(fn)` — транзакция на выделенном соединении;
12
+ * - `withAdvisoryLock(key, fn)` — session-level advisory-лок (выделенное соединение);
13
+ * - `tryAdvisoryLock(key, fn)` — неблокирующий вариант (`pg_try_advisory_lock`).
14
+ */
15
+ import type { Pool as PgPool, PoolClient as PgPoolClient, QueryResultRow } from 'pg';
16
+ import { type PostgresSslMode, type SecurityTlsConfig, type TlsRuntimeSettings } from '@itphx/synth-shared';
17
+ /** Локальный тип модуля `pg` (пакет опционален, но резолвится в рантайме). */
18
+ interface PgModule {
19
+ Pool: new (config: Record<string, unknown>) => PgPool;
20
+ Client: new (config: Record<string, unknown>) => PgPoolClient & {
21
+ end(): Promise<void>;
22
+ };
23
+ }
24
+ /** Лениво загружает optional-зависимость `pg` (один раз на процесс). */
25
+ export declare function loadPgModule(): Promise<PgModule>;
26
+ /** Параметры подключения/пула, транслируемые в `pg.Pool`. */
27
+ export interface PostgresPoolConfig {
28
+ host?: string;
29
+ port?: number;
30
+ user?: string;
31
+ /** Пароль (инвариант 13: env/файл; в config.yaml не хранится). */
32
+ password?: string;
33
+ database?: string;
34
+ /** Максимальный размер пула (дефолт драйвера — 10). */
35
+ max?: number;
36
+ /** Таймаут установления соединения, мс (дефолт 5000). */
37
+ connectionTimeoutMillis?: number;
38
+ /** Таймаут простаивающего соединения, мс (дефолт 30000). */
39
+ idleTimeoutMillis?: number;
40
+ /**
41
+ * ADR-099/ADR-097: TLS-режим (`disable`/`require`/`verify-full`; `verify-ca` —
42
+ * алиас `verify-full`). Не задан — используется legacy `ssl`, иначе без TLS.
43
+ */
44
+ sslmode?: PostgresSslMode;
45
+ /**
46
+ * TLS: `true`/`false` либо объект опций (`ca`/`rejectUnauthorized`/…).
47
+ * Legacy-поле: применяется, только если `sslmode` не задан.
48
+ */
49
+ ssl?: boolean | Record<string, unknown>;
50
+ }
51
+ /** Конфиг подключения драйвера (подмножество полного конфига драйвера). */
52
+ export interface PostgresConnectionConfig {
53
+ /** Строка подключения `postgres://…`; приоритетнее полей `pool`. */
54
+ connectionString?: string;
55
+ /** Параметры подключения, если не задана `connectionString`. */
56
+ pool?: PostgresPoolConfig;
57
+ /**
58
+ * ADR-099: доверие TLS/CA (`security.tls`) — источник CA/mTLS для
59
+ * `sslmode=verify-full` (`buildPostgresSslOptions`).
60
+ */
61
+ tls?: SecurityTlsConfig;
62
+ /**
63
+ * ADR-099: runtime bootstrap-настройки TLS (`{dataDir}/security-tls.json`) —
64
+ * per-host mTLS-профили (выбор по `host` БД) и CA/rejectUnauthorized.
65
+ */
66
+ tlsRuntime?: TlsRuntimeSettings;
67
+ /** Env для резолва `security.tls` (ADR-023: env > runtime > config). */
68
+ env?: NodeJS.ProcessEnv;
69
+ /** Пароль БД отдельным полем (env/файл) — приоритетнее `pool.password`. */
70
+ password?: string;
71
+ /** Схема БД (namespace таблиц); по умолчанию `public`. */
72
+ schema?: string;
73
+ /** `statement_timeout`, мс (дефолт 15000). */
74
+ statementTimeoutMillis?: number;
75
+ /** `idle_in_transaction_session_timeout`, мс (дефолт 60000). */
76
+ idleInTransactionTimeoutMillis?: number;
77
+ /** `application_name` (дефолт `synth`). */
78
+ applicationName?: string;
79
+ }
80
+ export declare const DEFAULT_POOL_MAX = 10;
81
+ export declare const DEFAULT_STATEMENT_TIMEOUT_MS = 15000;
82
+ export declare const DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 60000;
83
+ export declare const DEFAULT_APPLICATION_NAME = "synth";
84
+ /**
85
+ * Исполнитель запросов: общий контракт для пула (`query`) и выделенного
86
+ * соединения (транзакция/advisory-лок). Возвращает массив строк.
87
+ */
88
+ export interface PostgresExecutor {
89
+ query<T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]): Promise<T[]>;
90
+ }
91
+ /**
92
+ * ADR-097: выделенное соединение, удерживаемое вызывающим (напр. для
93
+ * session-level advisory-лока лидера). Пока оно не возвращено в пул, пул не
94
+ * может его переиспользовать — держите не больше одного такого соединения на
95
+ * процесс, если в этом нет необходимости (`poolMax` по умолчанию невелик).
96
+ */
97
+ export interface HeldPostgresClient {
98
+ /** Исполнитель запросов на выделенном соединении. */
99
+ executor: PostgresExecutor;
100
+ /** Вернуть соединение в пул (идемпотентно, best-effort). */
101
+ release(): void;
102
+ /** Подписка на разрыв/ошибку соединения (детект потери advisory-лока). */
103
+ onError(handler: (err: unknown) => void): void;
104
+ }
105
+ /** Преобразует пользовательский ключ в 64-битный знаковый advisory-лок-ключ. */
106
+ export declare function advisoryLockKeyToBigInt(key: string): bigint;
107
+ /** Собирает объект конфигурации `pg.Pool` из конфига драйвера. */
108
+ export declare function buildPoolConfig(config: PostgresConnectionConfig, schema: string): Record<string, unknown>;
109
+ /**
110
+ * ADR-099/ADR-097: fail-closed проверка DSN на TLS-параметры. DSN из
111
+ * `storage.postgres.dsn` не должен нести `sslmode`/`sslrootcert`/`sslcert`/`sslkey`/…:
112
+ * `pg` накладывает DSN поверх конфига и молча перекрывает `ssl`-объект, что
113
+ * обнуляло бы политику CA. Задавайте TLS только в `storage.postgres.sslmode` +
114
+ * `security.tls`.
115
+ */
116
+ export declare function assertNoDsnTlsParams(connectionString: string | undefined): void;
117
+ /**
118
+ * Защитная сеть драйвера: удаляет реальные U+0000 из строковых параметров
119
+ * запроса (PostgreSQL отвергает их в `text`/`jsonb`). `Buffer`, числа и прочие
120
+ * не-строки не трогаются; SQL-текст не меняется. JSON-параметры дополнительно
121
+ * санитизируются до `JSON.stringify` (`jsonbParam`), иначе NUL стал бы escape'ом
122
+ * `\u0000`, который в готовой строке уже неотличим от литеральной
123
+ * последовательности.
124
+ */
125
+ export declare function sanitizeQueryParams(params?: unknown[]): unknown[] | undefined;
126
+ /**
127
+ * Соединение с PostgreSQL: ленивый пул + примитивы запросов/транзакций/локов.
128
+ * Каждый вызов `createPostgresConnection` создаёт независимое соединение
129
+ * (никаких модульных синглтонов — важно для герметичных тестов и переключаемых схем).
130
+ */
131
+ export declare class PostgresConnection implements PostgresExecutor {
132
+ private readonly _schema;
133
+ private readonly _poolConfig;
134
+ private _pool;
135
+ /** `end()` уже вызван: пул закрыт, ленивое пересоздание запрещено. */
136
+ private _closed;
137
+ constructor(config: PostgresConnectionConfig);
138
+ /** Схема, к которой привязано соединение. */
139
+ get schema(): string;
140
+ /** Ленивое создание пула (первое обращение к БД). */
141
+ getPool(): Promise<PgPool>;
142
+ query<T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]): Promise<T[]>;
143
+ /** Транзакция на выделенном соединении; ошибка callback'а → `ROLLBACK`. */
144
+ withTransaction<T>(fn: (tx: PostgresExecutor) => Promise<T>): Promise<T>;
145
+ /**
146
+ * Выполнить `fn` под session-level advisory-локом (выделенное соединение:
147
+ * лок живёт всю сессию, не транзакцию). Результат `fn` возвращается.
148
+ */
149
+ withAdvisoryLock<T>(key: string, fn: (tx: PostgresExecutor) => Promise<T>): Promise<T>;
150
+ /**
151
+ * Неблокирующий advisory-лок: `acquired:false`, если лок уже кем-то взят
152
+ * (свой или чужой процесс). Успех — `{ acquired:true, result }`.
153
+ */
154
+ tryAdvisoryLock<T>(key: string, fn: (tx: PostgresExecutor) => Promise<T>): Promise<{
155
+ acquired: boolean;
156
+ result?: T;
157
+ }>;
158
+ /**
159
+ * Захватить выделенное соединение, удерживаемое вызывающим (не возвращается в
160
+ * пул до `release()`). Нужно для session-level advisory-локов: лок живёт ровно
161
+ * столько, сколько открыто соединение, и снимается автоматически при его
162
+ * разрыве/закрытии (ADR-097).
163
+ */
164
+ acquireHeldClient(): Promise<HeldPostgresClient>;
165
+ /** Закрыть пул (идемпотентно). После закрытия запросы запрещены (не пересоздаём пул). */
166
+ end(): Promise<void>;
167
+ /**
168
+ * Удалить схему (`DROP SCHEMA … CASCADE`) — тестовая/сервисная операция.
169
+ * Пул закрывается, удаление выполняется отдельным клиентом без `search_path`
170
+ * на удаляемую схему.
171
+ */
172
+ dropSchema(schema?: string): Promise<void>;
173
+ private _acquire;
174
+ private _withDedicatedClient;
175
+ }
176
+ /** Создать соединение с PostgreSQL (ленивый пул; `pg` загружается при первом запросе). */
177
+ export declare function createPostgresConnection(config: PostgresConnectionConfig): PostgresConnection;
178
+ export {};
package/dist/pool.js ADDED
@@ -0,0 +1,382 @@
1
+ /**
2
+ * Пул соединений и низкоуровневые хелперы PostgreSQL-драйвера (ADR-097, волна 3a).
3
+ *
4
+ * Модуль **не требует** установленного `pg` на импорте: `pg` подключается лениво,
5
+ * внутри `createPostgresConnection`/при первом обращении к пулу (типы `pg` приходят
6
+ * из `@types/pg` и стираются на этапе компиляции). Это требование формы поставки
7
+ * (`pg` — `optionalDependencies`, ADR-097).
8
+ *
9
+ * Публичные примитивы следующей волны (портов):
10
+ * - `query(text, params)` — запрос через пул (с маппингом ошибок);
11
+ * - `withTransaction(fn)` — транзакция на выделенном соединении;
12
+ * - `withAdvisoryLock(key, fn)` — session-level advisory-лок (выделенное соединение);
13
+ * - `tryAdvisoryLock(key, fn)` — неблокирующий вариант (`pg_try_advisory_lock`).
14
+ */
15
+ import { createHash } from 'node:crypto';
16
+ import { buildPostgresSslOptions, findDsnTlsParams, stripNullBytes, } from '@itphx/synth-shared';
17
+ import { PostgresConnectionError, PostgresStorageConfigError, PostgresStorageDependencyError, mapPgError, } from './errors.js';
18
+ import { DEFAULT_SCHEMA, assertValidSchema, quoteIdent } from './schema.js';
19
+ /** Аннотация `string` намеренная — `import()` не должен резолвиться на этапе типов. */
20
+ const PG_MODULE = 'pg';
21
+ /** Кэш модуля `pg` на процесс (ленивая загрузка, без верхнеуровневого импорта). */
22
+ let pgModulePromise = null;
23
+ /** Лениво загружает optional-зависимость `pg` (один раз на процесс). */
24
+ export async function loadPgModule() {
25
+ if (!pgModulePromise) {
26
+ pgModulePromise = (async () => {
27
+ let mod;
28
+ try {
29
+ mod = await import(PG_MODULE);
30
+ }
31
+ catch (cause) {
32
+ throw new PostgresStorageDependencyError('Не удалось загрузить драйвер `pg` (optional-зависимость). Установите его: pnpm add pg', { cause });
33
+ }
34
+ const candidate = mod;
35
+ const Pool = candidate.Pool ?? candidate.default?.Pool;
36
+ if (typeof Pool !== 'function') {
37
+ throw new PostgresStorageDependencyError('Модуль `pg` не экспортирует Pool (несовместимая версия).');
38
+ }
39
+ return mod;
40
+ })().catch((err) => {
41
+ // Сбрасываем кэш при неудаче, чтобы следующий вызов повторил попытку.
42
+ pgModulePromise = null;
43
+ throw err;
44
+ });
45
+ }
46
+ return pgModulePromise;
47
+ }
48
+ export const DEFAULT_POOL_MAX = 10;
49
+ export const DEFAULT_STATEMENT_TIMEOUT_MS = 15_000;
50
+ export const DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 60_000;
51
+ export const DEFAULT_APPLICATION_NAME = 'synth';
52
+ const DEFAULT_CONNECTION_TIMEOUT_MS = 5_000;
53
+ const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
54
+ /** Преобразует пользовательский ключ в 64-битный знаковый advisory-лок-ключ. */
55
+ export function advisoryLockKeyToBigInt(key) {
56
+ const digest = createHash('sha256').update(key).digest();
57
+ let value = 0n;
58
+ for (let i = 0; i < 8; i += 1) {
59
+ value = (value << 8n) | BigInt(digest[i] ?? 0);
60
+ }
61
+ const SIGN = 0x8000000000000000n;
62
+ const MOD = 0x10000000000000000n;
63
+ return value >= SIGN ? value - MOD : value;
64
+ }
65
+ /** Собирает объект конфигурации `pg.Pool` из конфига драйвера. */
66
+ export function buildPoolConfig(config, schema) {
67
+ // ADR-099/ADR-097: TLS-параметры в DSN запрещены — `pg` накладывает DSN поверх
68
+ // конфига (`Object.assign({}, config, parse(connectionString))`) и молча
69
+ // перекрывает явные ssl-опции (вплоть до отключения TLS).
70
+ assertNoDsnTlsParams(config.connectionString);
71
+ const pool = config.pool;
72
+ const pgConfig = {
73
+ max: pool?.max ?? DEFAULT_POOL_MAX,
74
+ connectionTimeoutMillis: pool?.connectionTimeoutMillis ?? DEFAULT_CONNECTION_TIMEOUT_MS,
75
+ idleTimeoutMillis: pool?.idleTimeoutMillis ?? DEFAULT_IDLE_TIMEOUT_MS,
76
+ // ADR-097: незанятые соединения не удерживают event loop — CLI-команды
77
+ // (`synth migrate`/`doctor`/…) со `storage.backend=postgres` завершаются,
78
+ // а не висят вечно из-за открытых idle-клиентов пула.
79
+ allowExitOnIdle: true,
80
+ statement_timeout: config.statementTimeoutMillis ?? DEFAULT_STATEMENT_TIMEOUT_MS,
81
+ idle_in_transaction_session_timeout: config.idleInTransactionTimeoutMillis ?? DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS,
82
+ application_name: config.applicationName ?? DEFAULT_APPLICATION_NAME,
83
+ // Схема драйвера — первая в search_path (таблицы без квалификации).
84
+ options: `-c search_path=${quoteIdent(schema)},public`,
85
+ };
86
+ if (config.connectionString) {
87
+ pgConfig.connectionString = config.connectionString;
88
+ }
89
+ else {
90
+ if (pool?.host)
91
+ pgConfig.host = pool.host;
92
+ if (pool?.port !== undefined)
93
+ pgConfig.port = pool.port;
94
+ if (pool?.user)
95
+ pgConfig.user = pool.user;
96
+ if (pool?.database)
97
+ pgConfig.database = pool.database;
98
+ }
99
+ const password = config.password ?? pool?.password;
100
+ if (password)
101
+ pgConfig.password = password;
102
+ // ADR-099/ADR-097: единый источник TLS — `sslmode` (`storage.postgres.sslmode`)
103
+ // + `security.tls` (CA/mTLS). Не задан — прежнее поведение (legacy `ssl` либо
104
+ // дефолт `pg` — без TLS). Ошибки сборки (нет CA при `verify-full`) — fail-closed
105
+ // доменной ошибкой конфигурации.
106
+ if (pool?.sslmode !== undefined) {
107
+ let ssl;
108
+ try {
109
+ ssl = buildPostgresSslOptions({
110
+ sslmode: pool.sslmode,
111
+ connectionString: config.connectionString,
112
+ host: pool.host,
113
+ config: config.tls ? { security: { tls: config.tls } } : undefined,
114
+ env: config.env,
115
+ runtime: config.tlsRuntime,
116
+ }).ssl;
117
+ }
118
+ catch (err) {
119
+ throw new PostgresStorageConfigError(err instanceof Error ? err.message : String(err));
120
+ }
121
+ if (ssl !== undefined)
122
+ pgConfig.ssl = ssl;
123
+ }
124
+ else if (pool?.ssl !== undefined) {
125
+ pgConfig.ssl = pool.ssl;
126
+ }
127
+ return pgConfig;
128
+ }
129
+ /**
130
+ * ADR-099/ADR-097: fail-closed проверка DSN на TLS-параметры. DSN из
131
+ * `storage.postgres.dsn` не должен нести `sslmode`/`sslrootcert`/`sslcert`/`sslkey`/…:
132
+ * `pg` накладывает DSN поверх конфига и молча перекрывает `ssl`-объект, что
133
+ * обнуляло бы политику CA. Задавайте TLS только в `storage.postgres.sslmode` +
134
+ * `security.tls`.
135
+ */
136
+ export function assertNoDsnTlsParams(connectionString) {
137
+ const found = findDsnTlsParams(connectionString);
138
+ if (found.length === 0)
139
+ return;
140
+ throw new PostgresStorageConfigError(`TLS-параметры в DSN запрещены (обнаружено: ${found.join(', ')}). ` +
141
+ 'Драйвер `pg` накладывает DSN поверх конфига и молча перекрывает ssl-опции ' +
142
+ '(вплоть до отключения TLS) — уберите TLS-параметры из DSN или задайте их ' +
143
+ 'только в storage.postgres.sslmode + security.tls');
144
+ }
145
+ /**
146
+ * Защитная сеть драйвера: удаляет реальные U+0000 из строковых параметров
147
+ * запроса (PostgreSQL отвергает их в `text`/`jsonb`). `Buffer`, числа и прочие
148
+ * не-строки не трогаются; SQL-текст не меняется. JSON-параметры дополнительно
149
+ * санитизируются до `JSON.stringify` (`jsonbParam`), иначе NUL стал бы escape'ом
150
+ * `\u0000`, который в готовой строке уже неотличим от литеральной
151
+ * последовательности.
152
+ */
153
+ export function sanitizeQueryParams(params) {
154
+ if (!params || params.length === 0)
155
+ return params;
156
+ let changed = false;
157
+ const sanitized = params.map((param) => {
158
+ if (typeof param === 'string' && param.includes('\u0000')) {
159
+ changed = true;
160
+ return stripNullBytes(param);
161
+ }
162
+ return param;
163
+ });
164
+ return changed ? sanitized : params;
165
+ }
166
+ /** Обёртка-исполнитель над соединением с маппингом ошибок в доменные классы. */
167
+ function wrapExecutor(client) {
168
+ return {
169
+ async query(text, params) {
170
+ try {
171
+ const result = await client.query(text, sanitizeQueryParams(params));
172
+ return result.rows;
173
+ }
174
+ catch (err) {
175
+ throw mapPgError(err);
176
+ }
177
+ },
178
+ };
179
+ }
180
+ /**
181
+ * Соединение с PostgreSQL: ленивый пул + примитивы запросов/транзакций/локов.
182
+ * Каждый вызов `createPostgresConnection` создаёт независимое соединение
183
+ * (никаких модульных синглтонов — важно для герметичных тестов и переключаемых схем).
184
+ */
185
+ export class PostgresConnection {
186
+ _schema;
187
+ _poolConfig;
188
+ _pool = null;
189
+ /** `end()` уже вызван: пул закрыт, ленивое пересоздание запрещено. */
190
+ _closed = false;
191
+ constructor(config) {
192
+ this._schema = assertValidSchema(config.schema ?? DEFAULT_SCHEMA);
193
+ this._poolConfig = buildPoolConfig(config, this._schema);
194
+ }
195
+ /** Схема, к которой привязано соединение. */
196
+ get schema() {
197
+ return this._schema;
198
+ }
199
+ /** Ленивое создание пула (первое обращение к БД). */
200
+ async getPool() {
201
+ // ADR-097 (W5): после `end()` пул не пересоздаётся — иначе запрос после
202
+ // `close()` снова поднимал бы соединение и «закрытие» было бы фиктивным.
203
+ if (this._closed) {
204
+ throw new PostgresConnectionError('Соединение с PostgreSQL закрыто (end()): пул недоступен.');
205
+ }
206
+ if (!this._pool) {
207
+ const pg = await loadPgModule();
208
+ this._pool = new pg.Pool(this._poolConfig);
209
+ }
210
+ return this._pool;
211
+ }
212
+ async query(text, params) {
213
+ const pool = await this.getPool();
214
+ try {
215
+ const result = await pool.query(text, sanitizeQueryParams(params));
216
+ return result.rows;
217
+ }
218
+ catch (err) {
219
+ throw mapPgError(err);
220
+ }
221
+ }
222
+ /** Транзакция на выделенном соединении; ошибка callback'а → `ROLLBACK`. */
223
+ async withTransaction(fn) {
224
+ const client = await this._acquire();
225
+ const tx = wrapExecutor(client);
226
+ try {
227
+ await tx.query('BEGIN');
228
+ const result = await fn(tx);
229
+ await tx.query('COMMIT');
230
+ return result;
231
+ }
232
+ catch (err) {
233
+ try {
234
+ await tx.query('ROLLBACK');
235
+ }
236
+ catch {
237
+ // rollback best-effort: соединение вернётся в пул, исходная ошибка важнее
238
+ }
239
+ throw mapPgError(err);
240
+ }
241
+ finally {
242
+ client.release();
243
+ }
244
+ }
245
+ /**
246
+ * Выполнить `fn` под session-level advisory-локом (выделенное соединение:
247
+ * лок живёт всю сессию, не транзакцию). Результат `fn` возвращается.
248
+ */
249
+ async withAdvisoryLock(key, fn) {
250
+ const lockKey = advisoryLockKeyToBigInt(key).toString();
251
+ return this._withDedicatedClient(async (tx) => {
252
+ await tx.query('SELECT pg_advisory_lock($1::bigint)', [lockKey]);
253
+ try {
254
+ return await fn(tx);
255
+ }
256
+ finally {
257
+ await tx.query('SELECT pg_advisory_unlock($1::bigint)', [lockKey]).catch(() => undefined);
258
+ }
259
+ });
260
+ }
261
+ /**
262
+ * Неблокирующий advisory-лок: `acquired:false`, если лок уже кем-то взят
263
+ * (свой или чужой процесс). Успех — `{ acquired:true, result }`.
264
+ */
265
+ async tryAdvisoryLock(key, fn) {
266
+ const lockKey = advisoryLockKeyToBigInt(key).toString();
267
+ return this._withDedicatedClient(async (tx) => {
268
+ const rows = await tx.query('SELECT pg_try_advisory_lock($1::bigint) AS locked', [lockKey]);
269
+ if (rows[0]?.locked !== true)
270
+ return { acquired: false };
271
+ try {
272
+ const result = await fn(tx);
273
+ return { acquired: true, result };
274
+ }
275
+ finally {
276
+ await tx.query('SELECT pg_advisory_unlock($1::bigint)', [lockKey]).catch(() => undefined);
277
+ }
278
+ });
279
+ }
280
+ /**
281
+ * Захватить выделенное соединение, удерживаемое вызывающим (не возвращается в
282
+ * пул до `release()`). Нужно для session-level advisory-локов: лок живёт ровно
283
+ * столько, сколько открыто соединение, и снимается автоматически при его
284
+ * разрыве/закрытии (ADR-097).
285
+ */
286
+ async acquireHeldClient() {
287
+ const client = await this._acquire();
288
+ const executor = wrapExecutor(client);
289
+ let released = false;
290
+ const errorHandlers = [];
291
+ // `pg.PoolClient` — EventEmitter; на ошибке соединения (сервер упал, сеть
292
+ // оборвалась) эмитит `error`. Потребитель (лидер) снимает себя с лидерства.
293
+ // Слушатель снимаем на `release()`: клиент возвращается в пул и
294
+ // переиспользуется — иначе накопились бы «висячие» обработчики.
295
+ const onClientError = (err) => {
296
+ for (const handler of errorHandlers) {
297
+ try {
298
+ handler(err);
299
+ }
300
+ catch {
301
+ // обратный вызов потребителя не должен ломать обработку ошибки
302
+ }
303
+ }
304
+ };
305
+ const emitter = client;
306
+ emitter.on?.('error', onClientError);
307
+ return {
308
+ executor,
309
+ release: () => {
310
+ if (released)
311
+ return;
312
+ released = true;
313
+ if (emitter.off)
314
+ emitter.off('error', onClientError);
315
+ else
316
+ emitter.removeListener?.('error', onClientError);
317
+ try {
318
+ client.release();
319
+ }
320
+ catch {
321
+ // пул закрывается / соединение уже отдано — best-effort
322
+ }
323
+ },
324
+ onError: (handler) => {
325
+ errorHandlers.push(handler);
326
+ },
327
+ };
328
+ }
329
+ /** Закрыть пул (идемпотентно). После закрытия запросы запрещены (не пересоздаём пул). */
330
+ async end() {
331
+ this._closed = true;
332
+ const pool = this._pool;
333
+ this._pool = null;
334
+ if (pool)
335
+ await pool.end();
336
+ }
337
+ /**
338
+ * Удалить схему (`DROP SCHEMA … CASCADE`) — тестовая/сервисная операция.
339
+ * Пул закрывается, удаление выполняется отдельным клиентом без `search_path`
340
+ * на удаляемую схему.
341
+ */
342
+ async dropSchema(schema = this._schema) {
343
+ const safeSchema = assertValidSchema(schema);
344
+ await this.end();
345
+ const pg = await loadPgModule();
346
+ const baseConfig = { ...this._poolConfig };
347
+ delete baseConfig.options;
348
+ const client = new pg.Client(baseConfig);
349
+ try {
350
+ await client.connect();
351
+ await client.query(`DROP SCHEMA IF EXISTS ${quoteIdent(safeSchema)} CASCADE`);
352
+ }
353
+ catch (err) {
354
+ throw mapPgError(err);
355
+ }
356
+ finally {
357
+ await client.end().catch(() => undefined);
358
+ }
359
+ }
360
+ async _acquire() {
361
+ const pool = await this.getPool();
362
+ try {
363
+ return await pool.connect();
364
+ }
365
+ catch (err) {
366
+ throw mapPgError(err);
367
+ }
368
+ }
369
+ async _withDedicatedClient(fn) {
370
+ const client = await this._acquire();
371
+ try {
372
+ return await fn(wrapExecutor(client));
373
+ }
374
+ finally {
375
+ client.release();
376
+ }
377
+ }
378
+ }
379
+ /** Создать соединение с PostgreSQL (ленивый пул; `pg` загружается при первом запросе). */
380
+ export function createPostgresConnection(config) {
381
+ return new PostgresConnection(config);
382
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Порт роллапов аналитики PostgreSQL-драйвера (ADR-102).
3
+ *
4
+ * Таблица `analytics_rollups` (миграция 003): ключ бакета — составной первичный
5
+ * ключ `(family, day, dimensions)` (`jsonb` нормализует порядок ключей объекта,
6
+ * поэтому равенство измерений устойчиво и годится для btree-равенства; отдельный
7
+ * `dimensions_key` не нужен). `measures`/`cost_by_currency` — `jsonb`-словари
8
+ * чисел (`cost_by_currency` пустая → `NULL`).
9
+ *
10
+ * `increment` — атомарный upsert `INSERT … ON CONFLICT (family, day, dimensions)
11
+ * DO UPDATE` с суммированием `measures`/`cost_by_currency` прямо в SQL (jsonb →
12
+ * `jsonb_each_text` → `SUM` → `jsonb_object_agg`); advisory-локи не нужны —
13
+ * конкурентные инкременты сериализуются конфликтом уникального ключа. `set` —
14
+ * точная перезапись полей из `EXCLUDED`.
15
+ *
16
+ * Семантика нормализации/сложения/агрегации повторяет общий core-хелпер
17
+ * (`analytics-rollup-helpers.ts`): драйвер не тянет core рантаймом (только
18
+ * `import type`), поэтому фильтр по семейству/периоду выполняется в SQL, а
19
+ * группировка `groupBy` и слияние мер — локальной точной репликой хелпера.
20
+ */
21
+ import type { StorageContext } from '@itphx/synth-core';
22
+ import type { PortDeps } from './deps.js';
23
+ /** Часть `StorageContext`, которой владеет группа `analytics`. */
24
+ export type AnalyticsPorts = Pick<StorageContext, 'analyticsRollups'>;
25
+ /** Собрать порт роллапов аналитики. */
26
+ export declare function buildAnalyticsPorts(deps: PortDeps): AnalyticsPorts;