google-cloud-pubsub 0.33.2 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e93469ccb43f93262792fbcc7c58a076930f3655dc39c059ad2f323305cea78d
-  data.tar.gz: f026ce8b7ca6054fc98c9904a0d4a400fc92f7076cb7c57b575b51f3646101c5
+  metadata.gz: 7e3e1d9e63979754089bd5108e56abee4648fa7cca2db8bd24c5b44b3608047c
+  data.tar.gz: dac86cdbc741948a11d052baa51c470096a49ed3d8fa2900785b70fa74910beb
 SHA512:
-  metadata.gz: 552944e31e98a88fcdeff590ffca5b9a10bfe0150f74feb9c907b92b3597776e64bde50e29115072523f9df8acea495caad3ae61e964095bb8b44dfa9fafe968
-  data.tar.gz: 19a1d398e0255684aa3c8c4269d857cee51c25be4c7e6828741fad86c040ce5de5994a7cc7565644c8610c1939bcbb98ab036349b54db693b843896531135ab9
+  metadata.gz: 0c9a754781fcb85633efcf1ef7fd4f6660f9faafb531e94f8bf9c0b82fcd385069d7ca8ba8cb845b5927b9c1c6d89205387fb877f1b28aa3e59da2eebd226824
+  data.tar.gz: 3b349b5b3aa431a143ba3091f849f21bdde791184d687cf51debf1ba85b44b7e6074b9cac3f7203e27006136b53d438a92a79d8b8db71ec0bc3bbcf211f3144b

data/AUTHENTICATION.md

@@ -78,7 +78,7 @@ The environment variables that Pub/Sub checks for project ID are:
 1. `PUBSUB_PROJECT`
 2. `GOOGLE_CLOUD_PROJECT`
 
-The environment variables that Pub/Sub checks for credentials are configured on {Google::Cloud::Pubsub::V1::Credentials}:
+The environment variables that Pub/Sub checks for credentials are configured on {Google::Cloud::PubSub::V1::Credentials}:
 
 1. `PUBSUB_CREDENTIALS` - Path to JSON file, or JSON contents
 2. `PUBSUB_KEYFILE` - Path to JSON file, or JSON contents
@@ -92,7 +92,7 @@ require "google/cloud/pubsub"
 ENV["PUBSUB_PROJECT"]     = "my-project-id"
 ENV["PUBSUB_CREDENTIALS"] = "path/to/keyfile.json"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 ```
 
 ### Configuration
@@ -102,12 +102,12 @@ The **Project ID** and **Credentials JSON** can be configured instead of placing
 ```ruby
 require "google/cloud/pubsub"
 
-Google::Cloud::Pubsub.configure do |config|
+Google::Cloud::PubSub.configure do |config|
   config.project_id  = "my-project-id"
   config.credentials = "path/to/keyfile.json"
 end
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 ```
 
 ### Cloud SDK

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Release History
 
+### 0.34.0 / 2019-02-01
+
+* Switch to use Google::Cloud::PubSub namespace.
+* Add PubSub on_error configuration.
+* Major updates to Subscriber
+  * Add dependency on current-ruby.
+  * Updates are now made using unary API calls, not the gRPC stream.
+  * Update Subscriber inventory lease mechanics:
+    * This change will help avoid race conditions by ensuring that
+      inventory lease renewal actions don't override ack/nack/delay
+      actions made on a received message via the Subscriber callback.
+  * Changes to avoid potential race conditions in updates.
+* Add reference?/resource? helper methods:
+  * Topic#reference?
+  * Topic#resource?
+  * Subscription#reference?
+  * Subscription#resource?
+* Add documentation for methods that will make an API call
+  when called on a reference object.
+  * Topic#labels
+  * Subscription#topic
+  * Subscription#deadline
+  * Subscription#retain_acked
+  * Subscription#retention
+  * Subscription#endpoint
+  * Subscription#labels
+  * Subscription#exists?
+  * Subscription#listen (without deadline optional argument)
+* Add example code for avoiding API calls to Overview guide.
+* Remove the #delay alias for modify_ack_deadline.
+  * Users should use the modify_ack_deadline and modify_ack_deadline!
+    methods directly instead.
+* Make use of Credentials#project_id
+  * Use Credentials#project_id
+    If a project_id is not provided, use the value on the Credentials object.
+    This value was added in googleauth 0.7.0.
+  * Loosen googleauth dependency
+    Allow for new releases up to 0.10.
+    The googleauth devs have committed to maintanining the current API
+    and will not make backwards compatible changes before 0.10.
+* Update low level API
+  * Add expiration_policy field
+  * Numerous updates and fixes to the low-level documentation,
+    including fixes for some broken links.i
+
 ### 0.33.2 / 2018-10-29
 
 * Rename delay methods to modify_ack_deadline

data/EMULATOR.md

@@ -17,7 +17,7 @@ require "google/cloud/pubsub"
 # Make Pub/Sub use the emulator
 ENV["PUBSUB_EMULATOR_HOST"] = "localhost:8918"
 
-pubsub = Google::Cloud::Pubsub.new "emulator-project-id"
+pubsub = Google::Cloud::PubSub.new "emulator-project-id"
 
 # Get a topic in the current project
 my_topic = pubsub.new_topic "my-topic"
@@ -29,7 +29,7 @@ Or by providing the `emulator_host` argument:
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new emulator_host: "localhost:8918"
+pubsub = Google::Cloud::PubSub.new emulator_host: "localhost:8918"
 
 # Get a topic in the current project
 my_topic = pubsub.new_topic "my-topic"

data/OVERVIEW.md

@@ -17,7 +17,7 @@ Guide}.
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 topic.publish "task completed"
@@ -29,24 +29,24 @@ To learn more about Pub/Sub, read the [Google Cloud Pub/Sub Overview
 ## Retrieving Topics
 
 A Topic is a named resource to which messages are sent by publishers. A Topic is
-found by its name. (See {Google::Cloud::Pubsub::Project#topic Project#topic})
+found by its name. (See {Google::Cloud::PubSub::Project#topic Project#topic})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 topic = pubsub.topic "my-topic"
 ```
 
 ## Creating a Topic
 
 A Topic is created from a Project. (See
-{Google::Cloud::Pubsub::Project#create_topic Project#create_topic})
+{Google::Cloud::PubSub::Project#create_topic Project#create_topic})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 topic = pubsub.create_topic "my-topic"
 ```
 
@@ -55,12 +55,12 @@ topic = pubsub.create_topic "my-topic"
 A Subscription is a named resource representing the stream of messages from a
 single, specific Topic, to be delivered to the subscribing application. A
 Subscription is found by its name. (See
-{Google::Cloud::Pubsub::Topic#subscription Topic#subscription})
+{Google::Cloud::PubSub::Topic#subscription Topic#subscription})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 subscription = topic.subscription "my-topic-subscription"
@@ -70,12 +70,12 @@ puts subscription.name
 ## Creating a Subscription
 
 A Subscription is created from a Topic. (See
-{Google::Cloud::Pubsub::Topic#subscribe Topic#subscribe})
+{Google::Cloud::PubSub::Topic#subscribe Topic#subscribe})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 sub = topic.subscribe "my-topic-sub"
@@ -88,7 +88,7 @@ be acknowledged as well as an endpoint URL to push the messages to:
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 sub = topic.subscribe "my-topic-sub",
@@ -100,12 +100,12 @@ sub = topic.subscribe "my-topic-sub",
 
 Messages are published to a topic. Any message published to a topic without a
 subscription will be lost. Ensure the topic has a subscription before
-publishing. (See {Google::Cloud::Pubsub::Topic#publish Topic#publish})
+publishing. (See {Google::Cloud::PubSub::Topic#publish Topic#publish})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 msg = topic.publish "task completed"
@@ -116,7 +116,7 @@ Messages can also be published with attributes:
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 msg = topic.publish "task completed",
@@ -125,13 +125,13 @@ msg = topic.publish "task completed",
 ```
 
 Messages can also be published in batches asynchronously using `publish_async`.
-(See {Google::Cloud::Pubsub::Topic#publish_async Topic#publish_async} and
-{Google::Cloud::Pubsub::AsyncPublisher AsyncPublisher})
+(See {Google::Cloud::PubSub::Topic#publish_async Topic#publish_async} and
+{Google::Cloud::PubSub::AsyncPublisher AsyncPublisher})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 topic.publish_async "task completed" do |result|
@@ -146,12 +146,12 @@ topic.async_publisher.stop.wait!
 ```
 
 Or multiple messages can be published in batches at the same time by passing a
-block to `publish`. (See {Google::Cloud::Pubsub::BatchPublisher BatchPublisher})
+block to `publish`. (See {Google::Cloud::PubSub::BatchPublisher BatchPublisher})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 topic = pubsub.topic "my-topic"
 msgs = topic.publish do |batch|
@@ -164,13 +164,13 @@ end
 ## Receiving messages
 
 Messages can be streamed from a subscription with a subscriber object that is
-created using `listen`. (See {Google::Cloud::Pubsub::Subscription#listen
-Subscription#listen} and {Google::Cloud::Pubsub::Subscriber Subscriber})
+created using `listen`. (See {Google::Cloud::PubSub::Subscription#listen
+Subscription#listen} and {Google::Cloud::PubSub::Subscriber Subscriber})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
@@ -187,12 +187,12 @@ subscriber.stop.wait!
 ```
 
 Messages also can be pulled directly in a one-time operation. (See
-{Google::Cloud::Pubsub::Subscription#pull Subscription#pull})
+{Google::Cloud::PubSub::Subscription#pull Subscription#pull})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 received_messages = sub.pull
@@ -203,7 +203,7 @@ A maximum number of messages to pull can be specified:
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 received_messages = sub.pull max: 10
@@ -216,13 +216,13 @@ to be removed so it cannot be pulled again.
 
 A Message that can be acknowledged is called a ReceivedMessage. ReceivedMessages
 can be acknowledged one at a time: (See
-{Google::Cloud::Pubsub::ReceivedMessage#acknowledge!
+{Google::Cloud::PubSub::ReceivedMessage#acknowledge!
 ReceivedMessage#acknowledge!})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
@@ -239,12 +239,12 @@ subscriber.stop.wait!
 ```
 
 Or, multiple messages can be acknowledged in a single API call: (See
-{Google::Cloud::Pubsub::Subscription#acknowledge Subscription#acknowledge})
+{Google::Cloud::PubSub::Subscription#acknowledge Subscription#acknowledge})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 received_messages = sub.pull
@@ -257,13 +257,13 @@ A message must be acknowledged after it is pulled, or Pub/Sub will mark the
 message for redelivery. The message acknowledgement deadline can delayed if more
 time is needed. This will allow more time to process the message before the
 message is marked for redelivery. (See
-{Google::Cloud::Pubsub::ReceivedMessage#modify_ack_deadline!
+{Google::Cloud::PubSub::ReceivedMessage#modify_ack_deadline!
 ReceivedMessage#modify_ack_deadline!})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 subscriber = sub.listen do |received_message|
@@ -285,7 +285,7 @@ The message can also be made available for immediate redelivery:
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 subscriber = sub.listen do |received_message|
@@ -303,19 +303,57 @@ subscriber.stop.wait!
 ```
 
 Multiple messages can be delayed or made available for immediate redelivery:
-(See {Google::Cloud::Pubsub::Subscription#modify_ack_deadline
+(See {Google::Cloud::PubSub::Subscription#modify_ack_deadline
 Subscription#modify_ack_deadline})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 received_messages = sub.pull
 sub.modify_ack_deadline 120, received_messages
 ```
 
+## Minimizing API calls before receiving and acknowledging messages
+
+A subscription object can be created without making any API calls by providing
+the `skip_lookup` argument to {Google::Cloud::PubSub::Project#subscription
+Project#subscription} or {Google::Cloud::PubSub::Topic#subscription
+Topic#subscription}. A subscriber object can also be created without an API call
+by providing the `deadline` optional argument to
+{Google::Cloud::PubSub::Subscription#listen Subscription#listen}:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+# No API call is made to retrieve the subscription resource.
+sub = pubsub.subscription "my-topic-sub", skip_lookup: true
+
+# No API call is made to retrieve the subscription deadline.
+subscriber = sub.listen deadline: 60 do |received_message|
+  # process message
+  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.wait!
+```
+
+Skipping API calls may be used to avoid `Google::Cloud::PermissionDeniedError`
+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
+complete list of Pub/Sub roles and permissions.
+
 ## Creating a snapshot and using seek
 
 You can create a snapshot to retain the existing backlog on a subscription. The
@@ -325,14 +363,14 @@ operation.
 
 Later, you can use `seek` to reset the subscription's backlog to the snapshot.
 
-(See {Google::Cloud::Pubsub::Subscription#create_snapshot
-Subscription#create_snapshot} and {Google::Cloud::Pubsub::Subscription#seek
+(See {Google::Cloud::PubSub::Subscription#create_snapshot
+Subscription#create_snapshot} and {Google::Cloud::PubSub::Subscription#seek
 Subscription#seek})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
@@ -348,13 +386,13 @@ sub.seek snapshot
 
 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})
+{Google::Cloud::PubSub::Subscription#listen Subscription#listen} and
+{Google::Cloud::PubSub::Subscriber Subscriber})
 
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
@@ -378,7 +416,7 @@ messages.
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new
+pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
@@ -395,7 +433,7 @@ subscriber.start
 ## Working Across Projects
 
 All calls to the Pub/Sub service use the same project and credentials provided
-to the {Google::Cloud::Pubsub.new Pubsub.new} method. However, it is common to
+to the {Google::Cloud::PubSub.new PubSub.new} method. However, it is common to
 reference topics or subscriptions in other projects, which can be achieved by
 using the `project` option. The main credentials must have permissions to the
 topics and subscriptions in other projects.
@@ -403,7 +441,7 @@ topics and subscriptions in other projects.
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new # my-project
+pubsub = Google::Cloud::PubSub.new # my-project
 
 # Get a topic in the current project
 my_topic = pubsub.topic "my-topic"
@@ -419,7 +457,7 @@ from a topic in another project:
 ```ruby
 require "google/cloud/pubsub"
 
-pubsub = Google::Cloud::Pubsub.new # my-project
+pubsub = Google::Cloud::PubSub.new # my-project
 
 # Get a topic in another project
 topic = pubsub.topic "other-topic", project: "other-project-id"