@ragestudio/scylla-odm 0.22.2 → 0.22.3

package/driver/metadata/table-metadata.js

@@ -0,0 +1,77 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+import util from "util"
+import DataCollection from "./data-collection.js"
+/**
+ * Creates a new instance of TableMetadata
+ * @classdesc Describes a table
+ * @param {String} name Name of the Table
+ * @augments {module:metadata~DataCollection}
+ * @alias module:metadata~TableMetadata
+ * @constructor
+ */
+function TableMetadata(name) {
+	DataCollection.call(this, name)
+	/**
+	 * Applies only to counter tables.
+	 * When set to true, replicates writes to all affected replicas regardless of the consistency level specified by
+	 * the client for a write request. For counter tables, this should always be set to true.
+	 * @type {Boolean}
+	 */
+	this.replicateOnWrite = true
+	/**
+	 * Returns the memtable flush period (in milliseconds) option for this table.
+	 * @type {Number}
+	 */
+	this.memtableFlushPeriod = 0
+	/**
+	 * Returns the index interval option for this table.
+	 * <p>
+	 * Note: this option is only available in Apache Cassandra 2.0. It is deprecated in Apache Cassandra 2.1 and
+	 * above, and will therefore return <code>null</code> for 2.1 nodes.
+	 * </p>
+	 * @type {Number|null}
+	 */
+	this.indexInterval = null
+	/**
+	 * Determines  whether the table uses the COMPACT STORAGE option.
+	 * @type {Boolean}
+	 */
+	this.isCompact = false
+	/**
+	 *
+	 * @type {Array.<Index>}
+	 */
+	this.indexes = null
+
+	/**
+	 * Determines whether the Change Data Capture (CDC) flag is set for the table.
+	 * @type {Boolean|null}
+	 */
+	this.cdc = null
+
+	/**
+	 * Determines whether the table is a virtual table or not.
+	 * @type {Boolean}
+	 */
+	this.virtual = false
+}
+
+util.inherits(TableMetadata, DataCollection)
+
+export default TableMetadata

package/driver/operation-state.js

@@ -0,0 +1,206 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+import util from "util"
+import utils from "./utils.js"
+import errors from "./errors.js"
+import { ExecuteRequest, QueryRequest } from "./requests.js"
+
+const state = {
+	init: 0,
+	completed: 1,
+	timedOut: 2,
+	cancelled: 3,
+}
+
+/**
+ * Maintains the state information of a request inside a Connection.
+ */
+class OperationState {
+	/**
+	 * Creates a new instance of OperationState.
+	 * @param {Request} request
+	 * @param {Function} rowCallback
+	 * @param {Function} callback
+	 */
+	constructor(request, rowCallback, callback) {
+		this.request = request
+		this._rowCallback = rowCallback
+		this._callback = callback
+		this._deadline = 0
+		this._state = state.init
+		this._rowIndex = 0
+		/**
+		 * Stream id that is set right before being written.
+		 * @type {number}
+		 */
+		this.streamId = -1
+	}
+
+	/**
+	 * Marks the operation as cancelled, clearing all callbacks.
+	 */
+	cancel() {
+		if (this._state !== state.init) {
+			return
+		}
+		this._state = state.cancelled
+		this._callback = utils.noop
+		this._deadline = 0
+	}
+
+	/**
+	 * Determines if the operation can be written to the wire (when it hasn't been cancelled or it hasn't timed out).
+	 */
+	canBeWritten() {
+		return this._state === state.init
+	}
+
+	/**
+	 * Determines if the response is going to be yielded by row.
+	 * @return {boolean}
+	 */
+	isByRow() {
+		return (
+			this._rowCallback &&
+			(this.request instanceof ExecuteRequest ||
+				this.request instanceof QueryRequest)
+		)
+	}
+
+	/**
+	 * Stores the timeout deadline for this operation.
+	 * The actual timer is managed by Connection to avoid per-operation setTimeout overhead.
+	 * @param {ExecutionOptions} execOptions
+	 * @param {Number} defaultReadTimeout
+	 * @param {String} address
+	 * @param {Function} onTimeout The callback to be invoked when it times out.
+	 * @param {Function} onResponse The callback to be invoked if a response is obtained after it timed out.
+	 */
+	setRequestTimeout(
+		execOptions,
+		defaultReadTimeout,
+		address,
+		onTimeout,
+		onResponse,
+	) {
+		if (this._state !== state.init) {
+			return
+		}
+		const millis =
+			execOptions.getReadTimeout() !== undefined
+				? execOptions.getReadTimeout()
+				: defaultReadTimeout
+		if (!(millis > 0)) {
+			return
+		}
+
+		this._deadline = Date.now() + millis
+		this._timeoutMillis = millis
+		this._onTimeoutCb = onTimeout
+		this._onResponseCb = onResponse
+		this._address = address
+	}
+
+	/**
+	 * Checks if this operation has timed out.
+	 * Called by the Connection's shared timeout timer.
+	 * @param {Number} now current timestamp
+	 * @returns {boolean} true if the operation timed out
+	 */
+	checkTimeout(now) {
+		if (
+			this._state !== state.init ||
+			!this._deadline ||
+			this._deadline > now
+		) {
+			return false
+		}
+
+		this._onTimeoutCb()
+		const message = util.format(
+			"The host %s did not reply before timeout %d ms",
+			this._address,
+			this._timeoutMillis,
+		)
+		this._markAsTimedOut(
+			new errors.OperationTimedOutError(message, this._address),
+			this._onResponseCb,
+		)
+		return true
+	}
+
+	setResultRow(row, meta, rowLength, flags, header) {
+		this._markAsCompleted()
+		if (!this._rowCallback) {
+			return this.setResult(
+				new errors.DriverInternalError(
+					"RowCallback not found for streaming frame handler",
+				),
+			)
+		}
+		this._rowCallback(this._rowIndex++, row, rowLength)
+		if (this._rowIndex === rowLength) {
+			this._swapCallbackAndInvoke(
+				null,
+				{ rowLength: rowLength, meta: meta, flags: flags },
+				header.bodyLength,
+			)
+		}
+	}
+
+	/**
+	 * Marks the current operation as timed out.
+	 * @param {Error} err
+	 * @param {Function} onResponse
+	 * @private
+	 */
+	_markAsTimedOut(err, onResponse) {
+		if (this._state !== state.init) {
+			return
+		}
+		this._state = state.timedOut
+		this._swapCallbackAndInvoke(err, null, null, onResponse)
+	}
+
+	_markAsCompleted() {
+		if (this._state !== state.init) {
+			return
+		}
+		this._state = state.completed
+		this._deadline = 0
+	}
+
+	/**
+	 * Sets the result of this operation, declaring that no further input will be processed for this operation.
+	 * @param {Error} err
+	 * @param {Object} [result]
+	 * @param {Number} [length]
+	 */
+	setResult(err, result, length) {
+		this._markAsCompleted()
+		this._swapCallbackAndInvoke(err, result, length)
+	}
+
+	_swapCallbackAndInvoke(err, result, length, newCallback) {
+		const callback = this._callback
+		this._callback = newCallback || utils.noop
+		callback(err, result, length)
+	}
+}
+
+export default OperationState

package/driver/policies/address-resolution.js

@@ -0,0 +1,145 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+import dns from "dns"
+import util from "util"
+import utils from "../utils.js"
+/** @module policies/addressResolution */
+/**
+ * @class
+ * @classdesc
+ * Translates IP addresses received from Cassandra nodes into locally queryable
+ * addresses.
+ * <p>
+ * The driver auto-detects new Cassandra nodes added to the cluster through server
+ * side pushed notifications and through checking the system tables. For each
+ * node, the address received will correspond to the address set as
+ * <code>rpc_address</code> in the node yaml file. In most case, this is the correct
+ * address to use by the driver and that is what is used by default. However,
+ * sometimes the addresses received through this mechanism will either not be
+ * reachable directly by the driver or should not be the preferred address to use
+ * to reach the node (for instance, the <code>rpc_address</code> set on Cassandra nodes
+ * might be a private IP, but some clients  may have to use a public IP, or
+ * pass by a router to reach that node). This interface allows to deal with
+ * such cases, by allowing to translate an address as sent by a Cassandra node
+ * to another address to be used by the driver for connection.
+ * <p>
+ * Please note that the contact points addresses provided while creating the
+ * {@link Client} instance are not "translated", only IP address retrieve from or sent
+ * by Cassandra nodes to the driver are.
+ * @constructor
+ */
+function AddressTranslator() {}
+
+/**
+ * Translates a Cassandra <code>rpc_address</code> to another address if necessary.
+ * @param {String} address the address of a node as returned by Cassandra.
+ * <p>
+ * Note that if the <code>rpc_address</code> of a node has been configured to <code>0.0.0.0</code>
+ * server side, then the provided address will be the node <code>listen_address</code>,
+ * *not* <code>0.0.0.0</code>.
+ * </p>
+ * @param {Number} port The port number, as specified in the [protocolOptions]{@link ClientOptions} at Client instance creation (9042 by default).
+ * @param {Function} callback Callback to invoke with endpoint as first parameter.
+ * The endpoint is an string composed of the IP address and the port number in the format <code>ipAddress:port</code>.
+ */
+AddressTranslator.prototype.translate = function (address, port, callback) {
+	callback(address + ":" + port)
+}
+
+/**
+ * @class
+ * @classdesc
+ * {@link AddressTranslator} implementation for multi-region EC2 deployments <strong>where clients are also deployed in EC2</strong>.
+ * <p>
+ * Its distinctive feature is that it translates addresses according to the location of the Cassandra host:
+ * </p>
+ * <ul>
+ *  <li>addresses in different EC2 regions (than the client) are unchanged</li>
+ *  <li>addresses in the same EC2 region are <strong>translated to private IPs</strong></li>
+ * </ul>
+ * <p>
+ * This optimizes network costs, because Amazon charges more for communication over public IPs.
+ * </p>
+ * @constructor
+ */
+function EC2MultiRegionTranslator() {}
+
+util.inherits(EC2MultiRegionTranslator, AddressTranslator)
+
+/**
+ * Addresses in the same EC2 region are translated to private IPs and addresses in
+ * different EC2 regions (than the client) are unchanged
+ */
+EC2MultiRegionTranslator.prototype.translate = function (
+	address,
+	port,
+	callback,
+) {
+	let newAddress = address
+	const self = this
+	let name
+	utils.series(
+		[
+			function resolve(next) {
+				dns.reverse(address, function (err, hostNames) {
+					if (err) {
+						return next(err)
+					}
+					if (!hostNames) {
+						return next()
+					}
+					name = hostNames[0]
+					next()
+				})
+			},
+			function lookup(next) {
+				if (!name) {
+					return next()
+				}
+				dns.lookup(name, function (err, lookupAddress) {
+					if (err) {
+						return next(err)
+					}
+					newAddress = lookupAddress
+					next()
+				})
+			},
+		],
+		function (err) {
+			if (err) {
+				//there was an issue while doing dns resolution
+				self.logError(address, err)
+			}
+			callback(newAddress + ":" + port)
+		},
+	)
+}
+
+/**
+ * Log method called to log errors that occurred while performing dns resolution.
+ * You can assign your own method to the class instance to do proper logging.
+ * @param {String} address
+ * @param {Error} err
+ */
+EC2MultiRegionTranslator.prototype.logError = function (address, err) {
+	//Do nothing by default
+}
+
+export { AddressTranslator, EC2MultiRegionTranslator }
+
+export default { AddressTranslator, EC2MultiRegionTranslator }

package/driver/policies/index.d.ts

@@ -0,0 +1,241 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+import { Client, EmptyCallback, ExecutionOptions, Host, HostMap } from ".."
+import { types } from "../types"
+
+export namespace policies {
+	function defaultAddressTranslator(): addressResolution.AddressTranslator
+
+	function defaultLoadBalancingPolicy(
+		localDc?: string,
+	): loadBalancing.LoadBalancingPolicy
+
+	function defaultReconnectionPolicy(): reconnection.ReconnectionPolicy
+
+	function defaultRetryPolicy(): retry.RetryPolicy
+
+	function defaultSpeculativeExecutionPolicy(): speculativeExecution.SpeculativeExecutionPolicy
+
+	function defaultTimestampGenerator(): timestampGeneration.TimestampGenerator
+
+	namespace addressResolution {
+		interface AddressTranslator {
+			translate(address: string, port: number, callback: Function): void
+		}
+
+		class EC2MultiRegionTranslator implements AddressTranslator {
+			translate(address: string, port: number, callback: Function): void
+		}
+	}
+
+	namespace loadBalancing {
+		abstract class LoadBalancingPolicy {
+			init(client: Client, hosts: HostMap, callback: EmptyCallback): void
+
+			getDistance(host: Host): types.distance
+
+			newQueryPlan(
+				keyspace: string,
+				executionOptions: ExecutionOptions,
+				callback: (error: Error, iterator: Iterator<Host>) => void,
+			): void
+
+			getOptions(): Map<string, object>
+		}
+
+		class DCAwareRoundRobinPolicy extends LoadBalancingPolicy {
+			constructor(localDc: string)
+		}
+
+		class TokenAwarePolicy extends LoadBalancingPolicy {
+			constructor(childPolicy: LoadBalancingPolicy)
+		}
+
+		class AllowListPolicy extends LoadBalancingPolicy {
+			constructor(childPolicy: LoadBalancingPolicy, allowList: string[])
+		}
+
+		class WhiteListPolicy extends AllowListPolicy {}
+
+		class RoundRobinPolicy extends LoadBalancingPolicy {
+			constructor()
+		}
+
+		class DefaultLoadBalancingPolicy extends LoadBalancingPolicy {
+			constructor(options?: {
+				localDc?: string
+				filter?: (host: Host) => boolean
+			})
+		}
+	}
+
+	namespace reconnection {
+		class ConstantReconnectionPolicy implements ReconnectionPolicy {
+			constructor(delay: number)
+
+			getOptions(): Map<string, object>
+
+			newSchedule(): Iterator<number>
+		}
+
+		class ExponentialReconnectionPolicy implements ReconnectionPolicy {
+			constructor(
+				baseDelay: number,
+				maxDelay: number,
+				startWithNoDelay?: boolean,
+			)
+
+			getOptions(): Map<string, object>
+
+			newSchedule(): Iterator<number>
+		}
+
+		interface ReconnectionPolicy {
+			getOptions(): Map<string, object>
+
+			newSchedule(): Iterator<number>
+		}
+	}
+
+	namespace retry {
+		class DecisionInfo {
+			decision: number
+			consistency: types.consistencies
+		}
+
+		class OperationInfo {
+			query: string
+			executionOptions: ExecutionOptions
+			nbRetry: number
+		}
+
+		class IdempotenceAwareRetryPolicy extends RetryPolicy {
+			constructor(childPolicy: RetryPolicy)
+		}
+
+		class FallthroughRetryPolicy extends RetryPolicy {
+			constructor()
+		}
+
+		class RetryPolicy {
+			onReadTimeout(
+				info: OperationInfo,
+				consistency: types.consistencies,
+				received: number,
+				blockFor: number,
+				isDataPresent: boolean,
+			): DecisionInfo
+
+			onRequestError(
+				info: OperationInfo,
+				consistency: types.consistencies,
+				err: Error,
+			): DecisionInfo
+
+			onUnavailable(
+				info: OperationInfo,
+				consistency: types.consistencies,
+				required: number,
+				alive: boolean,
+			): DecisionInfo
+
+			onWriteTimeout(
+				info: OperationInfo,
+				consistency: types.consistencies,
+				received: number,
+				blockFor: number,
+				writeType: string,
+			): DecisionInfo
+
+			rethrowResult(): DecisionInfo
+
+			retryResult(
+				consistency: types.consistencies,
+				useCurrentHost?: boolean,
+			): DecisionInfo
+		}
+
+		namespace RetryDecision {
+			enum retryDecision {
+				ignore,
+				rethrow,
+				retry,
+			}
+		}
+	}
+
+	namespace speculativeExecution {
+		class ConstantSpeculativeExecutionPolicy implements SpeculativeExecutionPolicy {
+			constructor(delay: number, maxSpeculativeExecutions: number)
+
+			getOptions(): Map<string, object>
+
+			init(client: Client): void
+
+			newPlan(
+				keyspace: string,
+				queryInfo: string | Array<object>,
+			): { nextExecution: Function }
+
+			shutdown(): void
+		}
+
+		class NoSpeculativeExecutionPolicy implements SpeculativeExecutionPolicy {
+			constructor()
+
+			getOptions(): Map<string, object>
+
+			init(client: Client): void
+
+			newPlan(
+				keyspace: string,
+				queryInfo: string | Array<object>,
+			): { nextExecution: Function }
+
+			shutdown(): void
+		}
+
+		interface SpeculativeExecutionPolicy {
+			getOptions(): Map<string, object>
+
+			init(client: Client): void
+
+			newPlan(
+				keyspace: string,
+				queryInfo: string | Array<object>,
+			): { nextExecution: Function }
+
+			shutdown(): void
+		}
+	}
+
+	namespace timestampGeneration {
+		class MonotonicTimestampGenerator implements TimestampGenerator {
+			constructor(warningThreshold: number, minLogInterval: number)
+
+			getDate(): number
+
+			next(client: Client): types.Long | number
+		}
+
+		interface TimestampGenerator {
+			next(client: Client): types.Long | number
+		}
+	}
+}