@fadhilp/stateql 0.17.0 → 0.18.0
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/dist/src/adapters.d.ts +17 -25
- package/dist/src/adapters.js +15 -95
- package/dist/src/catalog.d.ts +6 -0
- package/dist/src/catalog.js +52 -0
- package/dist/src/connect.d.ts +16 -0
- package/dist/src/connect.js +205 -0
- package/dist/src/core.d.ts +78 -0
- package/dist/src/core.js +477 -0
- package/dist/src/execution.d.ts +27 -0
- package/dist/src/execution.js +87 -0
- package/dist/src/filter.js +3 -1
- package/dist/src/index.d.ts +1 -1
- package/dist/src/migrations.d.ts +1 -1
- package/dist/src/mongodb.d.ts +4 -2
- package/dist/src/mongodb.js +5 -56
- package/dist/src/panel.d.ts +64 -0
- package/dist/src/panel.js +316 -0
- package/dist/src/plans.d.ts +31 -0
- package/dist/src/plans.js +275 -0
- package/dist/src/reads.d.ts +35 -0
- package/dist/src/reads.js +184 -0
- package/dist/src/redis.d.ts +4 -2
- package/dist/src/redis.js +7 -33
- package/dist/src/response-data.d.ts +1 -0
- package/dist/src/response-data.js +13 -10
- package/dist/src/results.d.ts +10 -0
- package/dist/src/results.js +153 -0
- package/dist/src/sqlite-process.js +16 -9
- package/dist/src/stateql.d.ts +7 -58
- package/dist/src/stateql.js +150 -2663
- package/dist/src/table-editor.js +2 -2
- package/dist/src/transactions.d.ts +8 -0
- package/dist/src/transactions.js +186 -0
- package/dist/src/types.d.ts +3 -17
- package/dist/src/writes.d.ts +48 -0
- package/dist/src/writes.js +320 -0
- package/docs/databases.md +2 -1
- package/docs/results.md +5 -0
- package/package.json +5 -3
package/dist/src/core.js
ADDED
|
@@ -0,0 +1,477 @@
|
|
|
1
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
|
+
import { env } from "node:process";
|
|
3
|
+
import { openAdapter } from "./adapters.js";
|
|
4
|
+
import { credentialSource, injectPassword, validateCredentialRef, validatePasswordReferenceTarget, } from "./connection.js";
|
|
5
|
+
import { asStateQLError, CredentialResolutionError, isTransientDatabaseError, StateQLError, } from "./errors.js";
|
|
6
|
+
import { AdapterExecutionError, createAdapterContext, stoppedStateQLError, } from "./execution.js";
|
|
7
|
+
import { compactRows, redact } from "./util.js";
|
|
8
|
+
const NATIVE_METHODS = {
|
|
9
|
+
mongodb: { query: "mongoQuery", exec: "mongoExec", plan: "mongoPlan" },
|
|
10
|
+
redis: { query: "redisQuery", exec: "redisExec", plan: "redisPlan" },
|
|
11
|
+
};
|
|
12
|
+
/** State and checks shared by every command; one instance per StateQL. */
|
|
13
|
+
export class Core {
|
|
14
|
+
store;
|
|
15
|
+
settings;
|
|
16
|
+
sessionName;
|
|
17
|
+
actorId;
|
|
18
|
+
now;
|
|
19
|
+
signal;
|
|
20
|
+
credentialResolver;
|
|
21
|
+
commandContexts = new AsyncLocalStorage();
|
|
22
|
+
constructor(store, settings, sessionName, actorId, now, signal, credentialResolver) {
|
|
23
|
+
this.store = store;
|
|
24
|
+
this.settings = settings;
|
|
25
|
+
this.sessionName = sessionName;
|
|
26
|
+
this.actorId = actorId;
|
|
27
|
+
this.now = now;
|
|
28
|
+
this.signal = signal;
|
|
29
|
+
this.credentialResolver = credentialResolver;
|
|
30
|
+
}
|
|
31
|
+
withCommandContext(supplied, action) {
|
|
32
|
+
return this.commandContexts.run(mergeCommandExecutionContext(this.commandContexts.getStore(), supplied), action);
|
|
33
|
+
}
|
|
34
|
+
executionContext(options) {
|
|
35
|
+
return createAdapterContext(executionTimeout(options.timeoutMs ?? this.settings.timeoutMs), combineAbortSignals(options.signal, this.commandContexts.getStore()?.signal, this.signal));
|
|
36
|
+
}
|
|
37
|
+
expiresAt(milliseconds) {
|
|
38
|
+
return new Date(this.now().getTime() + milliseconds).toISOString();
|
|
39
|
+
}
|
|
40
|
+
async openAdapter(connection, context, source) {
|
|
41
|
+
try {
|
|
42
|
+
return await openAdapter(connection, context, source);
|
|
43
|
+
}
|
|
44
|
+
catch (error) {
|
|
45
|
+
if (error instanceof StateQLError)
|
|
46
|
+
throw error;
|
|
47
|
+
throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/** Resolves read credentials, then runs the action on a fresh adapter. */
|
|
51
|
+
async withAdapter(session, connection, operation, context, action) {
|
|
52
|
+
const source = await this.resolveConnectionSource(connection, session, operation, "read", context);
|
|
53
|
+
return this.runOnAdapter(connection, context, source, action);
|
|
54
|
+
}
|
|
55
|
+
/** Opens the adapter, maps driver errors to StateQL errors, and always closes it. */
|
|
56
|
+
async runOnAdapter(connection, context, source, action) {
|
|
57
|
+
const adapter = await this.openAdapter(connection, context, source);
|
|
58
|
+
try {
|
|
59
|
+
return await action(adapter);
|
|
60
|
+
}
|
|
61
|
+
catch (error) {
|
|
62
|
+
if (error instanceof StateQLError)
|
|
63
|
+
throw error;
|
|
64
|
+
if (error instanceof AdapterExecutionError)
|
|
65
|
+
throw stoppedStateQLError(error, true);
|
|
66
|
+
throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: isTransientDatabaseError(error), executed: true });
|
|
67
|
+
}
|
|
68
|
+
finally {
|
|
69
|
+
await closeAdapterQuietly(adapter);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
async run(command, action, historySql, historyTarget) {
|
|
73
|
+
const started = performance.now();
|
|
74
|
+
const duration = () => Math.round((performance.now() - started) * 1000) / 1000;
|
|
75
|
+
const commandContext = this.commandContexts.getStore();
|
|
76
|
+
const entry = {
|
|
77
|
+
actorId: this.actorId,
|
|
78
|
+
origin: commandContext?.origin ?? "legacy",
|
|
79
|
+
category: historyCategory(command),
|
|
80
|
+
internal: commandContext?.internal ?? false,
|
|
81
|
+
command,
|
|
82
|
+
target: historyTarget,
|
|
83
|
+
};
|
|
84
|
+
const session = this.store.ensureSession(this.sessionName);
|
|
85
|
+
if (!this.store.isSessionMember(session.id, this.actorId)) {
|
|
86
|
+
const error = new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
|
|
87
|
+
return {
|
|
88
|
+
ok: false,
|
|
89
|
+
command_id: this.store.randomId("cmd"),
|
|
90
|
+
session_id: session.id,
|
|
91
|
+
error: error.details,
|
|
92
|
+
meta: { duration_ms: duration() },
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
const actorName = this.store.getActor(session.id, this.actorId).actor_name;
|
|
96
|
+
try {
|
|
97
|
+
const result = await action(session);
|
|
98
|
+
const sqlText = typeof historySql === "function" ? historySql() : historySql;
|
|
99
|
+
const history = this.store.addHistory({
|
|
100
|
+
...entry,
|
|
101
|
+
sessionId: session.id,
|
|
102
|
+
actorName,
|
|
103
|
+
...(result.handle ? { handle: result.handle } : {}),
|
|
104
|
+
...(sqlText !== undefined ? { sql: sqlText } : {}),
|
|
105
|
+
executed: result.executed ?? false,
|
|
106
|
+
cached: result.cached ?? false,
|
|
107
|
+
success: true,
|
|
108
|
+
});
|
|
109
|
+
return {
|
|
110
|
+
ok: true,
|
|
111
|
+
command_id: history.id,
|
|
112
|
+
session_id: (result.session ?? session).id,
|
|
113
|
+
data: result.data,
|
|
114
|
+
warnings: result.warnings ?? [],
|
|
115
|
+
meta: {
|
|
116
|
+
duration_ms: duration(),
|
|
117
|
+
...(result.stateVersion ? { state_version: result.stateVersion } : {}),
|
|
118
|
+
...(result.confidence ? { state_confidence: result.confidence } : {}),
|
|
119
|
+
},
|
|
120
|
+
};
|
|
121
|
+
}
|
|
122
|
+
catch (error) {
|
|
123
|
+
const stateqlError = asStateQLError(error);
|
|
124
|
+
const sqlText = typeof historySql === "function" ? historySql() : historySql;
|
|
125
|
+
const history = this.store.addHistory({
|
|
126
|
+
...entry,
|
|
127
|
+
sessionId: session.id,
|
|
128
|
+
actorName,
|
|
129
|
+
...(sqlText !== undefined ? { sql: sqlText } : {}),
|
|
130
|
+
executed: stateqlError.details.executed,
|
|
131
|
+
cached: false,
|
|
132
|
+
success: false,
|
|
133
|
+
errorCode: stateqlError.details.code,
|
|
134
|
+
});
|
|
135
|
+
return {
|
|
136
|
+
ok: false,
|
|
137
|
+
command_id: history.id,
|
|
138
|
+
session_id: session.id,
|
|
139
|
+
error: stateqlError.details,
|
|
140
|
+
meta: { duration_ms: duration() },
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
/** Runs a command on a stored result that has not expired. */
|
|
145
|
+
withResult(command, idOrAlias, action) {
|
|
146
|
+
return this.run(command, async (session) => {
|
|
147
|
+
const result = this.requireResult(idOrAlias, session);
|
|
148
|
+
if (Date.parse(result.expires_at) <= this.now().getTime()) {
|
|
149
|
+
throw new StateQLError("RESULT_EXPIRED", `Result "${result.id}" has expired.`, { retryable: true, suggestedAction: "Run the original query again." });
|
|
150
|
+
}
|
|
151
|
+
return action(result, session);
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
async resolveConnectionSource(connection, session, operation, access, context) {
|
|
155
|
+
const references = [connection.secret_env, connection.credential_ref, connection.password_ref]
|
|
156
|
+
.filter((value) => value !== null);
|
|
157
|
+
if (references.length > 1) {
|
|
158
|
+
throw new StateQLError("STATE_CORRUPTED", "Connection has ambiguous credential references.");
|
|
159
|
+
}
|
|
160
|
+
const details = {
|
|
161
|
+
connection: {
|
|
162
|
+
id: connection.id,
|
|
163
|
+
name: connection.name,
|
|
164
|
+
driver: connection.driver,
|
|
165
|
+
database: connection.database_name,
|
|
166
|
+
readOnly: Boolean(connection.read_only),
|
|
167
|
+
},
|
|
168
|
+
};
|
|
169
|
+
if (connection.password_ref !== null) {
|
|
170
|
+
validateCredentialRef(connection.password_ref);
|
|
171
|
+
const driver = validatePasswordReferenceTarget(connection.source);
|
|
172
|
+
if (driver !== connection.driver) {
|
|
173
|
+
throw new StateQLError("STATE_CORRUPTED", "Password-reference target driver does not match the stored connection.");
|
|
174
|
+
}
|
|
175
|
+
const password = await this.resolveCredential(connection.password_ref, "password_ref", session, operation, access, context, details, connection.source);
|
|
176
|
+
return injectPassword(connection.source, password).source;
|
|
177
|
+
}
|
|
178
|
+
const reference = connection.secret_env ?? connection.credential_ref;
|
|
179
|
+
if (!reference)
|
|
180
|
+
return connection.source;
|
|
181
|
+
const source = connection.secret_env
|
|
182
|
+
? "secret_env"
|
|
183
|
+
: "credential_ref";
|
|
184
|
+
const value = await this.resolveCredential(reference, source, session, operation, access, context, details);
|
|
185
|
+
return credentialSource(value, connection.driver, source).source;
|
|
186
|
+
}
|
|
187
|
+
async resolveCredential(reference, source, session, operation, access, context, details = {}, passwordTarget) {
|
|
188
|
+
const resolver = this.credentialResolver;
|
|
189
|
+
const credentialContext = createAdapterContext(this.settings.credentialTimeoutMs, context.signal);
|
|
190
|
+
let value;
|
|
191
|
+
if (!resolver) {
|
|
192
|
+
if (credentialContext.signal?.aborted) {
|
|
193
|
+
throw credentialStateQLError(reference, new CredentialResolutionError("cancelled"));
|
|
194
|
+
}
|
|
195
|
+
if (credentialContext.deadline <= Date.now()) {
|
|
196
|
+
throw credentialStateQLError(reference, new CredentialResolutionError("timeout"));
|
|
197
|
+
}
|
|
198
|
+
if (source === "secret_env")
|
|
199
|
+
value = env[reference];
|
|
200
|
+
}
|
|
201
|
+
else {
|
|
202
|
+
const baseRequest = {
|
|
203
|
+
reference,
|
|
204
|
+
actorId: this.actorId,
|
|
205
|
+
session: { id: session.id, name: session.name },
|
|
206
|
+
operation,
|
|
207
|
+
access,
|
|
208
|
+
...(context.signal ? { signal: context.signal } : {}),
|
|
209
|
+
...details,
|
|
210
|
+
};
|
|
211
|
+
const request = source === "password_ref"
|
|
212
|
+
? { ...baseRequest, source, target: passwordTarget }
|
|
213
|
+
: { ...baseRequest, source };
|
|
214
|
+
try {
|
|
215
|
+
value = await resolveCredentialBeforeDeadline(resolver, request, credentialContext);
|
|
216
|
+
}
|
|
217
|
+
catch (error) {
|
|
218
|
+
throw credentialStateQLError(reference, error);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
const missing = value === undefined || (source !== "password_ref" && value === "");
|
|
222
|
+
if (missing) {
|
|
223
|
+
throw credentialStateQLError(reference, new CredentialResolutionError("unavailable"));
|
|
224
|
+
}
|
|
225
|
+
// The database deadline starts after credential resolution, which may wait for a person.
|
|
226
|
+
context.deadline = Date.now() + (context.timeoutMs ?? this.settings.timeoutMs);
|
|
227
|
+
return value;
|
|
228
|
+
}
|
|
229
|
+
requireConnection(session) {
|
|
230
|
+
const connection = this.store.activeConnection(session);
|
|
231
|
+
if (!connection) {
|
|
232
|
+
throw new StateQLError("CONNECTION_NOT_FOUND", "No active connection.", { suggestedAction: "Run stql connect first." });
|
|
233
|
+
}
|
|
234
|
+
return connection;
|
|
235
|
+
}
|
|
236
|
+
requireSqlConnection(session, command) {
|
|
237
|
+
const connection = this.requireConnection(session);
|
|
238
|
+
rejectSqlOnNativeConnection(connection, command);
|
|
239
|
+
return connection;
|
|
240
|
+
}
|
|
241
|
+
requireNativeConnection(session, driver, command) {
|
|
242
|
+
const connection = this.requireConnection(session);
|
|
243
|
+
if (connection.driver !== driver) {
|
|
244
|
+
throw new StateQLError("INVALID_COMMAND", `${NATIVE_METHODS[driver][command]} requires an active ${driverDisplayName(driver)} connection.`);
|
|
245
|
+
}
|
|
246
|
+
return connection;
|
|
247
|
+
}
|
|
248
|
+
requireWritable(connection) {
|
|
249
|
+
if (!connection.read_only)
|
|
250
|
+
return;
|
|
251
|
+
throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.", { suggestedAction: "Reconnect with --read-write." });
|
|
252
|
+
}
|
|
253
|
+
requireResult(idOrAlias, session) {
|
|
254
|
+
const result = this.store.getResult(idOrAlias, session.id);
|
|
255
|
+
if (!result) {
|
|
256
|
+
throw new StateQLError("RESULT_NOT_FOUND", `Result "${idOrAlias}" was not found.`);
|
|
257
|
+
}
|
|
258
|
+
return result;
|
|
259
|
+
}
|
|
260
|
+
requireActiveTransaction(session, id) {
|
|
261
|
+
const transactionId = id ?? session.active_transaction_id;
|
|
262
|
+
if (!transactionId) {
|
|
263
|
+
throw new StateQLError("TRANSACTION_NOT_FOUND", "No active transaction.");
|
|
264
|
+
}
|
|
265
|
+
const transaction = this.store.getTransaction(transactionId);
|
|
266
|
+
const active = transaction !== undefined &&
|
|
267
|
+
transaction.session_id === session.id &&
|
|
268
|
+
transaction.state === "active" &&
|
|
269
|
+
session.active_transaction_id === transaction.id;
|
|
270
|
+
if (!active) {
|
|
271
|
+
throw new StateQLError("TRANSACTION_NOT_FOUND", `Active transaction "${transactionId}" was not found.`);
|
|
272
|
+
}
|
|
273
|
+
if (transaction.owner_actor_id !== this.actorId) {
|
|
274
|
+
throw new StateQLError("PERMISSION_DENIED", "Only the transaction owner may control it.");
|
|
275
|
+
}
|
|
276
|
+
return transaction;
|
|
277
|
+
}
|
|
278
|
+
rejectDuringStagedTransaction(session, operation) {
|
|
279
|
+
if (!session.active_transaction_id)
|
|
280
|
+
return;
|
|
281
|
+
throw new StateQLError("TRANSACTION_FAILED", `${operation} cannot run while a staged transaction is active.`, { suggestedAction: "Commit or roll back the transaction first." });
|
|
282
|
+
}
|
|
283
|
+
throwMembershipDenied(session) {
|
|
284
|
+
throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
|
|
285
|
+
}
|
|
286
|
+
resultData(result, cached, previewRows = this.settings.previewRows) {
|
|
287
|
+
const rows = this.store.resultRows(result);
|
|
288
|
+
const preview = compactRows(rows.slice(0, previewRows), this.settings.maxCellCharacters);
|
|
289
|
+
const alias = result.alias ?? this.store.generatedAlias(result.id);
|
|
290
|
+
return {
|
|
291
|
+
result_id: result.id,
|
|
292
|
+
alias,
|
|
293
|
+
display_alias: alias,
|
|
294
|
+
rows: result.row_count,
|
|
295
|
+
columns: this.store.resultColumns(result),
|
|
296
|
+
preview,
|
|
297
|
+
preview_count: preview.length,
|
|
298
|
+
truncated: preview.length < result.row_count,
|
|
299
|
+
cached,
|
|
300
|
+
...(cached ? { duplicate_of: result.id } : {}),
|
|
301
|
+
...(result.sql.startsWith("Redis native ") ? { next_cursor: redisResultCursor(result.parameters) } : {}),
|
|
302
|
+
state_version: result.state_version,
|
|
303
|
+
storage: {
|
|
304
|
+
mode: "materialized",
|
|
305
|
+
expires_at: result.expires_at,
|
|
306
|
+
},
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
cacheValid(result, stateVersion, stateSignature) {
|
|
310
|
+
const now = this.now().getTime();
|
|
311
|
+
return Date.parse(result.expires_at) > now &&
|
|
312
|
+
Date.parse(result.created_at) + this.settings.cacheTtlSeconds * 1000 > now &&
|
|
313
|
+
result.state_version === stateVersion &&
|
|
314
|
+
result.state_signature === stateSignature;
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
export function adapterOfKind(adapter, kind) {
|
|
318
|
+
if (adapter.kind !== kind) {
|
|
319
|
+
throw new StateQLError("STATE_CORRUPTED", "Adapter does not match the statement driver.");
|
|
320
|
+
}
|
|
321
|
+
return adapter;
|
|
322
|
+
}
|
|
323
|
+
export function rejectSqlOnNativeConnection(connection, command) {
|
|
324
|
+
if (connection.driver !== "mongodb" && connection.driver !== "redis")
|
|
325
|
+
return;
|
|
326
|
+
const method = NATIVE_METHODS[connection.driver][command];
|
|
327
|
+
const name = driverDisplayName(connection.driver);
|
|
328
|
+
throw new StateQLError("INVALID_COMMAND", `SQL is not supported for ${name} connections; use ${method} instead.`, { suggestedAction: `Use ${method} with a native ${name} command.` });
|
|
329
|
+
}
|
|
330
|
+
export function driverDisplayName(driver) {
|
|
331
|
+
switch (driver) {
|
|
332
|
+
case "mongodb": return "MongoDB";
|
|
333
|
+
case "redis": return "Redis";
|
|
334
|
+
case "postgres": return "PostgreSQL";
|
|
335
|
+
case "mysql": return "MySQL";
|
|
336
|
+
case "sqlite": return "SQLite";
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
const COMMAND_ORIGINS = new Set(["legacy", "user", "model", "system", "api"]);
|
|
340
|
+
export function parseCommandOrigin(value) {
|
|
341
|
+
if (typeof value === "string" && COMMAND_ORIGINS.has(value)) {
|
|
342
|
+
return value;
|
|
343
|
+
}
|
|
344
|
+
throw new StateQLError("INVALID_COMMAND", `Unknown command origin "${String(value)}".`);
|
|
345
|
+
}
|
|
346
|
+
export function mergeCommandExecutionContext(inherited, supplied) {
|
|
347
|
+
if (!supplied || typeof supplied !== "object") {
|
|
348
|
+
throw new StateQLError("INVALID_COMMAND", "Command execution context must be an object.");
|
|
349
|
+
}
|
|
350
|
+
if (supplied.signal !== undefined && !(supplied.signal instanceof AbortSignal)) {
|
|
351
|
+
throw new StateQLError("INVALID_COMMAND", "Command execution context signal must be an AbortSignal.");
|
|
352
|
+
}
|
|
353
|
+
if (supplied.internal !== undefined && typeof supplied.internal !== "boolean") {
|
|
354
|
+
throw new StateQLError("INVALID_COMMAND", "Command execution context internal must be boolean.");
|
|
355
|
+
}
|
|
356
|
+
return {
|
|
357
|
+
signal: combineAbortSignals(inherited?.signal, supplied.signal),
|
|
358
|
+
origin: supplied.origin === undefined ? inherited?.origin : parseCommandOrigin(supplied.origin),
|
|
359
|
+
internal: supplied.internal ?? inherited?.internal,
|
|
360
|
+
};
|
|
361
|
+
}
|
|
362
|
+
function combineAbortSignals(...signals) {
|
|
363
|
+
const present = signals.filter((signal) => signal !== undefined);
|
|
364
|
+
if (present.length === 0)
|
|
365
|
+
return undefined;
|
|
366
|
+
if (present.length === 1)
|
|
367
|
+
return present[0];
|
|
368
|
+
return AbortSignal.any(present);
|
|
369
|
+
}
|
|
370
|
+
export async function closeAdapterQuietly(adapter) {
|
|
371
|
+
try {
|
|
372
|
+
await adapter.close();
|
|
373
|
+
}
|
|
374
|
+
catch {
|
|
375
|
+
// Preserve the operation result or primary sanitized error.
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
async function resolveCredentialBeforeDeadline(resolver, request, context) {
|
|
379
|
+
if (context.signal?.aborted)
|
|
380
|
+
throw new CredentialResolutionError("cancelled");
|
|
381
|
+
const remaining = context.deadline - Date.now();
|
|
382
|
+
if (remaining <= 0)
|
|
383
|
+
throw new CredentialResolutionError("timeout");
|
|
384
|
+
return new Promise((resolve, reject) => {
|
|
385
|
+
let settled = false;
|
|
386
|
+
const finish = (action, value) => {
|
|
387
|
+
if (settled)
|
|
388
|
+
return;
|
|
389
|
+
settled = true;
|
|
390
|
+
clearTimeout(timer);
|
|
391
|
+
context.signal?.removeEventListener("abort", abort);
|
|
392
|
+
action(value);
|
|
393
|
+
};
|
|
394
|
+
const abort = () => finish(() => reject(new CredentialResolutionError("cancelled")));
|
|
395
|
+
const timer = setTimeout(() => finish(() => reject(new CredentialResolutionError("timeout"))), remaining);
|
|
396
|
+
context.signal?.addEventListener("abort", abort, { once: true });
|
|
397
|
+
Promise.resolve()
|
|
398
|
+
.then(() => resolver(request))
|
|
399
|
+
.then((value) => finish(resolve, value), (error) => finish(() => reject(error)));
|
|
400
|
+
});
|
|
401
|
+
}
|
|
402
|
+
function credentialStateQLError(reference, error) {
|
|
403
|
+
if (error instanceof CredentialResolutionError) {
|
|
404
|
+
switch (error.reason) {
|
|
405
|
+
case "unavailable":
|
|
406
|
+
return new StateQLError("CREDENTIAL_UNAVAILABLE", `Credential reference "${reference}" is unavailable.`, { retryable: true });
|
|
407
|
+
case "denied":
|
|
408
|
+
return new StateQLError("PERMISSION_DENIED", `Credential access for "${reference}" was denied.`);
|
|
409
|
+
case "cancelled":
|
|
410
|
+
return new StateQLError("OPERATION_CANCELLED", "Credential resolution was cancelled.", { retryable: true });
|
|
411
|
+
case "timeout":
|
|
412
|
+
return new StateQLError("DEADLINE_EXCEEDED", "Credential resolution exceeded the credential deadline.", { retryable: true });
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
return new StateQLError("CREDENTIAL_RESOLUTION_FAILED", `Credential reference "${reference}" could not be resolved.`, { retryable: true });
|
|
416
|
+
}
|
|
417
|
+
export function safeCredentialErrorMessage(error, source) {
|
|
418
|
+
let message = errorMessage(error).split(source).join("[credential redacted]");
|
|
419
|
+
const authority = /^[a-z][a-z\d+.-]*:\/\/([^/?#]*)/i.exec(source)?.[1];
|
|
420
|
+
if (authority) {
|
|
421
|
+
const at = authority.lastIndexOf("@");
|
|
422
|
+
const colon = at < 0 ? -1 : authority.slice(0, at).indexOf(":");
|
|
423
|
+
const password = colon < 0 ? "" : authority.slice(colon + 1, at);
|
|
424
|
+
const secrets = new Set([password]);
|
|
425
|
+
try {
|
|
426
|
+
secrets.add(decodeURIComponent(password));
|
|
427
|
+
}
|
|
428
|
+
catch { /* malformed values stay encoded */ }
|
|
429
|
+
for (const secret of secrets) {
|
|
430
|
+
if (secret)
|
|
431
|
+
message = message.split(secret).join("[credential redacted]");
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
return redact(message).replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+(?::[^\s/@]*)?@/giu, "$1***@");
|
|
435
|
+
}
|
|
436
|
+
export function executionTimeout(value, name = "timeoutMs") {
|
|
437
|
+
const timeout = positiveInteger(value, name);
|
|
438
|
+
if (timeout > 2_147_483_647) {
|
|
439
|
+
throw new StateQLError("INVALID_COMMAND", `${name} cannot exceed 2147483647 milliseconds.`);
|
|
440
|
+
}
|
|
441
|
+
return timeout;
|
|
442
|
+
}
|
|
443
|
+
export function nonNegativeInteger(value, name) {
|
|
444
|
+
if (Number.isInteger(value) && value >= 0)
|
|
445
|
+
return value;
|
|
446
|
+
throw new StateQLError("INVALID_COMMAND", `${name} must be a non-negative integer.`);
|
|
447
|
+
}
|
|
448
|
+
export function positiveInteger(value, name) {
|
|
449
|
+
if (Number.isInteger(value) && value > 0)
|
|
450
|
+
return value;
|
|
451
|
+
throw new StateQLError("INVALID_COMMAND", `${name} must be a positive integer.`);
|
|
452
|
+
}
|
|
453
|
+
export function errorMessage(error) {
|
|
454
|
+
return error instanceof Error ? error.message : String(error);
|
|
455
|
+
}
|
|
456
|
+
function redisResultCursor(parameters) {
|
|
457
|
+
try {
|
|
458
|
+
const value = JSON.parse(parameters);
|
|
459
|
+
const cursor = Array.isArray(value) ? value[1] : null;
|
|
460
|
+
return typeof cursor === "string" ? cursor : null;
|
|
461
|
+
}
|
|
462
|
+
catch {
|
|
463
|
+
return null;
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
export function historyCategory(command) {
|
|
467
|
+
if (["query", "exec", "plan", "apply", "mongo.query", "mongo.exec", "mongo.plan", "redis.query", "redis.exec", "redis.plan", "filter"].includes(command))
|
|
468
|
+
return "statement";
|
|
469
|
+
if (command.startsWith("inspect.") || ["objects.list", "object.describe", "table.read"].includes(command))
|
|
470
|
+
return "introspection";
|
|
471
|
+
return "management";
|
|
472
|
+
}
|
|
473
|
+
export function parseHistoryCategory(value) {
|
|
474
|
+
if (value === "statement" || value === "introspection" || value === "management")
|
|
475
|
+
return value;
|
|
476
|
+
throw new StateQLError("INVALID_COMMAND", `Unknown history category "${String(value)}".`);
|
|
477
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { StateQLError } from "./errors.js";
|
|
2
|
+
export interface AdapterContext {
|
|
3
|
+
deadline: number;
|
|
4
|
+
timeoutMs?: number;
|
|
5
|
+
signal?: AbortSignal;
|
|
6
|
+
}
|
|
7
|
+
export declare class AdapterExecutionError extends Error {
|
|
8
|
+
readonly reason: "timeout" | "aborted";
|
|
9
|
+
readonly outcomeUnknown: boolean;
|
|
10
|
+
constructor(message: string, reason: "timeout" | "aborted", outcomeUnknown: boolean);
|
|
11
|
+
}
|
|
12
|
+
export declare class BatchWriteError extends Error {
|
|
13
|
+
readonly outcomeUnknown: boolean;
|
|
14
|
+
constructor(message: string, outcomeUnknown: boolean);
|
|
15
|
+
}
|
|
16
|
+
export declare class AdapterWriteError extends Error {
|
|
17
|
+
readonly outcomeUnknown: boolean;
|
|
18
|
+
constructor(message: string, outcomeUnknown: boolean);
|
|
19
|
+
}
|
|
20
|
+
export declare function createAdapterContext(timeoutMs: number, signal?: AbortSignal): AdapterContext;
|
|
21
|
+
export declare function remainingMilliseconds(context: AdapterContext): number;
|
|
22
|
+
export declare function isStopped(context: AdapterContext): boolean;
|
|
23
|
+
export declare function throwIfStopped(context: AdapterContext, outcomeUnknown: boolean): void;
|
|
24
|
+
export declare function stoppedError(context: AdapterContext, outcomeUnknown: boolean): AdapterExecutionError;
|
|
25
|
+
/** Settles with a stopped error at the deadline or on abort, and calls onStop to release the driver. */
|
|
26
|
+
export declare function withContext<T>(promise: Promise<T>, context: AdapterContext, onStop: () => void, outcomeUnknown: boolean): Promise<T>;
|
|
27
|
+
export declare function stoppedStateQLError(error: AdapterExecutionError, executed: boolean): StateQLError;
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { StateQLError } from "./errors.js";
|
|
2
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
3
|
+
export class AdapterExecutionError extends Error {
|
|
4
|
+
reason;
|
|
5
|
+
outcomeUnknown;
|
|
6
|
+
constructor(message, reason, outcomeUnknown) {
|
|
7
|
+
super(message);
|
|
8
|
+
this.reason = reason;
|
|
9
|
+
this.outcomeUnknown = outcomeUnknown;
|
|
10
|
+
this.name = "AdapterExecutionError";
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
export class BatchWriteError extends Error {
|
|
14
|
+
outcomeUnknown;
|
|
15
|
+
constructor(message, outcomeUnknown) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.outcomeUnknown = outcomeUnknown;
|
|
18
|
+
this.name = "BatchWriteError";
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
export class AdapterWriteError extends Error {
|
|
22
|
+
outcomeUnknown;
|
|
23
|
+
constructor(message, outcomeUnknown) {
|
|
24
|
+
super(message);
|
|
25
|
+
this.outcomeUnknown = outcomeUnknown;
|
|
26
|
+
this.name = "AdapterWriteError";
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
export function createAdapterContext(timeoutMs, signal) {
|
|
30
|
+
return {
|
|
31
|
+
deadline: Date.now() + timeoutMs,
|
|
32
|
+
timeoutMs,
|
|
33
|
+
...(signal ? { signal } : {}),
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
export function remainingMilliseconds(context) {
|
|
37
|
+
return Math.max(1, Math.min(MAX_TIMER_MS, Math.ceil(context.deadline - Date.now())));
|
|
38
|
+
}
|
|
39
|
+
export function isStopped(context) {
|
|
40
|
+
return Boolean(context.signal?.aborted) || context.deadline <= Date.now();
|
|
41
|
+
}
|
|
42
|
+
export function throwIfStopped(context, outcomeUnknown) {
|
|
43
|
+
if (isStopped(context))
|
|
44
|
+
throw stoppedError(context, outcomeUnknown);
|
|
45
|
+
}
|
|
46
|
+
export function stoppedError(context, outcomeUnknown) {
|
|
47
|
+
const aborted = context.signal?.aborted ?? false;
|
|
48
|
+
return new AdapterExecutionError(aborted ? "Database operation cancelled." : "Database operation timed out.", aborted ? "aborted" : "timeout", outcomeUnknown);
|
|
49
|
+
}
|
|
50
|
+
/** Settles with a stopped error at the deadline or on abort, and calls onStop to release the driver. */
|
|
51
|
+
export function withContext(promise, context, onStop, outcomeUnknown) {
|
|
52
|
+
const stopQuietly = () => {
|
|
53
|
+
try {
|
|
54
|
+
onStop();
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
// Preserve the deadline or cancellation error.
|
|
58
|
+
}
|
|
59
|
+
};
|
|
60
|
+
if (isStopped(context)) {
|
|
61
|
+
stopQuietly();
|
|
62
|
+
return Promise.reject(stoppedError(context, outcomeUnknown));
|
|
63
|
+
}
|
|
64
|
+
return new Promise((resolve, reject) => {
|
|
65
|
+
let settled = false;
|
|
66
|
+
const finish = (action) => {
|
|
67
|
+
if (settled)
|
|
68
|
+
return;
|
|
69
|
+
settled = true;
|
|
70
|
+
clearTimeout(timer);
|
|
71
|
+
context.signal?.removeEventListener("abort", stop);
|
|
72
|
+
action();
|
|
73
|
+
};
|
|
74
|
+
const stop = () => {
|
|
75
|
+
finish(() => {
|
|
76
|
+
stopQuietly();
|
|
77
|
+
reject(stoppedError(context, outcomeUnknown));
|
|
78
|
+
});
|
|
79
|
+
};
|
|
80
|
+
const timer = setTimeout(stop, remainingMilliseconds(context));
|
|
81
|
+
context.signal?.addEventListener("abort", stop, { once: true });
|
|
82
|
+
promise.then((value) => (isStopped(context) ? stop() : finish(() => resolve(value))), (error) => (isStopped(context) ? stop() : finish(() => reject(error))));
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
export function stoppedStateQLError(error, executed) {
|
|
86
|
+
return new StateQLError(error.reason === "timeout" ? "DEADLINE_EXCEEDED" : "OPERATION_CANCELLED", error.message, { retryable: true, executed });
|
|
87
|
+
}
|
package/dist/src/filter.js
CHANGED
|
@@ -183,7 +183,9 @@ function validateFilterExpression(value, columns, tableName) {
|
|
|
183
183
|
throw new StateQLError("INVALID_SQL", `Filter function "${name ?? "unknown"}" is not allowed.`);
|
|
184
184
|
}
|
|
185
185
|
}
|
|
186
|
-
Object.values(record)
|
|
186
|
+
for (const item of Object.values(record)) {
|
|
187
|
+
validateFilterExpression(item, columns, tableName);
|
|
188
|
+
}
|
|
187
189
|
}
|
|
188
190
|
function filterFunctionName(record) {
|
|
189
191
|
const name = record.name;
|
package/dist/src/index.d.ts
CHANGED
|
@@ -3,4 +3,4 @@ export { agentResponse } from "./agent-response.js";
|
|
|
3
3
|
export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
|
|
4
4
|
export type { CredentialResolutionFailure } from "./errors.js";
|
|
5
5
|
export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
|
|
6
|
-
export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, ColumnSummary, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, SummaryData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
|
|
6
|
+
export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, ColumnSummary, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResponseMeta, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLErrorShape, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, SummaryData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
|
package/dist/src/migrations.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { DatabaseSync } from "node:sqlite";
|
|
1
|
+
import type { DatabaseSync } from "node:sqlite";
|
|
2
2
|
export declare function runMigrations(db: DatabaseSync, now: () => Date): void;
|
package/dist/src/mongodb.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import type { BaseAdapter } from "./adapters.js";
|
|
2
|
+
import { type AdapterContext } from "./execution.js";
|
|
2
3
|
import type { ConnectionRecord } from "./store.js";
|
|
3
4
|
import type { CatalogObject, Column, DescribeObjectData, ListObjectsData, ListObjectsFilter, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, Row } from "./types.js";
|
|
4
5
|
interface MongoReadResult {
|
|
@@ -19,8 +20,9 @@ export declare function analyzeMongoWriteSafety(command: MongoWriteCommand): Mon
|
|
|
19
20
|
/** Deterministic EJSON preserves BSON types and property order. */
|
|
20
21
|
export declare function serializeMongoCommand(command: MongoReadCommand | MongoWriteCommand): string;
|
|
21
22
|
export declare function deserializeMongoWriteCommand(value: string): MongoWriteCommand;
|
|
22
|
-
export declare class MongoAdapter {
|
|
23
|
+
export declare class MongoAdapter implements BaseAdapter {
|
|
23
24
|
private readonly context;
|
|
25
|
+
readonly kind: "mongodb";
|
|
24
26
|
readonly confidence: "ttl_based";
|
|
25
27
|
private readonly client;
|
|
26
28
|
private readonly databaseName;
|