Added call timeouts when using Oracle client libraries 18.1 and higher

Author: cjbj

doc/api.md

@@ -111,11 +111,12 @@ limitations under the License.
 4. [Connection Class](#connectionclass)
     - 4.1 [Connection Properties](#connectionproperties)
         - 4.1.1 [`action`](#propconnaction)
-        - 4.1.2 [`clientId`](#propconnclientid)
-        - 4.1.3 [`module`](#propconnmodule)
-        - 4.1.4 [`oracleServerVersion`](#propconnoracleserverversion)
-        - 4.1.5 [`oracleServerVersionString`](#propconnoracleserverversionstring)
-        - 4.1.6 [`stmtCacheSize`](#propconnstmtcachesize)
+        - 4.1.2 [`callTimeout`](#propconncalltimeout)
+        - 4.1.3 [`clientId`](#propconnclientid)
+        - 4.1.4 [`module`](#propconnmodule)
+        - 4.1.5 [`oracleServerVersion`](#propconnoracleserverversion)
+        - 4.1.6 [`oracleServerVersionString`](#propconnoracleserverversionstring)
+        - 4.1.7 [`stmtCacheSize`](#propconnstmtcachesize)
     - 4.2 [Connection Methods](#connectionmethods)
         - 4.2.1 [`break()`](#break)
         - 4.2.2 [`changePassword()`](#changepassword)
@@ -232,6 +233,7 @@ limitations under the License.
     - 8.9 [Connections and High Availability](#connectionha)
         - 8.9.1 [Fast Application Notification (FAN)](#connectionfan)
         - 8.9.2 [Runtime Load Balancing (RLB)](#connectionrlb)
+        - 8.9.3 [Database Call Timeouts](#dbcalltimeouts)
     - 8.10 [Optional Client Configuration Files](#tnsadmin)
 9. [SQL Execution](#sqlexecution)
     - 9.1 [SELECT Statements](#select)
@@ -1187,7 +1189,7 @@ This property may be overridden when [creating a connection pool](#createpool).
 See [Connection Pool Pinging](#connpoolpinging) for more discussion.
 
 This property was added in node-oracledb 1.12.  It was disabled when
-using Oracle Client 12.2+ until node-oracledb 3.0.
+using Oracle Client 12.2 (and later) until node-oracledb 3.0.
 
 ##### Example
 
@@ -1946,7 +1948,26 @@ This is a write-only property.  Displaying a Connection object will
 show a value of `null` for this attribute.  See
 [End-to-end Tracing, Mid-tier Authentication, and Auditing](#endtoend).
 
-#### <a name="propconnclientid"></a> 4.1.2 `connection.clientId`
+#### <a name="propconncalltimeout"></a> 4.1.2 `connection.callTimeout`
+
+```
+Number callTimeout
+```
+
+Sets the maximum number of milliseconds that each underlying
+round-trip between node-oracledb and Oracle Database may take.  Each
+node-oracledb method or operation may make zero or more round-trips.
+The `callTimeout` value applies to each round-trip individually, not
+to the sum of all round-trips.  Time spent processing in node-oracledb
+before or after the completion of each round-trip is not counted.
+
+See [Database Call Timeouts](#dbcalltimeouts) for more information.
+
+This property was added in node-oracledb 3.0.  An exception will occur
+if node-oracledb is not using Oracle client library version 18.1 or
+later.
+
+#### <a name="propconnclientid"></a> 4.1.3 `connection.clientId`
 
 ```
 writeonly String clientId
@@ -1960,7 +1981,7 @@ This is a write-only property.  Displaying a Connection object will
 show a value of `null` for this attribute.  See
 [End-to-end Tracing, Mid-tier Authentication, and Auditing](#endtoend).
 
-#### <a name="propconnmodule"></a> 4.1.3 `connection.module`
+#### <a name="propconnmodule"></a> 4.1.4 `connection.module`
 
 ```
 writeonly String module
@@ -1972,7 +1993,7 @@ This is a write-only property.  Displaying a Connection object will
 show a value of `null` for this attribute.  See
 [End-to-end Tracing, Mid-tier Authentication, and Auditing](#endtoend).
 
-#### <a name="propconnoracleserverversion"></a> 4.1.4 `connection.oracleServerVersion`
+#### <a name="propconnoracleserverversion"></a> 4.1.5 `connection.oracleServerVersion`
 
 ```
 readonly Number oracleServerVersion
@@ -1988,7 +2009,7 @@ instead of 1803000000.
 
 This property was added in node-oracledb 1.3.
 
-#### <a name="propconnoracleserverversionstring"></a> 4.1.5 `connection.oracleServerVersionString`
+#### <a name="propconnoracleserverversionstring"></a> 4.1.6 `connection.oracleServerVersionString`
 
 ```
 readonly String oracleServerVersionString
@@ -2003,7 +2024,7 @@ libraries.  Otherwise it will show the base release such as
 
 This property was added in node-oracledb 2.2.
 
-#### <a name="propconnstmtcachesize"></a> 4.1.6 `connection.stmtCacheSize`
+#### <a name="propconnstmtcachesize"></a> 4.1.7 `connection.stmtCacheSize`
 
 ```
 readonly Number stmtCacheSize
@@ -4879,7 +4900,6 @@ application being aware of any service disruption.
 For a more information on FAN see the [whitepaper on Fast Application
 Notification][97].
 
-
 #### <a name="connectionrlb"></a> 8.9.2 Runtime Load Balancing (RLB)
 
 [Oracle Database RAC][93] users with [Oracle Database (RLB)][65]
@@ -4894,6 +4914,44 @@ requests across RAC instances.
 For a more information on RLB, see the [whitepaper on Fast Application
 Notification][97].
 
+#### <a name="dbcalltimeouts"></a> 8.9.3 Database Call Timeouts
+
+When node-oracledb is using Oracle client 18 libraries, a millisecond
+timeout for database calls can be set with
+[`connection.callTimeout`](#propconncalltimeout).
+
+The call timeout is on each individual round-trip between
+node-oracledb and Oracle Database.  Each node-oracledb method or
+operation may require zero or more round-trips to Oracle Database.
+The `callTimeout` value applies to each round-trip individually, not
+to the sum of all round-trips.  Time spent processing in node-oracledb
+before or after the completion of each round-trip is not counted.
+
+- If the time from the start of any one round-trip to the completion
+  of that same round-trip exceeds `callTimeout` milliseconds, then the
+  operation is halted and error "DPI-1067: call timeout of N ms exceeded
+  with ORA-XXX" is returned.
+
+- In the case where a node-oracledb operation requires more than one
+  round-trip and each round-trip takes less than `callTimeout`
+  milliseconds, then no timeout will occur, even if the sum of all
+  round-trip calls exceeds `callTimeout`.
+
+- If no round-trip is required, the operation will never be
+  interrupted.
+
+After a timeout occurs, node-oracledb attempts to clean up the
+internal connection state.  The cleanup is allowed to take another
+`callTimeout` milliseconds.
+
+If the cleanup was successful, an *DPI-1067* error will be returned and the
+application can continue to use the connection.
+
+For small values of `callTimeout`, the connection cleanup may not
+complete successfully within the additional `callTimeout` period.  In
+this case an *ORA-3114* is returned and the connection will no longer
+be usable.  It should be closed.
+
 ### <a name="tnsadmin"></a> 8.10 Optional Client Configuration Files
 
 Optional Oracle Client configuration files are read when node-oracledb

examples/calltimeout.js

@@ -0,0 +1,74 @@
+/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * NAME
+ *   calltimeout.js
+ *
+ * DESCRIPTION
+ *   Shows how to time out long running database calls.
+ *   See https://oracle.github.io/node-oracledb/doc/api.html#dbcalltimeouts
+ *   Node-oracledb must be using Oracle Client 18c libraries, or greater.
+ *
+ *   This example uses Async/Await of Node 8.
+ *
+ *****************************************************************************/
+
+let oracledb = require("oracledb");
+let dbConfig = require('./dbconfig.js');
+
+// "Sleep" in the database for a number of seconds.
+// This uses an inefficent sleep implementation instead of
+// dbms_lock.sleep() which not all users can use.
+const sql = `
+  DECLARE
+     t DATE := SYSDATE + (:sleepsec * (1/86400));
+  BEGIN
+    LOOP
+      EXIT WHEN t <= SYSDATE;
+    END LOOP;
+  END;`;
+
+let dboptime = 4; // seconds the DB operation will take
+let timeout  = 2; // seconds the application will wait for the DB operation
+
+async function runTest() {
+  let connection;
+
+  try {
+    connection = await oracledb.getConnection(dbConfig);
+    connection.callTimeout = timeout * 1000;  // milliseconds
+    console.log("Database call timeout set to " + connection.callTimeout / 1000 + " seconds");
+    console.log("Executing a " + dboptime + " second DB operation");
+    await connection.execute(sql, [dboptime]);
+    console.log("DB operation successfully completed");
+  } catch (err) {
+    if (err.message.startsWith('DPI-1067:') || err.errorNum === 3114)
+      console.log('DB operation was stopped after exceeding the call timeout');
+    else
+      console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+runTest();

src/njsConnection.cpp

@@ -113,6 +113,9 @@ void njsConnection::Init(Local<Object> target)
             Nan::New<v8::String>("oracleServerVersionString").ToLocalChecked(),
             njsConnection::GetOracleServerVersionString,
             njsConnection::SetOracleServerVersionString);
+    Nan::SetAccessor(tpl->InstanceTemplate(),
+            Nan::New<v8::String>("callTimeout").ToLocalChecked(),
+            njsConnection::GetCallTimeout, njsConnection::SetCallTimeout);
 
     connectionTemplate_s.Reset(tpl);
     Nan::Set(target, Nan::New<v8::String>("Connection").ToLocalChecked(),
@@ -2803,3 +2806,49 @@ NAN_SETTER(njsConnection::SetOracleServerVersionString)
     PropertyIsReadOnly("oracleServerVersionString");
 }
 
+
+//-----------------------------------------------------------------------------
+// njsConnection::GetCallTimeout()
+//   Get accessor of "callTimeout" property.
+//-----------------------------------------------------------------------------
+NAN_GETTER(njsConnection::GetCallTimeout)
+{
+    uint32_t callTimeout;
+
+    njsConnection *connection = (njsConnection*) ValidateGetter(info);
+    if (!connection)
+        return;
+    if (!connection->IsValid()) {
+        info.GetReturnValue().Set(Nan::Undefined());
+        return;
+    }
+    if (dpiConn_getCallTimeout(connection->dpiConnHandle, &callTimeout) < 0) {
+        njsOracledb::ThrowDPIError();
+        return;
+    }
+    info.GetReturnValue().Set(callTimeout);
+}
+
+
+//-----------------------------------------------------------------------------
+// njsConnection::SetCallTimeout()
+//   Set accessor of "callTimeout" property.
+//-----------------------------------------------------------------------------
+NAN_SETTER(njsConnection::SetCallTimeout)
+{
+    uint32_t callTimeout;
+
+    njsConnection *connection = (njsConnection*) ValidateSetter(info);
+    if (!connection)
+        return;
+    if (!value->IsUint32()) {
+        string errMsg = njsMessages::Get(errInvalidPropertyValue,
+                "callTimeout");
+        Nan::ThrowError(errMsg.c_str());
+        return;
+    }
+    callTimeout = Nan::To<uint32_t>(value).FromJust();
+    if (dpiConn_setCallTimeout(connection->dpiConnHandle, callTimeout) < 0)
+        njsOracledb::ThrowDPIError();
+}
+

src/njsConnection.h

@@ -156,6 +156,7 @@ class njsConnection: public njsCommon {
     static NAN_GETTER(GetAction);
     static NAN_GETTER(GetOracleServerVersion);
     static NAN_GETTER(GetOracleServerVersionString);
+    static NAN_GETTER(GetCallTimeout);
 
     // Define Setter Accessors to properties
     static NAN_SETTER(SetStmtCacheSize);
@@ -164,6 +165,7 @@ class njsConnection: public njsCommon {
     static NAN_SETTER(SetAction);
     static NAN_SETTER(SetOracleServerVersion);
     static NAN_SETTER(SetOracleServerVersionString);
+    static NAN_SETTER(SetCallTimeout);
 
     // internal methods
     static bool CreateVarBuffer(njsVariable *var, njsBaton *baton);