google-cloud-pubsub 0.34.1 → 0.35.0

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

@@ -133,7 +133,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/subscription/push_config.rb

@@ -0,0 +1,244 @@
+# 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
+        #   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
+        #
+        class PushConfig
+          ##
+          # @private
+          def initialize
+            @grpc = Google::Cloud::PubSub::V1::PushConfig.new
+          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
+
+            ##
+            # Service account email to be used for generating the OIDC token.
+            #
+            # @return [String]
+            def email
+              @grpc.service_account_email
+            end
+
+            ##
+            # Service account email to be used for generating the OIDC token.
+            #
+            # @param [String] new_email New service account email value.
+            def email= new_email
+              @grpc.service_account_email = new_email
+            end
+
+            ##
+            # 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
+            #
+            # @return [String]
+            def audience
+              @grpc.audience
+            end
+
+            ##
+            # Sets the audience to be used when generating OIDC token.
+            #
+            # @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

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

@@ -422,7 +422,7 @@ module Google
         def publish_async data = nil, attributes = {}, &block
           ensure_service!
 
-          @async_publisher ||= AsyncPublisher.new(name, service, @async_opts)
+          @async_publisher ||= AsyncPublisher.new name, service, @async_opts
           @async_publisher.publish data, attributes, &block
         end
 
@@ -606,6 +606,27 @@ module Google
           !@grpc.nil?
         end
 
+        ##
+        # Reloads the topic with current data from the Pub/Sub service.
+        #
+        # @return [Google::Cloud::PubSub::Topic] Returns the reloaded topic
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #   topic.reload!
+        #
+        def reload!
+          ensure_service!
+          @grpc = service.get_topic name
+          @resource_name = nil
+          self
+        end
+        alias refresh! reload!
+
         ##
         # @private New Topic from a Google::Cloud::PubSub::V1::Topic object.
         def self.from_grpc grpc, service, async: nil
@@ -638,8 +659,7 @@ module Google
         # Ensures a Google::Cloud::PubSub::V1::Topic object exists.
         def ensure_grpc!
           ensure_service!
-          @grpc = service.get_topic name if reference?
-          @resource_name = nil
+          reload! if reference?
         end
 
         ##

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

@@ -127,7 +127,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/v1/doc/google/protobuf/field_mask.rb

@@ -83,57 +83,49 @@ module Google
     # describe the updated values, the API ignores the values of all
     # fields not covered by the mask.
     #
-    # If a repeated field is specified for an update operation, the existing
-    # repeated values in the target resource will be overwritten by the new values.
-    # Note that a repeated field is only allowed in the last position of a `paths`
-    # string.
+    # If a repeated field is specified for an update operation, new values will
+    # be appended to the existing repeated field in the target resource. Note that
+    # a repeated field is only allowed in the last position of a `paths` string.
     #
     # If a sub-message is specified in the last position of the field mask for an
-    # update operation, then the existing sub-message in the target resource is
-    # overwritten. Given the target message:
+    # update operation, then new value will be merged into the existing sub-message
+    # in the target resource.
+    #
+    # For example, given the target message:
     #
     #     f {
     #       b {
-    #         d : 1
-    #         x : 2
+    #         d: 1
+    #         x: 2
     #       }
-    #       c : 1
+    #       c: [1]
     #     }
     #
     # And an update message:
     #
     #     f {
     #       b {
-    #         d : 10
+    #         d: 10
     #       }
+    #       c: [2]
     #     }
     #
     # then if the field mask is:
     #
-    #  paths: "f.b"
+    #  paths: ["f.b", "f.c"]
     #
     # then the result will be:
     #
     #     f {
     #       b {
-    #         d : 10
+    #         d: 10
+    #         x: 2
     #       }
-    #       c : 1
+    #       c: [1, 2]
     #     }
     #
-    # However, if the update mask was:
-    #
-    #  paths: "f.b.d"
-    #
-    # then the result would be:
-    #
-    #     f {
-    #       b {
-    #         d : 10
-    #         x : 2
-    #       }
-    #       c : 1
-    #     }
+    # An implementation may provide options to override this default behavior for
+    # repeated and message fields.
     #
     # In order to reset a field's value to the default, the field must
     # be in the mask and set to the default value in the provided resource.

data/lib/google/cloud/pubsub/v1/doc/google/protobuf/timestamp.rb

@@ -15,17 +15,19 @@
 
 module Google
   module Protobuf
-    # A Timestamp represents a point in time independent of any time zone
-    # or calendar, represented as seconds and fractions of seconds at
-    # nanosecond resolution in UTC Epoch time. It is encoded using the
-    # Proleptic Gregorian Calendar which extends the Gregorian calendar
-    # backwards to year one. It is encoded assuming all minutes are 60
-    # seconds long, i.e. leap seconds are "smeared" so that no leap second
-    # table is needed for interpretation. Range is from
-    # 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
-    # By restricting to that range, we ensure that we can convert to
-    # and from  RFC 3339 date strings.
-    # See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+    # A Timestamp represents a point in time independent of any time zone or local
+    # calendar, encoded as a count of seconds and fractions of seconds at
+    # nanosecond resolution. The count is relative to an epoch at UTC midnight on
+    # January 1, 1970, in the proleptic Gregorian calendar which extends the
+    # Gregorian calendar backwards to year one.
+    #
+    # All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
+    # second table is needed for interpretation, using a [24-hour linear
+    # smear](https://developers.google.com/time/smear).
+    #
+    # The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
+    # restricting to that range, we ensure that we can convert to and from [RFC
+    # 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
     #
     # = Examples
     #
@@ -86,12 +88,12 @@ module Google
     # 01:30 UTC on January 15, 2017.
     #
     # In JavaScript, one can convert a Date object to this format using the
-    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
     # method. In Python, a standard `datetime.datetime` object can be converted
     # to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)
     # with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
     # can use the Joda Time's [`ISODateTimeFormat.dateTime()`](
-    # http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
+    # http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D
     # ) to obtain a formatter capable of generating timestamps in this format.
     # @!attribute [rw] seconds
     #   @return [Integer]

data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb

@@ -76,6 +76,15 @@ module Google
       #     The time at which the message was published, populated by the server when
       #     it receives the `Publish` call. It must not be populated by the
       #     publisher in a `Publish` call.
+      # @!attribute [rw] ordering_key
+      #   @return [String]
+      #     Identifies related messages for which publish order should be respected.
+      #     If a `Subscription` has `enable_message_ordering` set to `true`, messages
+      #     published with the same `ordering_key` value will be delivered to
+      #     subscribers in the order in which they are received by the Pub/Sub system.
+      #     <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+      #     API might be changed in backward-incompatible ways and is not recommended
+      #     for production use. It is not subject to any SLA or deprecation policy.
       class PubsubMessage; end
 
       # Request for the GetTopic method.
@@ -254,7 +263,8 @@ module Google
       #     messages are not expunged from the subscription's backlog, even if they are
       #     acknowledged, until they fall out of the `message_retention_duration`
       #     window. This must be true if you would like to
-      #     <a href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
+      #     <a
+      #     href="https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time">
       #     Seek to a timestamp</a>.
       #     <br><br>
       #     <b>BETA:</b> This feature is part of a beta release. This API might be
@@ -275,6 +285,15 @@ module Google
       #   @return [Hash{String => String}]
       #     See <a href="https://cloud.google.com/pubsub/docs/labels"> Creating and
       #     managing labels</a>.
+      # @!attribute [rw] enable_message_ordering
+      #   @return [true, false]
+      #     If true, messages published with the same `ordering_key` in `PubsubMessage`
+      #     will be delivered to the subscribers in the order in which they
+      #     are received by the Pub/Sub system. Otherwise, they may be delivered in
+      #     any order.
+      #     <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
+      #     API might be changed in backward-incompatible ways and is not recommended
+      #     for production use. It is not subject to any SLA or deprecation policy.
       # @!attribute [rw] expiration_policy
       #   @return [Google::Cloud::PubSub::V1::ExpirationPolicy]
       #     A policy that specifies the conditions for this subscription's expiration.
@@ -328,7 +347,32 @@ module Google
       #
       #     * `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.
-      class PushConfig; end
+      # @!attribute [rw] oidc_token
+      #   @return [Google::Cloud::PubSub::V1::PushConfig::OidcToken]
+      #     If specified, Pub/Sub will generate and attach an OIDC JWT token as an
+      #     `Authorization` header in the HTTP request for every pushed message.
+      class PushConfig
+        # Contains information needed for generating an
+        # [OpenID Connect
+        # token](https://developers.google.com/identity/protocols/OpenIDConnect).
+        # @!attribute [rw] service_account_email
+        #   @return [String]
+        #     [Service account
+        #     email](https://cloud.google.com/iam/docs/service-accounts)
+        #     to be used for generating the OIDC token. The caller (for
+        #     CreateSubscription, UpdateSubscription, and ModifyPushConfig calls) must
+        #     have the iam.serviceAccounts.actAs permission for the service account.
+        #     See https://cloud.google.com/iam/docs/understanding-roles#service-accounts-roles.
+        # @!attribute [rw] audience
+        #   @return [String]
+        #     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 Push endpoint URL will be used.
+        class OidcToken; end
+      end
 
       # A message and its corresponding acknowledgment ID.
       # @!attribute [rw] ack_id
@@ -513,9 +557,9 @@ module Google
       class StreamingPullResponse; end
 
       # Request for the `CreateSnapshot` method.<br><br>
-      # <b>BETA:</b> This feature is part of a beta release. This API might be changed in
-      # backward-incompatible ways and is not recommended for production use.
-      # It is not subject to any SLA or deprecation policy.
+      # <b>BETA:</b> This feature is part of a beta release. This API might be
+      # changed in backward-incompatible ways and is not recommended for production
+      # use. It is not subject to any SLA or deprecation policy.
       # @!attribute [rw] name
       #   @return [String]
       #     Optional user-provided name for this snapshot.