google-cloud-pubsub 0.34.1 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7e9076f21ca7cc0d91beb6d1a9c47af43dcb4016657ab58f174ee945a13d32e
-  data.tar.gz: eebba9543b5870f7bad014fe56bfa814d4682be7931236b23d202695caece7bb
+  metadata.gz: 9eb65ead0bfa397fca5d4eab13a005d64dabb629da1b0b4638fbbd45fab65cf3
+  data.tar.gz: 01027a9e96bda8a16107309c06eba2f4cd971a56ca851b59463a1958c06a63ec
 SHA512:
-  metadata.gz: 3695804541d32698fd556b9b954a50666ee5584c8b93eda85376801e51be0f286abd829963b78a0946a1effa52cb27b231f18736f10b7f5dcdbeeeb287326da1
-  data.tar.gz: c955d2a764101590c29c8ee821e2cc56a48eaa4fe322fd27c3a238fc9b8cc614f5f11a7ea3fded7b1c8e994c0f35d3597f728a4ea76729b4a0088cfea82475a7
+  metadata.gz: 93dfbbcc2ea3e8cb444ed00bbf92a9d514cbf3868fc7cbe540be112358203c0d0becf16dd36e459accd65a1cb12db589f7e29a8942685418356b8a530ce374c9
+  data.tar.gz: 660f2887f98ddef1f1c5a83f928e4855008f6770c3bbe02ac6f9a1c567ad8bd3dfc160bdbb7abc397de8197ccd27e6d588443c352a8ff3a6b8cfd3e09b3231bb

data/AUTHENTICATION.md

@@ -2,20 +2,39 @@
 
 In general, the google-cloud-pubsub library uses [Service
 Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
-credentials to connect to Google Cloud services. When running on Compute Engine
+credentials to connect to Google Cloud services. When running within [Google
+Cloud Platform environments](#google-cloud-platform-environments)
 the credentials will be discovered automatically. When running on other
 environments, the Service Account credentials can be specified by providing the
 path to the [JSON
 keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
-the account (or the JSON itself) in environment variables. Additionally, Cloud
-SDK credentials can also be discovered automatically, but this is only
-recommended during development.
+the account (or the JSON itself) in [environment
+variables](#environment-variables). Additionally, Cloud SDK credentials can also
+be discovered automatically, but this is only recommended during development.
+
+## Quickstart
+
+1. [Create a service account and credentials](#creating-a-service-account).
+2. Set the [environment variable](#environment-variables).
+
+```sh
+export PUBSUB_CREDENTIALS=/path/to/json`
+```
+
+3. Initialize the client.
+
+```ruby
+require "google/cloud/pubsub"
+
+client = Google::Cloud::PubSub.new
+```
 
 ## Project and Credential Lookup
 
-The google-cloud-pubsub library aims to make authentication as simple as
-possible, and provides several mechanisms to configure your system without
-providing **Project ID** and **Service Account Credentials** directly in code.
+The google-cloud-pubsub library aims to make authentication
+as simple as possible, and provides several mechanisms to configure your system
+without providing **Project ID** and **Service Account Credentials** directly in
+code.
 
 **Project ID** is discovered in the following order:
 
@@ -23,6 +42,7 @@ providing **Project ID** and **Service Account Credentials** directly in code.
 2. Specify project ID in configuration
 3. Discover project ID in environment variables
 4. Discover GCE project ID
+5. Discover project ID in credentials JSON
 
 **Credentials** are discovered in the following order:
 
@@ -73,12 +93,12 @@ environment variable, or the **Credentials JSON** itself can be stored for
 environments such as Docker containers where writing files is difficult or not
 encouraged.
 
-The environment variables that Pub/Sub checks for project ID are:
+The environment variables that google-cloud-pubsub 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 google-cloud-pubsub 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 +112,7 @@ require "google/cloud/pubsub"
 ENV["PUBSUB_PROJECT"]     = "my-project-id"
 ENV["PUBSUB_CREDENTIALS"] = "path/to/keyfile.json"
 
-pubsub = Google::Cloud::PubSub.new
+client = Google::Cloud::PubSub.new
 ```
 
 ### Configuration
@@ -107,7 +127,7 @@ Google::Cloud::PubSub.configure do |config|
   config.credentials = "path/to/keyfile.json"
 end
 
-pubsub = Google::Cloud::PubSub.new
+client = Google::Cloud::PubSub.new
 ```
 
 ### Cloud SDK
@@ -140,7 +160,8 @@ Google Cloud requires a **Project ID** and **Service Account Credentials** to
 connect to the APIs. You will use the **Project ID** and **JSON key file** to
 connect to most services with google-cloud-pubsub.
 
-If you are not running this client on Google Compute Engine, you need a Google
+If you are not running this client within [Google Cloud Platform
+environments](#google-cloud-platform-environments), you need a Google
 Developers service account.
 
 1. Visit the [Google Developers Console][dev-console].

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Release History
 
+### 0.35.0 / 2019-04-25
+
+* Add Subscription#push_config and Subscription::PushConfig
+* Add Subscription#expires_in
+* Add Topic#reload!
+* Add Subscription#reload!
+* Update low-level generated files  
+  * Add PushConfig#oidc_token
+  * Add ordering_key to PubsubMessage.
+  * Add enable_message_ordering to Subscription.
+  * Extract gRPC header values from request.
+  * Update documentation.
+
 ### 0.34.1 / 2019-02-13
 
 * Fix bug (typo) in retrieving default on_error proc.

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

@@ -217,7 +217,8 @@ module Google
                 @cond.wait
               else
                 # still waiting for the interval to publish the batch...
-                @cond.wait(@interval - time_since_first_publish)
+                timeout = @interval - time_since_first_publish
+                @cond.wait timeout
               end
             end
           end
@@ -234,21 +235,21 @@ module Google
         def publish_batch_async topic_name, batch
           return unless @publish_thread_pool.running?
 
-          Concurrent::Future.new(executor: @publish_thread_pool) do
+          Concurrent::Future.new executor: @publish_thread_pool do
             begin
               grpc = @service.publish topic_name, batch.messages
-              batch.items.zip(Array(grpc.message_ids)) do |item, id|
+              batch.items.zip Array(grpc.message_ids) do |item, id|
                 next unless item.callback
 
                 item.msg.message_id = id
-                publish_result = PublishResult.from_grpc(item.msg)
+                publish_result = PublishResult.from_grpc item.msg
                 execute_callback_async item.callback, publish_result
               end
             rescue StandardError => e
               batch.items.each do |item|
                 next unless item.callback
 
-                publish_result = PublishResult.from_error(item.msg, e)
+                publish_result = PublishResult.from_error item.msg, e
                 execute_callback_async item.callback, publish_result
               end
             end
@@ -258,7 +259,7 @@ module Google
         def execute_callback_async callback, publish_result
           return unless @callback_thread_pool.running?
 
-          Concurrent::Future.new(executor: @callback_thread_pool) do
+          Concurrent::Future.new executor: @callback_thread_pool do
             callback.call publish_result
           end.execute
         end

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

@@ -150,7 +150,7 @@ module Google
         def topic topic_name, project: nil, skip_lookup: nil, async: nil
           ensure_service!
           options = { project: project }
-          return Topic.from_name(topic_name, service, options) if skip_lookup
+          return Topic.from_name topic_name, service, options if skip_lookup
           grpc = service.get_topic topic_name
           Topic.from_grpc grpc, service, async: async
         rescue Google::Cloud::NotFoundError

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

@@ -168,7 +168,7 @@ module Google
         ##
         # Gets the details of a subscription.
         def get_subscription subscription_name, options = {}
-          subscription = subscription_path(subscription_name, options)
+          subscription = subscription_path subscription_name, options
           execute do
             subscriber.get_subscription subscription, options: default_options
           end
@@ -218,8 +218,8 @@ module Google
         ##
         # Creates a subscription on a given topic for a given subscriber.
         def create_subscription topic, subscription_name, options = {}
-          name = subscription_path(subscription_name, options)
-          topic = topic_path(topic)
+          name = subscription_path subscription_name, options
+          topic = topic_path topic
           push_config = if options[:endpoint]
                           Google::Cloud::PubSub::V1::PushConfig.new \
                             push_endpoint: options[:endpoint],
@@ -263,7 +263,7 @@ module Google
         ##
         # Pulls a single message from the server.
         def pull subscription, options = {}
-          subscription = subscription_path(subscription, options)
+          subscription = subscription_path subscription, options
           max_messages = options.fetch(:max, 100).to_i
           return_immediately = !(!options.fetch(:immediate, true))
 
@@ -293,7 +293,7 @@ module Google
         ##
         # Modifies the PushConfig for a specified subscription.
         def modify_push_config subscription, endpoint, attributes
-          subscription = subscription_path(subscription)
+          subscription = subscription_path subscription
           # Convert attributes to strings to match the protobuf definition
           attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
           push_config = Google::Cloud::PubSub::V1::PushConfig.new(
@@ -370,7 +370,7 @@ module Google
         ##
         # Adjusts the given subscription to a time or snapshot.
         def seek subscription, time_or_snapshot
-          subscription = subscription_path(subscription)
+          subscription = subscription_path subscription
           execute do
             if a_time? time_or_snapshot
               time = Convert.time_to_timestamp time_or_snapshot
@@ -394,7 +394,7 @@ module Google
         end
 
         def set_topic_policy topic_name, new_policy, options = {}
-          resource = topic_path(topic_name, options)
+          resource = topic_path topic_name, options
 
           execute do
             publisher.set_iam_policy resource, new_policy,
@@ -403,7 +403,7 @@ module Google
         end
 
         def test_topic_permissions topic_name, permissions, options = {}
-          resource = topic_path(topic_name, options)
+          resource = topic_path topic_name, options
 
           execute do
             publisher.test_iam_permissions resource, permissions,
@@ -412,7 +412,7 @@ module Google
         end
 
         def get_subscription_policy subscription_name, options = {}
-          resource = subscription_path(subscription_name, options)
+          resource = subscription_path subscription_name, options
 
           execute do
             subscriber.get_iam_policy resource, options: default_options
@@ -420,7 +420,7 @@ module Google
         end
 
         def set_subscription_policy subscription_name, new_policy, options = {}
-          resource = subscription_path(subscription_name, options)
+          resource = subscription_path subscription_name, options
 
           execute do
             subscriber.set_iam_policy resource, new_policy,
@@ -430,7 +430,7 @@ module Google
 
         def test_subscription_permissions subscription_name,
                                           permissions, options = {}
-          resource = subscription_path(subscription_name, options)
+          resource = subscription_path subscription_name, options
 
           execute do
             subscriber.test_iam_permissions resource, permissions,
@@ -445,19 +445,19 @@ module Google
 
         def topic_path topic_name, options = {}
           return topic_name if topic_name.to_s.include? "/"
-          "#{project_path(options)}/topics/#{topic_name}"
+          "#{project_path options}/topics/#{topic_name}"
         end
 
         def subscription_path subscription_name, options = {}
           return subscription_name if subscription_name.to_s.include? "/"
-          "#{project_path(options)}/subscriptions/#{subscription_name}"
+          "#{project_path options}/subscriptions/#{subscription_name}"
         end
 
         def snapshot_path snapshot_name, options = {}
           if snapshot_name.nil? || snapshot_name.to_s.include?("/")
             return snapshot_name
           end
-          "#{project_path(options)}/snapshots/#{snapshot_name}"
+          "#{project_path options}/snapshots/#{snapshot_name}"
         end
 
         def inspect

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

@@ -138,7 +138,7 @@ module Google
         #
         def labels= new_labels
           raise ArgumentError, "Value must be a Hash" if new_labels.nil?
-          labels_map = Google::Protobuf::Map.new(:string, :string)
+          labels_map = Google::Protobuf::Map.new :string, :string
           Hash(new_labels).each { |k, v| labels_map[String(k)] = String(v) }
           update_grpc = @grpc.dup
           update_grpc.labels = labels_map

data/lib/google/cloud/pubsub/snapshot/list.rb

@@ -128,7 +128,7 @@ module Google
           def all request_limit: nil
             request_limit = request_limit.to_i if request_limit
             unless block_given?
-              return enum_for(:all, request_limit: request_limit)
+              return enum_for :all, request_limit: request_limit
             end
             results = self
             loop do

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

@@ -91,7 +91,7 @@ module Google
           @started = nil
           @stopped = nil
 
-          stream_pool = Array.new(@streams) do
+          stream_pool = Array.new @streams do
             Thread.new { Stream.new self }
           end
           @stream_pool = stream_pool.map(&:value)

data/lib/google/cloud/pubsub/subscriber/enumerator_queue.rb

@@ -37,7 +37,7 @@ module Google
           end
 
           def each
-            return enum_for(:each) unless block_given?
+            return enum_for :each unless block_given?
 
             loop do
               obj = @queue.pop

data/lib/google/cloud/pubsub/subscriber/stream.rb

@@ -266,7 +266,7 @@ module Google
           def perform_callback_async rec_msg
             return unless callback_thread_pool.running?
 
-            Concurrent::Future.new(executor: callback_thread_pool) do
+            Concurrent::Future.new executor: callback_thread_pool do
               begin
                 @subscriber.callback.call rec_msg
               rescue StandardError => callback_error

data/lib/google/cloud/pubsub/subscriber/timed_unary_buffer.rb

@@ -34,7 +34,7 @@ module Google
             # entry.
             @register = {}
 
-            @task = Concurrent::TimerTask.new(execution_interval: interval) do
+            @task = Concurrent::TimerTask.new execution_interval: interval do
               flush!
             end
           end
@@ -204,7 +204,7 @@ module Google
           end
 
           def add_future pool
-            Concurrent::Future.new(executor: pool) do
+            Concurrent::Future.new executor: pool do
               begin
                 yield
               rescue StandardError => error

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

@@ -16,6 +16,7 @@
 require "google/cloud/pubsub/convert"
 require "google/cloud/errors"
 require "google/cloud/pubsub/subscription/list"
+require "google/cloud/pubsub/subscription/push_config"
 require "google/cloud/pubsub/received_message"
 require "google/cloud/pubsub/snapshot"
 require "google/cloud/pubsub/subscriber"
@@ -189,7 +190,8 @@ module Google
 
         ##
         # Returns the URL locating the endpoint to which messages should be
-        # pushed.
+        # pushed. For example, a Webhook endpoint might use
+        # "https://example.com/push".
         #
         # Makes an API call to retrieve the endpoint value when called on a
         # reference object. See {#reference?}.
@@ -203,6 +205,7 @@ module Google
 
         ##
         # Sets the URL locating the endpoint to which messages should be pushed.
+        # For example, a Webhook endpoint might use "https://example.com/push".
         #
         # @param [String] new_endpoint The new endpoint value.
         #
@@ -218,6 +221,65 @@ module Google
           )
         end
 
+        ##
+        # Inspect the Subscription's push configuration settings. The
+        # configuration can be changed by modifying the values in the method's
+        # block.
+        #
+        # Subscription objects that are reference only will return an empty
+        # {Subscription::PushConfig} object, which can be configured and saved
+        # using the method's block. Unlike {#endpoint}, which will retrieve the
+        # full resource from the API before returning. To get the actual values
+        # for a reference object, call {#reload!} before calling {#push_config}.
+        #
+        # @yield [push_config] a block for modifying the push configuration
+        # @yieldparam [Subscription::PushConfig] push_config the push
+        #   configuration
+        #
+        # @return [Subscription::PushConfig]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.push_config.endpoint #=> "http://example.com/callback"
+        #   sub.push_config.authentication.email #=> "user@example.com"
+        #   sub.push_config.authentication.audience #=> "client-12345"
+        #
+        # @example Update the push configuration by passing a block:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   sub = pubsub.subscription "my-subscription"
+        #
+        #   sub.push_config do |pc|
+        #     pc.endpoint = "http://example.net/callback"
+        #     pc.set_oidc_token "user@example.net", "client-67890"
+        #   end
+        #
+        def push_config
+          ensure_service!
+
+          orig_config = reference? ? nil : @grpc.push_config
+          config = PushConfig.from_grpc orig_config
+
+          if block_given?
+            old_config = config.to_grpc.dup
+            yield config
+            new_config = config.to_grpc
+
+            if old_config != new_config # has the object been changed?
+              update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
+                name: name, push_config: new_config
+              @grpc = service.update_subscription update_grpc, :push_config
+            end
+          end
+
+          config.freeze
+        end
+
         ##
         # A hash of user-provided labels associated with this subscription.
         # Labels can be used to organize and group subscriptions.See [Creating
@@ -256,6 +318,48 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # The duration (in seconds) for when a subscription expires after the
+        # subscription goes inactive. A subscription is considered active as
+        # long as any connected subscriber is successfully consuming messages
+        # from the subscription or is issuing operations on the subscription.
+        #
+        # If {#expires_in=} is not set, a *default* value of of 31 days will be
+        # used. The minimum allowed value is 1 day.
+        #
+        # Makes an API call to retrieve the labels value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Numeric, nil] The expiration duration, or `nil` if unset.
+        #
+        def expires_in
+          ensure_grpc!
+
+          return nil if @grpc.expiration_policy.nil?
+
+          Convert.duration_to_number @grpc.expiration_policy.ttl
+        end
+
+        ##
+        # Sets the duration (in seconds) for when a subscription expires after
+        # the subscription goes inactive.
+        #
+        # See also {#expires_in}.
+        #
+        # @param [Numeric, nil] ttl The expiration duration in seconds, or `nil`
+        #   to unset.
+        #
+        def expires_in= ttl
+          new_expiration_policy = Google::Pubsub::V1::ExpirationPolicy.new(
+            ttl: Convert.number_to_duration(ttl)
+          )
+
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
+            name: name, expiration_policy: new_expiration_policy
+          @grpc = service.update_subscription update_grpc, :expiration_policy
+          @resource_name = nil
+        end
+
         ##
         # Determines whether the subscription exists in the Pub/Sub service.
         #
@@ -682,6 +786,28 @@ module Google
           !@grpc.nil?
         end
 
+        ##
+        # Reloads the subscription with current data from the Pub/Sub service.
+        #
+        # @return [Google::Cloud::PubSub::Subscription] Returns the reloaded
+        #   subscription
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.get_subscription "my-topic-sub"
+        #   sub.reload!
+        #
+        def reload!
+          ensure_service!
+          @grpc = service.get_subscription name
+          @resource_name = nil
+          self
+        end
+        alias refresh! reload!
+
         ##
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for this subscription.
@@ -834,8 +960,7 @@ module Google
         # Ensures a Google::Cloud::PubSub::V1::Subscription object exists.
         def ensure_grpc!
           ensure_service!
-          @grpc = service.get_subscription name if reference?
-          @resource_name = nil
+          reload! if reference?
         end
 
         ##