aerospike 5.13.1 → 6.0.0

package/README.md

@@ -340,6 +340,10 @@ To run all the test cases:
 
     npm test
 
+To run a specific tests, use:
+
+    npm test --testfile=filename.js
+
 Note: make sure your server has TTL enabled for the `test` namespace ([Namespace Retention Configuration](https://docs.aerospike.com/server/operations/configure/namespace/retention)) to allow all tests to run correctly.
 
 To run the tests and also report on test coverage:

package/binding.gyp

@@ -67,6 +67,7 @@
       'sources': [
         'src/main/aerospike.cc',
         'src/main/client.cc',
+        'src/main/transaction.cc',
         'src/main/config.cc',
         'src/main/events.cc',
         'src/main/cdt_ctx.cc',
@@ -125,11 +126,17 @@
         'src/main/commands/scan_background.cc',
         'src/main/commands/scan_pages.cc',
         'src/main/commands/select_async.cc',
+        'src/main/commands/transaction_abort.cc',
+        'src/main/commands/transaction_commit.cc',
         'src/main/commands/truncate.cc',
         'src/main/commands/user_create.cc',
         'src/main/commands/user_drop.cc',
         'src/main/commands/udf_register.cc',
         'src/main/commands/udf_remove.cc',
+        'src/main/enums/abort_status.cc',
+        'src/main/enums/commit_status.cc',
+        'src/main/enums/txn_state.cc',
+        'src/main/enums/txn_capacity.cc',
         'src/main/enums/predicates.cc',
         'src/main/enums/bitwise_enum.cc',
         'src/main/enums/hll_enum.cc',

package/examples/mrtAbort.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// *****************************************************************************
+// Copyright 2013-2024 Aerospike, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with 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.
+// *****************************************************************************
+//
+const Aerospike = require('aerospike')
+const shared = require('./shared')
+
+shared.runner()
+
+async function mrtAbort (client, argv) {
+  // sconst record1 = { abc: 123 }
+  const record2 = { def: 456 }
+
+  const mrt = new Aerospike.Transaction()
+
+  const policy = {
+    txn: mrt
+  }
+  const keyList = []
+  for (let i = 0; i < argv.keys.length; i++) {
+    keyList.push(new Aerospike.Key(argv.namespace, argv.set, argv.keys[i]))
+  }
+
+  for (let i = 0; i < keyList.length; i++) {
+    await client.put(keyList[i], record2, policy)
+    await client.get(keyList[i], policy)
+  }
+
+  console.log(keyList)
+
+  console.log('aborting multi-record transaction with %d operations.', keyList.length * 2)
+  await client.abort(mrt)
+  console.info('multi-record transaction has been aborted.')
+}
+
+exports.command = 'mrtAbort <keys..>'
+exports.describe = 'Abort a multi-record transaction'
+exports.handler = shared.run(mrtAbort)
+exports.builder = {
+  keys: {
+    desc: 'Provide keys for the records in the multi-record transaction',
+    type: 'array',
+    group: 'Command:'
+  }
+}

package/examples/mrtCommit.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// *****************************************************************************
+// Copyright 2013-2024 Aerospike, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with 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.
+// *****************************************************************************
+//
+const Aerospike = require('aerospike')
+const shared = require('./shared')
+
+shared.runner()
+
+async function mrtCommit (client, argv) {
+  // const record1 = { abc: 123 }
+  const record2 = { def: 456 }
+
+  const mrt = new Aerospike.Transaction()
+
+  const policy = {
+    txn: mrt
+  }
+  const keyList = []
+  for (let i = 0; i < argv.keys.length; i++) {
+    keyList.push(new Aerospike.Key(argv.namespace, argv.set, argv.keys[i]))
+  }
+  for (let i = 0; i < argv.keys.length; i++) {
+    await client.put(keyList[i], record2, policy)
+    await client.get(keyList[i], policy)
+  }
+
+  console.log(keyList)
+
+  console.log('committing multi-record transaction with %d operations.', keyList.length * 2)
+  await client.commit(mrt)
+  console.info('multi-record transaction has been committed.')
+}
+
+exports.command = 'mrtCommit <keys..>'
+exports.describe = 'Commit a multi-record transaction'
+exports.handler = shared.run(mrtCommit)
+exports.builder = {
+  keys: {
+    desc: 'Provide keys for the records in the multi-record transaction',
+    type: 'array',
+    group: 'Command:'
+  }
+}

package/examples/run.js

@@ -28,6 +28,8 @@ const commands = [
   'geospatialMonteCarlo',
   'get',
   'info',
+  'mrtAbort',
+  'mrtCommit',
   'operate',
   'put',
   'query',

package/lib/abort_status.js

@@ -0,0 +1,28 @@
+// *****************************************************************************
+// Copyright 2024 Aerospike, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the 'License')
+// you may not use this file except in compliance with 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.
+// *****************************************************************************
+
+'use strict'
+
+const as = require('bindings')('aerospike.node')
+const abortStatus = as.abortStatus
+
+module.exports = {
+  OK: abortStatus.OK,
+  ALREADY_COMMITTED: abortStatus.ALREADY_COMMITTED,
+  ALREADY_ABORTED: abortStatus.ALREADY_ABORTED,
+  ROLL_BACK_ABANDONED: abortStatus.ROLL_BACK_ABANDONED,
+  CLOSE_ABANDONED: abortStatus.CLOSE_ABANDONED
+}

package/lib/aerospike.js

@@ -19,7 +19,11 @@
 const as = require('bindings')('aerospike.node')
 const AerospikeError = require('./error')
 const EventLoop = require('./event_loop')
+const TransactionPool = require('./transaction_pool')
 
+const _transactionPool = new TransactionPool()
+
+exports._transactionPool = _transactionPool
 /**
  * @module aerospike
  *
@@ -238,6 +242,39 @@ exports.Config = require('./config')
  */
 exports.Double = require('./double')
 
+/**
+ * Multi-record transaction (MRT) class. All commands in the same MRT must use the same namespace.
+ *
+ * note: By default, open transactions are destroyed when the final client in a process is closed.
+ * If you need your transaction to persist after the last client has been closed, provide `false` for the
+ * destroy Transactions argument in {@link Client#close} (see example below).
+ *
+ * @example
+ *
+ * const Aerospike = require('aerospike')
+ *
+ * // INSERT HOSTNAME AND PORT NUMBER OF AEROSPIKE SERVER NODE HERE!
+ * var config = {
+ *   hosts: '192.168.33.10:3000',
+ * }
+ * Aerospike.connect(config)
+ *   .then(client => {
+ *     // client is ready to accept commands
+ *     console.log("Connected. Now Closing Connection.")
+ *     client.close()
+ *   })
+ *   .catch(error => {
+ *     client.close(
+ *       false, // do not release the event loop
+ *       false // do not destroy open transactions
+ *     )
+ *     console.error('Failed to connect to cluster: %s', error.message)
+ *   })
+ *
+ * @summary {@link Transaction} class
+ */
+exports.Transaction = require('./transaction')
+
 /**
  * Representation of a GeoJSON value. Since GeoJSON values are JSON objects
  * they need to be wrapped in the {@link GeoJSON} class so that the client can
@@ -701,6 +738,22 @@ exports.setupGlobalCommandQueue = function (policy) {
  */
 exports.batchType = require('./batch_type')
 
+/**
+ * The {@link module:aerospike/commit_status|aerospike/commit_status}
+ * module contains a list of commit statuses.
+ *
+ * @summary {@link module:aerospike/commit_status|aerospike/commit_status} module
+ */
+exports.commitStatus = require('./commit_status')
+
+/**
+ * The {@link module:aerospike/abortStatus|aerospike/abort_status}
+ * module contains a list of abort statuses.
+ *
+ * @summary {@link module:aerospike/abortStatus|aerospike/abort_status} module
+ */
+exports.abortStatus = require('./abort_status')
+
 /**
  * The {@link module:aerospike/privilegeCode|aerospike/privilege_code}
  * module is comprised of permission codes which define the type of

package/lib/client.js

@@ -22,6 +22,10 @@ const EventEmitter = require('events')
 
 const as = require('bindings')('aerospike.node')
 const AerospikeError = require('./error')
+const abortStatus = require('./abort_status')
+const commitStatus = require('./commit_status')
+const txnState = require('./txn_state')
+const Transaction = require('./transaction')
 const Context = require('./cdt_context')
 const Commands = require('./commands')
 const Config = require('./config')
@@ -35,6 +39,7 @@ const utils = require('./utils')
 
 // number of client instances currently connected to any Aerospike cluster
 let _connectedClients = 0
+const { _transactionPool } = require('./aerospike')
 
 // callback function for cluster events (node added/removed, etc.)
 function eventsCallback (event) {
@@ -211,6 +216,40 @@ Client.prototype.getNodes = function () {
   return this.as_client.getNodes()
 }
 
+Client.prototype.abort = function (transaction, callback) {
+  _transactionPool.tendTransactions()
+  if (transaction instanceof Transaction) {
+    if (transaction.getState() === txnState.COMMITTED) {
+      return abortStatus.ALREADY_COMMITTED
+    } else if (transaction.getState() === txnState.ABORTED) {
+      return abortStatus.ALREADY_ABORTED
+    } else if (transaction.getDestroyed() === true) {
+      throw new AerospikeError('The object has been destroyed, please create a new transaction.')
+    }
+  } else {
+    throw new AerospikeError('transaction must be an instance of class Transaction.')
+  }
+  const cmd = new Commands.TransactionAbort(this, [transaction.transaction], callback)
+  return cmd.execute()
+}
+
+Client.prototype.commit = function (transaction, callback) {
+  _transactionPool.tendTransactions()
+  if (transaction instanceof Transaction) {
+    if (transaction.getState() === txnState.COMMITTED) {
+      return commitStatus.ALREADY_COMMITTED
+    } else if (transaction.getState() === txnState.ABORTED) {
+      return commitStatus.ALREADY_ABORTED
+    } else if (transaction.getDestroyed() === true) {
+      throw new AerospikeError('The object has been destroyed, please create a new transaction.')
+    }
+  } else {
+    throw new AerospikeError('transaction must be an instance of class Transaction.')
+  }
+  const cmd = new Commands.TransactionCommit(this, [transaction.transaction], callback)
+  return cmd.execute()
+}
+
 /**
  * @function Client#contextToBase64
  *
@@ -1711,7 +1750,8 @@ Client.prototype.batchSelect = function (keys, bins, policy, callback) {
  *
  * @summary Closes the client connection to the cluster.
  *
- * @param {boolean} [releaseEventLoop=false] - Whether to release the event loop handle after the client is closed.
+ * @param {boolean} [releaseEventLoop=false] - Whether to release the event loop handle after the last client is closed.
+ * @param {boolean} [destroyTransactions=true] - Whether to destroy any open transactions after the last client is closed.
  *
  * @see module:aerospike.releaseEventLoop
  *
@@ -1734,13 +1774,16 @@ Client.prototype.batchSelect = function (keys, bins, policy, callback) {
  *     console.error('Failed to connect to cluster: %s', error.message)
  *   })
  */
-Client.prototype.close = function (releaseEventLoop = false) {
+Client.prototype.close = function (releaseEventLoop = false, destroyTransactions = true) {
   if (this.isConnected(false)) {
     this.connected = false
     this.as_client.close()
     _connectedClients -= 1
   }
   if (_connectedClients === 0) {
+    if (destroyTransactions) {
+      _transactionPool.removeAllTransactions()
+    }
     if (releaseEventLoop) {
       EventLoop.releaseEventLoop()
     } else {

package/lib/commands/index.js

@@ -70,6 +70,8 @@ exports.ScanPages = class ScanPagesCommand extends StreamCommand('scanPages') {
 exports.ScanBackground = class ScanBackgroundCommand extends QueryBackgroundBaseCommand('scanBackground') { }
 exports.ScanOperate = class ScanOperateCommand extends QueryBackgroundBaseCommand('scanBackground') { }
 exports.Select = class SelectCommand extends ReadRecordCommand('selectAsync') { }
+exports.TransactionAbort = class TransactionAbortCommand extends Command('transactionAbort') { }
+exports.TransactionCommit = class TransactionCommitCommand extends Command('transactionCommit') { }
 exports.Truncate = class TruncateCommand extends Command('truncate') { }
 exports.UdfRegister = class UdfRegisterCommand extends Command('udfRegister') { }
 exports.UdfRemove = class UdfRemoveCommand extends Command('udfRemove') { }

package/lib/commit_status.js

@@ -0,0 +1,30 @@
+// *****************************************************************************
+// Copyright 2024 Aerospike, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the 'License')
+// you may not use this file except in compliance with 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.
+// *****************************************************************************
+
+'use strict'
+
+const as = require('bindings')('aerospike.node')
+const commitStatus = as.commitStatus
+
+module.exports = {
+  OK: commitStatus.OK,
+  ALREADY_COMMITTED: commitStatus.ALREADY_COMMITTED,
+  ALREADY_ABORTED: commitStatus.ALREADY_ABORTED,
+  VERIFY_FAILED: commitStatus.VERIFY_FAILED,
+  MARK_ROLL_FORWARD_ABANDONED: commitStatus.MARK_ROLL_FORWARD_ABANDONED,
+  ROLL_FORWARD_ABANDONED: commitStatus.ROLL_FORWARD_ABANDONED,
+  CLOSE_ABANDONED: commitStatus.CLOSE_ABANDONED
+}

package/lib/policies/base_policy.js

@@ -121,6 +121,8 @@ class BasePolicy {
      * @since v3.14.0
      */
     this.compress = props.compress
+
+    this.txn = props.txn
   }
 }
 

package/lib/status.js

@@ -24,6 +24,12 @@ const as = require('bindings')('aerospike.node')
  * @description Database operation error codes.
  */
 
+/**
+ * Multi-record transaction failed.
+ * @const {number}
+ */
+exports.TXN_FAILED = exports.AEROSPIKE_TXN_FAILED = as.status.AEROSPIKE_TXN_FAILED
+
 /**
  * One or more keys failed in a batch.
  * @const {number}
@@ -303,6 +309,8 @@ exports.FILTERED_OUT = exports.AEROSPIKE_FILTERED_OUT = as.status.AEROSPIKE_FILT
  */
 exports.LOST_CONFLICT = exports.AEROSPIKE_LOST_CONFLICT = as.status.AEROSPIKE_LOST_CONFLICT
 
+exports.XDR_KEY_BUSY = exports.AEROSPIKE_XDR_KEY_BUSY = as.status.AEROSPIKE_XDR_KEY_BUSY
+
 /**
  * There are no more records left for query.
  * @const {number}
@@ -441,6 +449,13 @@ exports.ROLE_VIOLATION = exports.AEROSPIKE_ROLE_VIOLATION = as.status.AEROSPIKE_
  */
 exports.ERR_UDF = exports.AEROSPIKE_ERR_UDF = as.status.AEROSPIKE_ERR_UDF
 
+exports.MRT_BLOCKED = exports.AEROSPIKE_MRT_BLOCKED = as.status.AEROSPIKE_MRT_BLOCKED
+exports.MRT_VERSION_MISMATCH = exports.AEROSPIKE_MRT_VERSION_MISMATCH = as.status.AEROSPIKE_MRT_VERSION_MISMATCH
+exports.MRT_EXPIRED = exports.AEROSPIKE_MRT_EXPIRED = as.status.AEROSPIKE_MRT_EXPIRED
+exports.MRT_TOO_MANY_WRITES = exports.AEROSPIKE_MRT_TOO_MANY_WRITES = as.status.AEROSPIKE_MRT_TOO_MANY_WRITES
+exports.MRT_COMMITTED = exports.AEROSPIKE_MRT_COMMITTED = as.status.AEROSPIKE_MRT_COMMITTED
+exports.MRT_ABORTED = exports.AEROSPIKE_MRT_ABORTED = as.status.AEROSPIKE_MRT_ABORTED
+
 /**
  * Batch functionality has been disabled.
  * @const {number}
@@ -553,6 +568,9 @@ exports.ERR_LUA_FILE_NOT_FOUND = exports.AEROSPIKE_ERR_LUA_FILE_NOT_FOUND = as.s
 exports.getMessage = function (code) {
   /* istanbul ignore next */
   switch (code) {
+    case exports.TXN_FAILED:
+      return 'Multi-record transaction failed.'
+
     case exports.ERR_INVALID_NODE:
       return 'Node invalid or could not be found.'
 
@@ -727,6 +745,24 @@ exports.getMessage = function (code) {
     case exports.ERR_UDF:
       return 'Generic UDF error.'
 
+    case exports.MRT_BLOCKED:
+      return 'MRT record blocked by a different transaction.'
+
+    case exports.MRT_VERSION_MISMATCH:
+      return 'MRT read version mismatch identified during commit. Some other command changed the record outside of the transaction.'
+
+    case exports.MRT_EXPIRED:
+      return 'MRT deadline reached without a successful commit or abort.'
+
+    case exports.MRT_TOO_MANY_WRITES:
+      return 'MRT write command limit (4096) exceeded.'
+
+    case exports.MRT_COMMITTED:
+      return 'MRT was already committed.'
+
+    case exports.MRT_ABORTED:
+      return 'MRT was already aborted.'
+
     case exports.ERR_BATCH_DISABLED:
       return 'Batch functionality has been disabled.'