@itphx/synth-storage-postgres 0.0.0-stage → 0.11.3
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.
- package/LICENSE +18 -0
- package/LICENSE.ru.md +31 -0
- package/dist/errors.d.ts +71 -0
- package/dist/errors.js +126 -0
- package/dist/index.d.ts +37 -0
- package/dist/index.js +34 -0
- package/dist/json-param.d.ts +14 -0
- package/dist/json-param.js +22 -0
- package/dist/locks.d.ts +104 -0
- package/dist/locks.js +201 -0
- package/dist/migrate.d.ts +58 -0
- package/dist/migrate.js +125 -0
- package/dist/migrations/001-init.d.ts +15 -0
- package/dist/migrations/001-init.js +457 -0
- package/dist/migrations/002-egress-audit.d.ts +12 -0
- package/dist/migrations/002-egress-audit.js +52 -0
- package/dist/migrations/003-analytics-rollups.d.ts +12 -0
- package/dist/migrations/003-analytics-rollups.js +21 -0
- package/dist/migrations/index.d.ts +23 -0
- package/dist/migrations/index.js +23 -0
- package/dist/pool.d.ts +178 -0
- package/dist/pool.js +382 -0
- package/dist/ports/analytics.d.ts +26 -0
- package/dist/ports/analytics.js +243 -0
- package/dist/ports/audit.d.ts +15 -0
- package/dist/ports/audit.js +189 -0
- package/dist/ports/content.d.ts +41 -0
- package/dist/ports/content.js +1539 -0
- package/dist/ports/core-sync.d.ts +31 -0
- package/dist/ports/core-sync.js +34 -0
- package/dist/ports/deps.d.ts +63 -0
- package/dist/ports/deps.js +19 -0
- package/dist/ports/events-bindings.d.ts +77 -0
- package/dist/ports/events-bindings.js +356 -0
- package/dist/ports/events-core.d.ts +35 -0
- package/dist/ports/events-core.js +71 -0
- package/dist/ports/events-journal.d.ts +68 -0
- package/dist/ports/events-journal.js +211 -0
- package/dist/ports/events-scheduler.d.ts +49 -0
- package/dist/ports/events-scheduler.js +231 -0
- package/dist/ports/events-webhooks.d.ts +64 -0
- package/dist/ports/events-webhooks.js +268 -0
- package/dist/ports/events.d.ts +20 -0
- package/dist/ports/events.js +27 -0
- package/dist/ports/principals-defaults.d.ts +21 -0
- package/dist/ports/principals-defaults.js +68 -0
- package/dist/ports/principals-documents.d.ts +23 -0
- package/dist/ports/principals-documents.js +38 -0
- package/dist/ports/principals-profiles.d.ts +21 -0
- package/dist/ports/principals-profiles.js +263 -0
- package/dist/ports/principals-projects.d.ts +19 -0
- package/dist/ports/principals-projects.js +158 -0
- package/dist/ports/principals-settings.d.ts +25 -0
- package/dist/ports/principals-settings.js +275 -0
- package/dist/ports/principals-shared.d.ts +33 -0
- package/dist/ports/principals-shared.js +44 -0
- package/dist/ports/principals.d.ts +27 -0
- package/dist/ports/principals.js +39 -0
- package/dist/ports/sessions-mapping.d.ts +237 -0
- package/dist/ports/sessions-mapping.js +405 -0
- package/dist/ports/sessions.d.ts +133 -0
- package/dist/ports/sessions.js +502 -0
- package/dist/ports/stub.d.ts +14 -0
- package/dist/ports/stub.js +32 -0
- package/dist/postgres-storage.d.ts +59 -0
- package/dist/postgres-storage.js +111 -0
- package/dist/schema.d.ts +13 -0
- package/dist/schema.js +22 -0
- package/dist/storage-context.d.ts +51 -0
- package/dist/storage-context.js +130 -0
- package/package.json +40 -3
- package/README.md +0 -3
|
@@ -0,0 +1,502 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Порт `SessionRepository` поверх PostgreSQL (PROP-032, волна 3b).
|
|
3
|
+
*
|
|
4
|
+
* Группа портов **сессий** PostgreSQL-драйвера: единственная фабрика
|
|
5
|
+
* `buildSessionPorts(deps)` собирает `StorageContext['sessions']`.
|
|
6
|
+
*
|
|
7
|
+
* Семантика — паритет с файловой (`FileStore`) и in-memory
|
|
8
|
+
* (`MemorySessionRepository`) реализациями:
|
|
9
|
+
* - `save` — **одна транзакция**: upsert строки `sessions` + **полная замена**
|
|
10
|
+
* child-таблиц (`messages`/`session_references`/`checkpoints`/`sticky_notes`):
|
|
11
|
+
* `DELETE … WHERE session_id` + массовый `INSERT` (по чанкам);
|
|
12
|
+
* - `appendMessage`/`updateMessage` — **точечные** операции над одной строкой
|
|
13
|
+
* `messages` в транзакции под тем же per-session advisory-локом, без
|
|
14
|
+
* перезаписи истории: append берёт `seq = MAX(seq)+1`, update целится по
|
|
15
|
+
* `seq` (fallback — `id`) и не меняет `id`/`seq`/`created_at`; обе операции
|
|
16
|
+
* обновляют `sessions.updated_at`;
|
|
17
|
+
* - `seq` сообщений — **позиционный**: при записи драйвер нормализует его по
|
|
18
|
+
* порядку массива `1..n`. Это снимает legacy-коллизию `UNIQUE (session_id, seq)`
|
|
19
|
+
* (у старых сессий у всех сообщений `seq = 0`) и делает порядок однозначным;
|
|
20
|
+
* домен и так переставляет `seq = i+1` при ветвлении/merge — приведение к
|
|
21
|
+
* позиции смысла не меняет;
|
|
22
|
+
* - `id` сообщения **не уникален** в пределах сессии (legacy-дубликаты):
|
|
23
|
+
* PK `messages` — суррогатный `message_uid`, поэтому дубликаты `id`
|
|
24
|
+
* сохраняются без потерь (upsert по `id` их молча схлопывал);
|
|
25
|
+
* - per-session сериализация записи — транзакционный `pg_advisory_xact_lock`
|
|
26
|
+
* (держится до `COMMIT`; аналог per-session `AsyncLock` файловой реализации);
|
|
27
|
+
* - чтения (`load`/`list`/`listForUser`/`listForUserScope`/`search`) отдают
|
|
28
|
+
* **полную** `Session`; сообщения/child-строки подгружаются **батчем**
|
|
29
|
+
* (`WHERE session_id = ANY($1)`, без N+1); порядок сообщений — по `seq` с
|
|
30
|
+
* тайбрейкером `created_at`, затем `id` (детерминированное чтение);
|
|
31
|
+
* - `listLight` — метаданные без истории (`messages`/`pendingMessages`/
|
|
32
|
+
* `checkpoints` пусты, child-таблицы не читаются): одна выборка из `sessions`
|
|
33
|
+
* тем же `WHERE`/порядком, что у `list`; `loadLight` — та же проекция по
|
|
34
|
+
* одному id (одна выборка по PK);
|
|
35
|
+
* - `list`/`listForUser*` сортируют `updated_at DESC`; архивированные сессии
|
|
36
|
+
* **не** отфильтровываются — это ответственность менеджера
|
|
37
|
+
* (`SessionManager.listSessions`, как и у файловой/memory реализаций);
|
|
38
|
+
* - `delete` отсутствующей — не ошибка; `load` отсутствующей → `null`;
|
|
39
|
+
* `list` пустого → `[]`; `addReference`/`removeReference` отсутствующей
|
|
40
|
+
* сессии → `throw`; `getReferences` отсутствующей → `[]`.
|
|
41
|
+
*
|
|
42
|
+
* `search` — подстрока без учёта регистра (`ILIKE`) по `title` и `content`
|
|
43
|
+
* сообщений; индекс `messages_content_trgm_idx` (`pg_trgm`) уже заведён в
|
|
44
|
+
* `001_init`. Символы `%`/`_`/`\` экранируются — семантика «подстрока», как у
|
|
45
|
+
* `includes` файловой/memory реализаций.
|
|
46
|
+
*/
|
|
47
|
+
import { jsonbParam } from '../json-param.js';
|
|
48
|
+
import { generateId, makeTextPart, nowISO } from '@itphx/synth-shared';
|
|
49
|
+
import { checkpointRow, deserializeMessage, deserializeReference, deserializeSession, deserializeSessionLight, emptySessionChildren, messageRow, referenceRow, serializeSession, stickyNoteRow, } from './sessions-mapping.js';
|
|
50
|
+
/** Колонки `sessions` (порядок — как в `001_init`). */
|
|
51
|
+
const SESSION_FIELDS = [
|
|
52
|
+
'id',
|
|
53
|
+
'title',
|
|
54
|
+
'icon',
|
|
55
|
+
'color',
|
|
56
|
+
'session_origin',
|
|
57
|
+
'parent_id',
|
|
58
|
+
'branch_point',
|
|
59
|
+
'plan_approved',
|
|
60
|
+
'mode',
|
|
61
|
+
'user_id',
|
|
62
|
+
'owner_id',
|
|
63
|
+
'project_id',
|
|
64
|
+
'todos',
|
|
65
|
+
'prompt_states',
|
|
66
|
+
'obfuscation_map',
|
|
67
|
+
'status',
|
|
68
|
+
'settings',
|
|
69
|
+
'mcp_servers',
|
|
70
|
+
'pending_messages',
|
|
71
|
+
'current_stream',
|
|
72
|
+
'summarization_pending',
|
|
73
|
+
'can_summarize',
|
|
74
|
+
'created_at',
|
|
75
|
+
'updated_at',
|
|
76
|
+
'expires_at',
|
|
77
|
+
'archived_at',
|
|
78
|
+
'input_tokens',
|
|
79
|
+
'output_tokens',
|
|
80
|
+
'total_tokens',
|
|
81
|
+
'cache_read_tokens',
|
|
82
|
+
'cache_write_tokens',
|
|
83
|
+
'reasoning_tokens',
|
|
84
|
+
'input_cost',
|
|
85
|
+
'output_cost',
|
|
86
|
+
'cache_read_cost',
|
|
87
|
+
'cache_write_cost',
|
|
88
|
+
'cache_hit_rate',
|
|
89
|
+
];
|
|
90
|
+
const SESSION_JSON_FIELDS = new Set([
|
|
91
|
+
'todos',
|
|
92
|
+
'prompt_states',
|
|
93
|
+
'obfuscation_map',
|
|
94
|
+
'status',
|
|
95
|
+
'settings',
|
|
96
|
+
'mcp_servers',
|
|
97
|
+
'pending_messages',
|
|
98
|
+
'current_stream',
|
|
99
|
+
]);
|
|
100
|
+
/** Колонки `messages` (порядок — как в `001_init`). */
|
|
101
|
+
const MESSAGE_FIELDS = [
|
|
102
|
+
'id',
|
|
103
|
+
'session_id',
|
|
104
|
+
'seq',
|
|
105
|
+
'role',
|
|
106
|
+
'origin',
|
|
107
|
+
'source_msg_id',
|
|
108
|
+
'content',
|
|
109
|
+
'parts',
|
|
110
|
+
'tool_calls',
|
|
111
|
+
'tool_call_id',
|
|
112
|
+
'usage',
|
|
113
|
+
'metadata',
|
|
114
|
+
'prompt_meta',
|
|
115
|
+
'debug_data',
|
|
116
|
+
'summary_of',
|
|
117
|
+
'model',
|
|
118
|
+
'provider',
|
|
119
|
+
'provider_type',
|
|
120
|
+
'reasoning',
|
|
121
|
+
'source',
|
|
122
|
+
'author',
|
|
123
|
+
'agent_role',
|
|
124
|
+
'qa_pass',
|
|
125
|
+
'qa_reason',
|
|
126
|
+
'disabled',
|
|
127
|
+
'pinned',
|
|
128
|
+
'hidden',
|
|
129
|
+
'ephemeral',
|
|
130
|
+
'created_at',
|
|
131
|
+
];
|
|
132
|
+
const MESSAGE_JSON_FIELDS = new Set([
|
|
133
|
+
'parts',
|
|
134
|
+
'tool_calls',
|
|
135
|
+
'usage',
|
|
136
|
+
'metadata',
|
|
137
|
+
'prompt_meta',
|
|
138
|
+
'debug_data',
|
|
139
|
+
'summary_of',
|
|
140
|
+
]);
|
|
141
|
+
/**
|
|
142
|
+
* Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
|
|
143
|
+
* суррогатный `message_uid` (PK), доменный `id`, `session_id`, позиционный
|
|
144
|
+
* `seq` и `created_at`: они сохраняются от исходной строки (цель ищется по
|
|
145
|
+
* `seq`, fallback по `id`).
|
|
146
|
+
*/
|
|
147
|
+
export const MESSAGE_MUTABLE_FIELDS = MESSAGE_FIELDS.filter((field) => field !== 'id' && field !== 'session_id' && field !== 'seq' && field !== 'created_at');
|
|
148
|
+
/** Обязательные поля сообщения: безопасные дефолты (паритет с file/memory). */
|
|
149
|
+
function prepareMessage(message) {
|
|
150
|
+
return {
|
|
151
|
+
...message,
|
|
152
|
+
id: message.id || generateId(),
|
|
153
|
+
origin: message.origin || 'local',
|
|
154
|
+
parts: message.parts && message.parts.length > 0
|
|
155
|
+
? message.parts
|
|
156
|
+
: [makeTextPart(message.content ?? '')],
|
|
157
|
+
createdAt: message.createdAt || nowISO(),
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
const REFERENCE_FIELDS = [
|
|
161
|
+
'id',
|
|
162
|
+
'session_id',
|
|
163
|
+
'ref_session_id',
|
|
164
|
+
'label',
|
|
165
|
+
'message_range',
|
|
166
|
+
'auto_summary',
|
|
167
|
+
'ordinal',
|
|
168
|
+
'created_at',
|
|
169
|
+
];
|
|
170
|
+
const REFERENCE_JSON_FIELDS = new Set(['message_range']);
|
|
171
|
+
const CHECKPOINT_FIELDS = ['id', 'session_id', 'messages', 'created_at'];
|
|
172
|
+
const CHECKPOINT_JSON_FIELDS = new Set(['messages']);
|
|
173
|
+
const NOTE_FIELDS = ['id', 'session_id', 'content', 'disabled', 'created_at', 'updated_at'];
|
|
174
|
+
const NOTE_JSON_FIELDS = new Set();
|
|
175
|
+
/** Размер пакета строк в одном `INSERT` (лимит параметров протокола — 65535). */
|
|
176
|
+
const INSERT_CHUNK_SIZE = 200;
|
|
177
|
+
/** Значение для jsonb-колонки: нативный объект/массив → JSON-строка (NUL — вычищены). */
|
|
178
|
+
export function jsonParam(value) {
|
|
179
|
+
return jsonbParam(value);
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Значения строки в порядке колонок (jsonb — сериализуются, `undefined` → `NULL`).
|
|
183
|
+
* Экспортирован для unit-тестов сериализации (NUL не должен доходить до PG).
|
|
184
|
+
*/
|
|
185
|
+
export function rowValues(row, fields, jsonFields) {
|
|
186
|
+
return fields.map((field) => (jsonFields.has(field) ? jsonParam(row[field]) : row[field] ?? null));
|
|
187
|
+
}
|
|
188
|
+
/** Экранирование спецсимволов `LIKE` — подстрока ищется буквально. */
|
|
189
|
+
function escapeLike(value) {
|
|
190
|
+
return value.replace(/[\\%_]/g, (char) => `\\${char}`);
|
|
191
|
+
}
|
|
192
|
+
/** Пакетный upsert строк (по частям, чтобы не упираться в лимит параметров). */
|
|
193
|
+
async function upsertRows(tx, table, fields, rows, jsonFields, conflictKey) {
|
|
194
|
+
if (rows.length === 0)
|
|
195
|
+
return;
|
|
196
|
+
const updatable = fields.filter((field) => !conflictKey.includes(field));
|
|
197
|
+
const conflictAction = updatable.length > 0
|
|
198
|
+
? `DO UPDATE SET ${updatable.map((field) => `${field} = EXCLUDED.${field}`).join(', ')}`
|
|
199
|
+
: 'DO NOTHING';
|
|
200
|
+
for (let offset = 0; offset < rows.length; offset += INSERT_CHUNK_SIZE) {
|
|
201
|
+
const chunk = rows.slice(offset, offset + INSERT_CHUNK_SIZE);
|
|
202
|
+
const valuesSql = chunk
|
|
203
|
+
.map((_row, rowIndex) => `(${fields.map((_field, colIndex) => `$${rowIndex * fields.length + colIndex + 1}`).join(', ')})`)
|
|
204
|
+
.join(', ');
|
|
205
|
+
const params = chunk.flatMap((row) => rowValues(row, fields, jsonFields));
|
|
206
|
+
await tx.query(`INSERT INTO ${table} (${fields.join(', ')}) VALUES ${valuesSql} ` +
|
|
207
|
+
`ON CONFLICT (${conflictKey.join(', ')}) ${conflictAction}`, params);
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* Пакетный `INSERT` строк без `ON CONFLICT` (по частям, чтобы не упираться в
|
|
212
|
+
* лимит параметров). Вызывается после `DELETE … WHERE session_id` — полная
|
|
213
|
+
* замена child-строк в той же транзакции.
|
|
214
|
+
*/
|
|
215
|
+
async function insertRows(tx, table, fields, rows, jsonFields) {
|
|
216
|
+
if (rows.length === 0)
|
|
217
|
+
return;
|
|
218
|
+
for (let offset = 0; offset < rows.length; offset += INSERT_CHUNK_SIZE) {
|
|
219
|
+
const chunk = rows.slice(offset, offset + INSERT_CHUNK_SIZE);
|
|
220
|
+
const valuesSql = chunk
|
|
221
|
+
.map((_row, rowIndex) => `(${fields.map((_field, colIndex) => `$${rowIndex * fields.length + colIndex + 1}`).join(', ')})`)
|
|
222
|
+
.join(', ');
|
|
223
|
+
const params = chunk.flatMap((row) => rowValues(row, fields, jsonFields));
|
|
224
|
+
await tx.query(`INSERT INTO ${table} (${fields.join(', ')}) VALUES ${valuesSql}`, params);
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
/** Полная замена child-строк сессии: `DELETE` + массовый `INSERT`. */
|
|
228
|
+
async function replaceRows(tx, table, fields, rows, jsonFields, sessionId) {
|
|
229
|
+
await tx.query(`DELETE FROM ${table} WHERE session_id = $1`, [sessionId]);
|
|
230
|
+
await insertRows(tx, table, fields, rows, jsonFields);
|
|
231
|
+
}
|
|
232
|
+
/** `WHERE` для `list`/`search` (фильтры — по колонкам `sessions`). */
|
|
233
|
+
function buildListWhere(filter) {
|
|
234
|
+
const conditions = [];
|
|
235
|
+
const params = [];
|
|
236
|
+
if (filter?.projectId) {
|
|
237
|
+
params.push(filter.projectId);
|
|
238
|
+
conditions.push(`s.project_id = $${params.length}`);
|
|
239
|
+
}
|
|
240
|
+
if (filter?.userId) {
|
|
241
|
+
params.push(filter.userId);
|
|
242
|
+
conditions.push(`s.user_id = $${params.length}`);
|
|
243
|
+
}
|
|
244
|
+
if (filter?.parentId !== undefined) {
|
|
245
|
+
if (filter.parentId === null) {
|
|
246
|
+
conditions.push('s.parent_id IS NULL');
|
|
247
|
+
}
|
|
248
|
+
else {
|
|
249
|
+
params.push(filter.parentId);
|
|
250
|
+
conditions.push(`s.parent_id = $${params.length}`);
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
if (filter?.search) {
|
|
254
|
+
params.push(`%${escapeLike(filter.search)}%`);
|
|
255
|
+
const pattern = `$${params.length}`;
|
|
256
|
+
conditions.push(`(s.title ILIKE ${pattern} OR EXISTS (` +
|
|
257
|
+
`SELECT 1 FROM messages m WHERE m.session_id = s.id AND m.content ILIKE ${pattern}))`);
|
|
258
|
+
}
|
|
259
|
+
return { sql: conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '', params };
|
|
260
|
+
}
|
|
261
|
+
/** `SessionRepository` поверх PostgreSQL. */
|
|
262
|
+
export class PostgresSessionRepository {
|
|
263
|
+
_connection;
|
|
264
|
+
constructor(_connection) {
|
|
265
|
+
this._connection = _connection;
|
|
266
|
+
}
|
|
267
|
+
async load(sessionId) {
|
|
268
|
+
const rows = await this._connection.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
|
|
269
|
+
const row = rows[0];
|
|
270
|
+
if (!row)
|
|
271
|
+
return null;
|
|
272
|
+
const children = await this._loadChildren([sessionId]);
|
|
273
|
+
return deserializeSession(row, children.get(sessionId) ?? emptySessionChildren());
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Запись сессии: одна транзакция, per-session advisory-лок, **полная замена**
|
|
277
|
+
* истории и child-таблиц. `seq` сообщений нормализуется позиционно (`1..n`),
|
|
278
|
+
* дубликаты `id` сохраняются как есть.
|
|
279
|
+
*/
|
|
280
|
+
async save(session) {
|
|
281
|
+
const sessionRow = serializeSession(session);
|
|
282
|
+
// `seq` — позиция сообщения в массиве (`1..n`): снимает legacy-коллизию
|
|
283
|
+
// `UNIQUE (session_id, seq)` (у старых сессий `seq = 0` у всех) и делает
|
|
284
|
+
// порядок однозначным. Дубликаты `id` сообщений сохраняются (PK — суррогатный).
|
|
285
|
+
const messageRows = (session.messages ?? []).map((msg, index) => messageRow(msg, session.id, index + 1));
|
|
286
|
+
const referenceRows = (session.references ?? []).map((ref, index) => referenceRow(session.id, ref, index));
|
|
287
|
+
const checkpointRows = (session.checkpoints ?? []).map(checkpointRow);
|
|
288
|
+
const noteRows = (session.stickyNotes ?? []).map((note) => stickyNoteRow(session.id, note));
|
|
289
|
+
await this._connection.withTransaction(async (tx) => {
|
|
290
|
+
await this._lockSession(tx, session.id);
|
|
291
|
+
await upsertRows(tx, 'sessions', SESSION_FIELDS, [sessionRow], SESSION_JSON_FIELDS, ['id']);
|
|
292
|
+
// Сообщения — полная замена в той же транзакции: `DELETE` + массовый
|
|
293
|
+
// `INSERT`. Дубликаты `id` допустимы (суррогатный PK `message_uid`);
|
|
294
|
+
// уникальность `(session_id, seq)` выполняется по построению (позиция).
|
|
295
|
+
await replaceRows(tx, 'messages', MESSAGE_FIELDS, messageRows, MESSAGE_JSON_FIELDS, session.id);
|
|
296
|
+
// Ссылки — полная замена (паритет с файловой реализацией: `save`
|
|
297
|
+
// перезаписывает `session.references` целиком); `id`/`ordinal` — свежие,
|
|
298
|
+
// дубликаты одной `ref_session_id` допустимы (разные диапазоны).
|
|
299
|
+
await replaceRows(tx, 'session_references', REFERENCE_FIELDS, referenceRows, REFERENCE_JSON_FIELDS, session.id);
|
|
300
|
+
await replaceRows(tx, 'checkpoints', CHECKPOINT_FIELDS, checkpointRows, CHECKPOINT_JSON_FIELDS, session.id);
|
|
301
|
+
await replaceRows(tx, 'sticky_notes', NOTE_FIELDS, noteRows, NOTE_JSON_FIELDS, session.id);
|
|
302
|
+
});
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Точечная дозапись сообщения (`SessionRepository.appendMessage`): одна
|
|
306
|
+
* транзакция + per-session advisory-лок (как у `save`), `seq = MAX(seq)+1`
|
|
307
|
+
* вычисляется в той же транзакции, `INSERT` одной строки, обновление
|
|
308
|
+
* `sessions.updated_at`. Остальная история не перезаписывается.
|
|
309
|
+
*/
|
|
310
|
+
async appendMessage(sessionId, message) {
|
|
311
|
+
const prepared = prepareMessage(message);
|
|
312
|
+
return this._connection.withTransaction(async (tx) => {
|
|
313
|
+
await this._lockSession(tx, sessionId);
|
|
314
|
+
const present = await tx.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
|
|
315
|
+
if (present[0]?.present !== true)
|
|
316
|
+
return null;
|
|
317
|
+
const next = await tx.query('SELECT COALESCE(MAX(seq), 0) + 1 AS seq FROM messages WHERE session_id = $1', [sessionId]);
|
|
318
|
+
const seq = Number(next[0]?.seq ?? 1);
|
|
319
|
+
const row = messageRow(prepared, sessionId, seq);
|
|
320
|
+
const placeholders = MESSAGE_FIELDS.map((_, index) => `$${index + 1}`).join(', ');
|
|
321
|
+
const inserted = await tx.query(`INSERT INTO messages (${MESSAGE_FIELDS.join(', ')}) VALUES (${placeholders}) RETURNING *`, rowValues(row, MESSAGE_FIELDS, MESSAGE_JSON_FIELDS));
|
|
322
|
+
await tx.query('UPDATE sessions SET updated_at = now() WHERE id = $1', [sessionId]);
|
|
323
|
+
const insertedRow = inserted[0];
|
|
324
|
+
return insertedRow ? deserializeMessage(insertedRow) : null;
|
|
325
|
+
});
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Точечное обновление сообщения (`SessionRepository.updateMessage`): одна
|
|
329
|
+
* транзакция + per-session advisory-лок; цель — по `seq` (первая по
|
|
330
|
+
* `seq, created_at, id`), fallback по `id`. `message_uid`/`id`/`seq`/
|
|
331
|
+
* `created_at` исходной строки не меняются, `sessions.updated_at` обновляется.
|
|
332
|
+
*/
|
|
333
|
+
async updateMessage(sessionId, message) {
|
|
334
|
+
const prepared = prepareMessage(message);
|
|
335
|
+
const row = messageRow(prepared, sessionId, prepared.seq);
|
|
336
|
+
const setSql = MESSAGE_MUTABLE_FIELDS
|
|
337
|
+
.map((field, index) => `${field} = $${index + 1}`)
|
|
338
|
+
.join(', ');
|
|
339
|
+
const params = rowValues(row, MESSAGE_MUTABLE_FIELDS, MESSAGE_JSON_FIELDS);
|
|
340
|
+
return this._connection.withTransaction(async (tx) => {
|
|
341
|
+
await this._lockSession(tx, sessionId);
|
|
342
|
+
const messageUid = await this._findMessageUid(tx, sessionId, prepared);
|
|
343
|
+
if (!messageUid)
|
|
344
|
+
return null;
|
|
345
|
+
const updated = await tx.query(`UPDATE messages SET ${setSql} WHERE message_uid = $${params.length + 1} RETURNING *`, [...params, messageUid]);
|
|
346
|
+
await tx.query('UPDATE sessions SET updated_at = now() WHERE id = $1', [sessionId]);
|
|
347
|
+
const updatedRow = updated[0];
|
|
348
|
+
return updatedRow ? deserializeMessage(updatedRow) : null;
|
|
349
|
+
});
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* Метаданные сессии без истории (`SessionRepository.loadLight`): одна
|
|
353
|
+
* выборка по PK, child-таблицы не читаются.
|
|
354
|
+
*/
|
|
355
|
+
async loadLight(sessionId) {
|
|
356
|
+
const rows = await this._connection.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
|
|
357
|
+
const row = rows[0];
|
|
358
|
+
return row ? deserializeSessionLight(row) : null;
|
|
359
|
+
}
|
|
360
|
+
async delete(sessionId) {
|
|
361
|
+
await this._connection.withTransaction(async (tx) => {
|
|
362
|
+
await this._lockSession(tx, sessionId);
|
|
363
|
+
// Child-таблицы уходят каскадом (`ON DELETE CASCADE`).
|
|
364
|
+
await tx.query('DELETE FROM sessions WHERE id = $1', [sessionId]);
|
|
365
|
+
});
|
|
366
|
+
}
|
|
367
|
+
async exists(sessionId) {
|
|
368
|
+
const rows = await this._connection.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
|
|
369
|
+
return rows[0]?.present === true;
|
|
370
|
+
}
|
|
371
|
+
async list(filter) {
|
|
372
|
+
const { sql, params } = buildListWhere(filter);
|
|
373
|
+
return this._listByWhere(sql, params);
|
|
374
|
+
}
|
|
375
|
+
/**
|
|
376
|
+
* Лёгкий список (`SessionRepository.listLight`): тот же `WHERE`/порядок, что у
|
|
377
|
+
* `list`, но **без** батчевой подгрузки child-таблиц — сообщения/чекпоинты не
|
|
378
|
+
* читаются вовсе. SQL содержит только `FROM sessions` (для `filter.search`
|
|
379
|
+
* добавляется `EXISTS (SELECT 1 FROM messages …)` — подзапрос-предикат, не join).
|
|
380
|
+
*/
|
|
381
|
+
async listLight(filter) {
|
|
382
|
+
const { sql, params } = buildListWhere(filter);
|
|
383
|
+
const rows = await this._connection.query(`SELECT s.* FROM sessions s ${sql} ORDER BY s.updated_at DESC, s.id ASC`, params);
|
|
384
|
+
return rows.map(deserializeSessionLight);
|
|
385
|
+
}
|
|
386
|
+
/** Поиск по содержимому — тот же скан, что у `list` (паритет с файловой реализацией). */
|
|
387
|
+
async search(query, filter) {
|
|
388
|
+
return this.list({ ...filter, search: query });
|
|
389
|
+
}
|
|
390
|
+
async listForUser(userId, ownerIds = []) {
|
|
391
|
+
// `ownerIds` — дополнительные id владельца (legacy-UUID профиля `local`, ADR-089).
|
|
392
|
+
const ids = [userId, ...ownerIds];
|
|
393
|
+
return this._listByWhere('WHERE (s.user_id = ANY($1::text[]) OR s.owner_id = ANY($1::text[]))', [ids]);
|
|
394
|
+
}
|
|
395
|
+
/** «Свои + сессии проектов участия» (ADR-089); пустой `projectIds` → `listForUser`. */
|
|
396
|
+
async listForUserScope(userId, projectIds, ownerIds = []) {
|
|
397
|
+
if (projectIds.length === 0)
|
|
398
|
+
return this.listForUser(userId, ownerIds);
|
|
399
|
+
const ids = [userId, ...ownerIds];
|
|
400
|
+
return this._listByWhere('WHERE ((s.user_id = ANY($1::text[]) OR s.owner_id = ANY($1::text[])) '
|
|
401
|
+
+ 'OR s.project_id = ANY($2::text[]))', [ids, projectIds]);
|
|
402
|
+
}
|
|
403
|
+
async addReference(sessionId, ref) {
|
|
404
|
+
await this._connection.withTransaction(async (tx) => {
|
|
405
|
+
await this._lockSession(tx, sessionId);
|
|
406
|
+
await this._assertSessionExists(tx, sessionId);
|
|
407
|
+
// Append (дубликаты разрешены): новая ссылка получает следующий `ordinal`.
|
|
408
|
+
const next = await tx.query('SELECT COALESCE(MAX(ordinal), -1) + 1 AS ordinal FROM session_references WHERE session_id = $1', [sessionId]);
|
|
409
|
+
const ordinal = Number(next[0]?.ordinal ?? 0);
|
|
410
|
+
await tx.query(`INSERT INTO session_references
|
|
411
|
+
(${REFERENCE_FIELDS.join(', ')})
|
|
412
|
+
VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`, rowValues(referenceRow(sessionId, ref, ordinal), REFERENCE_FIELDS, REFERENCE_JSON_FIELDS));
|
|
413
|
+
});
|
|
414
|
+
}
|
|
415
|
+
async removeReference(sessionId, refSessionId) {
|
|
416
|
+
await this._connection.withTransaction(async (tx) => {
|
|
417
|
+
await this._lockSession(tx, sessionId);
|
|
418
|
+
await this._assertSessionExists(tx, sessionId);
|
|
419
|
+
// Удаляются **все** совпадения (паритет с file/memory: `filter` по refSessionId).
|
|
420
|
+
await tx.query('DELETE FROM session_references WHERE session_id = $1 AND ref_session_id = $2', [sessionId, refSessionId]);
|
|
421
|
+
});
|
|
422
|
+
}
|
|
423
|
+
async getReferences(sessionId) {
|
|
424
|
+
if (!(await this.exists(sessionId)))
|
|
425
|
+
return [];
|
|
426
|
+
const rows = await this._connection.query('SELECT * FROM session_references WHERE session_id = $1 ORDER BY ordinal', [sessionId]);
|
|
427
|
+
return rows.map(deserializeReference);
|
|
428
|
+
}
|
|
429
|
+
/** Список по готовому `WHERE` + батчевая подгрузка child-данных. */
|
|
430
|
+
async _listByWhere(whereSql, params) {
|
|
431
|
+
const rows = await this._connection.query(`SELECT s.* FROM sessions s ${whereSql} ORDER BY s.updated_at DESC, s.id ASC`, params);
|
|
432
|
+
if (rows.length === 0)
|
|
433
|
+
return [];
|
|
434
|
+
const children = await this._loadChildren(rows.map((row) => row.id));
|
|
435
|
+
return rows.map((row) => deserializeSession(row, children.get(row.id) ?? emptySessionChildren()));
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Child-данные набора сессий — четыре запроса с `ANY($1)` (никакого N+1),
|
|
439
|
+
* `ORDER BY session_id, …` для стабильного порядка внутри каждой сессии.
|
|
440
|
+
*/
|
|
441
|
+
async _loadChildren(sessionIds) {
|
|
442
|
+
const buckets = new Map();
|
|
443
|
+
for (const sessionId of sessionIds)
|
|
444
|
+
buckets.set(sessionId, emptySessionChildren());
|
|
445
|
+
if (sessionIds.length === 0)
|
|
446
|
+
return buckets;
|
|
447
|
+
const [messages, references, checkpoints, notes] = await Promise.all([
|
|
448
|
+
this._connection.query('SELECT * FROM messages WHERE session_id = ANY($1::text[]) '
|
|
449
|
+
+ 'ORDER BY session_id, seq, created_at, id', [sessionIds]),
|
|
450
|
+
this._connection.query('SELECT * FROM session_references WHERE session_id = ANY($1::text[]) '
|
|
451
|
+
+ 'ORDER BY session_id, ordinal', [sessionIds]),
|
|
452
|
+
this._connection.query('SELECT * FROM checkpoints WHERE session_id = ANY($1::text[]) '
|
|
453
|
+
+ 'ORDER BY session_id, created_at, id', [sessionIds]),
|
|
454
|
+
this._connection.query('SELECT * FROM sticky_notes WHERE session_id = ANY($1::text[]) '
|
|
455
|
+
+ 'ORDER BY session_id, created_at, id', [sessionIds]),
|
|
456
|
+
]);
|
|
457
|
+
for (const row of messages)
|
|
458
|
+
buckets.get(row.session_id ?? '')?.messages.push(row);
|
|
459
|
+
for (const row of references)
|
|
460
|
+
buckets.get(row.session_id)?.references.push(row);
|
|
461
|
+
for (const row of checkpoints)
|
|
462
|
+
buckets.get(row.session_id)?.checkpoints.push(row);
|
|
463
|
+
for (const row of notes)
|
|
464
|
+
buckets.get(row.session_id)?.stickyNotes.push(row);
|
|
465
|
+
return buckets;
|
|
466
|
+
}
|
|
467
|
+
/**
|
|
468
|
+
* `message_uid` цели `updateMessage`: сначала по `seq` (при legacy-дублях —
|
|
469
|
+
* первая по `seq, created_at, id`), затем fallback по доменному `id`.
|
|
470
|
+
*/
|
|
471
|
+
async _findMessageUid(tx, sessionId, message) {
|
|
472
|
+
if (Number.isFinite(message.seq)) {
|
|
473
|
+
const rows = await tx.query('SELECT message_uid FROM messages WHERE session_id = $1 AND seq = $2 '
|
|
474
|
+
+ 'ORDER BY seq, created_at, id LIMIT 1', [sessionId, message.seq]);
|
|
475
|
+
if (rows[0])
|
|
476
|
+
return rows[0].message_uid;
|
|
477
|
+
}
|
|
478
|
+
if (message.id) {
|
|
479
|
+
const rows = await tx.query('SELECT message_uid FROM messages WHERE session_id = $1 AND id = $2 '
|
|
480
|
+
+ 'ORDER BY seq, created_at, id LIMIT 1', [sessionId, message.id]);
|
|
481
|
+
if (rows[0])
|
|
482
|
+
return rows[0].message_uid;
|
|
483
|
+
}
|
|
484
|
+
return null;
|
|
485
|
+
}
|
|
486
|
+
/** PROP-032: per-session сериализация записи — транзакционный advisory-лок. */
|
|
487
|
+
async _lockSession(tx, sessionId) {
|
|
488
|
+
await tx.query('SELECT pg_advisory_xact_lock(hashtext($1::text)::bigint)', [sessionId]);
|
|
489
|
+
}
|
|
490
|
+
/** `addReference`/`removeReference` отсутствующей сессии → ошибка (как в file/memory). */
|
|
491
|
+
async _assertSessionExists(tx, sessionId) {
|
|
492
|
+
const rows = await tx.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
|
|
493
|
+
if (rows[0]?.present !== true)
|
|
494
|
+
throw new Error(`Session ${sessionId} not found`);
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
/** Собрать порты группы `sessions`. */
|
|
498
|
+
export function buildSessionPorts(deps) {
|
|
499
|
+
return {
|
|
500
|
+
sessions: new PostgresSessionRepository(deps.connection),
|
|
501
|
+
};
|
|
502
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Общая заглушка портов PostgreSQL-драйвера (PROP-032, волна 3b).
|
|
3
|
+
*
|
|
4
|
+
* Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
|
|
5
|
+
* (прокси, любой доступ к методу которого бросает
|
|
6
|
+
* `PostgresStorageNotImplementedError` с именем порта). Это даёт:
|
|
7
|
+
* - контрактную поверхность `StorageContext` целиком (прокси отдаёт любой метод);
|
|
8
|
+
* - понятную ошибку вместо `undefined is not a function`;
|
|
9
|
+
* - один общий элемент для всех четырёх групп портов (`sessions`/`principals`/
|
|
10
|
+
* `events`/`content`), который волна реализации заменяет по мере готовности.
|
|
11
|
+
*
|
|
12
|
+
* Методы кэшируются (стабильные ссылки на функцию), символьные ключи не трогаем.
|
|
13
|
+
*/
|
|
14
|
+
export declare function notImplementedPort<T>(port: string): T;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Общая заглушка портов PostgreSQL-драйвера (PROP-032, волна 3b).
|
|
3
|
+
*
|
|
4
|
+
* Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
|
|
5
|
+
* (прокси, любой доступ к методу которого бросает
|
|
6
|
+
* `PostgresStorageNotImplementedError` с именем порта). Это даёт:
|
|
7
|
+
* - контрактную поверхность `StorageContext` целиком (прокси отдаёт любой метод);
|
|
8
|
+
* - понятную ошибку вместо `undefined is not a function`;
|
|
9
|
+
* - один общий элемент для всех четырёх групп портов (`sessions`/`principals`/
|
|
10
|
+
* `events`/`content`), который волна реализации заменяет по мере готовности.
|
|
11
|
+
*
|
|
12
|
+
* Методы кэшируются (стабильные ссылки на функцию), символьные ключи не трогаем.
|
|
13
|
+
*/
|
|
14
|
+
import { PostgresStorageNotImplementedError } from '../errors.js';
|
|
15
|
+
export function notImplementedPort(port) {
|
|
16
|
+
const methods = new Map();
|
|
17
|
+
const proxy = new Proxy({}, {
|
|
18
|
+
get(_target, prop) {
|
|
19
|
+
if (typeof prop === 'symbol')
|
|
20
|
+
return undefined;
|
|
21
|
+
let method = methods.get(prop);
|
|
22
|
+
if (!method) {
|
|
23
|
+
method = () => {
|
|
24
|
+
throw new PostgresStorageNotImplementedError(`Порт '${port}' ещё не реализован в PostgreSQL-драйвере (PROP-032, волна реализации портов).`);
|
|
25
|
+
};
|
|
26
|
+
methods.set(prop, method);
|
|
27
|
+
}
|
|
28
|
+
return method;
|
|
29
|
+
},
|
|
30
|
+
});
|
|
31
|
+
return proxy;
|
|
32
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Драйвер слоя хранения Synth на PostgreSQL — публичная фабрика (ADR-096/ADR-097,
|
|
3
|
+
* PROP-032).
|
|
4
|
+
*
|
|
5
|
+
* Пакет `@itphx/synth-storage-postgres` — in-tree **опциональный** драйвер: он
|
|
6
|
+
* реализует доменные порты `StorageContext` и подключается из
|
|
7
|
+
* `createStorageContext` динамическим `import()` при `storage.backend === 'postgres'`.
|
|
8
|
+
*
|
|
9
|
+
* Волна 3a — **инфраструктура**: пул/подключение, схема БД и миграции
|
|
10
|
+
* (`migrate.ts` + `migrations/*`), сборка контекста (`storage-context.ts`).
|
|
11
|
+
* Доменные порты реализуются следующей волной, поэтому `createPostgresStorage`
|
|
12
|
+
* применяет (или проверяет) схему и возвращает контекст с файловыми FS-портами
|
|
13
|
+
* и заглушками PG-портов.
|
|
14
|
+
*
|
|
15
|
+
* `pg` — `optionalDependencies` пакета и подключается **лениво** (`pool.ts`):
|
|
16
|
+
* импорт модуля драйвера не требует установленного `pg`.
|
|
17
|
+
*/
|
|
18
|
+
import type { StorageContext, StorageContextConfig } from '@itphx/synth-core';
|
|
19
|
+
import { type PostgresConnectionConfig } from './pool.js';
|
|
20
|
+
import type { CoreSyncDeps } from './ports/deps.js';
|
|
21
|
+
export * from './errors.js';
|
|
22
|
+
export type { PostgresPoolConfig, PostgresConnectionConfig } from './pool.js';
|
|
23
|
+
export type { PostgresExecutor } from './pool.js';
|
|
24
|
+
/** Конфиг драйвера: параметры подключения к БД + общие параметры слоя хранения. */
|
|
25
|
+
export interface PostgresStorageConfig extends StorageContextConfig, PostgresConnectionConfig {
|
|
26
|
+
/** Схема БД (по умолчанию — `public`). */
|
|
27
|
+
schema?: string;
|
|
28
|
+
/** Применять миграции схемы при сборке контекста (по умолчанию — `true`). */
|
|
29
|
+
migrate?: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* PROP-032: режим работы со схемой при сборке (`apply`/`assert`/`skip`);
|
|
32
|
+
* приоритетнее `migrate`. `skip` — только подключение (диагностика/CLI,
|
|
33
|
+
* управляющие миграциями сами). Не задан — выводится из `migrate`
|
|
34
|
+
* (`false` → `assert`, иначе `apply`).
|
|
35
|
+
*/
|
|
36
|
+
schemaMode?: 'apply' | 'assert' | 'skip';
|
|
37
|
+
/**
|
|
38
|
+
* ADR-097/PROP-032: синхронные данные/хелперы core (`secretPatterns`/
|
|
39
|
+
* `protectedPaths`/`dictionaries`), инъектируемые core'ом
|
|
40
|
+
* (`packages/core/src/storage/storage-context.ts`). Не заданы (прямой вызов
|
|
41
|
+
* фабрики) — драйвер собирает их ленивым `import('@itphx/synth-core')`.
|
|
42
|
+
*/
|
|
43
|
+
coreSync?: CoreSyncDeps;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Валидация конфига **до** любого обращения к БД: нужен либо
|
|
47
|
+
* `connectionString`, либо пара `pool.host` + `pool.database`; схема — безопасный
|
|
48
|
+
* идентификатор.
|
|
49
|
+
*/
|
|
50
|
+
export declare function validatePostgresConfig(config: PostgresStorageConfig): void;
|
|
51
|
+
/**
|
|
52
|
+
* Собрать `StorageContext` на PostgreSQL (форма — ADR-097/PROP-032).
|
|
53
|
+
*
|
|
54
|
+
* Валидирует конфиг, лениво подключается к БД, применяет миграции (или, при
|
|
55
|
+
* `migrate:false`, проверяет актуальность схемы — fail-closed) и возвращает
|
|
56
|
+
* контекст: FS/package-bound порты (`skills`/`contextFiles`/`blobs`) — файловые,
|
|
57
|
+
* остальные — заглушки PG (порты реализуются следующей волной).
|
|
58
|
+
*/
|
|
59
|
+
export declare function createPostgresStorage(config: PostgresStorageConfig): Promise<StorageContext>;
|