@xeplr/actions 2.2.0 → 2.2.2

package/README.md

@@ -26,6 +26,7 @@ Everything else is an **optional peer**, required only when an action actually u
 | `mailparser` | `email-read` (unless `body: 'none'`), `email-download-attachments` |
 | `nodemailer` (^10.0.13 — up to 10.0.5 has high-severity advisories) | `email-send` with its own connection |
 | `@xeplr/email` | `email-send` with `templateName` |
+| `@xeplr/push` | `push-send` (the host sets it up at boot: `push.init({ knex })`) |
 | `knex` | the knex meta store |
 | `mongodb`, `ssh2-sftp-client`, `exceljs` | declared, but their drivers/sources are not implemented |
 
@@ -121,7 +122,7 @@ The input is checked exactly as a run checks it.
 
 | previewed (reads, up to 5) | example only (writes or sends; never run) |
 |---|---|
-| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
+| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `push-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
 
 Neither: `db-push`, `db-move`, `http-request` (an outside system, which may change something), `spawn-program`, `file-upload`; a designer asks for an example by hand. `test/previews.test.js` checks it on a real folder, file and Postgres: five rows read and no file spooled, the real count kept, a deleting step's file still there.
 
@@ -144,6 +145,7 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `dbListColumns` | `db-list-columns` | `{ columns }` — `name`, `dataType`, `udtName` and `maxLength` (characters; `-1` is SQL Server `(max)`, `null` when it has none) for one table. |
 | `fileUpload` | `file-upload` | Read a file (`sourceType`, `sourcePath`), parse it (`format`), load it into `targetTable` (`dbType`, `dbConnection`) as a New table, Append or Replace (`mode`, see [Import modes](#import-modes)). Passes `system.onProgress` (`{ rowsRead, batches, rowsWritten }`, per batch) and `system.signal` (stop) to the uploader, as `db-move` does. |
 | `sendEmail` | `email-send` | Send one message. See [Email](#email). |
+| `pushSend` | `push-send` | A push notification on people's phones and computers, even with the app closed, by `emails` and/or `userIds`: `title` (required), `body`, `url` (a page of the app a tap opens), `tag`. Returns `{ devices, sent, removed, failed }`. Through [`@xeplr/push`](https://www.npmjs.com/package/@xeplr/push), which the host sets up. |
 | `emailRead` | `email-read` | List messages, newest first, with `unread_only`, `limit` (1–1000, default 50), `since`, `from_equals`, `from_contains`, `subject_contains`, `body: 'full' \| 'text' \| 'none'`, optional NDJSON spooling. |
 | `emailMove` | `email-move` | Move a message (`messageId`, `folder`) to `toFolder`. |
 | `emailDelete` | `email-delete` | Flag `\Deleted` **and expunge** — permanent, not a move to Trash. |
@@ -582,6 +584,32 @@ await driver.query(pool, userSql, params)          // reads only
 
 **Values are bound, never written into SQL.** On MySQL, `stringifyObjects` is always on, so an object or array passed as a value is compared as text instead of being expanded into `key = value` pairs. **Procedure parameter names** are written into the call (`@region = @p0`, `region => $1`) and must be plain names — letters, digits and `_`.
 
+## Stopping a query — the stop reaches the database
+
+A query nobody is waiting for must not keep running. Every driver's `query` and `fetchStream` take a stop signal and a time limit:
+
+```js
+const stop = new AbortController()
+await driver.query(pool, sql, params, { signal: stop.signal, timeoutMs: 120000 })
+for await (const row of driver.fetchStream(pool, { sql, params, signal: stop.signal, timeoutMs: 120000 })) { … }
+stop.abort(new Error('Nobody is waiting for this'))   // cancels it IN THE DATABASE
+```
+
+- **A stop cancels the query in the database, not just our read.** A `GROUP BY` or `ORDER BY` is worked out in full before the first row comes back, so a stop that only ended our read loop left the database working, holding its CPU and a connection, until it finished.
+- **The two errors:** `code: 'QUERY_STOPPED'`, whose message is the signal's reason; and `code: 'QUERY_TIMEOUT'`, "The database stopped this query after 2 minutes, its time limit…".
+- **A signal that has already fired:** the query is never sent.
+- **Neither option given:** the query runs exactly as before.
+
+| Driver | How it is stopped | Time limit |
+|---|---|---|
+| postgres | `pg_cancel_backend(<the query's backend>)`, sent on a connection of its own, so a pool whose connections are all busy (often with the very queries being stopped) cannot block it. The stopped query's connection is destroyed, not reused | `statement_timeout`, enforced by Postgres even if this process dies. For `fetchStream` it applies to each FETCH. On a writable connection it is set for the query and reset after, without adding a transaction |
+| duckdb | `interrupt()` on the query's own connection. A query still waiting for a free connection is let go before it runs | a timer that interrupts the same way |
+| mssql | `request.cancel()`, an attention on the query's own connection | a timer that cancels the same way (SQL Server has no per-statement limit) |
+| mysql | `KILL QUERY <thread id>`, sent on a connection of its own. The stopped query's connection is destroyed | a timer that kills the same way (`max_execution_time` covers SELECTs only, and MariaDB names it differently) |
+| mongo | not yet | — |
+
+The tests prove that the database itself let go: Postgres by `pg_stat_activity`, SQL Server by `sys.dm_exec_requests`, MySQL by the processlist, and DuckDB by its one connection answering at once (`test/drivers/stop.*.test.js`). The SQL Server and MySQL ones run when `MSSQL_*` and `MYSQL_*` are set.
+
 ## Rules the code enforces, and why
 
 | rule | why |

package/lib/builtins/index.js

@@ -22,6 +22,8 @@ module.exports = {
   dataOperation: require('./data-operation'),
   spawnProgram: require('./spawn-program'),
   sendEmail:    require('./send-email'),
+  // A notification on people's devices (Web Push) — peer @xeplr/push.
+  pushSend:     require('./push-send'),
 
   // DB actions — factory-shaped (call fileUpload({ metaKnex }) to get a
   // registerable module) so the Knex handle for the meta store binds at

package/lib/builtins/push-send.js

@@ -0,0 +1,58 @@
+// push-send action — a notification on people's phones and computers, even
+// with the app closed, through @xeplr/push (Web Push).
+//
+// Peer dep: `@xeplr/push`, lazy-required here, so an install that never
+// pushes does not need it. The host app sets it up once at boot —
+// push.init({ knex }) with its VAPID keys — and this step only sends.
+//
+// WHO: account ids (`userIds`) and/or emails (`emails`) — every device each of
+// them switched on, each device once. Nobody to send to is refused, rather
+// than "succeeding" with nothing sent.
+//
+// WHERE A TAP GOES: `url` is a page of the app ("/orders/{params.id}"). A full
+// address to another site is replaced by the app's home by @xeplr/push, so a
+// step can never send people off somewhere else.
+
+function asList(v) {
+  if (v === undefined || v === null || v === '') return [];
+  return (Array.isArray(v) ? v : [v]).map(function(x) { return String(x).trim(); }).filter(Boolean);
+}
+
+module.exports = {
+  name: 'push-send',
+  // It sends, so it is never previewed.
+  example: { devices: 2, sent: 2, removed: 0, failed: 0 },
+  description: 'Send a push notification to people\'s phones and computers (Web Push, through @xeplr/push) — by account id or email. A tap opens the page given.',
+  requires: [],   // @xeplr/push checked at runtime
+
+  inputSchema: [
+    { name: 'emails',  type: 'array',  order: 1,
+      description: 'Who gets it, by email. A bare string is accepted and wrapped.' },
+    { name: 'userIds', type: 'array',  order: 2,
+      description: 'Who gets it, by account id — instead of, or as well as, emails.' },
+    { name: 'title',   type: 'string', required: true, order: 3,
+      description: 'The first line, e.g. "RTO: #{params.orderNumber}". At most 120 characters.' },
+    { name: 'body',    type: 'string', order: 4,
+      description: 'Under it. At most 300 characters.' },
+    { name: 'url',     type: 'string', order: 5,
+      description: 'The page of the app a tap opens, e.g. /orders/{params.id}. Leave empty for the home page.' },
+    { name: 'tag',     type: 'string', order: 6, group: 'Message options',
+      description: 'A new notification with the same tag replaces the one shown, so repeats stack as one.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var push;
+    try {
+      push = require('@xeplr/push');
+    } catch (_) {
+      throw new Error("push-send: '@xeplr/push' is not installed. Run: npm install @xeplr/push — and set it up at boot with push.init({ knex }).");
+    }
+    if (!push.enabled || !push.enabled()) {
+      throw new Error('push-send: push is not set up on this server — the host must call push.init() with PUSH_VAPID_PUBLIC_KEY / PUSH_VAPID_PRIVATE_KEY / PUSH_VAPID_SUBJECT (npx xeplr-push keys).');
+    }
+    var target = { emails: asList(input.emails), userIds: asList(input.userIds) };
+    if (!target.emails.length && !target.userIds.length) throw new Error('push-send: say who gets it — emails or userIds.');
+    return push.send(target, { title: input.title, body: input.body, url: input.url, tag: input.tag });
+  }
+};

package/lib/drivers/db/duckdb.js

@@ -349,6 +349,33 @@ async function acquire(entry) {
   return new Promise(function(resolve) { entry.waiters.push(resolve); });
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// DuckDB runs in this process, so a stop is conn.interrupt() on the query's
+// own connection, and the time limit is a timer that does the same. A query
+// still waiting for a free connection is let go of before it ever runs.
+var stop = require('./stop');
+
+/** acquire(), unless the stop comes first; a connection that arrives too late goes straight back. */
+function acquireUnlessStopped(entry, signal) {
+  if (!signal) return acquire(entry);
+  stop.throwIfStopped(signal);
+  return new Promise(function(resolve, reject) {
+    var gaveUp = false;
+    function onAbort() { gaveUp = true; reject(stop.stoppedError(signal)); }
+    signal.addEventListener('abort', onAbort, { once: true });
+    acquire(entry).then(function(conn) {
+      signal.removeEventListener('abort', onAbort);
+      if (gaveUp) release(entry, conn);
+      else resolve(conn);
+    }, function(err) { signal.removeEventListener('abort', onAbort); reject(err); });
+  });
+}
+
+/** Watch one connection's query: interrupt it on a stop or past the limit. */
+function watchConn(conn, opts) {
+  return stop.watch(opts && opts.signal, opts && opts.timeoutMs, function() { conn.interrupt(); });
+}
+
 function release(entry, conn) {
   var waiter = entry.waiters.shift();
   if (waiter) waiter(conn);
@@ -421,10 +448,11 @@ function plainDeep(v) {
  * The result's OWN return type is what distinguishes the two cases, so that is
  * what this reads. CHANGED_ROWS is DML; QUERY_RESULT is a select.
  */
-async function query(pool, sql, params) {
+async function query(pool, sql, params, opts) {
   var entry = entryOf(pool);
   refuseIndex(entry, sql);
-  var conn = await acquire(entry);
+  var conn = await acquireUnlessStopped(entry, opts && opts.signal);
+  var w = watchConn(conn, opts);
   try {
     var api = require('@duckdb/node-api');
     var reader = await conn.runAndReadAll(sql, params && params.length ? params : undefined);
@@ -441,8 +469,10 @@ async function query(pool, sql, params) {
     });
     return { rows: rows, rowCount: rows.length, columns: columns };
   } catch (err) {
+    if (w.why()) throw w.why();
     throw explainLockError(err, entry.key, entry.access, 0);
   } finally {
+    w.done();
     release(entry, conn);
   }
 }
@@ -756,7 +786,8 @@ async function plainValuesPlan(conn, sql) {
  */
 async function* fetchStream(pool, opts) {
   var entry = entryOf(pool);
-  var conn = await acquire(entry);
+  var conn = await acquireUnlessStopped(entry, opts.signal);
+  var w = watchConn(conn, opts);
   try {
     var plan = await plainValuesPlan(conn, opts.sql);
     var result = await conn.stream(plan.sql, (opts.params && opts.params.length) ? opts.params : undefined);
@@ -764,6 +795,7 @@ async function* fetchStream(pool, opts) {
     var dates = plan.dateColumns;
     var jsons = plan.jsonColumns;
     while (true) {
+      if (w.why()) throw w.why();
       var chunk = await result.fetchChunk();
       if (!chunk || chunk.rowCount === 0) break;
       var rows = chunk.getRowObjects(names);
@@ -783,8 +815,10 @@ async function* fetchStream(pool, opts) {
       }
     }
   } catch (err) {
+    if (w.why()) throw w.why();
     throw explainLockError(err, entry.key, entry.access, 0);
   } finally {
+    w.done();
     release(entry, conn);
   }
 }

package/lib/drivers/db/mssql.js

@@ -96,17 +96,34 @@ async function close(pool) {
   if (pool) await pool.close();
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// A stop is request.cancel(): an ATTENTION sent on the query's own
+// connection, which SQL Server answers by abandoning the batch. SQL Server
+// has no per-statement time limit of its own, so the limit is a timer here
+// that cancels the same way.
+var stop = require('./stop');
+
 // Bind params as @p0..@pN and normalize `{ recordset, rowsAffected }` to
 // Postgres shape. NOTE: mssql infers the SQL type from each JS value; a null
 // with no sibling non-null value in the batch falls back to NVARCHAR, which is
 // fine for our INSERTs since the column type is already declared.
-async function query(pool, sql, params) {
+async function query(pool, sql, params, opts) {
+  opts = opts || {};
+  stop.throwIfStopped(opts.signal);
   var request = pool.request();
   params = params || [];
   for (var i = 0; i < params.length; i++) {
     request.input('p' + i, params[i]);
   }
-  var r = await request.query(sql);
+  var w = stop.watch(opts.signal, opts.timeoutMs, function() { request.cancel(); });
+  var r;
+  try {
+    r = await request.query(sql);
+  } catch (err) {
+    throw w.why() || err;
+  } finally {
+    w.done();
+  }
   var rows = r.recordset || [];
   var rowCount = Array.isArray(r.rowsAffected)
     ? r.rowsAffected.reduce(function(a, b) { return a + b; }, 0)
@@ -382,8 +399,9 @@ async function ensureUpsertIndex(pool, tableName, primaryKeys) {
 // with real backpressure: pause the request once `batchSize` rows are buffered,
 // resume after the consumer drains them.
 //
-//   opts: { sql, params?, batchSize? }  →  async iterable<row>
+//   opts: { sql, params?, batchSize?, signal?, timeoutMs? }  →  async iterable<row>
 async function* fetchStream(pool, opts) {
+  stop.throwIfStopped(opts.signal);
   var high = Math.max(1, parseInt(opts.batchSize || 1000, 10));
   var request = pool.request();
   var params = opts.params || [];
@@ -406,12 +424,21 @@ async function* fetchStream(pool, opts) {
   request.on('error', function(err) { error = err; signal(); });
   request.on('done',  function()    { done = true;  signal(); });
 
+  // A stop cancels the request and wakes the consumer, which may be waiting
+  // for a first row the server is still working out.
+  var w = stop.watch(opts.signal, opts.timeoutMs, function() {
+    try { request.cancel(); } catch (_) {}
+    error = error || w.why();
+    signal();
+  });
+
   // Fire the query — with stream=true this drives the events above. We don't
   // await the returned promise; the events are the source of truth.
   request.query(opts.sql).catch(function(err) { error = error || err; signal(); });
 
   try {
     while (true) {
+      if (w.why()) throw w.why();
       if (buffer.length) {
         var batch = buffer;
         buffer = [];
@@ -419,11 +446,12 @@ async function* fetchStream(pool, opts) {
         for (var j = 0; j < batch.length; j++) yield batch[j];
         continue;
       }
-      if (error) throw error;
+      if (error) throw w.why() || error;
       if (done) return;
       await new Promise(function(res) { wake = res; });
     }
   } finally {
+    w.done();
     // If the consumer breaks out early, stop the underlying request.
     if (!done && !error) { try { request.cancel(); } catch (_) {} }
   }

package/lib/drivers/db/mysql.js

@@ -106,13 +106,67 @@ async function close(pool) {
   if (pool) await pool.end();
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// A stop is KILL QUERY <the connection's thread id>, sent on a connection of
+// its own: the pool's may all be busy with the very queries being stopped.
+// The time limit is a timer here that kills the same way — MySQL's own
+// max_execution_time covers SELECTs only, and MariaDB spells it differently.
+var stop = require('./stop');
+
+/** Kill whatever thread `threadId` is running, from a connection of its own. */
+async function killQuery(pool, threadId) {
+  var mysql = require('mysql2/promise');
+  var c = pool.pool.config.connectionConfig;
+  var conn = await mysql.createConnection({ host: c.host, port: c.port, user: c.user, password: c.password, connectTimeout: 5000 });
+  try {
+    await conn.query('KILL QUERY ' + Number(threadId));
+  } finally {
+    await conn.end().catch(function() {});
+  }
+}
+
+/** Watch one checked-out connection's query; `killed` is the pending kill. */
+function watchConn(pool, conn, opts) {
+  var state = { killed: null };
+  state.w = stop.watch(opts.signal, opts.timeoutMs, function() {
+    state.killed = killQuery(pool, conn.connection.threadId).catch(function() { /* it finished first, or the server is gone */ });
+  });
+  return state;
+}
+
+/** Give the connection back — destroyed when a query on it was stopped. */
+async function giveBack(state, conn) {
+  state.w.done();
+  if (state.killed) await state.killed;
+  if (state.w.why()) conn.destroy();
+  else conn.release();
+}
+
 // Normalize mysql2's `[rows|ResultSetHeader, fields]` to Postgres shape.
 //
 // The second element is the field list, which mysql2 returns even for a
 // SELECT that matched nothing — so `columns` describes the result's shape
 // when there is not a single row to infer it from.
-async function query(pool, sql, params) {
-  var res = await pool.query(sql, params || []);
+async function query(pool, sql, params, opts) {
+  opts = opts || {};
+  stop.throwIfStopped(opts.signal);
+  var res;
+  if (opts.signal || stop.limitOf(opts.timeoutMs)) {
+    var conn = await pool.getConnection();
+    var state = watchConn(pool, conn, opts);
+    try {
+      res = await conn.query(sql, params || []);
+      // A killed statement can still come back normally (SLEEP() answers 1
+      // when killed): stopped is stopped, whatever it returned.
+      if (state.w.why()) throw state.w.why();
+    } catch (err) {
+      throw state.w.why() || err;
+    } finally {
+      await giveBack(state, conn);
+    }
+  } else {
+    res = await pool.query(sql, params || []);
+  }
   var out = res[0];
   var fields = res[1];
 
@@ -412,10 +466,12 @@ function upsertIndexName(tableName) {
 // `for await` over it applies backpressure (highWaterMark bounds the rows
 // buffered in the driver before it pauses reading from the socket).
 //
-//   opts: { sql, params?, batchSize? }  →  async iterable<row>
+//   opts: { sql, params?, batchSize?, signal?, timeoutMs? }  →  async iterable<row>
 async function* fetchStream(pool, opts) {
+  stop.throwIfStopped(opts.signal);
   var batchSize = Math.max(1, parseInt(opts.batchSize || 1000, 10));
   var conn = await pool.getConnection();
+  var state = watchConn(pool, conn, opts);
   try {
     // .stream() lives on the core (non-promise) connection under .connection.
     var core = conn.connection;
@@ -423,9 +479,15 @@ async function* fetchStream(pool, opts) {
       ? { sql: opts.sql, values: opts.params }
       : opts.sql;
     var stream = core.query(q).stream({ highWaterMark: batchSize });
-    for await (var row of stream) yield row;
+    for await (var row of stream) {
+      if (state.w.why()) throw state.w.why();
+      yield row;
+    }
+    if (state.w.why()) throw state.w.why();
+  } catch (err) {
+    throw state.w.why() || err;
   } finally {
-    conn.release();
+    await giveBack(state, conn);
   }
 }
 

package/lib/drivers/db/postgres.js

@@ -8,7 +8,7 @@
 //
 //   requires:                 ['pg']
 //   async connect(config)                       → pool
-//   async query(pool, sql, params?)             → { rows, rowCount, ... }
+//   async query(pool, sql, params?, { signal?, timeoutMs }?)  → { rows, rowCount, ... }
 //   async close(pool)                           → void
 //
 //   buildCreateTableSql(tableName, columns, primaryKeys?)  → string
@@ -82,6 +82,56 @@ async function close(pool) {
   if (pool) await pool.end();
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// A stop is pg_cancel_backend(<its backend's pid>), sent on a connection of
+// its own: the pool's may all be busy — quite possibly with the very queries
+// being stopped — and a cancel that waits for a free one never arrives. The
+// time limit is statement_timeout, so Postgres enforces it even if this
+// process dies; our own timer, a little later, is only the backstop.
+var stop = require('./stop');
+var QUERY_CANCELED = '57014';
+var BACKSTOP_MS = 2000;
+
+/** Cancel whatever `pid` is running, from a connection of its own. */
+async function cancelBackend(pool, pid) {
+  var pg = require('pg');
+  var o = pool.options || {};
+  var c = new pg.Client({ host: o.host, port: o.port, user: o.user, password: o.password, database: o.database, connectionTimeoutMillis: 5000 });
+  try {
+    await c.connect();
+    await c.query('SELECT pg_cancel_backend($1)', [pid]);
+  } finally {
+    await c.end().catch(function() {});
+  }
+}
+
+/**
+ * Watch one checked-out client's query for `opts` (signal, timeoutMs).
+ * `cancelled` is the pending cancel, awaited before the client goes back.
+ */
+function watchClient(pool, client, opts) {
+  var limit = stop.limitOf(opts.timeoutMs);
+  var state = { cancelled: null, limit: limit };
+  state.w = stop.watch(opts.signal, limit ? limit + BACKSTOP_MS : 0, function() {
+    state.cancelled = cancelBackend(pool, client.processID).catch(function() { /* it finished first, or the server is gone */ });
+  });
+  return state;
+}
+
+/** The error to reject with: ours when we stopped it, the time limit when Postgres did. */
+function stopReason(state, err) {
+  if (state.w.why()) return state.w.why();
+  if (err && err.code === QUERY_CANCELED && state.limit) return stop.timeoutError(state.limit);
+  return err;
+}
+
+/** Give the client back — destroyed when a query on it was stopped, so no half-cancelled state is reused. */
+async function giveBack(state, client) {
+  state.w.done();
+  if (state.cancelled) await state.cancelled;
+  client.release(state.w.why() ? true : undefined);
+}
+
 // `columns` is the query's OUTPUT COLUMNS, which the server describes whether
 // or not any row matched. Callers that need the shape of a result — a report
 // listing its columns, say — must not have to infer it from the first row,
@@ -90,16 +140,33 @@ async function close(pool) {
 // Attached to pg's own Result rather than wrapping it: callers already treat
 // this as the canonical shape the other drivers normalize TO, so replacing
 // the object risks dropping a property something else reads.
-async function query(pool, sql, params) {
+async function query(pool, sql, params, opts) {
+  opts = opts || {};
+  stop.throwIfStopped(opts.signal);
   var result;
-  if (pool.__xeplrReadOnly) {
+  var limit = stop.limitOf(opts.timeoutMs);
+  if (pool.__xeplrReadOnly || opts.signal || limit) {
+    var readOnly = Boolean(pool.__xeplrReadOnly);
     var client = await pool.connect();
+    var state = watchClient(pool, client, opts);
     try {
-      await client.query('BEGIN TRANSACTION READ ONLY');
-      result = await client.query({ text: sql, values: params || [], queryMode: 'extended' });
+      // Read-only: inside its own transaction, the limit with it (LOCAL).
+      // Otherwise the statement runs as it always did — no transaction added,
+      // which some statements refuse — and the limit is on the session until
+      // it is reset below.
+      if (readOnly) await client.query('BEGIN TRANSACTION READ ONLY');
+      if (limit) await client.query((readOnly ? 'SET LOCAL' : 'SET') + ' statement_timeout = ' + limit);
+      result = await client.query(readOnly ? { text: sql, values: params || [], queryMode: 'extended' } : sql, readOnly ? undefined : (params || []));
+    } catch (err) {
+      throw stopReason(state, err);
     } finally {
-      try { await client.query('ROLLBACK'); } catch (_) { /* the connection is released either way */ }
-      client.release();
+      if (!state.w.why()) {
+        try {
+          if (readOnly) await client.query('ROLLBACK');
+          else if (limit) await client.query('RESET statement_timeout');
+        } catch (_) { /* the connection is released either way */ }
+      }
+      await giveBack(state, client);
     }
   } else {
     result = await pool.query(sql, params || []);
@@ -342,14 +409,23 @@ async function listProcedures(pool, schema) {
 // rows at a time. The async generator naturally applies backpressure: the next
 // FETCH only fires when the consumer asks for more.
 //
-//   opts: { sql, params?, batchSize? }  →  async iterable<row>
+//   opts: { sql, params?, batchSize?, signal?, timeoutMs? }  →  async iterable<row>
+//
+// A GROUP BY or ORDER BY is worked out in full by the FIRST FETCH, which can
+// take minutes — so a stop must cancel that FETCH in Postgres, not wait for
+// it to come back. timeoutMs is per statement (each FETCH), as Postgres
+// counts it.
 async function* fetchStream(pool, opts) {
+  stop.throwIfStopped(opts.signal);
   var batchSize = Math.max(1, parseInt(opts.batchSize || 1000, 10));
+  var limit = stop.limitOf(opts.timeoutMs);
   var client = await pool.connect();
+  var state = watchClient(pool, client, opts);
   var declared = false;
   try {
     var readOnly = Boolean(pool.__xeplrReadOnly);
     await client.query(readOnly ? 'BEGIN TRANSACTION READ ONLY' : 'BEGIN');
+    if (limit) await client.query('SET LOCAL statement_timeout = ' + limit);
     // Extended protocol when read-only: one statement, so the caller's SQL
     // cannot close the cursor declaration and carry on with its own.
     await client.query(readOnly
@@ -357,14 +433,19 @@ async function* fetchStream(pool, opts) {
       : 'DECLARE __xeplr_fetch_cur NO SCROLL CURSOR FOR ' + opts.sql, readOnly ? undefined : (opts.params || []));
     declared = true;
     while (true) {
+      if (state.w.why()) throw state.w.why();
       var res = await client.query('FETCH FORWARD ' + batchSize + ' FROM __xeplr_fetch_cur');
       if (res.rows.length === 0) break;
       for (var i = 0; i < res.rows.length; i++) yield res.rows[i];
     }
+  } catch (err) {
+    throw stopReason(state, err);
   } finally {
-    try { if (declared) await client.query('CLOSE __xeplr_fetch_cur'); } catch (_) {}
-    try { await client.query(pool.__xeplrReadOnly ? 'ROLLBACK' : 'COMMIT'); } catch (_) {}
-    client.release();
+    if (!state.w.why()) {
+      try { if (declared) await client.query('CLOSE __xeplr_fetch_cur'); } catch (_) {}
+      try { await client.query(pool.__xeplrReadOnly ? 'ROLLBACK' : 'COMMIT'); } catch (_) {}
+    }
+    await giveBack(state, client);
   }
 }
 

package/lib/drivers/db/stop.js

@@ -0,0 +1,89 @@
+// STOPPING A QUERY — the part every driver shares.
+//
+// A query nobody is waiting for must not run (see CLAUDE.md, "No query runs
+// that nobody needs"). Every driver's query() and fetchStream() take
+//
+//   signal      an AbortSignal: when it fires, the query is CANCELLED IN THE
+//               DATABASE (each driver's own way), not just abandoned here —
+//               a GROUP BY the database is still working on would otherwise
+//               keep its CPU and its connection until it finished
+//   timeoutMs   a time limit; past it the query is cancelled the same way
+//
+// and reject with one of two errors a caller can tell apart:
+//
+//   code QUERY_STOPPED   the signal fired; the message is its reason's
+//   code QUERY_TIMEOUT   the time limit passed
+//
+// Neither is given: the query runs as it always did.
+
+/** The error a stopped query rejects with. */
+function stoppedError(signal) {
+  var reason = signal && signal.reason;
+  // abort() with no reason gives a generic AbortError: say it in our words.
+  var said = reason && reason.name !== 'AbortError' && reason.message;
+  var err = new Error(said || 'The query was stopped');
+  err.code = 'QUERY_STOPPED';
+  return err;
+}
+
+/** "45 seconds", "2 minutes" — how long a limit is, as a person says it. */
+function durationText(ms) {
+  var secs = Math.max(1, Math.round(ms / 1000));
+  if (secs < 60) return secs + ' second' + (secs === 1 ? '' : 's');
+  var mins = Math.round(secs / 60);
+  return mins + ' minute' + (mins === 1 ? '' : 's');
+}
+
+/** The error a query past its time limit rejects with. */
+function timeoutError(timeoutMs) {
+  var err = new Error('The database stopped this query after ' + durationText(timeoutMs) +
+    ', its time limit. Narrow it with a filter or a shorter date range, then run it again.');
+  err.code = 'QUERY_TIMEOUT';
+  return err;
+}
+
+/** A positive whole number of milliseconds, or 0 for no limit. */
+function limitOf(timeoutMs) {
+  var n = Math.floor(Number(timeoutMs));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Watch one query: call `cancel()` once — when `signal` fires or `timeoutMs`
+ * passes, whichever is first — and remember why. `why()` is the error to
+ * reject with after the database has given up the query (null: not stopped).
+ * `done()` stops watching; call it in a finally.
+ */
+function watch(signal, timeoutMs, cancel) {
+  var limit = limitOf(timeoutMs);
+  var reason = null;
+  var timer = null;
+  function fire(err) {
+    if (reason) return;
+    reason = err;
+    try { cancel(); } catch (_) { /* the driver's cancel reports its own failures */ }
+  }
+  function onAbort() { fire(stoppedError(signal)); }
+  if (signal) {
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+  if (limit && !reason) {
+    timer = setTimeout(function() { fire(timeoutError(limit)); }, limit);
+    if (timer.unref) timer.unref();
+  }
+  return {
+    why: function() { return reason; },
+    done: function() {
+      if (timer) clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+    }
+  };
+}
+
+/** Throw now when the signal has already fired: never start a query nobody wants. */
+function throwIfStopped(signal) {
+  if (signal && signal.aborted) throw stoppedError(signal);
+}
+
+module.exports = { watch: watch, throwIfStopped: throwIfStopped, stoppedError: stoppedError, timeoutError: timeoutError, limitOf: limitOf, durationText: durationText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {
@@ -42,6 +42,7 @@
     "@duckdb/node-api": "1.5.5-r.3",
     "@xeplr/db": "^1.1.0",
     "@xeplr/email": "^1.0.0",
+    "@xeplr/push": "^1.0.0",
     "@xeplr/utils": "^1.0.0",
     "csv-parse": "^7.0.2",
     "dejavu-fonts-ttf": "^2.37.3",
@@ -61,61 +62,64 @@
     "unzipper": "^0.12.5"
   },
   "peerDependenciesMeta": {
-    "@xeplr/utils": {
-      "optional": true
-    },
     "@duckdb/node-api": {
       "optional": true
     },
-    "knex": {
+    "@xeplr/email": {
       "optional": true
     },
-    "pg": {
+    "@xeplr/push": {
       "optional": true
     },
-    "mysql2": {
+    "@xeplr/utils": {
       "optional": true
     },
-    "mssql": {
+    "csv-parse": {
       "optional": true
     },
-    "mongodb": {
+    "dejavu-fonts-ttf": {
       "optional": true
     },
     "exceljs": {
       "optional": true
     },
-    "unzipper": {
+    "fflate": {
       "optional": true
     },
-    "saxes": {
+    "imapflow": {
       "optional": true
     },
-    "csv-parse": {
+    "knex": {
       "optional": true
     },
-    "imapflow": {
+    "mailparser": {
       "optional": true
     },
-    "mailparser": {
+    "mongodb": {
+      "optional": true
+    },
+    "mssql": {
+      "optional": true
+    },
+    "mysql2": {
       "optional": true
     },
     "nodemailer": {
       "optional": true
     },
-    "ssh2-sftp-client": {
+    "pdfkit": {
       "optional": true
     },
-    "@xeplr/email": {
+    "pg": {
       "optional": true
     },
-    "fflate": {
+    "saxes": {
       "optional": true
     },
-    "pdfkit": {
+    "ssh2-sftp-client": {
       "optional": true
     },
-    "dejavu-fonts-ttf": {
+    "unzipper": {
       "optional": true
     }
   },