UNPKG

@azure/storage-queue

Version:
727 lines (726 loc) 29.9 kB
var __defProp = Object.defineProperty; var __getOwnPropDesc = Object.getOwnPropertyDescriptor; var __getOwnPropNames = Object.getOwnPropertyNames; var __hasOwnProp = Object.prototype.hasOwnProperty; var __export = (target, all) => { for (var name in all) __defProp(target, name, { get: all[name], enumerable: true }); }; var __copyProps = (to, from, except, desc) => { if (from && typeof from === "object" || typeof from === "function") { for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable }); } return to; }; var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod); var QueueClient_exports = {}; __export(QueueClient_exports, { QueueClient: () => QueueClient }); module.exports = __toCommonJS(QueueClient_exports); var import_core_auth = require("@azure/core-auth"); var import_core_util = require("@azure/core-util"); var import_Pipeline = require("./Pipeline.js"); var import_StorageClient = require("./StorageClient.js"); var import_utils_common = require("./utils/utils.common.js"); var import_storage_common = require("@azure/storage-common"); var import_storage_common2 = require("@azure/storage-common"); var import_tracing = require("./utils/tracing.js"); var import_QueueSASSignatureValues = require("./QueueSASSignatureValues.js"); var import_core_rest_pipeline = require("@azure/core-rest-pipeline"); class QueueClient extends import_StorageClient.StorageClient { /** * messagesContext provided by protocol layer. */ messagesContext; /** * queueContext provided by protocol layer. */ queueContext; _name; _messagesUrl; /** * The name of the queue. */ get name() { return this._name; } constructor(urlOrConnectionString, credentialOrPipelineOrQueueName, options) { options = options || {}; let pipeline; let url; if ((0, import_Pipeline.isPipelineLike)(credentialOrPipelineOrQueueName)) { url = urlOrConnectionString; pipeline = credentialOrPipelineOrQueueName; } else if (import_core_util.isNode && credentialOrPipelineOrQueueName instanceof import_storage_common.StorageSharedKeyCredential || credentialOrPipelineOrQueueName instanceof import_storage_common2.AnonymousCredential || (0, import_core_auth.isTokenCredential)(credentialOrPipelineOrQueueName)) { url = urlOrConnectionString; pipeline = (0, import_Pipeline.newPipeline)(credentialOrPipelineOrQueueName, options); } else if (!credentialOrPipelineOrQueueName && typeof credentialOrPipelineOrQueueName !== "string") { url = urlOrConnectionString; pipeline = (0, import_Pipeline.newPipeline)(new import_storage_common2.AnonymousCredential(), options); } else if (credentialOrPipelineOrQueueName && typeof credentialOrPipelineOrQueueName === "string") { const extractedCreds = (0, import_utils_common.extractConnectionStringParts)(urlOrConnectionString); if (extractedCreds.kind === "AccountConnString") { if (import_core_util.isNode) { const queueName = credentialOrPipelineOrQueueName; const sharedKeyCredential = new import_storage_common.StorageSharedKeyCredential( extractedCreds.accountName, extractedCreds.accountKey ); url = (0, import_utils_common.appendToURLPath)(extractedCreds.url, queueName); if (!options.proxyOptions) { options.proxyOptions = (0, import_core_rest_pipeline.getDefaultProxySettings)(extractedCreds.proxyUri); } pipeline = (0, import_Pipeline.newPipeline)(sharedKeyCredential, options); } else { throw new Error("Account connection string is only supported in Node.js environment"); } } else if (extractedCreds.kind === "SASConnString") { const queueName = credentialOrPipelineOrQueueName; url = (0, import_utils_common.appendToURLPath)(extractedCreds.url, queueName) + "?" + extractedCreds.accountSas; pipeline = (0, import_Pipeline.newPipeline)(new import_storage_common2.AnonymousCredential(), options); } else { throw new Error( "Connection string must be either an Account connection string or a SAS connection string" ); } } else { throw new Error("Expecting non-empty strings for queueName parameter"); } super(url, pipeline); this._name = this.getQueueNameFromUrl(); this.queueContext = this.storageClientContext.queue; const partsOfUrl = this.url.split("?"); this._messagesUrl = partsOfUrl[1] ? (0, import_utils_common.appendToURLPath)(partsOfUrl[0], "messages") + "?" + partsOfUrl[1] : (0, import_utils_common.appendToURLPath)(partsOfUrl[0], "messages"); this.messagesContext = (0, import_StorageClient.getStorageClientContext)(this._messagesUrl, this.pipeline).messages; } getMessageIdContext(messageId) { const partsOfUrl = this._messagesUrl.split("?"); const urlWithMessageId = partsOfUrl[1] ? (0, import_utils_common.appendToURLPath)(partsOfUrl[0], messageId) + "?" + partsOfUrl[1] : (0, import_utils_common.appendToURLPath)(partsOfUrl[0], messageId); return (0, import_StorageClient.getStorageClientContext)(urlWithMessageId, this.pipeline).messageId; } /** * Creates a new queue under the specified account. * @see https://learn.microsoft.com/rest/api/storageservices/create-queue4 * * @param options - Options to Queue create operation. * @returns Response data for the Queue create operation. * * Example usage: * * ```ts snippet:ReadmeSampleCreateQueue * import { QueueServiceClient } from "@azure/storage-queue"; * import { DefaultAzureCredential } from "@azure/identity"; * * const account = "<account>"; * const queueServiceClient = new QueueServiceClient( * `https://${account}.queue.core.windows.net`, * new DefaultAzureCredential(), * ); * * const queueName = "<valid queue name>"; * const queueClient = queueServiceClient.getQueueClient(queueName); * const createQueueResponse = await queueClient.create(); * console.log( * `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`, * ); * ``` */ async create(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-create", options, async (updatedOptions) => { return (0, import_utils_common.assertResponse)( await this.queueContext.create(updatedOptions) ); }); } /** * Creates a new queue under the specified account if it doesn't already exist. * If the queue already exists, it is not changed. * @see https://learn.microsoft.com/rest/api/storageservices/create-queue4 * * @param options - */ async createIfNotExists(options = {}) { return import_tracing.tracingClient.withSpan( "QueueClient-createIfNotExists", options, async (updatedOptions) => { try { const response = await this.create(updatedOptions); if (response._response.status === 204) { return { succeeded: false, ...response }; } return { succeeded: true, ...response }; } catch (e) { if (e.details?.errorCode === "QueueAlreadyExists") { return { succeeded: false, ...e.response?.parsedHeaders, _response: e.response }; } throw e; } } ); } /** * Deletes the specified queue permanently if it exists. * @see https://learn.microsoft.com/rest/api/storageservices/delete-queue3 * * @param options - */ async deleteIfExists(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-deleteIfExists", options, async (updatedOptions) => { try { const res = await this.delete(updatedOptions); return { succeeded: true, ...res }; } catch (e) { if (e.details?.errorCode === "QueueNotFound") { return { succeeded: false, ...e.response?.parsedHeaders, _response: e.response }; } throw e; } }); } /** * Deletes the specified queue permanently. * @see https://learn.microsoft.com/rest/api/storageservices/delete-queue3 * * @param options - Options to Queue delete operation. * @returns Response data for the Queue delete operation. * * Example usage: * * ```ts snippet:ReadmeSampleDeleteQueue * import { QueueServiceClient } from "@azure/storage-queue"; * import { DefaultAzureCredential } from "@azure/identity"; * * const account = "<account>"; * const queueServiceClient = new QueueServiceClient( * `https://${account}.queue.core.windows.net`, * new DefaultAzureCredential(), * ); * * const queueName = "<valid queue name>"; * const queueClient = queueServiceClient.getQueueClient(queueName); * const deleteQueueResponse = await queueClient.delete(); * console.log( * `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`, * ); * ``` */ async delete(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-delete", options, async (updatedOptions) => { return (0, import_utils_common.assertResponse)( await this.queueContext.delete({ abortSignal: options.abortSignal, tracingOptions: updatedOptions.tracingOptions }) ); }); } /** * Returns true if the specified queue exists; false otherwise. * * NOTE: use this function with care since an existing queue might be deleted by other clients or * applications. Vice versa new queues might be added by other clients or applications after this * function completes. * * @param options - options to Exists operation. */ async exists(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-exists", options, async (updatedOptions) => { try { await this.getProperties(updatedOptions); return true; } catch (e) { if (e.statusCode === 404) { return false; } throw e; } }); } /** * Gets all user-defined metadata and system properties for the specified * queue. Metadata is associated with the queue as name-values pairs. * @see https://learn.microsoft.com/rest/api/storageservices/get-queue-metadata * * WARNING: The `metadata` object returned in the response will have its keys in lowercase, even if * they originally contained uppercase characters. This differs from the metadata keys returned by * the `listQueues` method of {@link QueueServiceClient} using the `includeMetadata` option, which * will retain their original casing. * * @param options - Options to Queue get properties operation. * @returns Response data for the Queue get properties operation. */ async getProperties(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-getProperties", options, async (updatedOptions) => { return (0, import_utils_common.assertResponse)( await this.queueContext.getProperties(updatedOptions) ); }); } /** * Sets one or more user-defined name-value pairs for the specified queue. * * If no option provided, or no metadata defined in the option parameter, the queue * metadata will be removed. * @see https://learn.microsoft.com/rest/api/storageservices/set-queue-metadata * * @param metadata - If no metadata provided, all existing metadata will be removed. * @param options - Options to Queue set metadata operation. * @returns Response data for the Queue set metadata operation. */ async setMetadata(metadata, options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-setMetadata", options, async (updatedOptions) => { return (0, import_utils_common.assertResponse)( await this.queueContext.setMetadata({ ...updatedOptions, metadata }) ); }); } /** * Gets details about any stored access policies specified on the queue that may be used with Shared Access Signatures. * * WARNING: JavaScript Date will potential lost precision when parsing start and expiry string. * For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z". * * @see https://learn.microsoft.com/rest/api/storageservices/get-queue-acl * * @param options - Options to Queue get access policy operation. * @returns Response data for the Queue get access policy operation. */ async getAccessPolicy(options = {}) { return import_tracing.tracingClient.withSpan( "QueueClient-getAccessPolicy", options, async (updatedOptions) => { const response = (0, import_utils_common.assertResponse)( await this.queueContext.getAccessPolicy({ abortSignal: options.abortSignal, tracingOptions: updatedOptions.tracingOptions }) ); const res = { _response: response._response, date: response.date, requestId: response.requestId, clientRequestId: response.clientRequestId, signedIdentifiers: [], version: response.version, errorCode: response.errorCode }; for (const identifier of response) { let accessPolicy = void 0; if (identifier.accessPolicy) { accessPolicy = { permissions: identifier.accessPolicy.permissions }; if (identifier.accessPolicy.expiresOn) { accessPolicy.expiresOn = new Date(identifier.accessPolicy.expiresOn); } if (identifier.accessPolicy.startsOn) { accessPolicy.startsOn = new Date(identifier.accessPolicy.startsOn); } } res.signedIdentifiers.push({ accessPolicy, id: identifier.id }); } return res; } ); } /** * Sets stored access policies for the queue that may be used with Shared Access Signatures. * @see https://learn.microsoft.com/rest/api/storageservices/set-queue-acl * * @param queueAcl - * @param options - Options to Queue set access policy operation. * @returns Response data for the Queue set access policy operation. */ async setAccessPolicy(queueAcl, options = {}) { return import_tracing.tracingClient.withSpan( "QueueClient-setAccessPolicy", options, async (updatedOptions) => { const acl = []; for (const identifier of queueAcl || []) { acl.push({ accessPolicy: { expiresOn: identifier.accessPolicy.expiresOn ? (0, import_utils_common.truncatedISO8061Date)(identifier.accessPolicy.expiresOn) : void 0, permissions: identifier.accessPolicy.permissions, startsOn: identifier.accessPolicy.startsOn ? (0, import_utils_common.truncatedISO8061Date)(identifier.accessPolicy.startsOn) : void 0 }, id: identifier.id }); } return (0, import_utils_common.assertResponse)( await this.queueContext.setAccessPolicy({ ...updatedOptions, queueAcl: acl }) ); } ); } /** * Clear deletes all messages from a queue. * @see https://learn.microsoft.com/rest/api/storageservices/clear-messages * * @param options - Options to clear messages operation. * @returns Response data for the clear messages operation. */ async clearMessages(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-clearMessages", options, async (updatedOptions) => { return (0, import_utils_common.assertResponse)( await this.messagesContext.clear(updatedOptions) ); }); } /** * sendMessage adds a new message to the back of a queue. The visibility timeout specifies how long * the message should be invisible to Dequeue and Peek operations. * The message content is up to 64KB in size, and must be in a format that can be included in an XML request with UTF-8 encoding. * To include markup in the message, the contents of the message must either be XML-escaped or Base64-encode. * @see https://learn.microsoft.com/rest/api/storageservices/put-message * * @param messageText - Text of the message to send * @param options - Options to send messages operation. * @returns Response data for the send messages operation. * * Example usage: * * ```ts snippet:ReadmeSampleSendMessage * import { QueueServiceClient } from "@azure/storage-queue"; * import { DefaultAzureCredential } from "@azure/identity"; * * const account = "<account>"; * const queueServiceClient = new QueueServiceClient( * `https://${account}.queue.core.windows.net`, * new DefaultAzureCredential(), * ); * * const queueName = "<valid queue name>"; * const queueClient = queueServiceClient.getQueueClient(queueName); * // Send a message into the queue using the sendMessage method. * const sendMessageResponse = await queueClient.sendMessage("Hello World!"); * console.log( * `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`, * ); * ``` */ async sendMessage(messageText, options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-sendMessage", options, async (updatedOptions) => { const response = (0, import_utils_common.assertResponse)( await this.messagesContext.enqueue( { messageText }, updatedOptions ) ); const item = response[0]; return { _response: response._response, date: response.date, requestId: response.requestId, clientRequestId: response.clientRequestId, version: response.version, errorCode: response.errorCode, messageId: item.messageId, popReceipt: item.popReceipt, nextVisibleOn: item.nextVisibleOn, insertedOn: item.insertedOn, expiresOn: item.expiresOn }; }); } /** * receiveMessages retrieves one or more messages from the front of the queue. * @see https://learn.microsoft.com/rest/api/storageservices/get-messages * * @param options - Options to receive messages operation. * @returns Response data for the receive messages operation. * * Example usage: * * ```ts snippet:ReadmeSampleReceiveMessage * import { QueueServiceClient } from "@azure/storage-queue"; * import { DefaultAzureCredential } from "@azure/identity"; * * const account = "<account>"; * const queueServiceClient = new QueueServiceClient( * `https://${account}.queue.core.windows.net`, * new DefaultAzureCredential(), * ); * * const queueName = "<valid queue name>"; * const queueClient = queueServiceClient.getQueueClient(queueName); * const response = await queueClient.receiveMessages(); * if (response.receivedMessageItems.length === 1) { * const receivedMessageItem = response.receivedMessageItems[0]; * console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`); * const deleteMessageResponse = await queueClient.deleteMessage( * receivedMessageItem.messageId, * receivedMessageItem.popReceipt, * ); * console.log( * `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`, * ); * } * ``` */ async receiveMessages(options = {}) { return import_tracing.tracingClient.withSpan( "QueueClient-receiveMessages", options, async (updatedOptions) => { const response = (0, import_utils_common.assertResponse)(await this.messagesContext.dequeue(updatedOptions)); const res = { _response: response._response, date: response.date, requestId: response.requestId, clientRequestId: response.clientRequestId, receivedMessageItems: [], version: response.version, errorCode: response.errorCode }; for (const item of response) { res.receivedMessageItems.push(item); } return res; } ); } /** * peekMessages retrieves one or more messages from the front of the queue but does not alter the visibility of the message. * @see https://learn.microsoft.com/rest/api/storageservices/peek-messages * * @param options - Options to peek messages operation. * @returns Response data for the peek messages operation. * * Example usage: * * ```ts snippet:ReadmeSamplePeekMessage * import { QueueServiceClient } from "@azure/storage-queue"; * import { DefaultAzureCredential } from "@azure/identity"; * * const account = "<account>"; * const queueServiceClient = new QueueServiceClient( * `https://${account}.queue.core.windows.net`, * new DefaultAzureCredential(), * ); * * const queueName = "<valid queue name>"; * const queueClient = queueServiceClient.getQueueClient(queueName); * const peekMessagesResponse = await queueClient.peekMessages(); * console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`); * ``` */ async peekMessages(options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-peekMessages", options, async (updatedOptions) => { const response = (0, import_utils_common.assertResponse)(await this.messagesContext.peek(updatedOptions)); const res = { _response: response._response, date: response.date, requestId: response.requestId, clientRequestId: response.clientRequestId, peekedMessageItems: [], version: response.version, errorCode: response.errorCode }; for (const item of response) { res.peekedMessageItems.push(item); } return res; }); } /** * deleteMessage permanently removes the specified message from its queue. * @see https://learn.microsoft.com/rest/api/storageservices/delete-message2 * * @param messageId - Id of the message. * @param popReceipt - A valid pop receipt value returned from an earlier call to the receive messages or update message operation. * @param options - Options to delete message operation. * @returns Response data for the delete message operation. */ async deleteMessage(messageId, popReceipt, options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-deleteMessage", options, async (updatedOptions) => { return (0, import_utils_common.assertResponse)( await this.getMessageIdContext(messageId).delete(popReceipt, updatedOptions) ); }); } /** * Update changes a message's visibility timeout and contents. * The message content is up to 64KB in size, and must be in a format that can be included in an XML request with UTF-8 encoding. * To include markup in the message, the contents of the message must either be XML-escaped or Base64-encode. * @see https://learn.microsoft.com/rest/api/storageservices/update-message * * @param messageId - Id of the message * @param popReceipt - A valid pop receipt value returned from an earlier call to the receive messages or update message operation. * @param message - Message to update. If this parameter is undefined, then the content of the message won't be updated. * @param visibilityTimeout - Specifies the new visibility timeout value, in seconds, * relative to server time. The new value must be larger than or equal to 0, * and cannot be larger than 7 days. The visibility timeout of a message cannot * be set to a value later than the expiry time. * A message can be updated until it has been deleted or has expired. * @param options - Options to update message operation. * @returns Response data for the update message operation. */ async updateMessage(messageId, popReceipt, message, visibilityTimeout, options = {}) { return import_tracing.tracingClient.withSpan("QueueClient-updateMessage", options, async (updatedOptions) => { let queueMessage = void 0; if (message !== void 0) { queueMessage = { messageText: message }; } return (0, import_utils_common.assertResponse)( await this.getMessageIdContext(messageId).update(popReceipt, visibilityTimeout || 0, { abortSignal: options.abortSignal, tracingOptions: updatedOptions.tracingOptions, queueMessage }) ); }); } getQueueNameFromUrl() { let queueName; try { const parsedUrl = new URL(this.url); if (parsedUrl.hostname.split(".")[1] === "queue") { queueName = parsedUrl.pathname.split("/")[1]; } else if ((0, import_utils_common.isIpEndpointStyle)(parsedUrl)) { queueName = parsedUrl.pathname.split("/")[2]; } else { queueName = parsedUrl.pathname.split("/")[1]; } if (!queueName) { throw new Error("Provided queueName is invalid."); } return queueName; } catch (error) { throw new Error("Unable to extract queueName with provided information."); } } /** * Only available for QueueClient constructed with a shared key credential. * * Generates a Service Shared Access Signature (SAS) URI based on the client properties * and parameters passed in. The SAS is signed by the shared key credential of the client. * * @see https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas * * @param options - Optional parameters. * @returns The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token. */ generateSasUrl(options) { if (!(this.credential instanceof import_storage_common.StorageSharedKeyCredential)) { throw RangeError( "Can only generate the SAS when the client is initialized with a shared key credential" ); } const sas = (0, import_QueueSASSignatureValues.generateQueueSASQueryParameters)( { queueName: this.name, ...options }, this.credential ).toString(); return (0, import_utils_common.appendToURLQuery)(this.url, sas); } /** * Only available for QueueClient constructed with a shared key credential. * * Generates string to sign for a Service Shared Access Signature (SAS) URI based on the client properties * and parameters passed in. The SAS is signed by the shared key credential of the client. * * @see https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas * * @param options - Optional parameters. * @returns The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token. */ /* eslint-disable-next-line @azure/azure-sdk/ts-naming-options*/ generateSasStringToSign(options) { if (!(this.credential instanceof import_storage_common.StorageSharedKeyCredential)) { throw RangeError( "Can only generate the SAS when the client is initialized with a shared key credential" ); } return (0, import_QueueSASSignatureValues.generateQueueSASQueryParametersInternal)( { queueName: this.name, ...options }, this.credential ).stringToSign; } /** * * Generates a Service Shared Access Signature (SAS) URI based on the client properties * and parameters passed in. The SAS is signed by the user delegation key credential input. * * @see https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas * * @param options - Optional parameters. * @param userDelegationKey - user delegation key used to sign the SAS URI * @returns The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token. */ generateUserDelegationSasUrl(options, userDelegationKey) { const sas = (0, import_QueueSASSignatureValues.generateQueueSASQueryParameters)( { queueName: this.name, ...options }, userDelegationKey, this.accountName ).toString(); return (0, import_utils_common.appendToURLQuery)(this.url, sas); } /** * * Generates a Service Shared Access Signature (SAS) URI based on the client properties * and parameters passed in. The SAS is signed by the user delegation key credential input. * * @see https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas * * @param options - Optional parameters. * @param userDelegationKey - user delegation key used to sign the SAS URI * @returns The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token. */ generateUserDelegationStringToSign(options, userDelegationKey) { return (0, import_QueueSASSignatureValues.generateQueueSASQueryParametersInternal)( { queueName: this.name, ...options }, userDelegationKey, this.accountName ).stringToSign; } } // Annotate the CommonJS export names for ESM import in node: 0 && (module.exports = { QueueClient }); //# sourceMappingURL=QueueClient.js.map