@ragestudio/scylla-odm 0.22.2 → 0.22.4

package/driver/types/protocol-version.js

@@ -0,0 +1,391 @@
+/*
+ * 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 utils from "../utils.js"
+import VersionNumber from "./version-number.js"
+
+const v200 = VersionNumber.parse("2.0.0")
+const v210 = VersionNumber.parse("2.1.0")
+const v220 = VersionNumber.parse("2.2.0")
+const v300 = VersionNumber.parse("3.0.0")
+const v510 = VersionNumber.parse("5.1.0")
+const v600 = VersionNumber.parse("6.0.0")
+
+/**
+ * Contains information for the different protocol versions supported by the driver.
+ * @type {Object}
+ * @property {Number} v1 Cassandra protocol v1, supported in Apache Cassandra 1.2-->2.2.
+ * @property {Number} v2 Cassandra protocol v2, supported in Apache Cassandra 2.0-->2.2.
+ * @property {Number} v3 Cassandra protocol v3, supported in Apache Cassandra 2.1-->3.x.
+ * @property {Number} v4 Cassandra protocol v4, supported in Apache Cassandra 2.2-->3.x.
+ * @property {Number} v5 Cassandra protocol v5, in beta from Apache Cassandra 3.x+. Currently not supported by the
+ * driver.
+ * @property {Number} dseV1 DataStax Enterprise protocol v1, DSE 5.1+
+ * @property {Number} dseV2 DataStax Enterprise protocol v2, DSE 6.0+
+ * @property {Number} maxSupported Returns the higher protocol version that is supported by this driver.
+ * @property {Number} minSupported Returns the lower protocol version that is supported by this driver.
+ * @property {Function} isSupported A function that returns a boolean determining whether a given protocol version
+ * is supported.
+ * @alias module:types~protocolVersion
+ */
+const protocolVersion = {
+	// Strict equality operators to compare versions are allowed, other comparison operators are discouraged. Instead,
+	// use a function that checks if a functionality is present on a certain version, for maintainability purposes.
+	v1: 0x01,
+	v2: 0x02,
+	v3: 0x03,
+	v4: 0x04,
+	v5: 0x05,
+	v6: 0x06,
+	dseV1: 0x41,
+	dseV2: 0x42,
+	maxSupported: 0x42,
+	minSupported: 0x01,
+
+	/**
+	 * Determines whether the protocol version is a DSE-specific protocol version.
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	isDse: function (version) {
+		return version >= this.dseV1 && version <= this.dseV2
+	},
+	/**
+	 * Returns true if the protocol version represents a version of Cassandra
+	 * supported by this driver, false otherwise
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	isSupportedCassandra: function (version) {
+		return version <= 0x04 && version >= 0x01
+	},
+	/**
+	 * Determines whether the protocol version is supported by this driver.
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	isSupported: function (version) {
+		return this.isDse(version) || this.isSupportedCassandra(version)
+	},
+
+	/**
+	 * Determines whether the protocol includes flags for PREPARE messages.
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	supportsPrepareFlags: function (version) {
+		return version === this.dseV2
+	},
+	/**
+	 * Determines whether the protocol supports sending the keyspace as part of PREPARE, QUERY, EXECUTE, and BATCH.
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	supportsKeyspaceInRequest: function (version) {
+		return version === this.dseV2
+	},
+	/**
+	 * Determines whether the protocol supports result_metadata_id on `prepared` response and
+	 * and `execute` request.
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	supportsResultMetadataId: function (version) {
+		return version === this.dseV2
+	},
+	/**
+	 * Determines whether the protocol supports partition key indexes in the `prepared` RESULT responses.
+	 * @param {Number} version
+	 * @returns {Boolean}
+	 * @ignore
+	 */
+	supportsPreparedPartitionKey: function (version) {
+		return version >= this.v4
+	},
+	/**
+	 * Determines whether the protocol supports up to 4 strings (ie: change_type, target, keyspace and table) in the
+	 * schema change responses.
+	 * @param version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsSchemaChangeFullMetadata: function (version) {
+		return version >= this.v3
+	},
+	/**
+	 * Determines whether the protocol supports continuous paging.
+	 * @param version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsContinuousPaging: function (version) {
+		return this.isDse(version)
+	},
+	/**
+	 * Determines whether the protocol supports paging state and serial consistency parameters in QUERY and EXECUTE
+	 * requests.
+	 * @param version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsPaging: function (version) {
+		return version >= this.v2
+	},
+	/**
+	 * Determines whether the protocol supports timestamps parameters in BATCH, QUERY and EXECUTE requests.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsTimestamp: function (version) {
+		return version >= this.v3
+	},
+	/**
+	 * Determines whether the protocol supports named parameters in QUERY and EXECUTE requests.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsNamedParameters: function (version) {
+		return version >= this.v3
+	},
+	/**
+	 * Determines whether the protocol supports unset parameters.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsUnset: function (version) {
+		return version >= this.v4
+	},
+	/**
+	 * Determines whether the protocol provides a reason map for read and write failure errors.
+	 * @param version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	supportsFailureReasonMap: function (version) {
+		return version >= this.v5
+	},
+	/**
+	 * Determines whether the protocol supports timestamp and serial consistency parameters in BATCH requests.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	uses2BytesStreamIds: function (version) {
+		return version >= this.v3
+	},
+	/**
+	 * Determines whether the collection length is encoded using 32 bits.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	uses4BytesCollectionLength: function (version) {
+		return version >= this.v3
+	},
+	/**
+	 * Determines whether the QUERY, EXECUTE and BATCH flags are encoded using 32 bits.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	uses4BytesQueryFlags: function (version) {
+		return this.isDse(version)
+	},
+	/**
+	 * Startup responses using protocol v4+ can be a SERVER_ERROR wrapping a ProtocolException, this method returns true
+	 * when is possible to receive such error.
+	 * @param {Number} version
+	 * @return {boolean}
+	 * @ignore
+	 */
+	canStartupResponseErrorBeWrapped: function (version) {
+		return version >= this.v4
+	},
+	/**
+	 * Gets the first version number that is supported, lower than the one provided.
+	 * Returns zero when there isn't a lower supported version.
+	 * @param {Number} version
+	 * @return {Number}
+	 * @ignore
+	 */
+	getLowerSupported: function (version) {
+		if (version >= this.v5) {
+			return this.v4
+		}
+		if (version <= this.v1) {
+			return 0
+		}
+		return version - 1
+	},
+
+	/**
+	 * Computes the highest supported protocol version collectively by the given hosts.
+	 *
+	 * Considers the cassandra_version of the input hosts to determine what protocol versions
+	 * are supported and uses the highest common protocol version among them.
+	 *
+	 * If hosts >= C* 3.0 are detected, any hosts older than C* 2.1 will not be considered
+	 * as those cannot be connected to.  In general this will not be a problem as C* does
+	 * not support clusters with nodes that have versions that are more than one major
+	 * version away from each other.
+	 * @param {Connection} connection Connection hosts were discovered from.
+	 * @param {Array.<Host>} hosts The hosts to determine highest protocol version from.
+	 * @return {Number} Highest supported protocol version among hosts.
+	 */
+	getHighestCommon: function (connection, hosts) {
+		const log = connection.log
+			? connection.log.bind(connection)
+			: utils.noop
+		let maxVersion = connection.protocolVersion
+		// whether or not protocol v3 is required (nodes detected that don't support < 3).
+		let v3Requirement = false
+		// track the common protocol version >= v3 in case we encounter older versions.
+		let maxVersionWith3OrMore = maxVersion
+		hosts.forEach((h) => {
+			let dseVersion = null
+			if (h.dseVersion) {
+				// As of DSE 5.1, DSE has it's own specific protocol versions.  If we detect 5.1+
+				// consider those protocol versions.
+				dseVersion = VersionNumber.parse(h.dseVersion)
+				log(
+					"verbose",
+					`Encountered host ${h.address} with dse version ${dseVersion}`,
+				)
+				if (dseVersion.compare(v510) >= 0) {
+					v3Requirement = true
+					if (dseVersion.compare(v600) >= 0) {
+						maxVersion = Math.min(this.dseV2, maxVersion)
+					} else {
+						maxVersion = Math.min(this.dseV1, maxVersion)
+					}
+					maxVersionWith3OrMore = maxVersion
+					return
+				}
+				// If DSE < 5.1, we fall back on the cassandra protocol logic.
+			}
+
+			if (!h.cassandraVersion || h.cassandraVersion.length === 0) {
+				log(
+					"warning",
+					"Encountered host " +
+						h.address +
+						" with no cassandra version," +
+						" skipping as part of protocol version evaluation",
+				)
+				return
+			}
+
+			try {
+				const cassandraVersion = VersionNumber.parse(h.cassandraVersion)
+				if (!dseVersion) {
+					log(
+						"verbose",
+						"Encountered host " +
+							h.address +
+							" with cassandra version " +
+							cassandraVersion,
+					)
+				}
+				if (cassandraVersion.compare(v300) >= 0) {
+					// Anything 3.0.0+ has a max protocol version of V4 and requires at least V3.
+					v3Requirement = true
+					maxVersion = Math.min(this.v4, maxVersion)
+					maxVersionWith3OrMore = maxVersion
+				} else if (cassandraVersion.compare(v220) >= 0) {
+					// Cassandra 2.2.x has a max protocol version of V4.
+					maxVersion = Math.min(this.v4, maxVersion)
+					maxVersionWith3OrMore = maxVersion
+				} else if (cassandraVersion.compare(v210) >= 0) {
+					// Cassandra 2.1.x has a max protocol version of V3.
+					maxVersion = Math.min(this.v3, maxVersion)
+					maxVersionWith3OrMore = maxVersion
+				} else if (cassandraVersion.compare(v200) >= 0) {
+					// Cassandra 2.0.x has a max protocol version of V2.
+					maxVersion = Math.min(this.v2, maxVersion)
+				} else {
+					// Anything else is < 2.x and requires protocol version V1.
+					maxVersion = this.v1
+				}
+			} catch (e) {
+				log(
+					"warning",
+					"Encountered host " +
+						h.address +
+						" with unparseable cassandra version " +
+						h.cassandraVersion +
+						" skipping as part of protocol version evaluation",
+				)
+			}
+		})
+
+		if (v3Requirement && maxVersion < this.v3) {
+			const addendum =
+				". This should not be possible as nodes within a cluster can't be separated by more than one major version"
+			if (maxVersionWith3OrMore < this.v3) {
+				log(
+					"error",
+					"Detected hosts that require at least protocol version 0x3, but currently connected to " +
+						connection.address +
+						":" +
+						connection.port +
+						" using protocol version 0x" +
+						maxVersionWith3OrMore +
+						". Will not be able to connect to these hosts" +
+						addendum,
+				)
+			} else {
+				log(
+					"error",
+					"Detected hosts with maximum protocol version of 0x" +
+						maxVersion.toString(16) +
+						" but there are some hosts that require at least version 0x3. Will not be able to connect to these older hosts" +
+						addendum,
+				)
+			}
+			maxVersion = maxVersionWith3OrMore
+		}
+
+		log(
+			"verbose",
+			"Resolved protocol version 0x" +
+				maxVersion.toString(16) +
+				" as the highest common protocol version among hosts",
+		)
+		return maxVersion
+	},
+
+	/**
+	 * Determines if the protocol is a BETA version of the protocol.
+	 * @param {Number} version
+	 * @return {Number}
+	 */
+	isBeta: function (version) {
+		return version === this.v5
+	},
+}
+
+export default protocolVersion

package/driver/types/result-set.js

@@ -0,0 +1,287 @@
+/*
+ * 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 utils from "../utils.js"
+import errors from "../errors.js"
+
+const asyncIteratorSymbol = Symbol.asyncIterator || "@@asyncIterator"
+
+/** @module types */
+
+/**
+ * Creates a new instance of ResultSet.
+ * @class
+ * @classdesc Represents the result of a query.
+ * @param {Object} response
+ * @param {String} host
+ * @param {Object} triedHosts
+ * @param {Number} speculativeExecutions
+ * @param {Number} consistency
+ * @param {Boolean} isSchemaInAgreement
+ * @constructor
+ */
+function ResultSet(
+	response,
+	host,
+	triedHosts,
+	speculativeExecutions,
+	consistency,
+	isSchemaInAgreement,
+) {
+	// if no execution was made at all, set to 0.
+	if (speculativeExecutions === -1) {
+		speculativeExecutions = 0
+	}
+	/**
+	 * Information on the execution of a successful query:
+	 * @member {Object}
+	 * @property {Number} achievedConsistency The consistency level that has been actually achieved by the query.
+	 * @property {String} queriedHost The Cassandra host that coordinated this query.
+	 * @property {Object} triedHosts Gets the associative array of host that were queried before getting a valid response,
+	 * being the last host the one that replied correctly.
+	 * @property {Object} speculativeExecutions The number of speculative executions (not including the first) executed before
+	 * getting a valid response.
+	 * @property {Uuid} traceId Identifier of the trace session.
+	 * @property {Array.<string>} warnings Warning messages generated by the server when executing the query.
+	 * @property {Boolean} isSchemaInAgreement Whether the cluster had reached schema agreement after the execution of
+	 * this query.
+	 * <p>
+	 *   After a successful schema-altering query (ex: creating a table), the driver will check if
+	 *   the cluster's nodes agree on the new schema version. If not, it will keep retrying for a given
+	 *   delay (see <code>protocolOptions.maxSchemaAgreementWaitSeconds</code>).
+	 * </p>
+	 * <p>
+	 *   Note that the schema agreement check is only performed for schema-altering queries For other
+	 *   query types, this method will always return <code>true</code>. If this method returns <code>false</code>,
+	 *   clients can call [Metadata.checkSchemaAgreement()]{@link module:metadata~Metadata#checkSchemaAgreement} later to
+	 *   perform the check manually.
+	 * </p>
+	 */
+	this.info = {
+		queriedHost: host,
+		triedHosts: triedHosts,
+		speculativeExecutions: speculativeExecutions,
+		achievedConsistency: consistency,
+		traceId: null,
+		warnings: null,
+		customPayload: null,
+		isSchemaInAgreement,
+	}
+
+	if (response.flags) {
+		this.info.traceId = response.flags.traceId
+		this.info.warnings = response.flags.warnings
+		this.info.customPayload = response.flags.customPayload
+	}
+
+	/**
+	 * Gets an array rows returned by the query.
+	 * When the result set represents a response from a write query, this property will be <code>undefined</code>.
+	 * When the read query result contains more rows than the fetch size (5000), this property will only contain the
+	 * first rows up to fetch size. To obtain all the rows, you can use the built-in async iterator that will retrieve the
+	 * following pages of results.
+	 * @type {Array<Row>|undefined}
+	 */
+	this.rows = response.rows
+
+	/**
+	 * Gets the row length of the result, regardless if the result has been buffered or not
+	 * @type {Number|undefined}
+	 */
+	this.rowLength = this.rows ? this.rows.length : response.rowLength
+
+	/**
+	 * Gets the columns returned in this ResultSet.
+	 * @type {Array.<{name, type}>}
+	 * @default null
+	 */
+	this.columns = null
+
+	/**
+	 * A string token representing the current page state of query. It can be used in the following executions to
+	 * continue paging and retrieve the remained of the result for the query.
+	 * @type {String|null}
+	 * @default null
+	 */
+	this.pageState = null
+
+	/**
+	 * Method used to manually fetch the next page of results.
+	 * This method is only exposed when using the {@link Client#eachRow} method and there are more rows available in
+	 * following pages.
+	 * @type Function
+	 */
+	this.nextPage = undefined
+
+	/**
+	 * Method used internally to fetch the next page of results using promises.
+	 * @internal
+	 * @ignore
+	 * @type {Function}
+	 */
+	this.nextPageAsync = undefined
+
+	const meta = response.meta
+
+	if (meta) {
+		this.columns = meta.columns
+
+		if (meta.pageState) {
+			this.pageState = meta.pageState.toString("hex")
+
+			// Expose rawPageState internally
+			Object.defineProperty(this, "rawPageState", {
+				value: meta.pageState,
+				enumerable: false,
+			})
+		}
+	}
+}
+
+/**
+ * Returns the first row or null if the result rows are empty.
+ */
+ResultSet.prototype.first = function () {
+	if (this.rows && this.rows.length) {
+		return this.rows[0]
+	}
+	return null
+}
+
+ResultSet.prototype.getPageState = function () {
+	// backward-compatibility
+	return this.pageState
+}
+
+ResultSet.prototype.getColumns = function () {
+	// backward-compatibility
+	return this.columns
+}
+
+/**
+ * When this instance is the result of a conditional update query, it returns whether it was successful.
+ * Otherwise, it returns <code>true</code>.
+ * <p>
+ *   For consistency, this method always returns <code>true</code> for non-conditional queries (although there is
+ *   no reason to call the method in that case). This is also the case for conditional DDL statements
+ *   (CREATE KEYSPACE... IF NOT EXISTS, CREATE TABLE... IF NOT EXISTS), for which the server doesn't return
+ *   information whether it was applied or not.
+ * </p>
+ */
+ResultSet.prototype.wasApplied = function () {
+	if (!this.rows || this.rows.length === 0) {
+		return true
+	}
+	const firstRow = this.rows[0]
+	const applied = firstRow["[applied]"]
+	return typeof applied === "boolean" ? applied : true
+}
+
+/**
+ * Gets the iterator function.
+ * <p>
+ *   Retrieves the iterator of the underlying fetched rows, without causing the driver to fetch the following
+ *   result pages. For more information on result paging,
+ *   [visit the documentation]{@link http://docs.datastax.com/en/developer/nodejs-driver/latest/features/paging/}.
+ * </p>
+ * @alias module:types~ResultSet#@@iterator
+ * @see {@link module:types~ResultSet#@@asyncIterator}
+ * @example <caption>Using for...of statement</caption>
+ * const query = 'SELECT user_id, post_id, content FROM timeline WHERE user_id = ?';
+ * const result = await client.execute(query, [ id ], { prepare: true });
+ * for (const row of result) {
+ *   console.log(row['email']);
+ * }
+ * @returns {Iterator.<Row>}
+ */
+ResultSet.prototype[Symbol.iterator] = function getIterator() {
+	if (!this.rows) {
+		return utils.emptyArray[Symbol.iterator]()
+	}
+	return this.rows[Symbol.iterator]()
+}
+
+/**
+ * Gets the async iterator function.
+ * <p>
+ *   Retrieves the async iterator representing the entire query result, the driver will fetch the following result
+ *   pages.
+ * </p>
+ * <p>Use the async iterator when the query result might contain more rows than the <code>fetchSize</code>.</p>
+ * <p>
+ *   Note that using the async iterator will not affect the internal state of the <code>ResultSet</code> instance.
+ *   You should avoid using both <code>rows</code> property that contains the row instances of the first page of
+ *   results, and the async iterator, that will yield all the rows in the result regardless on the number of pages.
+ * </p>
+ * <p>Multiple concurrent async iterations are not supported.</p>
+ * @alias module:types~ResultSet#@@asyncIterator
+ * @example <caption>Using for await...of statement</caption>
+ * const query = 'SELECT user_id, post_id, content FROM timeline WHERE user_id = ?';
+ * const result = await client.execute(query, [ id ], { prepare: true });
+ * for await (const row of result) {
+ *   console.log(row['email']);
+ * }
+ * @returns {AsyncIterator<Row>}
+ */
+ResultSet.prototype[asyncIteratorSymbol] = function getAsyncGenerator() {
+	let index = 0
+	let pageState = this.rawPageState
+	let rows = this.rows
+
+	if (!rows || rows.length === 0) {
+		return { next: () => Promise.resolve({ done: true }) }
+	}
+
+	const self = this
+
+	// Async generators are not present in Node 8, implement it manually
+	return {
+		async next() {
+			if (index >= rows.length && pageState) {
+				if (!self.nextPageAsync) {
+					throw new errors.DriverInternalError(
+						"Property nextPageAsync should be set when pageState is defined",
+					)
+				}
+
+				const rs = await self.nextPageAsync(pageState)
+				rows = rs.rows
+				index = 0
+				pageState = rs.rawPageState
+			}
+
+			if (index < rows.length) {
+				return { done: false, value: rows[index++] }
+			}
+
+			return { done: true }
+		},
+	}
+}
+
+/**
+ * Determines whether there are more pages of results.
+ * If so, the driver will initially retrieve and contain only the first page of results.
+ * To obtain all the rows, use the [AsyncIterator]{@linkcode module:types~ResultSet#@@asyncIterator}.
+ * @returns {boolean}
+ */
+ResultSet.prototype.isPaged = function () {
+	return !!this.rawPageState
+}
+
+export default ResultSet