@fadhilp/stateql 0.17.0 → 0.19.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.
Files changed (43) hide show
  1. package/dist/src/adapters.d.ts +17 -25
  2. package/dist/src/adapters.js +15 -95
  3. package/dist/src/catalog.d.ts +6 -0
  4. package/dist/src/catalog.js +52 -0
  5. package/dist/src/cli.js +8 -3
  6. package/dist/src/connect.d.ts +16 -0
  7. package/dist/src/connect.js +205 -0
  8. package/dist/src/core.d.ts +78 -0
  9. package/dist/src/core.js +477 -0
  10. package/dist/src/execution.d.ts +27 -0
  11. package/dist/src/execution.js +87 -0
  12. package/dist/src/filter.js +3 -1
  13. package/dist/src/index.d.ts +2 -1
  14. package/dist/src/index.js +1 -0
  15. package/dist/src/migrations.d.ts +1 -1
  16. package/dist/src/mongodb.d.ts +4 -2
  17. package/dist/src/mongodb.js +5 -56
  18. package/dist/src/os-credentials.d.ts +6 -1
  19. package/dist/src/os-credentials.js +171 -10
  20. package/dist/src/panel.d.ts +64 -0
  21. package/dist/src/panel.js +316 -0
  22. package/dist/src/plans.d.ts +31 -0
  23. package/dist/src/plans.js +275 -0
  24. package/dist/src/reads.d.ts +35 -0
  25. package/dist/src/reads.js +184 -0
  26. package/dist/src/redis.d.ts +4 -2
  27. package/dist/src/redis.js +7 -33
  28. package/dist/src/response-data.d.ts +1 -0
  29. package/dist/src/response-data.js +13 -10
  30. package/dist/src/results.d.ts +10 -0
  31. package/dist/src/results.js +153 -0
  32. package/dist/src/sqlite-process.js +16 -9
  33. package/dist/src/stateql.d.ts +7 -58
  34. package/dist/src/stateql.js +150 -2663
  35. package/dist/src/table-editor.js +2 -2
  36. package/dist/src/transactions.d.ts +8 -0
  37. package/dist/src/transactions.js +186 -0
  38. package/dist/src/types.d.ts +3 -17
  39. package/dist/src/writes.d.ts +48 -0
  40. package/dist/src/writes.js +320 -0
  41. package/docs/databases.md +2 -1
  42. package/docs/results.md +5 -0
  43. package/package.json +5 -3
@@ -1,6 +1,6 @@
1
1
  import { createRequire } from "node:module";
2
2
  import { BSON } from "bson";
3
- import { AdapterExecutionError, AdapterWriteError, BatchWriteError, } from "./adapters.js";
3
+ import { AdapterExecutionError, AdapterWriteError, BatchWriteError, isStopped, remainingMilliseconds, stoppedError, throwIfStopped, withContext, } from "./execution.js";
4
4
  const require = createRequire(import.meta.url);
5
5
  let mongodbModule;
6
6
  const mongodb = () => (mongodbModule ??= require("mongodb"));
@@ -156,6 +156,7 @@ export function deserializeMongoWriteCommand(value) {
156
156
  }
157
157
  export class MongoAdapter {
158
158
  context;
159
+ kind = "mongodb";
159
160
  confidence = "ttl_based";
160
161
  client;
161
162
  databaseName;
@@ -258,7 +259,7 @@ export class MongoAdapter {
258
259
  const stopped = writeStoppedError(error, this.context, true);
259
260
  if (stopped)
260
261
  throw stopped;
261
- throw new AdapterWriteError(errorText(error), knownNoWrite(error) ? false : true);
262
+ throw new AdapterWriteError(errorText(error), !knownNoWrite(error));
262
263
  }
263
264
  }
264
265
  async writeBatch(commands, isolation, expectedRows = false) {
@@ -838,75 +839,23 @@ function ejsonSafe(value) {
838
839
  return null;
839
840
  return JSON.parse(BSON.EJSON.stringify(value, { relaxed: false }));
840
841
  }
841
- function escapeRegex(value) {
842
- return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
843
- }
844
- function remainingMilliseconds(context) {
845
- return Math.max(1, Math.min(2_147_483_647, Math.ceil(context.deadline - Date.now())));
846
- }
847
842
  function operationSignal(context) {
848
843
  const deadlineSignal = AbortSignal.timeout(remainingMilliseconds(context));
849
844
  return context.signal ? AbortSignal.any([context.signal, deadlineSignal]) : deadlineSignal;
850
845
  }
851
- function throwIfStopped(context, outcomeUnknown) {
852
- if (context.signal?.aborted || context.deadline <= Date.now()) {
853
- throw stoppedError(context, outcomeUnknown);
854
- }
855
- }
856
- function stoppedError(context, outcomeUnknown) {
857
- const aborted = context.signal?.aborted ?? false;
858
- return new AdapterExecutionError(aborted ? "Database operation cancelled." : "Database operation timed out.", aborted ? "aborted" : "timeout", outcomeUnknown);
859
- }
860
- function withContext(promise, context, onStop, outcomeUnknown) {
861
- try {
862
- throwIfStopped(context, outcomeUnknown);
863
- }
864
- catch (error) {
865
- return Promise.reject(error);
866
- }
867
- return new Promise((resolve, reject) => {
868
- let settled = false;
869
- const finish = (action) => {
870
- if (settled)
871
- return;
872
- settled = true;
873
- clearTimeout(timer);
874
- context.signal?.removeEventListener("abort", stop);
875
- action();
876
- };
877
- const stop = () => finish(() => {
878
- try {
879
- onStop();
880
- }
881
- catch {
882
- // Preserve cancellation/deadline error.
883
- }
884
- reject(stoppedError(context, outcomeUnknown));
885
- });
886
- const timer = setTimeout(stop, remainingMilliseconds(context));
887
- context.signal?.addEventListener("abort", stop, { once: true });
888
- promise.then((result) => context.signal?.aborted || context.deadline <= Date.now()
889
- ? stop()
890
- : finish(() => resolve(result)), (error) => context.signal?.aborted || context.deadline <= Date.now()
891
- ? stop()
892
- : finish(() => reject(error)));
893
- });
894
- }
895
846
  function readError(error, context) {
896
847
  if (error instanceof AdapterExecutionError)
897
848
  return error;
898
- if (isTimeoutError(error) || context.signal?.aborted || context.deadline <= Date.now()) {
849
+ if (isTimeoutError(error) || isStopped(context))
899
850
  return stoppedError(context, false);
900
- }
901
851
  return error;
902
852
  }
903
853
  function writeStoppedError(error, context, outcomeUnknown) {
904
854
  if (error instanceof AdapterExecutionError) {
905
855
  return new AdapterExecutionError(error.message, error.reason, outcomeUnknown);
906
856
  }
907
- if (isTimeoutError(error) || context.signal?.aborted || context.deadline <= Date.now()) {
857
+ if (isTimeoutError(error) || isStopped(context))
908
858
  return stoppedError(context, outcomeUnknown);
909
- }
910
859
  return undefined;
911
860
  }
912
861
  function isTimeoutError(error) {
@@ -1,6 +1,11 @@
1
1
  import type { CredentialRequest } from "./types.js";
2
2
  export declare function isOsPasswordRef(reference: string | null | undefined): reference is string;
3
+ export declare function createOsPasswordRef(): string;
3
4
  export declare function cliCredentialResolver(request: CredentialRequest): Promise<string | undefined>;
4
- export declare function saveOsPassword(password: string): Promise<string>;
5
+ export declare function saveOsPassword(reference: string, target: string, password: string): Promise<void>;
6
+ /** Returns the password only when it was saved for the same destination as `target`. */
7
+ export declare function readOsPassword(reference: string, target: string): Promise<string | undefined>;
8
+ /** Marks a saved password as rejected by the database, so it is not used again. */
9
+ export declare function invalidateOsPassword(reference: string): Promise<boolean>;
5
10
  export declare function deleteOsPassword(reference: string | null | undefined): Promise<void>;
6
11
  export declare function askPassword(profile: string, target: string): Promise<string>;
@@ -1,35 +1,196 @@
1
1
  import { execFile } from "node:child_process";
2
- import { randomUUID } from "node:crypto";
2
+ import { createHash, randomUUID } from "node:crypto";
3
3
  import { env, platform } from "node:process";
4
4
  import { promisify } from "node:util";
5
5
  const SERVICE = "stql";
6
6
  const PREFIX = "os:";
7
+ const MAX_TARGET_LENGTH = 8_192;
8
+ const MAX_PAYLOAD_LENGTH = 16_384;
9
+ const MAX_PASSWORD_LENGTH = 4_096;
10
+ const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/u;
11
+ const PROTOCOLS = ["postgres:", "mysql:", "mongodb:", "mongodb+srv:", "redis:", "rediss:"];
12
+ const TARGET_OVERRIDE_KEYS = new Set(["password", "pwd", "user", "username", "host", "port", "database", "dbname"]);
13
+ // TLS settings are connection options, not destination identity. pylon_tls_ca is Pylon's CA preset.
14
+ const TLS_QUERY_KEYS = new Set([
15
+ "sslmode",
16
+ "ssl",
17
+ "sslrootcert",
18
+ "sslcert",
19
+ "sslkey",
20
+ "rejectunauthorized",
21
+ "uselibpqcompat",
22
+ "sslnegotiation",
23
+ "pylon_tls_ca",
24
+ ]);
7
25
  const run = promisify(execFile);
8
26
  export function isOsPasswordRef(reference) {
9
27
  return reference?.startsWith(PREFIX) ?? false;
10
28
  }
29
+ export function createOsPasswordRef() {
30
+ return `${PREFIX}${randomUUID()}`;
31
+ }
11
32
  export async function cliCredentialResolver(request) {
12
33
  if (request.source === "credential_ref")
13
34
  return undefined;
14
35
  if (request.source !== "password_ref")
15
36
  return env[request.reference];
16
- if (!isOsPasswordRef(request.reference))
37
+ return readOsPassword(request.reference, request.target);
38
+ }
39
+ export async function saveOsPassword(reference, target, password) {
40
+ if (!isOsPasswordRef(reference))
41
+ throw new Error("Password reference must start with os:.");
42
+ if (!validPassword(password))
43
+ throw new Error("Password is too long or contains control characters.");
44
+ const fingerprint = targetFingerprint(target);
45
+ if (!fingerprint)
46
+ throw new Error("Cannot save a password for this target.");
47
+ const stored = { version: 2, fingerprint, password };
48
+ await (await osEntry(reference)).setPassword(JSON.stringify(stored));
49
+ }
50
+ /** Returns the password only when it was saved for the same destination as `target`. */
51
+ export async function readOsPassword(reference, target) {
52
+ if (!isOsPasswordRef(reference))
53
+ return undefined;
54
+ const value = await (await osEntry(reference)).getPassword();
55
+ if (value === null)
17
56
  return undefined;
18
- return (await osEntry(request.reference)).getPassword() ?? undefined;
57
+ if (!isRecord(value))
58
+ return value; // Raw password saved before passwords were bound to a target.
59
+ const stored = storedPassword(value);
60
+ if (!stored || stored.stale)
61
+ return undefined;
62
+ return stored.fingerprint === targetFingerprint(target) ? stored.password : undefined;
19
63
  }
20
- export async function saveOsPassword(password) {
21
- const reference = `${PREFIX}${randomUUID()}`;
22
- (await osEntry(reference)).setPassword(password);
23
- return reference;
64
+ /** Marks a saved password as rejected by the database, so it is not used again. */
65
+ export async function invalidateOsPassword(reference) {
66
+ if (!isOsPasswordRef(reference))
67
+ return false;
68
+ const entry = await osEntry(reference);
69
+ const stored = storedPassword((await entry.getPassword()) ?? "");
70
+ if (!stored)
71
+ return false;
72
+ await entry.setPassword(JSON.stringify({ ...stored, stale: true }));
73
+ return true;
24
74
  }
25
75
  export async function deleteOsPassword(reference) {
26
76
  if (!isOsPasswordRef(reference))
27
77
  return;
28
- (await osEntry(reference)).deletePassword();
78
+ await (await osEntry(reference)).deleteCredential();
29
79
  }
30
80
  async function osEntry(reference) {
31
- const { Entry } = await import("@napi-rs/keyring");
32
- return new Entry(SERVICE, reference.slice(PREFIX.length));
81
+ const { AsyncEntry } = await import("@napi-rs/keyring");
82
+ // The keyutils fallback loses saved passwords after reboot.
83
+ return new AsyncEntry(SERVICE, reference.slice(PREFIX.length), { linux: { store: "secret-service" } });
84
+ }
85
+ function isRecord(value) {
86
+ try {
87
+ const parsed = JSON.parse(value);
88
+ return typeof parsed === "object" && parsed !== null && "version" in parsed;
89
+ }
90
+ catch {
91
+ return false;
92
+ }
93
+ }
94
+ function storedPassword(value) {
95
+ if (!value || value.length > MAX_PAYLOAD_LENGTH)
96
+ return undefined;
97
+ let record;
98
+ try {
99
+ const parsed = JSON.parse(value);
100
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
101
+ return undefined;
102
+ record = parsed;
103
+ }
104
+ catch {
105
+ return undefined;
106
+ }
107
+ const knownKeys = Object.keys(record).every((key) => ["version", "fingerprint", "password", "stale"].includes(key));
108
+ if (!knownKeys || record.version !== 2)
109
+ return undefined;
110
+ if (typeof record.fingerprint !== "string" || !FINGERPRINT_PATTERN.test(record.fingerprint))
111
+ return undefined;
112
+ if (!validPassword(record.password))
113
+ return undefined;
114
+ if (record.stale !== undefined && record.stale !== true)
115
+ return undefined;
116
+ return {
117
+ version: 2,
118
+ fingerprint: record.fingerprint,
119
+ password: record.password,
120
+ ...(record.stale ? { stale: true } : {}),
121
+ };
122
+ }
123
+ function validPassword(password) {
124
+ return typeof password === "string" && password.length <= MAX_PASSWORD_LENGTH && !hasControlCharacters(password);
125
+ }
126
+ function hasControlCharacters(value) {
127
+ return /[\u0000-\u001f\u007f]/u.test(value);
128
+ }
129
+ function targetFingerprint(target) {
130
+ const unsafeTarget = !target || target.length > MAX_TARGET_LENGTH || hasControlCharacters(target);
131
+ if (unsafeTarget || /%(?![0-9a-f]{2})/iu.test(target))
132
+ return undefined;
133
+ // WHATWG URL rejects multi-host MongoDB targets; bind those to the exact target instead.
134
+ const identity = parsesAsUrl(target) ? destinationIdentity(target) : target;
135
+ return identity ? createHash("sha256").update(identity).digest("hex") : undefined;
136
+ }
137
+ function parsesAsUrl(target) {
138
+ try {
139
+ new URL(target);
140
+ return true;
141
+ }
142
+ catch {
143
+ return false;
144
+ }
145
+ }
146
+ function destinationIdentity(target) {
147
+ const url = new URL(target);
148
+ const protocol = url.protocol.toLowerCase() === "postgresql:" ? "postgres:" : url.protocol.toLowerCase();
149
+ if (!PROTOCOLS.includes(protocol) || !url.hostname || url.hash || url.password)
150
+ return undefined;
151
+ const username = decodedPart(url.username);
152
+ const database = decodedPart(url.pathname);
153
+ if (username === undefined || database === undefined)
154
+ return undefined;
155
+ const query = [];
156
+ for (const [key, value] of url.searchParams.entries()) {
157
+ const normalizedKey = key.toLowerCase();
158
+ if (hasControlCharacters(key) || hasControlCharacters(value))
159
+ return undefined;
160
+ if (TARGET_OVERRIDE_KEYS.has(normalizedKey))
161
+ return undefined;
162
+ if (!TLS_QUERY_KEYS.has(normalizedKey))
163
+ query.push([key, value]);
164
+ }
165
+ query.sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey === rightKey ? leftValue.localeCompare(rightValue) : leftKey.localeCompare(rightKey));
166
+ return JSON.stringify({
167
+ protocol,
168
+ username,
169
+ hostname: url.hostname.toLowerCase().replace(/\.$/u, ""),
170
+ port: url.port || defaultPort(protocol),
171
+ database,
172
+ query,
173
+ });
174
+ }
175
+ function decodedPart(value) {
176
+ try {
177
+ const decoded = decodeURIComponent(value);
178
+ return hasControlCharacters(decoded) ? undefined : decoded;
179
+ }
180
+ catch {
181
+ return undefined;
182
+ }
183
+ }
184
+ function defaultPort(protocol) {
185
+ if (protocol === "postgres:")
186
+ return "5432";
187
+ if (protocol === "mysql:")
188
+ return "3306";
189
+ if (protocol === "mongodb:")
190
+ return "27017";
191
+ if (protocol === "redis:" || protocol === "rediss:")
192
+ return "6379";
193
+ return "";
33
194
  }
34
195
  export async function askPassword(profile, target) {
35
196
  const url = new URL(target);
@@ -0,0 +1,64 @@
1
+ import { type Core } from "./core.js";
2
+ import { type EditableTable, type TableChange, type TableIdentity } from "./table-editor.js";
3
+ import type { Column, CommandOrigin, ExecutionOptions, MongoReadCommand, PlanData, QueryOptions, Response, ResultData, RowsData, RowsOptions, StateQLSnapshot, StateQLSnapshotOptions } from "./types.js";
4
+ /** Public StateQL commands the panel calls, so they are recorded in history as usual. */
5
+ export interface PanelHost {
6
+ snapshot(options: StateQLSnapshotOptions): StateQLSnapshot;
7
+ inspect(kind: string, table: string, options: ExecutionOptions): Promise<Response<unknown>>;
8
+ query(sql: string, options: QueryOptions): Promise<Response<ResultData>>;
9
+ mongoQuery(command: MongoReadCommand, options: QueryOptions): Promise<Response<ResultData>>;
10
+ }
11
+ export type MaterializedPage = RowsData & {
12
+ columns: Column[];
13
+ row_tokens: Array<string | null>;
14
+ writable_columns: string[];
15
+ editing_reason?: string;
16
+ };
17
+ export type TableRead = ResultData & {
18
+ table: {
19
+ schema?: string;
20
+ name: string;
21
+ };
22
+ sample_limit: number;
23
+ query: string;
24
+ };
25
+ /** Bounded table browsing and row editing for host UIs, with in-memory row identities. */
26
+ export declare class Panel {
27
+ private readonly core;
28
+ private readonly host;
29
+ private readonly tableResults;
30
+ private readonly editTokens;
31
+ private panelRows?;
32
+ constructor(core: Core, host: PanelHost);
33
+ clear(): void;
34
+ /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
35
+ readMaterialized(id: string, options?: RowsOptions & {
36
+ signal?: AbortSignal;
37
+ }): MaterializedPage;
38
+ /** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
39
+ serializeResult(id: string, format: "json" | "jsonl" | "csv", signal?: AbortSignal, origin?: CommandOrigin): Promise<Response<{
40
+ content: string;
41
+ format: string;
42
+ rows: number;
43
+ }>>;
44
+ readTable(table: {
45
+ schema?: string;
46
+ name: string;
47
+ }, limit?: number, options?: QueryOptions & {
48
+ origin?: CommandOrigin;
49
+ }): Promise<Response<TableRead>>;
50
+ planTableUpdate(token: string, changes: TableChange, options?: ExecutionOptions & {
51
+ origin?: CommandOrigin;
52
+ }): Promise<Response<PlanData>>;
53
+ planTableUpdates(changes: Array<{
54
+ row_token: string;
55
+ changes: TableChange;
56
+ }>, options?: ExecutionOptions & {
57
+ origin?: CommandOrigin;
58
+ }): Promise<Response<PlanData>>;
59
+ editableMetadata(table: TableIdentity, options: ExecutionOptions): Promise<EditableTable>;
60
+ private issueEditToken;
61
+ private liveEditToken;
62
+ private panelResult;
63
+ private fullResultRows;
64
+ }