node-firebird 2.5.0 → 2.6.0

package/README.md

@@ -14,7 +14,7 @@
 - [Connection types](#connection-types) — connection options, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
-- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
+- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
 - [Contributing](#contributing) · [Contributors](#contributors)
@@ -1151,6 +1151,47 @@ Firebird.attach({
 });
 ```
 
+### Query Cancellation with AbortSignal (Firebird 2.5+)
+
+Any query can be cancelled while it is executing on the server. Pass an
+`AbortSignal` in the query options — when it fires, the driver sends an
+out-of-band `op_cancel` packet and the running statement fails with
+`err.gdscode === GDSCode.CANCELLED`. The connection itself stays healthy and
+can run further queries immediately.
+
+```js
+const { GDSCode } = require('node-firebird/lib/gdscodes');
+
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // or req.on('close', ...) in Express
+
+try {
+    const rows = await db.queryAsync('SELECT /* expensive */ ...', [], { signal: controller.signal });
+} catch (err) {
+    if (err.gdscode === GDSCode.CANCELLED) {
+        // cancelled server-side; the connection remains usable
+    } else if (err.name === 'AbortError') {
+        // the signal was already aborted — the query was never sent
+    } else {
+        throw err;
+    }
+}
+```
+
+The option works with the callback API as well (`db.query(sql, params, cb,
+{ signal })`) and on transaction-level queries. A running operation can also
+be cancelled manually from anywhere with `db.cancel()` / `await
+db.cancelAsync()`.
+
+Notes:
+
+- Cancellation is **per attachment** (that is how the Firebird protocol
+  defines it): it cancels whatever is currently executing on that
+  connection. With a pool this is naturally scoped to the request holding
+  the connection.
+- A signal that is already aborted rejects immediately with an `AbortError`
+  without contacting the server; cancelling an idle connection is harmless.
+
 ### Statement Timeouts (Firebird 4.0+)
 Setting a statement timeout allows the client to automatically abort queries that take too long on the server.
 ```js

package/lib/types.d.ts

@@ -67,6 +67,15 @@ export type TransactionOptions = {
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
+    /**
+     * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
+     * If the signal is already aborted the query is not sent at all and the
+     * callback/promise fails with an `AbortError`. If it fires mid-flight an
+     * out-of-band op_cancel is sent and the query fails with
+     * `err.gdscode === GDSCode.CANCELLED`. Cancellation is per-attachment:
+     * it cancels whatever is currently executing on the connection.
+     */
+    signal?: AbortSignal;
 };
 export interface Database {
     detach(callback?: SimpleCallback): Database;
@@ -94,6 +103,14 @@ export interface Database {
     attachEventAsync(): Promise<any>;
     /** Starts a transaction, commits when `work` resolves, rolls back when it rejects. */
     withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
+    /**
+     * Cancel the operation currently executing on this connection
+     * (Firebird 2.5+ / protocol 12+). The cancelled operation fails through
+     * its own callback/promise with `err.gdscode === GDSCode.CANCELLED`.
+     */
+    cancel(callback?: SimpleCallback): Database;
+    cancel(kind: number, callback?: SimpleCallback): Database;
+    cancelAsync(kind?: number): Promise<void>;
 }
 export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;

package/lib/wire/connection.d.ts

@@ -57,6 +57,13 @@ declare class Connection {
     sendOpContAuth(authData: any, authDataEnc: any, pluginName: any): void;
     sendOpCrypt(encryptPlugin: any): void;
     sendOpCryptKeyCallback(pluginData: any): void;
+    /**
+     * Send an out-of-band op_cancel packet (protocol 12+ / Firebird 2.5+).
+     * The server reads it asynchronously while an operation is executing and
+     * makes that operation fail with isc_cancelled (GDSCode.CANCELLED); the
+     * op_cancel packet itself has no response, so nothing is queued here.
+     */
+    cancelOperation(kind: any, callback: any): this;
     _queueEvent(callback: any, defer?: boolean): void;
     connect(options: any, callback: any): void;
     attach(options: any, callback?: any, db?: any): void;

package/lib/wire/connection.js

@@ -294,6 +294,32 @@ class Connection {
         msg.addBlr(pluginData); // Send the callback response data as a buffer
         this._socket.write(msg.getData());
     }
+    /**
+     * Send an out-of-band op_cancel packet (protocol 12+ / Firebird 2.5+).
+     * The server reads it asynchronously while an operation is executing and
+     * makes that operation fail with isc_cancelled (GDSCode.CANCELLED); the
+     * op_cancel packet itself has no response, so nothing is queued here.
+     */
+    cancelOperation(kind, callback) {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        kind = kind || const_1.default.fb_cancel_raise;
+        if (this._isClosed)
+            return this.throwClosed(callback);
+        if (!this.accept || this.accept.protocolVersion < const_1.default.PROTOCOL_VERSION12) {
+            (0, callback_1.doError)(new Error('Query cancellation requires protocol 12+ (Firebird 2.5 or newer)'), callback);
+            return;
+        }
+        var msg = this._msg;
+        msg.pos = 0;
+        msg.addInt(const_1.default.op_cancel);
+        msg.addInt(kind);
+        this._socket.write(msg.getData());
+        if (callback)
+            callback();
+    }
     _queueEvent(callback, defer = false) {
         var self = this;
         if (self._isClosed) {

package/lib/wire/const.d.ts

@@ -104,6 +104,10 @@ declare const Const: Readonly<{
     DSQL_close: number;
     DSQL_drop: number;
     DSQL_unprepare: number;
+    fb_cancel_disable: number;
+    fb_cancel_enable: number;
+    fb_cancel_raise: number;
+    fb_cancel_abort: number;
     fetch_next: number;
     fetch_prior: number;
     fetch_first: number;

package/lib/wire/const.js

@@ -117,6 +117,13 @@ const dsql = {
     DSQL_drop: 2,
     DSQL_unprepare: 4, // >: 2.5
 };
+// fb_cancel_operation kinds sent with op_cancel (protocol 12+ / Firebird 2.5+)
+const cancelKind = {
+    fb_cancel_disable: 1, // disable execution of fb_cancel_raise requests
+    fb_cancel_enable: 2, // re-enable delivery of cancel requests
+    fb_cancel_raise: 3, // cancel the operation currently executing on the attachment
+    fb_cancel_abort: 4, // forcibly abort the attachment's current activity
+};
 const fetchOp = {
     fetch_next: 0,
     fetch_prior: 1,
@@ -794,6 +801,7 @@ const Const = Object.freeze({
     ...blr,
     ...blobType,
     ...buffer,
+    ...cancelKind,
     ...cnct,
     ...common,
     ...connect,

package/lib/wire/database.d.ts

@@ -12,6 +12,14 @@ declare class Database extends Events.EventEmitter {
     sequentially(query: string, params?: any, on?: any, callback?: any, options?: any): this;
     query(query: string, params?: any, callback?: any, options?: any): this;
     drop(callback?: (err?: any) => void): void;
+    /**
+     * Cancel the operation currently executing on this connection by sending
+     * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
+     * operation fails through its own callback with err.gdscode ===
+     * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
+     * per-attachment, not per-statement.
+     */
+    cancel(kind?: number | ((err?: any) => void), callback?: (err?: any) => void): this;
     attachEvent(callback: (err: any, evt?: any) => void): this;
     /**
      * Create a physical tablespace.
@@ -62,6 +70,7 @@ declare class Database extends Events.EventEmitter {
     detachAsync(force?: boolean): Promise<void>;
     dropAsync(): Promise<void>;
     attachEventAsync(): Promise<any>;
+    cancelAsync(kind?: number): Promise<void>;
     /**
      * Run `work` inside a transaction: commits when the returned promise
      * resolves, rolls back when it rejects (the original error is rethrown,

package/lib/wire/database.js

@@ -273,6 +273,21 @@ class Database extends events_1.default.EventEmitter {
     drop(callback) {
         return this.connection.dropDatabase(callback);
     }
+    /**
+     * Cancel the operation currently executing on this connection by sending
+     * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
+     * operation fails through its own callback with err.gdscode ===
+     * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
+     * per-attachment, not per-statement.
+     */
+    cancel(kind, callback) {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        this.connection.cancelOperation(kind, callback);
+        return this;
+    }
     attachEvent(callback) {
         var self = this;
         const eventid = self.eventid++;
@@ -423,6 +438,10 @@ class Database extends events_1.default.EventEmitter {
         var self = this;
         return (0, callback_1.fromCallback)(function (cb) { self.attachEvent(cb); });
     }
+    cancelAsync(kind) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.cancel(kind, cb); });
+    }
     /**
      * Run `work` inside a transaction: commits when the returned promise
      * resolves, rolls back when it rejects (the original error is rethrown,

package/lib/wire/transaction.d.ts

@@ -1,8 +1,3 @@
-/***************************************
- *
- *   Transaction
- *
- ***************************************/
 declare class Transaction {
     connection: any;
     db: any;

package/lib/wire/transaction.js

@@ -10,6 +10,36 @@ const const_1 = __importDefault(require("./const"));
  *   Transaction
  *
  ***************************************/
+/** The error delivered when options.signal was already aborted on entry. */
+function abortError(signal) {
+    if (signal && signal.reason instanceof Error)
+        return signal.reason;
+    var err = new Error('The operation was aborted');
+    err.name = 'AbortError';
+    err.code = 'ABORT_ERR';
+    return err;
+}
+/**
+ * Wire an AbortSignal to a running statement: on abort, send an out-of-band
+ * op_cancel so the server fails the executing operation with isc_cancelled
+ * (surfaced through the statement's own callback as err.gdscode ===
+ * GDSCode.CANCELLED). Returns the wrapped callback that detaches the
+ * listener once the operation settles.
+ */
+function hookAbortSignal(connection, signal, callback) {
+    var settled = false;
+    var onAbort = function () {
+        if (!settled)
+            connection.cancelOperation(const_1.default.fb_cancel_raise);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    return function (err, result, meta, isSelect) {
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        if (callback)
+            callback(err, result, meta, isSelect);
+    };
+}
 class Transaction {
     constructor(connection) {
         this.connection = connection;
@@ -32,6 +62,14 @@ class Transaction {
             callback = params;
             params = undefined;
         }
+        var signal = options && options.signal;
+        if (signal) {
+            if (signal.aborted) {
+                (0, callback_1.doError)(abortError(signal), callback);
+                return;
+            }
+            callback = hookAbortSignal(this.connection, signal, callback);
+        }
         var self = this;
         this.newStatement(query, function (err, statement) {
             if (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.5.0",
+    "version": "2.6.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/types.ts

@@ -78,6 +78,15 @@ export type TransactionOptions = {
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
+    /**
+     * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
+     * If the signal is already aborted the query is not sent at all and the
+     * callback/promise fails with an `AbortError`. If it fires mid-flight an
+     * out-of-band op_cancel is sent and the query fails with
+     * `err.gdscode === GDSCode.CANCELLED`. Cancellation is per-attachment:
+     * it cancels whatever is currently executing on the connection.
+     */
+    signal?: AbortSignal;
 }
 
 export interface Database {
@@ -109,6 +118,14 @@ export interface Database {
     attachEventAsync(): Promise<any>;
     /** Starts a transaction, commits when `work` resolves, rolls back when it rejects. */
     withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
+    /**
+     * Cancel the operation currently executing on this connection
+     * (Firebird 2.5+ / protocol 12+). The cancelled operation fails through
+     * its own callback/promise with `err.gdscode === GDSCode.CANCELLED`.
+     */
+    cancel(callback?: SimpleCallback): Database;
+    cancel(kind: number, callback?: SimpleCallback): Database;
+    cancelAsync(kind?: number): Promise<void>;
 }
 
 export interface Transaction {

package/src/wire/connection.ts

@@ -369,6 +369,38 @@ class Connection {
     }
 
 
+    /**
+     * Send an out-of-band op_cancel packet (protocol 12+ / Firebird 2.5+).
+     * The server reads it asynchronously while an operation is executing and
+     * makes that operation fail with isc_cancelled (GDSCode.CANCELLED); the
+     * op_cancel packet itself has no response, so nothing is queued here.
+     */
+    cancelOperation(kind, callback) {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        kind = kind || Const.fb_cancel_raise;
+
+        if (this._isClosed)
+            return this.throwClosed(callback);
+
+        if (!this.accept || this.accept.protocolVersion < Const.PROTOCOL_VERSION12) {
+            doError(new Error('Query cancellation requires protocol 12+ (Firebird 2.5 or newer)'), callback);
+            return;
+        }
+
+        var msg = this._msg;
+        msg.pos = 0;
+        msg.addInt(Const.op_cancel);
+        msg.addInt(kind);
+        this._socket.write(msg.getData());
+
+        if (callback)
+            callback();
+    }
+
+
     _queueEvent(callback, defer = false) {
         var self = this;
     

package/src/wire/const.ts

@@ -132,6 +132,14 @@ const dsql = {
     DSQL_unprepare : 4, // >: 2.5
 };
 
+// fb_cancel_operation kinds sent with op_cancel (protocol 12+ / Firebird 2.5+)
+const cancelKind = {
+    fb_cancel_disable : 1, // disable execution of fb_cancel_raise requests
+    fb_cancel_enable  : 2, // re-enable delivery of cancel requests
+    fb_cancel_raise   : 3, // cancel the operation currently executing on the attachment
+    fb_cancel_abort   : 4, // forcibly abort the attachment's current activity
+};
+
 const fetchOp = {
     fetch_next                : 0,
     fetch_prior               : 1,
@@ -859,6 +867,7 @@ const Const = Object.freeze({
     ...blr,
     ...blobType,
     ...buffer,
+    ...cancelKind,
     ...cnct,
     ...common,
     ...connect,

package/src/wire/database.ts

@@ -322,6 +322,22 @@ class Database extends Events.EventEmitter {
         return this.connection.dropDatabase(callback);
     }
 
+    /**
+     * Cancel the operation currently executing on this connection by sending
+     * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
+     * operation fails through its own callback with err.gdscode ===
+     * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
+     * per-attachment, not per-statement.
+     */
+    cancel(kind?: number | ((err?: any) => void), callback?: (err?: any) => void): this {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        this.connection.cancelOperation(kind, callback);
+        return this;
+    }
+
     attachEvent(callback: (err: any, evt?: any) => void): this {
         var self = this;
         const eventid = self.eventid++;
@@ -496,6 +512,11 @@ class Database extends Events.EventEmitter {
         return fromCallback(function(cb) { self.attachEvent(cb); });
     }
 
+    cancelAsync(kind?: number): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.cancel(kind, cb); });
+    }
+
     /**
      * Run `work` inside a transaction: commits when the returned promise
      * resolves, rolls back when it rejects (the original error is rethrown,

package/src/wire/transaction.ts

@@ -8,6 +8,38 @@ import Const from './const';
  *
  ***************************************/
 
+/** The error delivered when options.signal was already aborted on entry. */
+function abortError(signal: any): Error {
+    if (signal && signal.reason instanceof Error)
+        return signal.reason;
+    var err: any = new Error('The operation was aborted');
+    err.name = 'AbortError';
+    err.code = 'ABORT_ERR';
+    return err;
+}
+
+/**
+ * Wire an AbortSignal to a running statement: on abort, send an out-of-band
+ * op_cancel so the server fails the executing operation with isc_cancelled
+ * (surfaced through the statement's own callback as err.gdscode ===
+ * GDSCode.CANCELLED). Returns the wrapped callback that detaches the
+ * listener once the operation settles.
+ */
+function hookAbortSignal(connection: any, signal: any, callback: any): any {
+    var settled = false;
+    var onAbort = function() {
+        if (!settled)
+            connection.cancelOperation(Const.fb_cancel_raise);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    return function(err?: any, result?: any, meta?: any, isSelect?: boolean) {
+        settled = true;
+        signal.removeEventListener('abort', onAbort);
+        if (callback)
+            callback(err, result, meta, isSelect);
+    };
+}
+
 class Transaction {
     connection: any;
     db: any;
@@ -38,6 +70,15 @@ class Transaction {
             params = undefined;
         }
 
+        var signal = options && options.signal;
+        if (signal) {
+            if (signal.aborted) {
+                doError(abortError(signal), callback);
+                return;
+            }
+            callback = hookAbortSignal(this.connection, signal, callback);
+        }
+
         var self = this;
         this.newStatement(query, function(err: any, statement: any) {