google-cloud-pubsub 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b3e195a29890f73bda2b6a0b6caa90a9c8570454
-  data.tar.gz: 6663923bc7039afc67d791d02215109ca70ac083
+  metadata.gz: 010d13829a25c127763e29f5c44826325d2ac57b
+  data.tar.gz: 4dd99f0b95e7c054b05794df5a502550d5481bf8
 SHA512:
-  metadata.gz: 8851ed8c44d1f85bef860c026bfc014726dc2bcf1ca90b6e70fbde6a9c4484e6585bcfe9880821fc783e1ce85b807537c73b3f2c62c97921d4b7717a78459462
-  data.tar.gz: 148697983bbdeb834e4bd261502dd518d0edb104004768f47634fbe68fc2cf0f85f32022cdb4303875c8d8ced2496158cb8a63360f07926fcf6f33800997ee69
+  metadata.gz: da3fe9646eae5487c32352fdc938883d73af6535ab4b1869033cbf1a8ddc74d13362967228bee132dada097d37e46b5f1f7de6114647ed15024b1187a7ece94a
+  data.tar.gz: b7f054ffd0e941ba6128c5f189ea69357ddf06e3dff36a0fd190278ebdfb2f02111dca12011cc07b10bc15d5d8788e40789ab45ddec2085be622bd03d9994b69

data/README.md

@@ -24,7 +24,7 @@ Instructions and configuration options are covered in the [Authentication Guide]
 require "google/cloud/pubsub"
 
 pubsub = Google::Cloud::Pubsub.new(
-  project: "my-todo-project",
+  project: "my-project",
   keyfile: "/path/to/keyfile.json"
 )
 

data/lib/google/cloud/pubsub.rb

@@ -131,7 +131,7 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # topic = pubsub.topic "my-topic"
-    # msg = topic.publish "new-message"
+    # msg = topic.publish "task completed"
     # ```
     #
     # Messages can also be published with attributes:
@@ -142,7 +142,7 @@ module Google
     # pubsub = Google::Cloud::Pubsub.new
     #
     # topic = pubsub.topic "my-topic"
-    # msg = topic.publish "new-message",
+    # msg = topic.publish "task completed",
     #                     foo: :bar,
     #                     this: :that
     # ```
@@ -156,9 +156,9 @@ module Google
     #
     # topic = pubsub.topic "my-topic"
     # msgs = topic.publish do |batch|
-    #   batch.publish "new-message-1", foo: :bar
-    #   batch.publish "new-message-2", foo: :baz
-    #   batch.publish "new-message-3", foo: :bif
+    #   batch.publish "task 1 completed", foo: :bar
+    #   batch.publish "task 2 completed", foo: :baz
+    #   batch.publish "task 3 completed", foo: :bif
     # end
     # ```
     #
@@ -281,6 +281,34 @@ module Google
     # sub.delay 120, received_messages
     # ```
     #
+    # ## Creating a snapshot and using seek
+    #
+    # You can create a snapshot to retain the existing backlog on a
+    # subscription. The snapshot will hold the messages in the subscription's
+    # backlog that are unacknowledged upon the successful completion of the
+    # `create_snapshot` operation.
+    #
+    # Later, you can use `seek` to reset the subscription's backlog to the
+    # snapshot.
+    #
+    # (See {Google::Cloud::Pubsub::Subscription#create_snapshot} and
+    # {Google::Cloud::Pubsub::Subscription#seek})
+    #
+    # ```ruby
+    # require "google/cloud/pubsub"
+    #
+    # pubsub = Google::Cloud::Pubsub.new
+    #
+    # sub = pubsub.subscription "my-topic-sub"
+    #
+    # snapshot = sub.create_snapshot
+    #
+    # messages = sub.pull
+    # sub.acknowledge messages
+    #
+    # sub.seek snapshot
+    # ```
+    #
     # ## Listening for Messages
     #
     # Long running workers are easy to create with `listen`, which runs an

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

@@ -35,13 +35,13 @@ module Google
       #
       #   # Publish a message
       #   topic = pubsub.topic "my-topic"
-      #   message = topic.publish "new-message"
-      #   puts message.data #=>  "new-message"
+      #   message = topic.publish "task completed"
+      #   message.data #=>  "task completed"
       #
       #   # Pull a message
       #   sub = pubsub.subscription "my-topic-sub"
       #   received_message = sub.pull.first
-      #   puts received_message.message.data #=>  "new-message"
+      #   received_message.message.data #=>  "task completed"
       #
       class Message
         ##

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

@@ -61,13 +61,11 @@ module Google
       #   pubsub = Google::Cloud::Pubsub.new
       #   topic = pubsub.topic "my-topic"
       #
-      #   policy = topic.policy # API call
-      #
-      #   policy.remove "roles/owner", "user:owner@example.com" # Local call
-      #   policy.add "roles/owner", "user:newowner@example.com" # Local call
-      #   policy.roles["roles/viewer"] = ["allUsers"] # Local call
-      #
-      #   topic.policy = policy # API call
+      #   topic.policy do |p|
+      #     p.remove "roles/owner", "user:owner@example.com"
+      #     p.add "roles/owner", "user:newowner@example.com"
+      #     p.roles["roles/viewer"] = ["allUsers"]
+      #   end
       #
       class Policy
         attr_reader :etag, :roles
@@ -98,11 +96,9 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
-        #   policy = topic.policy # API call
-        #
-        #   policy.add "roles/owner", "user:newowner@example.com" # Local call
-        #
-        #   topic.policy = policy # API call
+        #   topic.policy do |p|
+        #     p.add "roles/owner", "user:newowner@example.com"
+        #   end
         #
         def add role_name, member
           role(role_name) << member
@@ -127,11 +123,9 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
-        #   policy = topic.policy # API call
-        #
-        #   policy.remove "roles/owner", "user:owner@example.com" # Local call
-        #
-        #   topic.policy = policy # API call
+        #   topic.policy do |p|
+        #     p.remove "roles/owner", "user:owner@example.com"
+        #   end
         #
         def remove role_name, member
           role(role_name).delete member
@@ -154,28 +148,14 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
-        #   policy = topic.policy
-        #
-        #   policy.role("roles/viewer") << "user:viewer@example.com"
+        #   topic.policy do |p|
+        #     p.role("roles/viewer") << "user:viewer@example.com"
+        #   end
         #
         def role role_name
           roles[role_name] ||= []
         end
 
-        ##
-        # Returns a deep copy of the policy.
-        #
-        # @return [Policy]
-        #
-        def deep_dup
-          dup.tap do |p|
-            roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
-              memo[k] = v.dup rescue value
-            end
-            p.instance_variable_set "@roles", roles_dup
-          end
-        end
-
         ##
         # @private Convert the Policy to a Google::Iam::V1::Policy object.
         def to_grpc

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

@@ -18,6 +18,7 @@ require "google/cloud/env"
 require "google/cloud/pubsub/service"
 require "google/cloud/pubsub/credentials"
 require "google/cloud/pubsub/topic"
+require "google/cloud/pubsub/snapshot"
 
 module Google
   module Cloud
@@ -60,11 +61,11 @@ module Google
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::Pubsub.new(
-        #     project: "my-todo-project",
+        #     project: "my-project",
         #     keyfile: "/path/to/keyfile.json"
         #   )
         #
-        #   pubsub.project #=> "my-todo-project"
+        #   pubsub.project #=> "my-project"
         #
         def project
           service.project
@@ -112,7 +113,7 @@ module Google
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::Pubsub.new
-        #   topic = pubsub.topic "non-existing-topic" #=> nil
+        #   topic = pubsub.topic "non-existing-topic" # nil
         #
         # @example With the `autocreate` option set to `true`.
         #   require "google/cloud/pubsub"
@@ -231,7 +232,7 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   msg = pubsub.publish "my-topic", "new-message"
+        #   msg = pubsub.publish "my-topic", "task completed"
         #
         # @example A message can be published using a File object:
         #   require "google/cloud/pubsub"
@@ -245,7 +246,7 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   msg = pubsub.publish "my-topic", "new-message", foo: :bar,
+        #   msg = pubsub.publish "my-topic", "task completed", foo: :bar,
         #                                                   this: :that
         #
         # @example Multiple messages can be sent at the same time using a block:
@@ -254,9 +255,9 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   msgs = pubsub.publish "my-topic" do |p|
-        #     p.publish "new-message-1", foo: :bar
-        #     p.publish "new-message-2", foo: :baz
-        #     p.publish "new-message-3", foo: :bif
+        #     p.publish "task 1 completed", foo: :bar
+        #     p.publish "task 2 completed", foo: :baz
+        #     p.publish "task 3 completed", foo: :bif
         #   end
         #
         # @example With `autocreate`:
@@ -264,7 +265,7 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   msg = pubsub.publish "new-topic", "new-message", autocreate: true
+        #   msg = pubsub.publish "new-topic", "task completed", autocreate: true
         #
         def publish topic_name, data = nil, attributes = {}
           # Fix parameters
@@ -295,6 +296,17 @@ module Google
         # @param [Integer] deadline The maximum number of seconds after a
         #   subscriber receives a message before the subscriber should
         #   acknowledge the message.
+        # @param [Boolean] retain_acked 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`.
+        # @param [Numeric] retention 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).
         # @param [String] endpoint A URL locating the endpoint to which messages
         #   should be pushed.
         # @param [String] autocreate Flag to control whether the topic will be
@@ -308,15 +320,7 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscribe "my-topic", "my-topic-sub"
-        #   puts sub.name # => "my-topic-sub"
-        #
-        # @example The name is optional, and will be generated if not given.
-        #   require "google/cloud/pubsub"
-        #
-        #   pubsub = Google::Cloud::Pubsub.new
-        #
-        #   sub = pubsub.subscribe "my-topic"
-        #   puts sub.name # => "generated-sub-name"
+        #   sub.name #=> "my-topic-sub"
         #
         # @example Wait 2 minutes for acknowledgement and push all to endpoint:
         #   require "google/cloud/pubsub"
@@ -336,9 +340,11 @@ module Google
         #                          autocreate: true
         #
         def subscribe topic_name, subscription_name, deadline: nil,
-                      endpoint: nil, autocreate: nil
+                      retain_acked: false, retention: nil, endpoint: nil,
+                      autocreate: nil
           ensure_service!
-          options = { deadline: deadline, endpoint: endpoint }
+          options = { deadline: deadline, retain_acked: retain_acked,
+                      retention: retention, endpoint: endpoint }
           grpc = service.create_subscription topic_name,
                                              subscription_name, options
           Subscription.from_grpc grpc, service
@@ -346,7 +352,8 @@ module Google
           if autocreate
             create_topic topic_name
             return subscribe(topic_name, subscription_name,
-                             deadline: deadline, endpoint: endpoint,
+                             deadline: deadline, retain_acked: retain_acked,
+                             retention: retention, endpoint: endpoint,
                              autocreate: false)
           end
           raise e
@@ -374,8 +381,8 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   subscription = pubsub.subscription "my-sub"
-        #   puts subscription.name
+        #   sub = pubsub.subscription "my-sub"
+        #   sub.name #=> "projects/my-project/subscriptions/my-sub"
         #
         # @example Skip the lookup against the service with `skip_lookup`:
         #   require "google/cloud/pubsub"
@@ -383,8 +390,8 @@ module Google
         #   pubsub = Google::Cloud::Pubsub.new
         #
         #   # No API call is made to retrieve the subscription information.
-        #   subscription = pubsub.subscription "my-sub", skip_lookup: true
-        #   puts subscription.name
+        #   sub = pubsub.subscription "my-sub", skip_lookup: true
+        #   sub.name #=> "projects/my-project/subscriptions/my-sub"
         #
         def subscription subscription_name, project: nil, skip_lookup: nil
           ensure_service!
@@ -415,9 +422,9 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   subscriptions = pubsub.subscriptions
-        #   subscriptions.each do |subscription|
-        #     puts subscription.name
+        #   subs = pubsub.subscriptions
+        #   subs.each do |sub|
+        #     puts sub.name
         #   end
         #
         # @example Retrieve all subscriptions: (See {Subscription::List#all})
@@ -425,9 +432,9 @@ module Google
         #
         #   pubsub = Google::Cloud::Pubsub.new
         #
-        #   subscriptions = pubsub.subscriptions
-        #   subscriptions.all do |subscription|
-        #     puts subscription.name
+        #   subs = pubsub.subscriptions
+        #   subs.all do |sub|
+        #     puts sub.name
         #   end
         #
         def subscriptions token: nil, max: nil
@@ -439,6 +446,46 @@ module Google
         alias_method :find_subscriptions, :subscriptions
         alias_method :list_subscriptions, :subscriptions
 
+
+        ##
+        # Retrieves a list of snapshots for the given project.
+        #
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of snapshots to return.
+        #
+        # @return [Array<Google::Cloud::Pubsub::Snapshot>] (See
+        #   {Google::Cloud::Pubsub::Snapshot::List})
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #
+        #   snapshots = pubsub.snapshots
+        #   snapshots.each do |snapshot|
+        #     puts snapshot.name
+        #   end
+        #
+        # @example Retrieve all snapshots: (See {Snapshot::List#all})
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #
+        #   snapshots = pubsub.snapshots
+        #   snapshots.all do |snapshot|
+        #     puts snapshot.name
+        #   end
+        #
+        def snapshots token: nil, max: nil
+          ensure_service!
+          options = { token: token, max: max }
+          grpc = service.list_snapshots options
+          Snapshot::List.from_grpc grpc, service, max
+        end
+        alias_method :find_snapshots, :snapshots
+        alias_method :list_snapshots, :snapshots
+
         protected
 
         ##

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

@@ -41,7 +41,12 @@ module Google
 
         def channel
           require "grpc"
-          GRPC::Core::Channel.new host, nil, chan_creds
+          GRPC::Core::Channel.new host, chan_args, chan_creds
+        end
+
+        def chan_args
+          { "grpc.max_send_message_length"    => -1,
+            "grpc.max_receive_message_length" => -1 }
         end
 
         def chan_creds
@@ -208,12 +213,16 @@ module Google
                             attributes: (options[:attributes] || {}).to_h
                         end
           deadline = options[:deadline]
+          retain_acked = options[:retain_acked]
+          mrd = number_to_duration options[:retention]
 
           execute do
             subscriber.create_subscription name,
                                            topic,
                                            push_config: push_config,
                                            ack_deadline_seconds: deadline,
+                                           retain_acked_messages: retain_acked,
+                                           message_retention_duration: mrd,
                                            options: default_options
           end
         end
@@ -279,6 +288,63 @@ module Google
           end
         end
 
+        ##
+        # Lists snapshots by project.
+        def list_snapshots options = {}
+          call_options = default_options
+          if (token = options[:token])
+            call_options = Google::Gax::CallOptions.new kwargs: default_headers,
+                                                        page_token: token
+          end
+
+          execute do
+            paged_enum = subscriber.list_snapshots project_path(options),
+                                                   page_size: options[:max],
+                                                   options: call_options
+
+            paged_enum.page.response
+          end
+        end
+
+        ##
+        # Creates a snapshot on a given subscription.
+        def create_snapshot subscription, snapshot_name
+          name = snapshot_path snapshot_name
+          execute do
+            subscriber.create_snapshot name,
+                                       subscription_path(subscription),
+                                       options: default_options
+          end
+        end
+
+        ##
+        # Deletes an existing snapshot.
+        # All pending messages in the snapshot are immediately dropped.
+        def delete_snapshot snapshot
+          execute do
+            subscriber.delete_snapshot snapshot_path(snapshot),
+                                       options: default_options
+          end
+        end
+
+        ##
+        # Adjusts the given subscription to a time or snapshot.
+        def seek subscription, time_or_snapshot
+          subscription = subscription_path(subscription)
+          execute do
+            if (time = time_to_timestamp time_or_snapshot)
+              subscriber.seek subscription, time: time, options: default_options
+            else
+              if time_or_snapshot.is_a? Snapshot
+                time_or_snapshot = time_or_snapshot.name
+              end
+              subscriber.seek subscription,
+                              snapshot: snapshot_path(time_or_snapshot),
+                              options: default_options
+            end
+          end
+        end
+
         def get_topic_policy topic_name, options = {}
           execute do
             publisher.get_iam_policy topic_path(topic_name, options),
@@ -346,6 +412,13 @@ module Google
           "#{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}"
+        end
+
         def inspect
           "#{self.class}(#{@project})"
         end
@@ -360,6 +433,27 @@ module Google
           Google::Gax::CallOptions.new kwargs: default_headers
         end
 
+        ##
+        # @private Get a Google::Protobuf::Timestamp object from a Time object.
+        def time_to_timestamp time
+          return nil if time.nil?
+          # Make sure to_time is supported.
+          return nil unless time.respond_to? :to_time
+          time = time.to_time
+          # Make sure we have a Time object.
+          # Rails' String#to_time returns nil if the string doesn't parse.
+          return nil unless time
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+        end
+
+        def number_to_duration number
+          return nil if number.nil?
+
+          Google::Protobuf::Duration.new \
+            seconds: number.to_i,
+            nanos: (number.remainder(1) * 1000000000).round
+        end
+
         def execute
           yield
         rescue Google::Gax::GaxError => e