google-cloud-pubsub 0.24.0 → 0.25.0

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

@@ -0,0 +1,165 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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
+#
+# 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/cloud/errors"
+require "google/cloud/pubsub/snapshot/list"
+
+module Google
+  module Cloud
+    module Pubsub
+      ##
+      # # Snapshot
+      #
+      # A named resource created from a subscription to retain a stream of
+      # messages from a topic. A snapshot is guaranteed to retain:
+      #
+      # * The existing backlog on the subscription. More precisely, this is
+      #   defined as the messages in the subscription's backlog that are
+      #   unacknowledged upon the successful completion of the
+      #   `create_snapshot` operation; as well as:
+      # * Any messages published to the subscription's topic following the
+      #   successful completion of the `create_snapshot` operation.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::Pubsub.new
+      #   sub = pubsub.subscription "my-sub"
+      #
+      #   snapshot = sub.create_snapshot "my-snapshot"
+      #   snapshot.name #=> "projects/my-project/snapshots/my-snapshot"
+      #
+      class Snapshot
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private The gRPC Google::Pubsub::V1::Snapshot object.
+        attr_accessor :grpc
+
+        ##
+        # @private Create an empty {Snapshot} object.
+        def initialize
+          @service = nil
+          @grpc = Google::Pubsub::V1::Snapshot.new
+        end
+
+        ##
+        # The name of the snapshot. Format is
+        # `projects/{project}/snapshots/{snap}`.
+        def name
+          @grpc.name
+        end
+
+        ##
+        # The {Topic} from which this snapshot is retaining messages.
+        #
+        # @return [Topic]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   sub = pubsub.subscription "my-sub"
+        #
+        #   snapshot = sub.create_snapshot "my-snapshot"
+        #   snapshot.topic.name #=> "projects/my-project/topics/my-topic"
+        #
+        def topic
+          Topic.new_lazy @grpc.topic, service
+        end
+
+        ##
+        # The snapshot is guaranteed to exist up until this time.
+        # A newly-created snapshot expires no later than 7 days from the time of
+        # its creation. Its exact lifetime is determined at creation by the
+        # existing backlog in the source subscription. Specifically, the
+        # lifetime of the snapshot is 7 days - (age of oldest unacked message in
+        # the subscription). For example, consider a subscription whose oldest
+        # unacked message is 3 days old. If a snapshot is created from this
+        # subscription, the snapshot -- which will always capture this 3-day-old
+        # backlog as long as the snapshot exists -- will expire in 4 days.
+        #
+        # @return [Time] The time until which the snapshot is guaranteed to
+        #   exist.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   sub = pubsub.subscription "my-sub"
+        #
+        #   snapshot = sub.create_snapshot "my-snapshot"
+        #   snapshot.topic.name #=> "projects/my-project/topics/my-topic"
+        #   snapshot.expiration_time
+        #
+        def expiration_time
+          self.class.timestamp_from_grpc @grpc.expiration_time
+        end
+
+        ##
+        # Removes an existing snapshot. All messages retained in the snapshot
+        # are immediately dropped. After a snapshot is deleted, a new one may be
+        # created with the same name, but the new one has no association with
+        # the old snapshot or its subscription, unless the same subscription is
+        # specified.
+        #
+        # @return [Boolean] Returns `true` if the snapshot was deleted.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #
+        #   pubsub.snapshots.each do |snapshot|
+        #     snapshot.delete
+        #   end
+        #
+        def delete
+          ensure_service!
+          service.delete_snapshot name
+          true
+        end
+
+        ##
+        # @private New Snapshot from a Google::Pubsub::V1::Snapshot
+        # object.
+        def self.from_grpc grpc, service
+          new.tap do |f|
+            f.grpc = grpc
+            f.service = service
+          end
+        end
+
+        ##
+        # @private Get a Time object from a Google::Protobuf::Timestamp object.
+        def self.timestamp_from_grpc grpc_timestamp
+          return nil if grpc_timestamp.nil?
+          Time.at grpc_timestamp.seconds, Rational(grpc_timestamp.nanos, 1000)
+        end
+
+        protected
+
+        ##
+        # @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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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
+#
+# 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 "delegate"
+
+module Google
+  module Cloud
+    module Pubsub
+      class Snapshot
+        ##
+        # Snapshot::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more snapshots
+          # that match the request and this value should be passed to
+          # the next {Google::Cloud::Pubsub::Project#snapshots} to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Snapshot::List with an array of values.
+          def initialize arr = []
+            @prefix = nil
+            @token = nil
+            @max = nil
+            super arr
+          end
+
+          ##
+          # Whether there a next page of snapshots.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::Pubsub.new
+          #
+          #   snapshots = pubsub.snapshots
+          #   if snapshots.next?
+          #     next_snapshots = snapshots.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of snapshots.
+          #
+          # @return [Snapshot::List]
+          #
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::Pubsub.new
+          #
+          #   snapshots = pubsub.snapshots
+          #   if snapshots.next?
+          #     next_snapshots = snapshots.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            next_snapshots
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # 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 snapshots. Default is no limit.
+          # @yield [snapshot] The block for accessing each snapshot.
+          # @yieldparam [Snapshot] snapshot The snapshot object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each snapshot by passing a block:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::Pubsub.new
+          #
+          #   snapshots = pubsub.snapshots
+          #   snapshots.all do |snapshot|
+          #     puts snapshot.name
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::Pubsub.new
+          #
+          #   snapshots = pubsub.snapshots
+          #   all_names = snapshots.all.map do |snapshot|
+          #     snapshot.name
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::Pubsub.new
+          #
+          #   snapshots = pubsub.snapshots
+          #   snapshots.all(request_limit: 10) do |snapshot|
+          #     puts snapshot.name
+          #   end
+          #
+          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)
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Snapshots::List from a
+          # Google::Pubsub::V1::ListSnapshotsRequest object.
+          def self.from_grpc grpc_list, service, max = nil
+            subs = new(Array(grpc_list.snapshots).map do |grpc|
+              Snapshot.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
+            subs
+          end
+
+          protected
+
+          ##
+          # @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
+          end
+
+          def next_snapshots
+            options = { prefix: @prefix, token: @token, max: @max }
+            grpc = @service.list_snapshots options
+            self.class.from_grpc grpc, @service, @max
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -16,6 +16,7 @@
 require "google/cloud/errors"
 require "google/cloud/pubsub/subscription/list"
 require "google/cloud/pubsub/received_message"
+require "google/cloud/pubsub/snapshot"
 
 module Google
   module Cloud
@@ -97,6 +98,36 @@ module Google
           @grpc.ack_deadline_seconds
         end
 
+        ##
+        # Indicates whether to retain acknowledged messages. If `true`, then
+        # messages are not expunged from the subscription's backlog, even if
+        # they are acknowledged, until they fall out of the
+        # {#retention_duration} window. Default is `false`.
+        #
+        # @return [Boolean] Returns `true` if acknowledged messages are
+        #   retained.
+        #
+        def retain_acked
+          ensure_grpc!
+          @grpc.retain_acked_messages
+        end
+
+        ##
+        # How long to retain unacknowledged messages in the subscription's
+        # backlog, from the moment a message is published. If
+        # {#retain_acked} is `true`, then this also configures the retention of
+        # acknowledged messages, and thus configures how far back in time a
+        # {#seek} can be done. Cannot be more than 604,800 seconds (7 days) or
+        # less than 600 seconds (10 minutes). Default is 604,800 seconds (7
+        # days).
+        #
+        # @return [Numeric] The message retention duration in seconds.
+        #
+        def retention
+          ensure_grpc!
+          duration_to_number @grpc.message_retention_duration
+        end
+
         ##
         # Returns the URL locating the endpoint to which messages should be
         # pushed.
@@ -207,8 +238,8 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   sub = pubsub.subscription "my-topic-sub", max: 10
-        #   sub.pull.each { |msg| msg.acknowledge! }
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.pull(max: 10).each { |msg| msg.acknowledge! }
         #
         # @example The call can block until messages are available:
         #   require "google/cloud/pubsub"
@@ -376,6 +407,105 @@ module Google
           true
         end
 
+        ##
+        # Creates a new {Snapshot} from the subscription. The created snapshot
+        # is guaranteed to retain:
+        #
+        # * The existing backlog on the subscription. More precisely, this is
+        #   defined as the messages in the subscription's backlog that are
+        #   unacknowledged upon the successful completion of the
+        #   `create_snapshot` operation; as well as:
+        # * Any messages published to the subscription's topic following the
+        #   successful completion of the `create_snapshot` operation.
+        #
+        # @param [String, nil] snapshot_name Name of the new snapshot. If the
+        #   name is not provided, the server will assign a random name
+        #   for this snapshot on the same project as the subscription. The
+        #   format is `projects/{project}/snapshots/{snap}`. The name must start
+        #   with a letter, and contain only letters ([A-Za-z]), numbers
+        #   ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
+        #   (+) or percent signs (%). It must be between 3 and 255 characters in
+        #   length, and it must not start with "goog". Optional.
+        #
+        # @return [Google::Cloud::Pubsub::Snapshot]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   sub = pubsub.subscription "my-sub"
+        #
+        #   snapshot = sub.create_snapshot "my-snapshot"
+        #   snapshot.name #=> "projects/my-project/snapshots/my-snapshot"
+        #
+        # @example Without providing a name:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   sub = pubsub.subscription "my-sub"
+        #
+        #   snapshot = sub.create_snapshot
+        #   snapshot.name #=> "projects/my-project/snapshots/gcr-analysis-..."
+        #
+        def create_snapshot snapshot_name = nil
+          ensure_service!
+          grpc = service.create_snapshot name, snapshot_name
+          Snapshot.from_grpc grpc, service
+        end
+        alias_method :new_snapshot, :create_snapshot
+
+        ##
+        # Resets the subscription's backlog to a given {Snapshot} or to a point
+        # in time, whichever is provided in the request.
+        #
+        # @param [Snapshot, String, Time] snapshot The `Snapshot` instance,
+        #   snapshot name, or time to which to perform the seek.
+        #   If the argument is a snapshot, the snapshot's topic must be the
+        #   same as that of the subscription. If it is a time, messages retained
+        #   in the subscription that were published before this time are marked
+        #   as acknowledged, and messages retained in the subscription that were
+        #   published after this time are marked as unacknowledged. Note that
+        #   this operation affects only those messages retained in the
+        #   subscription. For example, if the time corresponds to a point before
+        #   the message retention window (or to a point before the system's
+        #   notion of the subscription creation time), only retained messages
+        #   will be marked as unacknowledged, and already-expunged messages will
+        #   not be restored.
+        #
+        # @return [Boolean] Returns `true` if the seek was successful.
+        #
+        # @example Using a snapshot
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   sub = pubsub.subscription "my-sub"
+        #
+        #   snapshot = sub.create_snapshot
+        #
+        #   messages = sub.pull
+        #   sub.acknowledge messages
+        #
+        #   sub.seek snapshot
+        #
+        # @example Using a time:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #   sub = pubsub.subscription "my-sub"
+        #
+        #   time = Time.now
+        #
+        #   messages = sub.pull
+        #   sub.acknowledge messages
+        #
+        #   sub.seek time
+        #
+        def seek snapshot
+          ensure_service!
+          service.seek name, snapshot
+          true
+        end
+
         ##
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for this subscription.
@@ -383,11 +513,6 @@ module Google
         # @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#iampolicy
         #   google.iam.v1.IAMPolicy
         #
-        # @param [Boolean] force Force the latest policy to be retrieved from
-        #   the Pub/Sub service when `true`. Otherwise the policy will be
-        #   memoized to reduce the number of API calls made to the Pub/Sub
-        #   service. The default is `false`.
-        #
         # @yield [policy] A block for updating the policy. The latest policy
         #   will be read from the Pub/Sub service and passed to the block. After
         #   the block completes, the modified policy will be written to the
@@ -397,23 +522,13 @@ module Google
         #
         # @return [Policy] the current Cloud IAM Policy for this subscription
         #
-        # @example Policy values are memoized to reduce the number of API calls:
-        #   require "google/cloud/pubsub"
-        #
-        #   pubsub = Google::Cloud::Pubsub.new
-        #   sub = pubsub.subscription "my-subscription"
-        #
-        #   policy = sub.policy # API call
-        #   policy_2 = sub.policy # No API call
-        #
-        # @example Use `force` to retrieve the latest policy from the service:
+        # @example
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #
-        #   policy = sub.policy force: true # API call
-        #   policy_2 = sub.policy force: true # API call
+        #   policy = sub.policy
         #
         # @example Update the policy by passing a block:
         #   require "google/cloud/pubsub"
@@ -421,21 +536,17 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #
-        #   policy = sub.policy do |p|
+        #   sub.policy do |p|
         #     p.add "roles/owner", "user:owner@example.com"
-        #   end # 2 API calls
-        #
-        def policy force: nil
-          @policy = nil if force || block_given?
-          @policy ||= begin
-            ensure_service!
-            grpc = service.get_subscription_policy name
-            Policy.from_grpc grpc
-          end
-          return @policy unless block_given?
-          p = @policy.deep_dup
-          yield p
-          self.policy = p
+        #   end
+        #
+        def policy
+          ensure_service!
+          grpc = service.get_subscription_policy name
+          policy = Policy.from_grpc grpc
+          return policy unless block_given?
+          yield policy
+          self.policy = policy
         end
 
         ##
@@ -453,6 +564,8 @@ module Google
         # @param [Policy] new_policy a new or modified Cloud IAM Policy for this
         #   subscription
         #
+        # @return [Policy] the policy returned by the API update operation
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -468,7 +581,7 @@ module Google
         def policy= new_policy
           ensure_service!
           grpc = service.set_subscription_policy name, new_policy.to_grpc
-          @policy = Policy.from_grpc grpc
+          Policy.from_grpc grpc
         end
 
         ##
@@ -522,6 +635,14 @@ module Google
 
         protected
 
+        def duration_to_number duration
+          return nil if duration.nil?
+
+          return duration.seconds if duration.nanos == 0
+
+          duration.seconds + (duration.nanos / 1000000000.0)
+        end
+
         ##
         # @private Raise an error unless an active connection to the service is
         # available.