node-firebird 2.0.2 → 2.3.0

package/lib/wire/connection.js

@@ -1,7 +1,6 @@
 const Events = require('events');
 const os = require('os');
 const path = require('path');
-const BigInt = require('big-integer');
 
 const {XdrWriter, BlrWriter, XdrReader, BitSet, BlrReader} = require('./serialize');
 const {doCallback, doError} = require('../callback');
@@ -140,6 +139,7 @@ class Connection {
     
         self._socket.on('data', function (data) {
             var xdr;
+            var hadSavedBuffer = Boolean(self._xdr);
     
             if (!self._xdr) {
                 xdr = new XdrReader(data);
@@ -147,6 +147,11 @@ class Connection {
                 xdr = new XdrReader(Buffer.concat([self._xdr.buffer, data], self._xdr.buffer.length + data.length));
                 delete (self._xdr);
             }
+
+            if (process.env.FIREBIRD_DEBUG) {
+                console.log('[fb-debug] data event: bytes=%d queue=%d pending=%d xdr.pos=%d savedBuf=%s',
+                    xdr.buffer.length, self._queue.length, self._pending.length, xdr.pos, hadSavedBuffer);
+            }
     
             while (xdr.pos < xdr.buffer.length) {
                 var cb = self._queue[0], pos = xdr.pos;
@@ -154,12 +159,30 @@ class Connection {
                 decodeResponse(xdr, cb, self, self._lowercase_keys, function (err, obj) {
     
                     if (err) {
-                        xdr.buffer = xdr.buffer.slice(pos);
-                        xdr.pos = 0;
-                        self._xdr = xdr;
-    
-                        if (self.accept.protocolMinimumType === Const.ptype_lazy_send && self._queue.length > 0) {
-                            self._queue[0].lazy_count = 2;
+                        if (err instanceof RangeError) {
+                            // Genuinely incomplete packet – buffer the remaining bytes
+                            // and wait for the next 'data' event to reassemble.
+                            xdr.buffer = xdr.buffer.slice(pos);
+                            xdr.pos = 0;
+                            self._xdr = xdr;
+
+                            if (process.env.FIREBIRD_DEBUG) {
+                                console.log('[fb-debug] incomplete packet: saved %d bytes at pos=%d queue=%d',
+                                    xdr.buffer.length, pos, self._queue.length);
+                            }
+
+                            if (self.accept && self.accept.protocolMinimumType === Const.ptype_lazy_send && self._queue.length > 0) {
+                                self._queue[0].lazy_count = 2;
+                            }
+                        } else {
+                            // Any other error (truly unknown opcode not handled above).
+                            // Save the buffer so it can be retried, but log a warning.
+                            if (process.env.FIREBIRD_DEBUG) {
+                                console.warn(`[fb-debug] unhandled protocol error: ${err.message} pos=${pos} bytes=${xdr.buffer.length} queue=${self._queue.length}`);
+                            }
+                            xdr.buffer = xdr.buffer.slice(pos);
+                            xdr.pos = 0;
+                            self._xdr = xdr;
                         }
                         return;
                     }
@@ -168,10 +191,27 @@ class Connection {
                     if (xdr.r) {
                         delete (xdr.r);
                     }
+
+                    // op_event / op_response_piggyback received on the main connection:
+                    // data has been consumed by decodeResponse but it does not belong to
+                    // any queued request – do NOT shift the queue or invoke any pending
+                    // callback.
+                    if (obj && obj._isOpEvent) {
+                        if (process.env.FIREBIRD_DEBUG) {
+                            console.log('[fb-debug] async opcode consumed (ignored): queue=%d xdr.pos=%d remaining=%d',
+                                self._queue.length, xdr.pos, xdr.buffer.length - xdr.pos);
+                        }
+                        return;
+                    }
     
                     self._queue.shift();
                     self._pending.shift();
     
+                    if (process.env.FIREBIRD_DEBUG) {
+                        console.log('[fb-debug] response dispatched: queue remaining=%d pending remaining=%d xdr.pos=%d',
+                            self._queue.length, self._pending.length, xdr.pos);
+                    }
+
                     if (obj && obj.status) {
                         obj.message = lookupMessages(obj.status);
                         doCallback(obj, cb);
@@ -272,6 +312,7 @@ class Connection {
         var blr = this._blr;
     
         this._pending.push('connect');
+        this._authStartTime = Date.now();
     
         msg.pos = 0;
         blr.pos = 0;
@@ -282,7 +323,11 @@ class Connection {
     
         var specificData = '';
         if (Const.AUTH_PLUGIN_SRP_LIST.indexOf(pluginName) > -1) {
+            const _t0 = Date.now();
             this.clientKeys = srp.clientSeed();
+            if (process.env.FIREBIRD_DEBUG) {
+                console.log('[fb-debug] srp.clientSeed: %dms', Date.now() - _t0);
+            }
             specificData = this.clientKeys.public.toString(16);
             blr.addMultiblockPart(Const.CNCT_specific_data, specificData, Const.DEFAULT_ENCODING);
         } else if (pluginName === Const.AUTH_PLUGIN_LEGACY) {
@@ -335,7 +380,7 @@ class Connection {
             // Wire encryption: send op_crypt if SRP session key is available
             if (ret.sessionKey && ret.protocolVersion >= Const.PROTOCOL_VERSION13 &&
                 options.wireCrypt !== Const.WIRE_CRYPT_DISABLE) {
-                var keyBuf = Buffer.from(srp.hexPad(ret.sessionKey.toString(16)), 'hex');
+                var keyBuf = Buffer.from(ret.sessionKey.toString(16).padStart(40, '0'), 'hex');
                 self.sendOpCrypt('Arc4');
                 self._socket.enableEncryption(keyBuf);
                 self._pending.push('crypt');
@@ -354,6 +399,9 @@ class Connection {
                 callback(undefined, ret);
         }
     
+        if (process.env.FIREBIRD_DEBUG) {
+            console.log('[fb-debug] auth: op_connect sent plugin=%s t=%dms', pluginName, Date.now() - this._authStartTime);
+        }
         this._queueEvent(cb);
     }
 
@@ -408,6 +456,10 @@ class Connection {
         if (this.accept.authData) {
             blr.addString(Const.isc_dpb_specific_auth_data, this.accept.authData, Const.DEFAULT_ENCODING);
         }
+
+        if (options.sessionTimeZone) {
+            blr.addString(Const.isc_dpb_session_time_zone, options.sessionTimeZone, Const.DEFAULT_ENCODING);
+        }
     
         msg.addInt(Const.op_attach);
         msg.addInt(0);  // Database Object ID
@@ -423,6 +475,8 @@ class Connection {
             self.dbhandle = ret.handle;
             if (callback)
                 callback(undefined, ret);
+            if (!db)
+                ret.emit('attach', ret);
         }
     
         // For reconnect
@@ -508,6 +562,10 @@ class Connection {
         if (this.accept.authData) {
             blr.addString(Const.isc_dpb_specific_auth_data, this.accept.authData, Const.DEFAULT_ENCODING);
         }
+
+        if (options.sessionTimeZone) {
+            blr.addString(Const.isc_dpb_session_time_zone, options.sessionTimeZone, Const.DEFAULT_ENCODING);
+        }
     
         blr.addNumeric(Const.isc_dpb_sql_dialect, 3);
         blr.addNumeric(Const.isc_dpb_force_write, 1);
@@ -527,14 +585,12 @@ class Connection {
     
             if (ret)
                 self.dbhandle = ret.handle;
-    
-            setImmediate(function() {
-                if (self.db)
-                    self.db.emit('attach', ret);
-            });
-    
+
             if (callback)
                 callback(err, ret);
+
+            if (!err && ret)
+                ret.emit('attach', ret);
         }
     
         cb.response = new Database(this);
@@ -910,17 +966,10 @@ class Connection {
         }
     
         function PrepareParams(params, input, callback) {
-    
+
             var value, meta;
             var ret = new Array(params.length);
-            var wait = params.length;
-    
-            function done() {
-                wait--;
-                if (wait === 0)
-                    callback(ret);
-            }
-    
+
             function putBlobData(index, value, callback) {
     
                 self.createBlob2(transaction, function(err, blob) {
@@ -943,41 +992,41 @@ class Connection {
                             self.batchSegments(blob, b, next);
                         }, function() {
                             ret[index] = new Xsql.SQLParamQuad(blob.oid);
-                            self.closeBlob(blob, callback);
+                            self.closeBlob(blob, callback, false);
                         });
                         return;
                     }
-    
+
                     var isReading = false;
                     var isEnd = false;
-    
+
                     value.on('data', function(chunk) {
                         // Optimization: If chunk is smaller than transfer size, send directly
                         if (chunk.length <= chunkSize) {
                             self.batchSegments(blob, chunk, function () {
                                 if (isEnd && !isReading) {
                                     ret[index] = new Xsql.SQLParamQuad(blob.oid);
-                                    self.closeBlob(blob, callback);
+                                    self.closeBlob(blob, callback, false);
                                 }
                             });
                             return;
                         }
-    
+
                         value.pause();
                         isReading = true;
                         bufferReader(chunk, chunkSize, function (b, next) {
                             self.batchSegments(blob, b, next);
                         }, function() {
                             isReading = false;
-    
+
                             if (isEnd) {
                                 ret[index] = new Xsql.SQLParamQuad(blob.oid);
-                                self.closeBlob(blob, callback);
+                                self.closeBlob(blob, callback, false);
                             } else
                                 value.resume();
                         });
                     });
-    
+
                     value.on('end', function() {
                         isEnd = true;
                         if (isReading)
@@ -986,16 +1035,21 @@ class Connection {
                         // If we are reading, the callback in batchSegments/bufferReader will handle closure
                         if (!isReading) {
                             ret[index] = new Xsql.SQLParamQuad(blob.oid);
-                            self.closeBlob(blob, callback);
+                            self.closeBlob(blob, callback, false);
                         }
                     });
                 });
             }
     
-            for (var i = 0, length = params.length; i < length; i++) {
+            function step(i) {
+                if (i === params.length) {
+                    callback(ret);
+                    return;
+                }
+
                 value = params[i];
                 meta = input[i];
-    
+
                 if (value === null || value === undefined) {
                     switch (meta.type) {
                         case Const.SQL_VARYING:
@@ -1011,6 +1065,10 @@ class Connection {
                         case Const.SQL_TYPE_DATE:
                         case Const.SQL_TYPE_TIME:
                         case Const.SQL_TIMESTAMP:
+                        case Const.SQL_TIME_TZ:
+                        case Const.SQL_TIME_TZ_EX:
+                        case Const.SQL_TIMESTAMP_TZ:
+                        case Const.SQL_TIMESTAMP_TZ_EX:
                             ret[i] = new Xsql.SQLParamDate(null);
                             break;
                         case Const.SQL_BLOB:
@@ -1027,27 +1085,30 @@ class Connection {
                         default:
                             ret[i] = null;
                     }
-                    done();
+                    step(i + 1);
                 } else {
                     switch (meta.type) {
                         case Const.SQL_BLOB:
-                            putBlobData(i, value, done);
+                            putBlobData(i, value, function() { step(i + 1); });
                             break;
-    
+
                         case Const.SQL_TIMESTAMP:
                         case Const.SQL_TYPE_DATE:
                         case Const.SQL_TYPE_TIME:
-    
+                        case Const.SQL_TIME_TZ:
+                        case Const.SQL_TIME_TZ_EX:
+                        case Const.SQL_TIMESTAMP_TZ:
+                        case Const.SQL_TIMESTAMP_TZ_EX:
                             if (value instanceof Date)
                                 ret[i] = new Xsql.SQLParamDate(value);
                             else if (typeof(value) === 'string')
                                 ret[i] = new Xsql.SQLParamDate(parseDate(value));
                             else
                                 ret[i] = new Xsql.SQLParamDate(new Date(value));
-    
-                            done();
+
+                            step(i + 1);
                             break;
-    
+
                         default:
                             switch (typeof value) {
                                 case 'bigint':
@@ -1073,10 +1134,12 @@ class Connection {
                                     ret[i] = new Xsql.SQLParamString(value.toString());
                                     break;
                             }
-                            done();
+                            step(i + 1);
                     }
                 }
             }
+
+            step(0);
         }
     
         var input = statement.input;
@@ -1173,6 +1236,11 @@ class Connection {
             }
             msg.addInt(0); // out_message_number = out_message_type
         }
+
+        if (this.accept.protocolVersion >= Const.PROTOCOL_VERSION16) {
+            // TODO impl statement timout
+            msg.addInt(statement.options?.timeout || 0); // p_sqldata_timeout
+        }
     
         callback.statement = statement;
         this._queueEvent(callback);
@@ -1208,7 +1276,7 @@ class Connection {
 
     fetchAll(statement, transaction, callback) {
         const self = this;
-        const custom = statement.custom || {};
+        const custom = statement.options || {};
         const asStream = custom.asStream && custom.on;
         const data = asStream ? null : [];
         let streamIndex = 0;
@@ -1272,12 +1340,12 @@ class Connection {
     }
 
 
-    closeBlob(blob, callback) {
+    closeBlob(blob, callback, defer = true) {
         var msg = this._msg;
         msg.pos = 0;
         msg.addInt(Const.op_close_blob);
         msg.addInt(blob.handle);
-        this._queueEvent(callback, true);
+        this._queueEvent(callback, defer);
     }
 
 
@@ -1449,9 +1517,16 @@ class Connection {
         msg.addInt(1); // async
         msg.addInt(self.dbhandle);
         msg.addInt(0);
+        if (process.env.FIREBIRD_DEBUG) {
+            console.log('[fb-debug] auxConnection: sending op_connect_request(53) dbhandle=%d queue_before=%d xdr_saved=%s',
+                self.dbhandle, self._queue.length, Boolean(self._xdr));
+        }
         function cb(err, ret) {
     
             if (err) {
+                if (process.env.FIREBIRD_DEBUG) {
+                    console.log('[fb-debug] auxConnection: op_connect_request error: %s queue=%d', err.message, self._queue.length);
+                }
                 doError(err, callback);
                 return;
             }
@@ -1461,6 +1536,11 @@ class Connection {
                 port: ret.buffer.readUInt16BE(2),
                 host: ret.buffer.readUInt8(4) + '.' + ret.buffer.readUInt8(5) + '.' + ret.buffer.readUInt8(6) + '.' + ret.buffer.readUInt8(7)
             }
+
+            if (process.env.FIREBIRD_DEBUG) {
+                console.log('[fb-debug] auxConnection: op_response ok → aux family=%d port=%d host=%s queue=%d',
+                    socket_info.family, socket_info.port, socket_info.host, self._queue.length);
+            }
     
             callback(undefined, socket_info);
         }
@@ -1470,7 +1550,6 @@ class Connection {
 
     queEvents(events, eventid, callback) {
         var self = this;
-        console.log('[Connection] queEvents called, eventid:', eventid, 'events:', Object.keys(events), 'isClosed:', this._isClosed);
         if (this._isClosed)
             return this.throwClosed(callback);
         var msg = this._msg;
@@ -1492,9 +1571,7 @@ class Connection {
         msg.addInt(0);   // args
         msg.addInt(eventid);
         
-        console.log('[Connection] queEvents: Message prepared, queuing event');
         function cb(err, ret) {
-            console.log('[Connection] queEvents callback invoked, err:', err, 'ret:', ret);
             if (err) {
                 doError(err, callback);
                 return;
@@ -1504,13 +1581,11 @@ class Connection {
         }
         
         this._queueEvent(cb);
-        console.log('[Connection] queEvents: Event queued');
     }
 
 
     closeEvents(eventid, callback) {
         var self = this;
-        console.log('[Connection] closeEvents called, eventid:', eventid, 'isClosed:', this._isClosed);
         if (this._isClosed)
             return this.throwClosed(callback);
         var msg = self._msg;
@@ -1520,7 +1595,6 @@ class Connection {
         msg.addInt(eventid);
     
         function cb(err, ret) {
-            console.log('[Connection] closeEvents callback invoked, err:', err);
             if (err) {
                 doError(err, callback);
                 return;
@@ -1530,17 +1604,26 @@ class Connection {
         }
     
         this._queueEvent(cb);
-        console.log('[Connection] closeEvents: Event queued');
     }
 
 }
 
+// Reverse-lookup table: opcode number → name for FIREBIRD_DEBUG trace logging.
+const opcodeNames = Object.fromEntries(
+    Object.entries(Const).filter(([k]) => k.startsWith('op_')).map(([k, v]) => [v, k])
+);
+
 function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
     try {
         do {
             var r = data.r || data.readInt();
         } while (r === Const.op_dummy);
 
+        if (process.env.FIREBIRD_DEBUG) {
+            console.log('[fb-debug] decodeResponse: opcode=%d(%s) pos=%d buflen=%d',
+                r, opcodeNames[r] || 'unknown', data.pos, data.buffer.length);
+        }
+
         var item, op, response;
 
         switch (r) {
@@ -1575,7 +1658,7 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
             case Const.op_sql_response:
                 var statement = callback.statement;
                 var output = statement.output;
-                var custom = statement.custom || {};
+                var custom = statement.options || {};
                 var isOpFetch = r === Const.op_fetch_response;
                 var _xdrpos;
                 statement.nbrowsfetched = statement.nbrowsfetched || 0;
@@ -1762,9 +1845,10 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                             // Server keys
                             cnx.serverKeys = {
                                 salt: d.buffer.slice(2, saltLen + 2).toString('utf8'),
-                                public: BigInt(d.buffer.slice(keyStart, d.buffer.length).toString('utf8'), 16)
+                                public: BigInt('0x' + d.buffer.slice(keyStart, d.buffer.length).toString('utf8'))
                             };
 
+                            const _t1 = Date.now();
                             var proof = srp.clientProof(
                                 cnx.options.user.toUpperCase(),
                                 cnx.options.password,
@@ -1774,6 +1858,9 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                                 cnx.clientKeys.private,
                                 accept.srpAlgo
                             );
+                            if (process.env.FIREBIRD_DEBUG) {
+                                console.log('[fb-debug] srp.clientProof(%s): %dms', accept.srpAlgo, Date.now() - _t1);
+                            }
 
                             accept.authData = proof.authData.toString(16);
                             accept.sessionKey = proof.clientSessionKey;
@@ -1792,9 +1879,20 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                     cnx._socket.enableCompression();
                 }
 
+                if (process.env.FIREBIRD_DEBUG) {
+                    console.log('[fb-debug] auth: %s received plugin=%s proto=%d t=%dms',
+                        r === Const.op_cond_accept ? 'op_cond_accept' : r === Const.op_accept_data ? 'op_accept_data' : 'op_accept',
+                        accept.pluginName, accept.protocolVersion,
+                        cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
+                }
+
                 // For op_cond_accept: send op_cont_auth and wait for response
                 if (r === Const.op_cond_accept && accept.authData) {
                     cnx._pendingAccept = accept;
+                    if (process.env.FIREBIRD_DEBUG) {
+                        console.log('[fb-debug] auth: sending op_cont_auth plugin=%s t=%dms',
+                            accept.pluginName, cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
+                    }
                     cnx.sendOpContAuth(
                         accept.authData,
                         Const.DEFAULT_ENCODING,
@@ -1810,8 +1908,43 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                 data.readString(Const.DEFAULT_ENCODING); // plist
                 data.readString(Const.DEFAULT_ENCODING); // pkey
 
+                if (process.env.FIREBIRD_DEBUG) {
+                    console.log('[fb-debug] auth: op_cont_auth received plugin=%s pendingAccept=%s t=%dms',
+                        pluginName,
+                        cnx._pendingAccept ? cnx._pendingAccept.pluginName : 'none',
+                        cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
+                }
+
+                // During SRP mutual authentication, the server sends op_cont_auth
+                // with its proof (M2) after receiving the client's proof (M1).
+                // When we have an active auth exchange for this plugin, just wait
+                // for the subsequent op_accept instead of treating it as an error.
+                if (cnx._pendingAccept && cnx._pendingAccept.pluginName === pluginName) {
+                    if (process.env.FIREBIRD_DEBUG) {
+                        console.log('[fb-debug] auth: server SRP proof (M2) received, waiting for op_accept t=%dms',
+                            cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
+                    }
+                    return; // Server SRP proof received - wait for op_accept
+                }
+
+                // Firebird 4/5 (protocols 16/17) chained-auth: after the client sends
+                // the SRP M1 proof, the server sends op_cont_auth with Legacy_Auth.
+                // SRP has already established the session key; the server additionally
+                // requires a Legacy_Auth verification step before sending op_accept.
+                // Respond with Legacy_Auth credentials and wait for op_accept.
+                if (cnx._pendingAccept && pluginName === Const.AUTH_PLUGIN_LEGACY) {
+                    if (process.env.FIREBIRD_DEBUG) {
+                        console.log('[fb-debug] auth: SRP+Legacy_Auth chained-auth (proto %d), sending Legacy_Auth credentials t=%dms',
+                            cnx._pendingAccept.protocolVersion,
+                            cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
+                    }
+                    var legacyAuthData = crypt.crypt(cnx.options.password, Const.LEGACY_AUTH_SALT).substring(2);
+                    cnx.sendOpContAuth(legacyAuthData, Const.DEFAULT_ENCODING, pluginName);
+                    return; // wait for op_accept
+                }
+
                 if (!cnx.options.pluginName) {
-                    if (cnx.accept.pluginName === pluginName) {
+                    if (cnx.accept && cnx.accept.pluginName === pluginName) {
                         // Erreur plugin not able to connect
                         return cb(new Error("Unable to connect with plugin " + cnx.accept.pluginName));
                     }
@@ -1830,7 +1963,15 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                     }
                 }
 
-                return data.accept;
+                // Server sent op_cont_auth but we don't know how to handle it.
+                if (process.env.FIREBIRD_DEBUG) {
+                    console.warn('[fb-debug] auth: op_cont_auth unhandled plugin=%s pendingAccept=%s options.plugin=%s t=%dms',
+                        pluginName,
+                        cnx._pendingAccept ? cnx._pendingAccept.pluginName : 'none',
+                        cnx.options.pluginName || 'none',
+                        cnx._authStartTime ? Date.now() - cnx._authStartTime : -1);
+                }
+                return cb(new Error('Unhandled server op_cont_auth for plugin: ' + pluginName));
             case Const.op_crypt_key_callback:
                 // Database encryption key callback
                 // Read server data (plugin data sent by server)
@@ -1849,10 +1990,64 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                 
                 // Don't call cb - wait for next operation (likely op_response or another op_crypt_key_callback)
                 return;
+            case Const.op_event:
+                // op_event may occasionally arrive on the main connection
+                // (e.g. Firebird routing an async notification here instead of
+                // the dedicated aux socket).  Consume all its fields so the
+                // buffer position advances correctly, then signal the data
+                // handler to skip queue manipulation for this frame.
+                //
+                // Firebird wire protocol – op_event payload (remote protocol):
+                //   p_event_database : Int32  – database handle
+                //   p_event_items    : Array  – event parameter block (EPB)
+                //   p_event_ast      : Int64  – AST routine pointer (0 for remote)
+                //   p_event_rid      : Int32  – remote event ID
+                {
+                    const evtDb = data.readInt();    // p_event_database
+                    data.readArray();               // p_event_items (EPB buffer)
+                    data.readInt64();               // p_event_ast
+                    const evtRid = data.readInt();  // p_event_rid
+                    if (process.env.FIREBIRD_DEBUG) {
+                        console.log('[fb-debug] op_event on main connection: db=%d rid=%d (consumed, not queued)', evtDb, evtRid);
+                    }
+                }
+                return cb(null, { _isOpEvent: true });
+            case Const.op_response_piggyback:
+                // Firebird 5 (Protocol 16/17) sends op_response_piggyback (72)
+                // as an unsolicited cleanup notification after certain operations
+                // (e.g. after the EventConnection aux socket is torn down).
+                // It has the same wire layout as op_response but does NOT
+                // correspond to any queued client request.  Parse and discard it
+                // so that the xdr buffer position advances correctly, then signal
+                // the data handler to skip queue manipulation.
+                //
+                // Wire layout (identical to op_response):
+                //   handle  : Int32
+                //   object  : Quad (2x Int32)
+                //   data    : Array
+                //   status  : status-vector ending with isc_arg_end
+                parseOpResponse(data, {}, function(err) {
+                    if (process.env.FIREBIRD_DEBUG) {
+                        if (err) {
+                            console.warn('[fb-debug] op_response_piggyback parse error:', err.message);
+                        } else {
+                            console.log('[fb-debug] op_response_piggyback consumed (unsolicited Firebird 5 cleanup)');
+                        }
+                    }
+                });
+                return cb(null, { _isOpEvent: true });
             default:
+                if (process.env.FIREBIRD_DEBUG) {
+                    console.warn('[fb-debug] unknown opcode=%d at pos=%d buflen=%d queue=%d',
+                        r, data.pos, data.buffer.length, cnx && cnx._queue ? cnx._queue.length : 0);
+                }
                 return cb(new Error('Unexpected:' + r));
         }
     } catch (err) {
+        if (process.env.FIREBIRD_DEBUG) {
+            console.warn('[fb-debug] decodeResponse exception: %s (RangeError=%s) pos=%d buflen=%d',
+                err.message, err instanceof RangeError, data.pos, data.buffer.length);
+        }
         if (err instanceof RangeError) {
             return cb(err);
         }
@@ -1980,6 +2175,10 @@ function describe(buff, statement) {
                                 case Const.SQL_TYPE_DATE: param = new Xsql.SQLVarDate(); break;
                                 case Const.SQL_TYPE_TIME: param = new Xsql.SQLVarTime(); break;
                                 case Const.SQL_TIMESTAMP: param = new Xsql.SQLVarTimeStamp(); break;
+                                case Const.SQL_TIME_TZ:   param = new Xsql.SQLVarTimeTz(); break;
+                                case Const.SQL_TIME_TZ_EX: param = new Xsql.SQLVarTimeTzEx(); break;
+                                case Const.SQL_TIMESTAMP_TZ: param = new Xsql.SQLVarTimeStampTz(); break;
+                                case Const.SQL_TIMESTAMP_TZ_EX: param = new Xsql.SQLVarTimeStampTzEx(); break;
                                 case Const.SQL_BLOB:      param = new Xsql.SQLVarBlob(); break;
                                 case Const.SQL_ARRAY:     param = new Xsql.SQLVarArray(); break;
                                 case Const.SQL_QUAD:      param = new Xsql.SQLVarQuad(); break;
@@ -1987,6 +2186,8 @@ function describe(buff, statement) {
                                 case Const.SQL_SHORT:     param = new Xsql.SQLVarShort(); break;
                                 case Const.SQL_INT64:     param = new Xsql.SQLVarInt64(); break;
                                 case Const.SQL_INT128:     param = new Xsql.SQLVarInt128(); break;
+                                case Const.SQL_DEC16:     param = new Xsql.SQLVarDecFloat16(); break;
+                                case Const.SQL_DEC34:     param = new Xsql.SQLVarDecFloat34(); break;
                                 case Const.SQL_BOOLEAN:   param = new Xsql.SQLVarBoolean(); break;
                                 default:
                                     throw new Error('Unexpected');