google-cloud-pubsub 0.20.0 → 2.6.1

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

@@ -1,10 +1,10 @@
-# Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2015 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
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#     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,
@@ -17,7 +17,7 @@ require "delegate"
 
 module Google
   module Cloud
-    module Pubsub
+    module PubSub
       class Subscription
         ##
         # Subscription::List is a special case Array with additional values.
@@ -25,7 +25,7 @@ module Google
           ##
           # If not empty, indicates that there are more subscriptions
           # that match the request and this value should be passed to
-          # the next {Google::Cloud::Pubsub::Topic#subscriptions} to continue.
+          # the next {Google::Cloud::PubSub::Topic#subscriptions} to continue.
           attr_accessor :token
 
           ##
@@ -44,10 +44,9 @@ module Google
           # @return [Boolean]
           #
           # @example
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::PubSub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   if subscriptions.next?
@@ -64,10 +63,9 @@ module Google
           # @return [Subscription::List]
           #
           # @example
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::PubSub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   if subscriptions.next?
@@ -85,15 +83,15 @@ module Google
           end
 
           ##
-          # Retrieves all subscriptions by repeatedly loading {#next} until
+          # Retrieves remaining results by repeatedly invoking {#next} until
           # {#next?} returns `false`. Calls the given block once for each
-          # subscription, which is passed as the parameter.
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all subscriptions are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all subscriptions. Default is no limit.
@@ -103,10 +101,9 @@ module Google
           # @return [Enumerator]
           #
           # @example Iterating each subscription by passing a block:
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::PubSub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   subscriptions.all do |subscription|
@@ -114,10 +111,9 @@ module Google
           #   end
           #
           # @example Using the enumerator by not passing a block:
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::PubSub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   all_names = subscriptions.all.map do |subscription|
@@ -125,27 +121,24 @@ module Google
           #   end
           #
           # @example Limit the number of API calls made:
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::PubSub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   subscriptions.all(request_limit: 10) do |subscription|
           #     puts subscription.name
           #   end
           #
-          def all request_limit: nil
+          def all request_limit: nil, &block
             request_limit = request_limit.to_i if request_limit
-            unless block_given?
-              return enum_for(:all, request_limit: request_limit)
-            end
+            return enum_for :all, request_limit: request_limit unless block_given?
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               if request_limit
                 request_limit -= 1
-                break if request_limit < 0
+                break if request_limit.negative?
               end
               break unless results.next?
               results = results.next
@@ -154,32 +147,32 @@ module Google
 
           ##
           # @private New Subscriptions::List from a
-          # Google::Pubsub::V1::ListSubscriptionsRequest object.
+          # Google::Cloud::PubSub::V1::ListSubscriptionsRequest object.
           def self.from_grpc grpc_list, service, max = nil
             subs = new(Array(grpc_list.subscriptions).map do |grpc|
               Subscription.from_grpc grpc, service
             end)
             token = grpc_list.next_page_token
-            token = nil if token == ""
-            subs.instance_variable_set "@token",   token
-            subs.instance_variable_set "@service", service
-            subs.instance_variable_set "@max",     max
+            token = nil if token == "".freeze
+            subs.instance_variable_set :@token,   token
+            subs.instance_variable_set :@service, service
+            subs.instance_variable_set :@max,     max
             subs
           end
 
           ##
           # @private New Subscriptions::List from a
-          # Google::Pubsub::V1::ListTopicSubscriptionsResponse object.
+          # Google::Cloud::PubSub::V1::ListTopicSubscriptionsResponse object.
           def self.from_topic_grpc grpc_list, service, topic, max = nil
             subs = new(Array(grpc_list.subscriptions).map do |grpc|
-              Subscription.new_lazy grpc, service
+              Subscription.from_name grpc, service
             end)
             token = grpc_list.next_page_token
-            token = nil if token == ""
-            subs.instance_variable_set "@token",   token
-            subs.instance_variable_set "@service", service
-            subs.instance_variable_set "@topic",   topic
-            subs.instance_variable_set "@max",     max
+            token = nil if token == "".freeze
+            subs.instance_variable_set :@token,   token
+            subs.instance_variable_set :@service, service
+            subs.instance_variable_set :@topic,   topic
+            subs.instance_variable_set :@max,     max
             subs
           end
 
@@ -189,7 +182,7 @@ module Google
           # @private Raise an error unless an active connection to the service
           # is available.
           def ensure_service!
-            fail "Must have active connection to service" unless @service
+            raise "Must have active connection to service" unless @service
           end
 
           def next_subscriptions
@@ -206,5 +199,7 @@ module Google
         end
       end
     end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end

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

@@ -0,0 +1,268 @@
+# Copyright 2019 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.
+
+
+require "google/pubsub/v1/pubsub_pb"
+
+module Google
+  module Cloud
+    module PubSub
+      class Subscription
+        ##
+        # Configuration for a push delivery endpoint.
+        #
+        # @example Create a push config:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: "http://example.net/callback"
+        #   push_config.set_oidc_token "service-account@example.net", "audience-header-value"
+        #
+        #   sub = topic.subscribe "my-subscription", push_config: push_config
+        #
+        # @example Read a push config:
+        #   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 a push config:
+        #   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
+        #
+        class PushConfig
+          ##
+          # Creates a new push configuration.
+          #
+          # @param [String] endpoint A URL locating the endpoint to which messages should be pushed. For
+          #   example, a Webhook endpoint might use `https://example.com/push`.
+          # @param [String] email The service account email to be used for generating the OIDC token.
+          #   The caller must have the `iam.serviceAccounts.actAs` permission for the service account.
+          # @param [String] audience The audience to be used when generating OIDC token. The audience claim identifies
+          #   the recipients that the JWT is intended for. The audience value is a single case-sensitive string. Having
+          #   multiple values (array) for the audience field is not supported. More info about the OIDC JWT token
+          #   audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint`
+          #   URL will be used.
+          #
+          def initialize endpoint: nil, email: nil, audience: nil
+            @grpc = Google::Cloud::PubSub::V1::PushConfig.new
+
+            self.endpoint = endpoint unless endpoint.nil?
+
+            raise ArgumentError, "audience provided without email. Authentication is invalid" if audience && !email
+
+            set_oidc_token email, audience if email
+          end
+
+          ##
+          # A URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might use
+          # `https://example.com/push`.
+          #
+          # @return [String]
+          def endpoint
+            @grpc.push_endpoint
+          end
+
+          ##
+          # 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, nil] new_endpoint New URL value
+          def endpoint= new_endpoint
+            @grpc.push_endpoint = String new_endpoint
+          end
+
+          ##
+          # The authentication method used by push endpoints to verify the source of push requests.
+          #
+          # @return [OidcToken, nil] An OIDC JWT token if specified, `nil`
+          #   otherwise.
+          def authentication
+            return nil unless @grpc.authentication_method == :oidc_token
+
+            OidcToken.from_grpc @grpc.oidc_token
+          end
+
+          ##
+          # Sets the authentication method used by push endpoints to verify the source of push requests.
+          #
+          # @param [OidcToken, nil] new_auth An authentication value.
+          def authentication= new_auth
+            if new_auth.nil?
+              @grpc.oidc_token = nil
+            else
+              raise ArgumentError unless new_auth.is_a? OidcToken
+
+              @grpc.oidc_token = new_auth.to_grpc
+            end
+          end
+
+          ##
+          # Checks whether authentication is an {OidcToken}.
+          #
+          # @return [Boolean]
+          def oidc_token?
+            authentication.is_a? OidcToken
+          end
+
+          ##
+          # Sets the authentication method to use an {OidcToken}.
+          #
+          # @param [String] email Service account email.
+          # @param [String] audience Audience to be used.
+          def set_oidc_token email, audience
+            oidc_token = OidcToken.new.tap do |token|
+              token.email = email
+              token.audience = audience
+            end
+            self.authentication = oidc_token
+          end
+
+          ##
+          # The format of the pushed message. This attribute indicates the version of the data expected by the endpoint.
+          # This controls the shape of the pushed message (i.e., its fields and metadata). The endpoint version is based
+          # on the version of the Pub/Sub API.
+          #
+          # If not present during the Subscription creation, it will default to the version of the API used to make such
+          # call.
+          #
+          # The possible values for this attribute are:
+          #
+          # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub
+          #   API.
+          # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub
+          #   API.
+          #
+          # @return [String]
+          def version
+            @grpc.attributes["x-goog-version"]
+          end
+
+          ##
+          # Sets the format of the pushed message.
+          #
+          # The possible values for this attribute are:
+          #
+          # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub
+          #   API.
+          # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub
+          #   API.
+          #
+          # @param [String, nil] new_version The new version value.
+          def version= new_version
+            if new_version.nil?
+              @grpc.attributes.delete "x-goog-version"
+            else
+              @grpc.attributes["x-goog-version"] = new_version
+            end
+          end
+
+          ##
+          # @private
+          def to_grpc
+            @grpc
+          end
+
+          ##
+          # @private
+          def self.from_grpc grpc
+            new.tap do |pc|
+              pc.instance_variable_set :@grpc, grpc.dup if grpc
+            end
+          end
+
+          ##
+          # Contains information needed for generating an [OpenID Connect
+          # token](https://developers.google.com/identity/protocols/OpenIDConnect).
+          class OidcToken
+            ##
+            # @private
+            def initialize
+              @grpc = Google::Cloud::PubSub::V1::PushConfig::OidcToken.new
+            end
+
+            ##
+            # The service account email to be used for generating the OIDC token. The caller must have the
+            # `iam.serviceAccounts.actAs` permission for the service account.
+            #
+            # @return [String]
+            def email
+              @grpc.service_account_email
+            end
+
+            ##
+            # Sets the service account email to be used for generating the OIDC token. The caller must have the
+            # `iam.serviceAccounts.actAs` permission for the service account.
+            #
+            # @param [String] new_email New service account email value.
+            def email= new_email
+              @grpc.service_account_email = new_email
+            end
+
+            ##
+            # The audience to be used when generating OIDC token. The audience claim identifies the recipients that
+            # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
+            # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
+            # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
+            #
+            # @return [String]
+            def audience
+              @grpc.audience
+            end
+
+            ##
+            # Sets the audience to be used when generating OIDC token. The audience claim identifies the recipients that
+            # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
+            # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
+            # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
+            #
+            # @param [String] new_audience New audience value.
+            def audience= new_audience
+              @grpc.audience = new_audience
+            end
+
+            ##
+            # @private
+            def to_grpc
+              @grpc
+            end
+
+            ##
+            # @private
+            def self.from_grpc grpc
+              grpc ||= Google::Cloud::PubSub::V1::PushConfig::OidcToken.new
+
+              new.tap do |pc|
+                pc.instance_variable_set :@grpc, grpc.dup
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end