google-cloud-pubsub 1.0.2 → 2.19.0

data/OVERVIEW.md

@@ -8,11 +8,11 @@ developers to communicate between independently written applications.
 
 The goal of google-cloud is to provide an API that is comfortable to Rubyists.
 Your authentication credentials are detected automatically in Google Cloud
-Platform environments such as Google Compute Engine, Google App Engine and
-Google Kubernetes Engine. In other environments you can configure authentication
-easily, either directly in your code or via environment variables. Read more
-about the options for connecting in the {file:AUTHENTICATION.md Authentication
-Guide}.
+Platform (GCP), including Google Compute Engine (GCE), Google Kubernetes Engine
+(GKE), Google App Engine (GAE), Google Cloud Functions (GCF) and Cloud Run. In
+other environments you can configure authentication easily, either directly in
+your code or via environment variables. Read more about the options for
+connecting in the {file:AUTHENTICATION.md Authentication Guide}.
 
 ```ruby
 require "google/cloud/pubsub"
@@ -142,7 +142,7 @@ topic.publish_async "task completed" do |result|
   end
 end
 
-topic.async_publisher.stop.wait!
+topic.async_publisher.stop!
 ```
 
 Or multiple messages can be published in batches at the same time by passing a
@@ -161,7 +161,7 @@ msgs = topic.publish do |batch|
 end
 ```
 
-## Receiving messages
+## Receiving Messages
 
 Messages can be streamed from a subscription with a subscriber object that is
 created using `listen`. (See {Google::Cloud::PubSub::Subscription#listen
@@ -174,28 +174,47 @@ pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
-subscriber = sub.listen do |received_message|
+# Create a subscriber to listen for available messages.
+# By default, this block will be called on 8 concurrent threads
+# but this can be tuned with the `threads` option.
+# The `streams` and `inventory` parameters allow further tuning.
+subscriber = sub.listen threads: { callback: 16 } do |received_message|
   # process message
+  puts "Data: #{received_message.message.data}, published at #{received_message.message.published_at}"
   received_message.acknowledge!
 end
 
+# Handle exceptions from listener
+subscriber.on_error do |exception|
+  puts "Exception: #{exception.class} #{exception.message}"
+end
+
+# Gracefully shut down the subscriber on program exit, blocking until
+# all received messages have been processed or 10 seconds have passed
+at_exit do
+  subscriber.stop!(10)
+end
+
 # Start background threads that will call the block passed to listen.
 subscriber.start
 
-# Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+# Block, letting processing threads continue in the background
+sleep
 ```
 
 Messages also can be pulled directly in a one-time operation. (See
 {Google::Cloud::PubSub::Subscription#pull Subscription#pull})
 
+The `immediate: false` option is recommended to avoid adverse impacts on the
+performance of pull operations.
+
 ```ruby
 require "google/cloud/pubsub"
 
 pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
-received_messages = sub.pull
+received_messages = sub.pull immediate: false
 ```
 
 A maximum number of messages to pull can be specified:
@@ -206,7 +225,7 @@ require "google/cloud/pubsub"
 pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
-received_messages = sub.pull max: 10
+received_messages = sub.pull immediate: false, max: 10
 ```
 
 ## Acknowledging a Message
@@ -235,7 +254,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 Or, multiple messages can be acknowledged in a single API call: (See
@@ -247,7 +266,7 @@ require "google/cloud/pubsub"
 pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
-received_messages = sub.pull
+received_messages = sub.pull immediate: false
 sub.acknowledge received_messages
 ```
 
@@ -277,7 +296,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 The message can also be made available for immediate redelivery:
@@ -299,7 +318,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 Multiple messages can be delayed or made available for immediate redelivery:
@@ -312,10 +331,92 @@ require "google/cloud/pubsub"
 pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
-received_messages = sub.pull
+received_messages = sub.pull immediate: false
 sub.modify_ack_deadline 120, received_messages
 ```
 
+## Using Ordering Keys
+
+Google Cloud Pub/Sub ordering keys provide the ability to ensure related
+messages are sent to subscribers in the order in which they were published.
+Messages can be tagged with an ordering key, a string that identifies related
+messages for which publish order should be respected. The service guarantees
+that, for a given ordering key and publisher, messages are sent to subscribers
+in the order in which they were published. Ordering does not require sacrificing
+high throughput or scalability, as the service automatically distributes
+messages for different ordering keys across subscribers.
+
+Note: At the time of this release, ordering keys are not yet publicly enabled
+and requires special project enablements.
+
+### Publishing Ordered Messages
+
+To use ordering keys when publishing messages, a call to
+{Google::Cloud::PubSub::Topic#enable_message_ordering!
+Topic#enable_message_ordering!} must be made and the `ordering_key` argument
+must be provided when calling {Google::Cloud::PubSub::Topic#publish_async
+Topic#publish_async}.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-ordered-topic"
+
+# Ensure that message ordering is enabled.
+topic.enable_message_ordering!
+
+# Publish an ordered message with an ordering key.
+topic.publish_async "task completed",
+                    ordering_key: "task-key"
+
+# Shut down the publisher when ready to stop publishing messages.
+topic.async_publisher.stop!
+```
+
+### Handling errors with Ordered Keys
+
+Ordered messages that fail to publish to the Pub/Sub API due to error will put
+the `ordering_key` in a failed state, and future calls to
+{Google::Cloud::PubSub::Topic#publish_async Topic#publish_async} with the
+`ordering_key` will raise {Google::Cloud::PubSub::OrderingKeyError
+OrderingKeyError}. To allow future messages with the `ordering_key` to be
+published, the `ordering_key` must be passed to
+{Google::Cloud::PubSub::Topic#resume_publish Topic#resume_publish}.
+
+### Receiving Ordered Messages
+
+To use ordering keys when subscribing to messages, the subscription must be
+created with message ordering enabled (See
+{Google::Cloud::PubSub::Topic#subscribe Topic#subscribe} and
+{Google::Cloud::PubSub::Subscription#message_ordering?
+Subscription#message_ordering?}) before calling
+{Google::Cloud::PubSub::Subscription#listen Subscription#listen}. When enabled,
+the subscriber will deliver messages with the same `ordering_key` in the order
+they were published.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-ordered-topic-sub"
+sub.message_ordering? #=> true
+
+subscriber = sub.listen do |received_message|
+  # Messsages with the same ordering_key are received
+  # in the order in which they were published.
+  received_message.acknowledge!
+end
+
+# Start background threads that will call block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop!
+```
+
 ## Minimizing API calls before receiving and acknowledging messages
 
 A subscription object can be created without making any API calls by providing
@@ -343,7 +444,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 Skipping API calls may be used to avoid `Google::Cloud::PermissionDeniedError`
@@ -351,7 +452,7 @@ if your account has limited access to the Pub/Sub API. In particular, the role
 `roles/pubsub.subscriber` does not have the permission
 `pubsub.subscriptions.get`, which is required to retrieve a subscription
 resource. See [Access Control -
-Roles](https://cloud.google.com/pubsub/docs/access-control#tbl_roles) for the
+Roles](https://cloud.google.com/pubsub/docs/access-control#roles) for the
 complete list of Pub/Sub roles and permissions.
 
 ## Creating a snapshot and using seek
@@ -376,60 +477,12 @@ sub = pubsub.subscription "my-topic-sub"
 
 snapshot = sub.create_snapshot
 
-received_messages = sub.pull
+received_messages = sub.pull immediate: false
 sub.acknowledge received_messages
 
 sub.seek snapshot
 ```
 
-## Listening for Messages
-
-A subscriber object can be created using `listen`, which streams messages from
-the backend and processes them as they are received. (See
-{Google::Cloud::PubSub::Subscription#listen Subscription#listen} and
-{Google::Cloud::PubSub::Subscriber Subscriber})
-
-```ruby
-require "google/cloud/pubsub"
-
-pubsub = Google::Cloud::PubSub.new
-
-sub = pubsub.subscription "my-topic-sub"
-
-subscriber = sub.listen do |received_message|
-  # process message
-  received_message.acknowledge!
-end
-
-# Start background threads that will call the block passed to listen.
-subscriber.start
-
-# Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
-```
-
-The subscriber object can be configured to control the number of concurrent
-streams to open, the number of received messages to be collected, and the number
-of threads each stream opens for concurrent calls made to handle the received
-messages.
-
-```ruby
-require "google/cloud/pubsub"
-
-pubsub = Google::Cloud::PubSub.new
-
-sub = pubsub.subscription "my-topic-sub"
-
-subscriber = sub.listen threads: { callback: 16 } do |received_message|
-  # store the message somewhere before acknowledging
-  store_in_backend received_message.data # takes a few seconds
-  received_message.acknowledge!
-end
-
-# Start background threads that will call the block passed to listen.
-subscriber.start
-```
-
 ## Working Across Projects
 
 All calls to the Pub/Sub service use the same project and credentials provided

data/TROUBLESHOOTING.md

@@ -24,14 +24,8 @@ improved, *please* create a new issue on GitHub so we can talk about it.
 
   - [New issue][gh-ruby]
 
-Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
-can use the "ruby" channel for general Ruby questions, or use the
-"google-cloud-ruby" channel if you have questions about this gem in particular.
-
 [so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+pubsub
 
-[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+pubsub%22
-
-[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
+[gh-search-ruby]: https://github.com/googleapis/google-cloud-ruby/issues?q=label%3A%22api%3A+pubsub%22
 
-[slack-ruby]: https://gcp-slack.appspot.com/
+[gh-ruby]: https://github.com/googleapis/google-cloud-ruby/issues/new

data/lib/google/cloud/pubsub/acknowledge_result.rb

@@ -0,0 +1,79 @@
+# Copyright 2022 Google LLC
+#
+# Licensed 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
+#
+#     https://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.
+
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # The result of a ack/nack/modack on messages.
+      #
+      # When the operation was successful the result will be marked
+      # {#succeeded?}. Otherwise, the result will be marked {#failed?} and the
+      # error raised will be availabe on {#error}.
+      #
+      class AcknowledgeResult
+        ##
+        # The constants below represents the status of ack/modack operations.
+        # Indicates successful ack/modack
+        SUCCESS = 1
+
+        ##
+        # Indicates occurence of permenant permission denied error
+        PERMISSION_DENIED = 2
+
+        ##
+        # Indicates occurence of permenant failed precondition error
+        FAILED_PRECONDITION = 3
+
+        ##
+        # Indicates occurence of permenant permission denied error
+        INVALID_ACK_ID = 4
+
+        ##
+        # Indicates occurence of permenant uncatogorised error
+        OTHER = 5
+
+        ##
+        # @return [Google::Cloud::Error] Error object of ack/modack operation
+        attr_reader :error
+
+        ##
+        # @return [Numeric] Status of the ack/modack operation.
+        attr_reader :status
+
+        ##
+        # @private Create an PublishResult object.
+        def initialize status, error = nil
+          @error = error
+          @status = status
+        end
+
+        ##
+        # @return [Boolean] Whether the operation was successful.
+        def succeeded?
+          @status == SUCCESS
+        end
+
+        ##
+        # @return [Boolean] Whether the operation failed.
+        def failed?
+          !succeeded?
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end