aws-sdk-sqs 1.39.0 → 1.86.0

data/lib/aws-sdk-sqs/queue_poller.rb

@@ -4,7 +4,6 @@ require 'set'
 
 module Aws
   module SQS
-
     # A utility class for long polling messages in a loop. **Messages are
     # automatically deleted from the queue at the end of the given block.**
     #
@@ -181,6 +180,16 @@ module Aws
     #   end
     #   ```
     #
+    # * Configure an {#after_empty_receive} callback.
+    #
+    #   ```
+    #   poller.after_empty_receive do |stats|
+    #     logger.info("requests: #{stats.request_count}")
+    #     logger.info("messages: #{stats.received_message_count}")
+    #     logger.info("last-timestamp: #{stats.last_message_received_at}")
+    #   end
+    #   ```
+    #
     # * Accept a 2nd argument in the poll block, for example:
     #
     #   ```
@@ -203,7 +212,6 @@ module Aws
     #   ```
     #
     class QueuePoller
-
       # @param [String] queue_url
       # @option options [Client] :client
       # @option (see #poll)
@@ -258,6 +266,21 @@ module Aws
         @default_config = @default_config.with(before_request: block) if block_given?
       end
 
+      # Registers a callback that is invoked when the poll requests returns with no messages.
+      # This callback is invoked after the idle timeout is checked.
+      #
+      #     poller.after_empty_receive do |stats|
+      #       # Handle empty receive
+      #     end
+      #
+      # @yieldparam [PollerStats] stats An object that tracks a few
+      #   client-side statistics about the queue polling.
+      #
+      # @return [void]
+      def after_empty_receive(&block)
+        @default_config = @default_config.with(after_empty_receive: block) if block_given?
+      end
+
       # Polls the queue, yielded a message, or an array of messages.
       # Messages are automatically deleted from the queue at the
       # end of the given block. See the class documentation on
@@ -333,7 +356,8 @@ module Aws
           loop do
             messages = get_messages(config, stats)
             if messages.empty?
-              check_idle_timeout(config, stats, messages)
+              check_idle_timeout(config, stats)
+              config.after_empty_receive&.call(stats)
             else
               process_messages(config, stats, messages, &block)
             end
@@ -348,21 +372,21 @@ module Aws
       #   `#receipt_handle`.
       # @param [Integer] seconds
       def change_message_visibility_timeout(message, seconds)
-        @client.change_message_visibility({
+        @client.change_message_visibility(
           queue_url: @queue_url,
           receipt_handle: message.receipt_handle,
-          visibility_timeout: seconds,
-        })
+          visibility_timeout: seconds
+        )
       end
 
       # @note This method should be called from inside a {#poll} block.
       # @param [#receipt_handle] message An object that responds to
       #   `#receipt_handle`.
       def delete_message(message)
-        @client.delete_message({
+        @client.delete_message(
           queue_url: @queue_url,
-          receipt_handle: message.receipt_handle,
-        })
+          receipt_handle: message.receipt_handle
+        )
       end
 
       # @note This method should be called from inside a {#poll} block.
@@ -372,16 +396,16 @@ module Aws
       def delete_messages(messages)
         @client.delete_message_batch(
           queue_url: @queue_url,
-          entries: messages.map { |msg|
+          entries: messages.map do |msg|
             { id: msg.message_id, receipt_handle: msg.receipt_handle }
-          }
+          end
         )
       end
 
       private
 
       def get_messages(config, stats)
-        config.before_request.call(stats) if config.before_request
+        config.before_request&.call(stats)
         messages = send_request(config).messages
         stats.request_count += 1
         messages
@@ -392,17 +416,22 @@ module Aws
         @client.receive_message(params)
       end
 
-      def check_idle_timeout(config, stats, messages)
-        if config.idle_timeout
-          since = stats.last_message_received_at || stats.polling_started_at
-          idle_time = Time.now - since
-          throw :stop_polling if idle_time > config.idle_timeout
-        end
+      def check_idle_timeout(config, stats)
+        return unless config.idle_timeout
+
+        since = stats.last_message_received_at || stats.polling_started_at
+        idle_time = Time.now - since
+        throw :stop_polling if idle_time > config.idle_timeout
       end
 
       def process_messages(config, stats, messages, &block)
         stats.received_message_count += messages.count
         stats.last_message_received_at = Time.now
+
+        # duplicated messages will have a different receipt handle
+        # so we need to provide the most recent receipt to
+        # delete a batch - thus, filtering below by message_id
+        messages = messages.reverse.uniq(&:message_id).reverse!
         catch(:skip_delete) do
           yield_messages(config, messages, stats, &block)
           delete_messages(messages) unless config.skip_delete
@@ -421,7 +450,6 @@ module Aws
 
       # Statistics tracked client-side by the {QueuePoller}.
       class PollerStats
-
         def initialize
           @request_count = 0
           @received_message_count = 0
@@ -444,27 +472,26 @@ module Aws
 
         # @return [Time,nil]
         attr_accessor :polling_stopped_at
-
       end
 
       # A read-only set of configuration used by the QueuePoller.
       class PollerConfig
-
         # @api private
-        CONFIG_OPTIONS = Set.new([
-          :idle_timeout,
-          :skip_delete,
-          :before_request,
-        ])
+        CONFIG_OPTIONS = Set.new %i[
+          idle_timeout
+          skip_delete
+          before_request
+          after_empty_receive
+        ]
 
         # @api private
-        PARAM_OPTIONS = Set.new([
-          :wait_time_seconds,
-          :max_number_of_messages,
-          :visibility_timeout,
-          :attribute_names,
-          :message_attribute_names,
-        ])
+        PARAM_OPTIONS = Set.new %i[
+          wait_time_seconds
+          max_number_of_messages
+          visibility_timeout
+          attribute_names
+          message_attribute_names
+        ]
 
         # @return [Integer,nil]
         attr_reader :idle_timeout
@@ -475,6 +502,9 @@ module Aws
         # @return [Proc,nil]
         attr_reader :before_request
 
+        # @return [Proc,nil]
+        attr_reader :after_empty_receive
+
         # @return [Hash]
         attr_reader :request_params
 
@@ -482,12 +512,13 @@ module Aws
           @idle_timeout = nil
           @skip_delete = false
           @before_request = nil
+          @after_empty_receive = nil
           @request_params = {
             wait_time_seconds: 20,
             max_number_of_messages: 1,
             visibility_timeout: nil,
             attribute_names: ['All'],
-            message_attribute_names: ['All'],
+            message_attribute_names: ['All']
           }
           options.each do |opt_name, value|
             if CONFIG_OPTIONS.include?(opt_name)
@@ -498,6 +529,12 @@ module Aws
               raise ArgumentError, "invalid option #{opt_name.inspect}"
             end
           end
+
+          max_number_of_messages = @request_params[:max_number_of_messages]
+          unless max_number_of_messages.is_a?(Integer) && max_number_of_messages.positive?
+            raise ArgumentError, ':max_number_of_messages must be a positive integer'
+          end
+
           @request_params.freeze
           freeze
         end
@@ -516,7 +553,6 @@ module Aws
           PARAM_OPTIONS.each { |key| hash[key] = @request_params[key] }
           hash
         end
-
       end
     end
   end

data/lib/aws-sdk-sqs/resource.rb

@@ -76,63 +76,101 @@ module Aws::SQS
     #   * `MessageRetentionPeriod` – The length of time, in seconds, for which
     #     Amazon SQS retains a message. Valid values: An integer from 60
     #     seconds (1 minute) to 1,209,600 seconds (14 days). Default: 345,600
-    #     (4 days).
-    #
-    #   * `Policy` – The queue's policy. A valid AWS policy. For more
-    #     information about policy structure, see [Overview of AWS IAM
-    #     Policies][1] in the *Amazon IAM User Guide*.
+    #     (4 days). When you change a queue's attributes, the change can take
+    #     up to 60 seconds for most of the attributes to propagate throughout
+    #     the Amazon SQS system. Changes made to the `MessageRetentionPeriod`
+    #     attribute can take up to 15 minutes and will impact existing
+    #     messages in the queue potentially causing them to be expired and
+    #     deleted if the `MessageRetentionPeriod` is reduced below the age of
+    #     existing messages.
+    #
+    #   * `Policy` – The queue's policy. A valid Amazon Web Services policy.
+    #     For more information about policy structure, see [Overview of Amazon
+    #     Web Services IAM Policies][1] in the *IAM User Guide*.
     #
     #   * `ReceiveMessageWaitTimeSeconds` – The length of time, in seconds,
     #     for which a ` ReceiveMessage ` action waits for a message to arrive.
     #     Valid values: An integer from 0 to 20 (seconds). Default: 0.
     #
+    #   * `VisibilityTimeout` – The visibility timeout for the queue, in
+    #     seconds. Valid values: An integer from 0 to 43,200 (12 hours).
+    #     Default: 30. For more information about the visibility timeout, see
+    #     [Visibility Timeout][2] in the *Amazon SQS Developer Guide*.
+    #
+    #   The following attributes apply only to [dead-letter queues:][3]
+    #
     #   * `RedrivePolicy` – The string that includes the parameters for the
     #     dead-letter queue functionality of the source queue as a JSON
-    #     object. For more information about the redrive policy and
-    #     dead-letter queues, see [Using Amazon SQS Dead-Letter Queues][2] in
-    #     the *Amazon Simple Queue Service Developer Guide*.
+    #     object. The parameters are as follows:
     #
     #     * `deadLetterTargetArn` – The Amazon Resource Name (ARN) of the
     #       dead-letter queue to which Amazon SQS moves messages after the
     #       value of `maxReceiveCount` is exceeded.
     #
     #     * `maxReceiveCount` – The number of times a message is delivered to
-    #       the source queue before being moved to the dead-letter queue. When
-    #       the `ReceiveCount` for a message exceeds the `maxReceiveCount` for
-    #       a queue, Amazon SQS moves the message to the dead-letter-queue.
-    #
-    #     <note markdown="1"> The dead-letter queue of a FIFO queue must also be a FIFO queue.
-    #     Similarly, the dead-letter queue of a standard queue must also be a
-    #     standard queue.
+    #       the source queue before being moved to the dead-letter queue.
+    #       Default: 10. When the `ReceiveCount` for a message exceeds the
+    #       `maxReceiveCount` for a queue, Amazon SQS moves the message to the
+    #       dead-letter-queue.
+    #
+    #   * `RedriveAllowPolicy` – The string that includes the parameters for
+    #     the permissions for the dead-letter queue redrive permission and
+    #     which source queues can specify dead-letter queues as a JSON object.
+    #     The parameters are as follows:
+    #
+    #     * `redrivePermission` – The permission type that defines which
+    #       source queues can specify the current queue as the dead-letter
+    #       queue. Valid values are:
+    #
+    #       * `allowAll` – (Default) Any source queues in this Amazon Web
+    #         Services account in the same Region can specify this queue as
+    #         the dead-letter queue.
+    #
+    #       * `denyAll` – No source queues can specify this queue as the
+    #         dead-letter queue.
+    #
+    #       * `byQueue` – Only queues specified by the `sourceQueueArns`
+    #         parameter can specify this queue as the dead-letter queue.
+    #
+    #     * `sourceQueueArns` – The Amazon Resource Names (ARN)s of the source
+    #       queues that can specify this queue as the dead-letter queue and
+    #       redrive messages. You can specify this parameter only when the
+    #       `redrivePermission` parameter is set to `byQueue`. You can specify
+    #       up to 10 source queue ARNs. To allow more than 10 source queues to
+    #       specify dead-letter queues, set the `redrivePermission` parameter
+    #       to `allowAll`.
+    #
+    #   <note markdown="1"> The dead-letter queue of a FIFO queue must also be a FIFO queue.
+    #   Similarly, the dead-letter queue of a standard queue must also be a
+    #   standard queue.
     #
-    #      </note>
-    #
-    #   * `VisibilityTimeout` – The visibility timeout for the queue, in
-    #     seconds. Valid values: An integer from 0 to 43,200 (12 hours).
-    #     Default: 30. For more information about the visibility timeout, see
-    #     [Visibility Timeout][3] in the *Amazon Simple Queue Service
-    #     Developer Guide*.
+    #    </note>
     #
-    #   The following attributes apply only to [server-side-encryption][4]\:
+    #   The following attributes apply only to [server-side-encryption][4]:
     #
-    #   * `KmsMasterKeyId` – The ID of an AWS-managed customer master key
-    #     (CMK) for Amazon SQS or a custom CMK. For more information, see [Key
-    #     Terms][5]. While the alias of the AWS-managed CMK for Amazon SQS is
-    #     always `alias/aws/sqs`, the alias of a custom CMK can, for example,
-    #     be `alias/MyAlias `. For more examples, see [KeyId][6] in the *AWS
-    #     Key Management Service API Reference*.
+    #   * `KmsMasterKeyId` – The ID of an Amazon Web Services managed customer
+    #     master key (CMK) for Amazon SQS or a custom CMK. For more
+    #     information, see [Key Terms][5]. While the alias of the Amazon Web
+    #     Services managed CMK for Amazon SQS is always `alias/aws/sqs`, the
+    #     alias of a custom CMK can, for example, be `alias/MyAlias `. For
+    #     more examples, see [KeyId][6] in the *Key Management Service API
+    #     Reference*.
     #
     #   * `KmsDataKeyReusePeriodSeconds` – The length of time, in seconds, for
     #     which Amazon SQS can reuse a [data key][7] to encrypt or decrypt
-    #     messages before calling AWS KMS again. An integer representing
-    #     seconds, between 60 seconds (1 minute) and 86,400 seconds (24
-    #     hours). Default: 300 (5 minutes). A shorter time period provides
-    #     better security but results in more calls to KMS which might incur
-    #     charges after Free Tier. For more information, see [How Does the
-    #     Data Key Reuse Period Work?][8].
+    #     messages before calling KMS again. An integer representing seconds,
+    #     between 60 seconds (1 minute) and 86,400 seconds (24 hours).
+    #     Default: 300 (5 minutes). A shorter time period provides better
+    #     security but results in more calls to KMS which might incur charges
+    #     after Free Tier. For more information, see [How Does the Data Key
+    #     Reuse Period Work?][8]
+    #
+    #   * `SqsManagedSseEnabled` – Enables server-side queue encryption using
+    #     SQS owned encryption keys. Only one server-side encryption option is
+    #     supported per queue (for example, [SSE-KMS][9] or [SSE-SQS][10]).
     #
     #   The following attributes apply only to [FIFO (first-in-first-out)
-    #   queues][9]\:
+    #   queues][11]:
     #
     #   * `FifoQueue` – Designates a queue as FIFO. Valid values are `true`
     #     and `false`. If you don't specify the `FifoQueue` attribute, Amazon
@@ -141,13 +179,13 @@ module Aws::SQS
     #     When you set this attribute, you must also provide the
     #     `MessageGroupId` for your messages explicitly.
     #
-    #     For more information, see [FIFO queue logic][10] in the *Amazon
-    #     Simple Queue Service Developer Guide*.
+    #     For more information, see [FIFO queue logic][12] in the *Amazon SQS
+    #     Developer Guide*.
     #
     #   * `ContentBasedDeduplication` – Enables content-based deduplication.
     #     Valid values are `true` and `false`. For more information, see
-    #     [Exactly-once processing][11] in the *Amazon Simple Queue Service
-    #     Developer Guide*. Note the following:
+    #     [Exactly-once processing][13] in the *Amazon SQS Developer Guide*.
+    #     Note the following:
     #
     #     * Every message must have a unique `MessageDeduplicationId`.
     #
@@ -178,7 +216,7 @@ module Aws::SQS
     #       duplicates and only one copy of the message is delivered.
     #
     #   The following attributes apply only to [high throughput for FIFO
-    #   queues][12]\:
+    #   queues][14]:
     #
     #   * `DeduplicationScope` – Specifies whether message deduplication
     #     occurs at the message group or queue level. Valid values are
@@ -201,27 +239,29 @@ module Aws::SQS
     #   deduplication occurs as specified.
     #
     #   For information on throughput quotas, see [Quotas related to
-    #   messages][13] in the *Amazon Simple Queue Service Developer Guide*.
+    #   messages][15] in the *Amazon SQS Developer Guide*.
     #
     #
     #
     #   [1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/PoliciesOverview.html
-    #   [2]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html
-    #   [3]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html
+    #   [2]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html
+    #   [3]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html
     #   [4]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-server-side-encryption.html
     #   [5]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-server-side-encryption.html#sqs-sse-key-terms
     #   [6]: https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html#API_DescribeKey_RequestParameters
     #   [7]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys
     #   [8]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-server-side-encryption.html#sqs-how-does-the-data-key-reuse-period-work
-    #   [9]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html
-    #   [10]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues-understanding-logic.html
-    #   [11]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues-exactly-once-processing.html
-    #   [12]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/high-throughput-fifo.html
-    #   [13]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html
+    #   [9]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-sse-existing-queue.html
+    #   [10]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-sqs-sse-queue.html
+    #   [11]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html
+    #   [12]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues-understanding-logic.html
+    #   [13]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues-exactly-once-processing.html
+    #   [14]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/high-throughput-fifo.html
+    #   [15]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html
     # @option options [Hash<String,String>] :tags
     #   Add cost allocation tags to the specified Amazon SQS queue. For an
-    #   overview, see [Tagging Your Amazon SQS Queues][1] in the *Amazon
-    #   Simple Queue Service Developer Guide*.
+    #   overview, see [Tagging Your Amazon SQS Queues][1] in the *Amazon SQS
+    #   Developer Guide*.
     #
     #   When you use queue tags, keep the following guidelines in mind:
     #
@@ -235,15 +275,15 @@ module Aws::SQS
     #   * A new tag with a key identical to that of an existing tag overwrites
     #     the existing tag.
     #
-    #   For a full list of tag restrictions, see [Limits Related to Queues][2]
-    #   in the *Amazon Simple Queue Service Developer Guide*.
+    #   For a full list of tag restrictions, see [Quotas related to queues][2]
+    #   in the *Amazon SQS Developer Guide*.
     #
     #   <note markdown="1"> To be able to tag a queue on creation, you must have the
     #   `sqs:CreateQueue` and `sqs:TagQueue` permissions.
     #
     #    Cross-account permissions don't apply to this action. For more
-    #   information, see [Grant cross-account permissions to a role and a user
-    #   name][3] in the *Amazon Simple Queue Service Developer Guide*.
+    #   information, see [Grant cross-account permissions to a role and a
+    #   username][3] in the *Amazon SQS Developer Guide*.
     #
     #    </note>
     #
@@ -254,7 +294,9 @@ module Aws::SQS
     #   [3]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-customer-managed-policy-examples.html#grant-cross-account-permissions-to-role-and-user-name
     # @return [Queue]
     def create_queue(options = {})
-      resp = @client.create_queue(options)
+      resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do
+        @client.create_queue(options)
+      end
       Queue.new(
         url: resp.data.queue_url,
         client: @client
@@ -275,10 +317,13 @@ module Aws::SQS
     #
     #   Queue URLs and names are case-sensitive.
     # @option options [String] :queue_owner_aws_account_id
-    #   The AWS account ID of the account that created the queue.
+    #   The Amazon Web Services account ID of the account that created the
+    #   queue.
     # @return [Queue]
     def get_queue_by_name(options = {})
-      resp = @client.get_queue_url(options)
+      resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do
+        @client.get_queue_url(options)
+      end
       Queue.new(
         url: resp.data.queue_url,
         client: @client
@@ -310,7 +355,9 @@ module Aws::SQS
     # @return [Queue::Collection]
     def queues(options = {})
       batches = Enumerator.new do |y|
-        resp = @client.list_queues(options)
+        resp = Aws::Plugins::UserAgent.metric('RESOURCE_MODEL') do
+          @client.list_queues(options)
+        end
         resp.each_page do |page|
           batch = []
           page.data.queue_urls.each do |q|