@ragestudio/scylla-odm 0.22.2 → 0.22.4

package/driver/policies/timestamp-generation.js

@@ -0,0 +1,176 @@
+/*
+ * 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 { Long } from "../types/index.js"
+import errors from "../errors.js"
+
+/** @module policies/timestampGeneration */
+
+/**
+ * Defines the maximum date in milliseconds that can be represented in microseconds using Number ((2 ^ 53) / 1000)
+ * @const
+ * @private
+ */
+const _maxSafeNumberDate = 9007199254740
+
+/**
+ * A long representing the value 1000
+ * @const
+ * @private
+ */
+const _longOneThousand = Long.fromInt(1000)
+
+/**
+ * Creates a new instance of {@link TimestampGenerator}.
+ * @classdesc
+ * Generates client-side, microsecond-precision query timestamps.
+ * <p>
+ *   Given that Cassandra uses those timestamps to resolve conflicts, implementations should generate
+ *   monotonically increasing timestamps for successive invocations of {@link TimestampGenerator.next()}.
+ * </p>
+ * @constructor
+ */
+function TimestampGenerator() {}
+
+/**
+ * Returns the next timestamp.
+ * <p>
+ *   Implementors should enforce increasing monotonicity of timestamps, that is,
+ *   a timestamp returned should always be strictly greater that any previously returned
+ *   timestamp.
+ * <p/>
+ * <p>
+ *   Implementors should strive to achieve microsecond precision in the best possible way,
+ *   which is usually largely dependent on the underlying operating system's capabilities.
+ * </p>
+ * @param {Client} client The {@link Client} instance to generate timestamps to.
+ * @returns {Long|Number|null} the next timestamp (in microseconds). If it's equals to <code>null</code>, it won't be
+ * sent by the driver, letting the server to generate the timestamp.
+ * @abstract
+ */
+TimestampGenerator.prototype.next = function (client) {
+	throw new Error("next() must be implemented")
+}
+
+/**
+ * A timestamp generator that guarantees monotonically increasing timestamps and logs warnings when timestamps
+ * drift in the future.
+ * <p>
+ *   {@link Date} has millisecond precision and client timestamps require microsecond precision. This generator
+ *   keeps track of the last generated timestamp, and if the current time is within the same millisecond as the last,
+ *   it fills the microsecond portion of the new timestamp with the value of an incrementing counter.
+ * </p>
+ * @param {Number} [warningThreshold] Determines how far in the future timestamps are allowed to drift before a
+ * warning is logged, expressed in milliseconds. Default: <code>1000</code>.
+ * @param {Number} [minLogInterval] In case of multiple log events, it determines the time separation between log
+ * events, expressed in milliseconds. Use 0 to disable. Default: <code>1000</code>.
+ * @extends {TimestampGenerator}
+ * @constructor
+ */
+function MonotonicTimestampGenerator(warningThreshold, minLogInterval) {
+	if (warningThreshold < 0) {
+		throw new errors.ArgumentError(
+			"warningThreshold can not be lower than 0",
+		)
+	}
+	this._warningThreshold = warningThreshold || 1000
+	this._minLogInterval = 1000
+	if (typeof minLogInterval === "number") {
+		// A value under 1 will disable logging
+		this._minLogInterval = minLogInterval
+	}
+	this._micros = -1
+	this._lastDate = 0
+	this._lastLogDate = 0
+}
+
+util.inherits(MonotonicTimestampGenerator, TimestampGenerator)
+
+/**
+ * Returns the current time in milliseconds since UNIX epoch
+ * @returns {Number}
+ */
+MonotonicTimestampGenerator.prototype.getDate = function () {
+	return Date.now()
+}
+
+MonotonicTimestampGenerator.prototype.next = function (client) {
+	let date = this.getDate()
+	let drifted = 0
+	if (date > this._lastDate) {
+		this._micros = 0
+		this._lastDate = date
+		return this._generateMicroseconds()
+	}
+
+	if (date < this._lastDate) {
+		drifted = this._lastDate - date
+		date = this._lastDate
+	}
+	if (++this._micros === 1000) {
+		this._micros = 0
+		if (date === this._lastDate) {
+			// Move date 1 millisecond into the future
+			date++
+			drifted++
+		}
+	}
+	const lastDate = this._lastDate
+	this._lastDate = date
+	const result = this._generateMicroseconds()
+	if (drifted >= this._warningThreshold) {
+		// Avoid logging an unbounded amount of times within a clock-skew event or during an interval when more than 1
+		// query is being issued by microsecond
+		const currentLogDate = Date.now()
+		if (
+			this._minLogInterval > 0 &&
+			this._lastLogDate + this._minLogInterval <= currentLogDate
+		) {
+			const message = util.format(
+				"Timestamp generated using current date was %d milliseconds behind the last generated timestamp (which " +
+					"millisecond portion was %d), the returned value (%s) is being artificially incremented to guarantee " +
+					"monotonicity.",
+				drifted,
+				lastDate,
+				result,
+			)
+			this._lastLogDate = currentLogDate
+			client.log("warning", message)
+		}
+	}
+	return result
+}
+
+/**
+ * @private
+ * @returns {Number|Long}
+ */
+MonotonicTimestampGenerator.prototype._generateMicroseconds = function () {
+	if (this._lastDate < _maxSafeNumberDate) {
+		// We are safe until Jun 06 2255, its faster to perform this operations on Number than on Long
+		// We hope to have native int64 by then :)
+		return this._lastDate * 1000 + this._micros
+	}
+	return Long.fromNumber(this._lastDate)
+		.multiply(_longOneThousand)
+		.add(Long.fromInt(this._micros))
+}
+
+export { TimestampGenerator, MonotonicTimestampGenerator }
+
+export default { TimestampGenerator, MonotonicTimestampGenerator }

package/driver/prepare-handler.js

@@ -0,0 +1,347 @@
+/*
+ * 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 errors from "./errors.js"
+import utils from "./utils.js"
+import types from "./types/index.js"
+import promiseUtils from "./promise-utils.js"
+
+/**
+ * Encapsulates the logic for dealing with the different prepare request and response flows, including failover when
+ * trying to prepare a query.
+ */
+class PrepareHandler {
+	/**
+	 * Creates a new instance of PrepareHandler
+	 * @param {Client} client
+	 * @param {LoadBalancingPolicy} loadBalancing
+	 */
+	constructor(client, loadBalancing) {
+		this._client = client
+		this._loadBalancing = loadBalancing
+		this.logEmitter = client.options.logEmitter
+		this.log = utils.log
+	}
+
+	/**
+	 * Gets the query id and metadata for a prepared statement, preparing it on
+	 * single host or on all hosts depending on the options.
+	 * @param {Client} client
+	 * @param {LoadBalancingPolicy} loadBalancing
+	 * @param {String} query
+	 * @param {String} keyspace
+	 * @returns {Promise<{queryId, meta}>}
+	 * @static
+	 */
+	static async getPrepared(client, loadBalancing, query, keyspace) {
+		const info = client.metadata.getPreparedInfo(keyspace, query)
+		if (info.queryId) {
+			return info
+		}
+
+		if (info.preparing) {
+			// It's already being prepared
+			return await promiseUtils.fromEvent(info, "prepared")
+		}
+
+		const instance = new PrepareHandler(client, loadBalancing)
+		return await instance._prepare(info, query, keyspace)
+	}
+
+	/**
+	 * @param {Client} client
+	 * @param {LoadBalancingPolicy} loadBalancing
+	 * @param {Array} queries
+	 * @param {String} keyspace
+	 * @static
+	 */
+	static async getPreparedMultiple(client, loadBalancing, queries, keyspace) {
+		const result = []
+
+		for (const item of queries) {
+			let query
+
+			if (item) {
+				query = typeof item === "string" ? item : item.query
+			}
+
+			if (typeof query !== "string") {
+				throw new errors.ArgumentError("Query item should be a string")
+			}
+
+			const { queryId, meta } = await PrepareHandler.getPrepared(
+				client,
+				loadBalancing,
+				query,
+				keyspace,
+			)
+			result.push({
+				query,
+				params: utils.adaptNamedParamsPrepared(
+					item.params,
+					meta.columns,
+				),
+				queryId,
+				meta,
+			})
+		}
+
+		return result
+	}
+
+	/**
+	 * Prepares the query on a single host or on all hosts depending on the options.
+	 * Uses the info 'prepared' event to emit the result.
+	 * @param {Object} info
+	 * @param {String} query
+	 * @param {String} keyspace
+	 * @returns {Promise<{queryId, meta}>}
+	 */
+	async _prepare(info, query, keyspace) {
+		info.preparing = true
+		let iterator
+
+		try {
+			iterator = await promiseUtils.newQueryPlan(
+				this._loadBalancing,
+				keyspace,
+				null,
+			)
+			return await this._prepareWithQueryPlan(
+				info,
+				iterator,
+				query,
+				keyspace,
+			)
+		} catch (err) {
+			info.preparing = false
+			err.query = query
+			info.emit("prepared", err)
+
+			throw err
+		}
+	}
+
+	/**
+	 * Uses the query plan to prepare the query on the first host and optionally on the rest of the hosts.
+	 * @param {Object} info
+	 * @param {Iterator} iterator
+	 * @param {String} query
+	 * @param {String} keyspace
+	 * @returns {Promise<{queryId, meta}>}
+	 * @private
+	 */
+	async _prepareWithQueryPlan(info, iterator, query, keyspace) {
+		const triedHosts = {}
+
+		while (true) {
+			const host = PrepareHandler.getNextHost(
+				iterator,
+				this._client.profileManager,
+				triedHosts,
+			)
+
+			if (host === null) {
+				throw new errors.NoHostAvailableError(triedHosts)
+			}
+
+			try {
+				const connection = await PrepareHandler._borrowWithKeyspace(
+					host,
+					keyspace,
+				)
+				const response = await connection.prepareOnceAsync(
+					query,
+					keyspace,
+				)
+
+				if (this._client.options.prepareOnAllHosts) {
+					await this._prepareOnAllHosts(iterator, query, keyspace)
+				}
+
+				// Set the prepared metadata
+				info.preparing = false
+				info.queryId = response.id
+				info.meta = response.meta
+				this._client.metadata.setPreparedById(info)
+				info.emit("prepared", null, info)
+
+				return info
+			} catch (err) {
+				triedHosts[host.address] = err
+
+				if (
+					!err.isSocketError &&
+					!(err instanceof errors.OperationTimedOutError)
+				) {
+					// There's no point in retrying syntax errors and other response errors
+					throw err
+				}
+			}
+		}
+	}
+
+	/**
+	 * Gets the next host from the query plan.
+	 * @param {Iterator} iterator
+	 * @param {ProfileManager} profileManager
+	 * @param {Object} [triedHosts]
+	 * @return {Host|null}
+	 */
+	static getNextHost(iterator, profileManager, triedHosts) {
+		let host
+		// Get a host that is UP in a sync loop
+		while (true) {
+			const item = iterator.next()
+			if (item.done) {
+				return null
+			}
+
+			host = item.value
+
+			// set the distance relative to the client first
+			const distance = profileManager.getDistance(host)
+			if (distance === types.distance.ignored) {
+				//If its marked as ignore by the load balancing policy, move on.
+				continue
+			}
+
+			if (host.isUp()) {
+				break
+			}
+
+			if (triedHosts) {
+				triedHosts[host.address] = "Host considered as DOWN"
+			}
+		}
+
+		return host
+	}
+
+	/**
+	 * Prepares all queries on a single host.
+	 * @param {Host} host
+	 * @param {Array} allPrepared
+	 */
+	static async prepareAllQueries(host, allPrepared) {
+		const anyKeyspaceQueries = []
+
+		const queriesByKeyspace = new Map()
+		allPrepared.forEach((info) => {
+			let arr
+			if (info.keyspace) {
+				arr = queriesByKeyspace.get(info.keyspace)
+
+				if (!arr) {
+					arr = []
+					queriesByKeyspace.set(info.keyspace, arr)
+				}
+			} else {
+				arr = anyKeyspaceQueries
+			}
+
+			arr.push(info.query)
+		})
+
+		for (const [keyspace, queries] of queriesByKeyspace) {
+			await PrepareHandler._borrowAndPrepare(host, keyspace, queries)
+		}
+
+		await PrepareHandler._borrowAndPrepare(host, null, anyKeyspaceQueries)
+	}
+
+	/**
+	 * Borrows a connection from the host and prepares the queries provided.
+	 * @param {Host} host
+	 * @param {String} keyspace
+	 * @param {Array} queries
+	 * @returns {Promise<void>}
+	 * @private
+	 */
+	static async _borrowAndPrepare(host, keyspace, queries) {
+		if (queries.length === 0) {
+			return
+		}
+
+		const connection = await PrepareHandler._borrowWithKeyspace(
+			host,
+			keyspace,
+		)
+
+		for (const query of queries) {
+			await connection.prepareOnceAsync(query, keyspace)
+		}
+	}
+
+	/**
+	 * Borrows a connection and changes the active keyspace on the connection, if needed.
+	 * It does not perform any retry or error handling.
+	 * @param {Host!} host
+	 * @param {string} keyspace
+	 * @returns {Promise<Connection>}
+	 * @throws {errors.BusyConnectionError} When the connection is busy.
+	 * @throws {errors.ResponseError} For invalid keyspaces.
+	 * @throws {Error} For socket errors.
+	 * @private
+	 */
+	static async _borrowWithKeyspace(host, keyspace) {
+		const connection = host.borrowConnection()
+
+		if (keyspace && connection.keyspace !== keyspace) {
+			await connection.changeKeyspace(keyspace)
+		}
+
+		return connection
+	}
+
+	/**
+	 * Prepares the provided query on all hosts, except the host provided.
+	 * @param {Iterator} iterator
+	 * @param {String} query
+	 * @param {String} keyspace
+	 * @private
+	 */
+	_prepareOnAllHosts(iterator, query, keyspace) {
+		const queries = [query]
+		let h
+		const hosts = []
+
+		while (
+			(h = PrepareHandler.getNextHost(
+				iterator,
+				this._client.profileManager,
+			)) !== null
+		) {
+			hosts.push(h)
+		}
+
+		return Promise.all(
+			hosts.map((h) =>
+				PrepareHandler._borrowAndPrepare(h, keyspace, queries).catch(
+					(err) =>
+						this.log(
+							"verbose",
+							`Unexpected error while preparing query (${query}) on ${h.address}`,
+							err,
+						),
+				),
+			),
+		)
+	}
+}
+
+export default PrepareHandler

package/driver/promise-utils.js

@@ -0,0 +1,191 @@
+/*
+ * 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.
+ */
+
+/**
+ * Creates a non-clearable timer that resolves the promise once elapses.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+	return new Promise((r) => setTimeout(r, ms || 0))
+}
+
+/**
+ * Creates a Promise that gets resolved or rejected based on an event.
+ * @param {object} emitter
+ * @param {string} eventName
+ * @returns {Promise}
+ */
+function fromEvent(emitter, eventName) {
+	return new Promise((resolve, reject) =>
+		emitter.once(eventName, (err, result) => {
+			if (err) {
+				reject(err)
+			} else {
+				resolve(result)
+			}
+		}),
+	)
+}
+
+/**
+ * Creates a Promise from a callback based function.
+ * @param {Function} fn
+ * @returns {Promise}
+ */
+function fromCallback(fn) {
+	return new Promise((resolve, reject) =>
+		fn((err, result) => {
+			if (err) {
+				reject(err)
+			} else {
+				resolve(result)
+			}
+		}),
+	)
+}
+
+/**
+ * Gets a function that has the signature of a callback that invokes the appropriate promise handler parameters.
+ * @param {Function} resolve
+ * @param {Function} reject
+ * @returns {Function}
+ */
+function getCallback(resolve, reject) {
+	return function (err, result) {
+		if (err) {
+			reject(err)
+		} else {
+			resolve(result)
+		}
+	}
+}
+
+async function invokeSequentially(info, length, fn) {
+	let index
+	while ((index = info.counter++) < length) {
+		await fn(index)
+	}
+}
+
+/**
+ * Invokes the new query plan of the load balancing policy and returns a Promise.
+ * @param {LoadBalancingPolicy} lbp The load balancing policy.
+ * @param {String} keyspace Name of currently logged keyspace at <code>Client</code> level.
+ * @param {ExecutionOptions|null} executionOptions The information related to the execution of the request.
+ * @returns {Promise<Iterator>}
+ */
+function newQueryPlan(lbp, keyspace, executionOptions) {
+	return new Promise((resolve, reject) => {
+		lbp.newQueryPlan(keyspace, executionOptions, (err, iterator) => {
+			if (err) {
+				reject(err)
+			} else {
+				resolve(iterator)
+			}
+		})
+	})
+}
+
+/**
+ * Method that handles optional callbacks (dual promise and callback support).
+ * When callback is undefined it returns the promise.
+ * When using a callback, it will use it as handlers of the continuation of the promise.
+ * @param {Promise} promise
+ * @param {Function?} callback
+ * @returns {Promise|undefined}
+ */
+function optionalCallback(promise, callback) {
+	if (!callback) {
+		return promise
+	}
+
+	toCallback(promise, callback)
+}
+
+/**
+ * Invokes the provided function multiple times, considering the concurrency level limit.
+ * @param {Number} count
+ * @param {Number} limit
+ * @param {Function} fn
+ * @returns {Promise}
+ */
+function times(count, limit, fn) {
+	if (limit > count) {
+		limit = count
+	}
+
+	const promises = new Array(limit)
+
+	const info = {
+		counter: 0,
+	}
+
+	for (let i = 0; i < limit; i++) {
+		promises[i] = invokeSequentially(info, count, fn)
+	}
+
+	return Promise.all(promises)
+}
+
+/**
+ * Deals with unexpected rejections in order to avoid the unhandled promise rejection warning or failure.
+ * @param {Promise} promise
+ * @returns {undefined}
+ */
+function toBackground(promise) {
+	promise.catch(() => {})
+}
+
+/**
+ * Invokes the callback once outside the promise chain the promise is resolved or rejected.
+ * @param {Promise} promise
+ * @param {Function?} callback
+ * @returns {undefined}
+ */
+function toCallback(promise, callback) {
+	promise.then(
+		(result) => process.nextTick(() => callback(null, result)),
+		// Avoid marking the promise as rejected
+		(err) => process.nextTick(() => callback(err)),
+	)
+}
+
+export {
+	delay,
+	fromCallback,
+	fromEvent,
+	getCallback,
+	newQueryPlan,
+	optionalCallback,
+	times,
+	toBackground,
+	toCallback,
+}
+
+export default {
+	delay,
+	fromCallback,
+	fromEvent,
+	getCallback,
+	newQueryPlan,
+	optionalCallback,
+	times,
+	toBackground,
+	toCallback,
+}