google-cloud-pubsub 1.4.0 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -52,7 +52,7 @@ module Google
52
52
 
53
53
  ##
54
54
  # A URL locating the endpoint to which messages should be pushed. For
55
- # example, a Webhook endpoint might use "https://example.com/push".
55
+ # example, a Webhook endpoint might use `https://example.com/push`.
56
56
  #
57
57
  # @return [String]
58
58
  def endpoint
@@ -62,7 +62,7 @@ module Google
62
62
  ##
63
63
  # Sets the URL locating the endpoint to which messages should be
64
64
  # pushed. For example, a Webhook endpoint might use
65
- # "https://example.com/push".
65
+ # `https://example.com/push`.
66
66
  #
67
67
  # @param [String, nil] new_endpoint New URL value
68
68
  def endpoint= new_endpoint
@@ -19,6 +19,7 @@ require "google/cloud/pubsub/async_publisher"
19
19
  require "google/cloud/pubsub/batch_publisher"
20
20
  require "google/cloud/pubsub/subscription"
21
21
  require "google/cloud/pubsub/policy"
22
+ require "google/cloud/pubsub/retry_policy"
22
23
 
23
24
  module Google
24
25
  module Cloud
@@ -297,6 +298,13 @@ module Google
297
298
  # the subscription's dead letter policy. Dead lettering is done on a best effort basis. The same message might
298
299
  # be dead lettered multiple times. The value must be between 5 and 100. If this parameter is 0, a default
299
300
  # value of 5 is used. The `dead_letter_topic` must also be set.
301
+ # @param [RetryPolicy] retry_policy A policy that specifies how Cloud Pub/Sub retries message delivery for
302
+ # this subscription. If not set, the default retry policy is applied. This generally implies that messages
303
+ # will be retried as soon as possible for healthy subscribers. Retry Policy will be triggered on NACKs or
304
+ # acknowledgement deadline exceeded events for a given message.
305
+ #
306
+ # **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
307
+ # production use. It is not subject to any SLA or deprecation policy.
300
308
  #
301
309
  # @return [Google::Cloud::PubSub::Subscription]
302
310
  #
@@ -340,8 +348,19 @@ module Google
340
348
  # dead_letter_topic: dead_letter_topic,
341
349
  # dead_letter_max_delivery_attempts: 10
342
350
  #
351
+ # @example Configure a Retry Policy:
352
+ # require "google/cloud/pubsub"
353
+ #
354
+ # pubsub = Google::Cloud::PubSub.new
355
+ #
356
+ # topic = pubsub.topic "my-topic"
357
+ #
358
+ # retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
359
+ # sub = topic.subscribe "my-topic-sub", retry_policy: retry_policy
360
+ #
343
361
  def subscribe subscription_name, deadline: nil, retain_acked: false, retention: nil, endpoint: nil, labels: nil,
344
- message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil
362
+ message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil,
363
+ retry_policy: nil
345
364
  ensure_service!
346
365
  options = { deadline: deadline, retain_acked: retain_acked, retention: retention, endpoint: endpoint,
347
366
  labels: labels, message_ordering: message_ordering,
@@ -351,6 +370,7 @@ module Google
351
370
  # Service error message "3:Invalid resource name given (name=)." does not identify param.
352
371
  raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
353
372
  end
373
+ options[:retry_policy] = retry_policy.to_grpc if retry_policy
354
374
  grpc = service.create_subscription name, subscription_name, options
355
375
  Subscription.from_grpc grpc, service
356
376
  end
@@ -107,9 +107,9 @@ module Google
107
107
  # @return [Google::Protobuf::FieldMask]
108
108
  # Required. Indicates which fields in the provided topic to update. Must be
109
109
  # specified and non-empty. Note that if `update_mask` contains
110
- # "message_storage_policy" then the new value will be determined based on the
111
- # policy configured at the project or organization level. The
112
- # `message_storage_policy` must not be set in the `topic` provided above.
110
+ # "message_storage_policy" but the `message_storage_policy` is not set in
111
+ # the `topic` provided above, then the updated value is determined by the
112
+ # policy configured at the project or organization level.
113
113
  class UpdateTopicRequest; end
114
114
 
115
115
  # Request for the Publish method.
@@ -173,7 +173,7 @@ module Google
173
173
  # Response for the `ListTopicSubscriptions` method.
174
174
  # @!attribute [rw] subscriptions
175
175
  # @return [Array<String>]
176
- # The names of the subscriptions that match the request.
176
+ # The names of subscriptions attached to the topic specified in the request.
177
177
  # @!attribute [rw] next_page_token
178
178
  # @return [String]
179
179
  # If not empty, indicates that there may be more subscriptions that match
@@ -214,6 +214,17 @@ module Google
214
214
  # Format is `projects/{project}/topics/{topic}`.
215
215
  class DeleteTopicRequest; end
216
216
 
217
+ # Request for the DetachSubscription method.
218
+ # @!attribute [rw] subscription
219
+ # @return [String]
220
+ # Required. The subscription to detach.
221
+ # Format is `projects/{project}/subscriptions/{subscription}`.
222
+ class DetachSubscriptionRequest; end
223
+
224
+ # Response for the DetachSubscription method.
225
+ # Reserved for future use.
226
+ class DetachSubscriptionResponse; end
227
+
217
228
  # A subscription resource.
218
229
  # @!attribute [rw] name
219
230
  # @return [String]
@@ -293,6 +304,15 @@ module Google
293
304
  # operations on the subscription. If `expiration_policy` is not set, a
294
305
  # *default policy* with `ttl` of 31 days will be used. The minimum allowed
295
306
  # value for `expiration_policy.ttl` is 1 day.
307
+ # @!attribute [rw] filter
308
+ # @return [String]
309
+ # An expression written in the Cloud Pub/Sub filter language. If non-empty,
310
+ # then only `PubsubMessage`s whose `attributes` field matches the filter are
311
+ # delivered on this subscription. If empty, then no messages are filtered
312
+ # out.
313
+ # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
314
+ # API might be changed in backward-incompatible ways and is not recommended
315
+ # for production use. It is not subject to any SLA or deprecation policy.
296
316
  # @!attribute [rw] dead_letter_policy
297
317
  # @return [Google::Cloud::PubSub::V1::DeadLetterPolicy]
298
318
  # A policy that specifies the conditions for dead lettering messages in
@@ -303,11 +323,41 @@ module Google
303
323
  # parent project (i.e.,
304
324
  # service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com) must have
305
325
  # permission to Acknowledge() messages on this subscription.
306
- # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
307
- # API might be changed in backward-incompatible ways and is not recommended
308
- # for production use. It is not subject to any SLA or deprecation policy.
326
+ # @!attribute [rw] retry_policy
327
+ # @return [Google::Cloud::PubSub::V1::RetryPolicy]
328
+ # A policy that specifies how Cloud Pub/Sub retries message delivery for this
329
+ # subscription.
330
+ #
331
+ # If not set, the default retry policy is applied. This generally implies
332
+ # that messages will be retried as soon as possible for healthy subscribers.
333
+ # RetryPolicy will be triggered on NACKs or acknowledgement deadline
334
+ # exceeded events for a given message.
335
+ # <b>EXPERIMENTAL:</b> This API might be changed in backward-incompatible
336
+ # ways and is not recommended for production use. It is not subject to any
337
+ # SLA or deprecation policy.
309
338
  class Subscription; end
310
339
 
340
+ # A policy that specifies how Cloud Pub/Sub retries message delivery.
341
+ #
342
+ # Retry delay will be exponential based on provided minimum and maximum
343
+ # backoffs. https://en.wikipedia.org/wiki/Exponential_backoff.
344
+ #
345
+ # RetryPolicy will be triggered on NACKs or acknowledgement deadline exceeded
346
+ # events for a given message.
347
+ #
348
+ # Retry Policy is implemented on a best effort basis. At times, the delay
349
+ # between consecutive deliveries may not match the configuration. That is,
350
+ # delay can be more or less than configured backoff.
351
+ # @!attribute [rw] minimum_backoff
352
+ # @return [Google::Protobuf::Duration]
353
+ # The minimum delay between consecutive deliveries of a given message.
354
+ # Value should be between 0 and 600 seconds. Defaults to 10 seconds.
355
+ # @!attribute [rw] maximum_backoff
356
+ # @return [Google::Protobuf::Duration]
357
+ # The maximum delay between consecutive deliveries of a given message.
358
+ # Value should be between 0 and 600 seconds. Defaults to 600 seconds.
359
+ class RetryPolicy; end
360
+
311
361
  # Dead lettering is done on a best effort basis. The same message might be
312
362
  # dead lettered multiple times.
313
363
  #
@@ -357,7 +407,7 @@ module Google
357
407
  # @!attribute [rw] push_endpoint
358
408
  # @return [String]
359
409
  # A URL locating the endpoint to which messages should be pushed.
360
- # For example, a Webhook endpoint might use "https://example.com/push".
410
+ # For example, a Webhook endpoint might use `https://example.com/push`.
361
411
  # @!attribute [rw] attributes
362
412
  # @return [Hash{String => String}]
363
413
  # Endpoint configuration attributes that can be used to control different
@@ -416,8 +466,11 @@ module Google
416
466
  # The message.
417
467
  # @!attribute [rw] delivery_attempt
418
468
  # @return [Integer]
419
- # Delivery attempt counter is 1 + (the sum of number of NACKs and number of
420
- # ack_deadline exceeds) for this message.
469
+ # The approximate number of times that Cloud Pub/Sub has attempted to deliver
470
+ # the associated message to a subscriber.
471
+ #
472
+ # More precisely, this is 1 + (number of NACKs) +
473
+ # (number of ack_deadline exceeds) for this message.
421
474
  #
422
475
  # A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
423
476
  # exceeds event is whenever a message is not acknowledged within
@@ -425,13 +478,10 @@ module Google
425
478
  # Subscription.ackDeadlineSeconds, but may get extended automatically by
426
479
  # the client library.
427
480
  #
428
- # The first delivery of a given message will have this value as 1. The value
429
- # is calculated at best effort and is approximate.
481
+ # Upon the first delivery of a given message, `delivery_attempt` will have a
482
+ # value of 1. The value is calculated at best effort and is approximate.
430
483
  #
431
484
  # If a DeadLetterPolicy is not set on the subscription, this will be 0.
432
- # <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. This
433
- # API might be changed in backward-incompatible ways and is not recommended
434
- # for production use. It is not subject to any SLA or deprecation policy.
435
485
  class ReceivedMessage; end
436
486
 
437
487
  # Request for the GetSubscription method.
@@ -64,7 +64,11 @@ module Google
64
64
  "list_topic_subscriptions" => Google::Gax::PageDescriptor.new(
65
65
  "page_token",
66
66
  "next_page_token",
67
- "subscriptions")
67
+ "subscriptions"),
68
+ "list_topic_snapshots" => Google::Gax::PageDescriptor.new(
69
+ "page_token",
70
+ "next_page_token",
71
+ "snapshots")
68
72
  }.freeze
69
73
 
70
74
  private_constant :PAGE_DESCRIPTORS
@@ -94,6 +98,12 @@ module Google
94
98
 
95
99
  private_constant :PROJECT_PATH_TEMPLATE
96
100
 
101
+ SUBSCRIPTION_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
102
+ "projects/{project}/subscriptions/{subscription}"
103
+ )
104
+
105
+ private_constant :SUBSCRIPTION_PATH_TEMPLATE
106
+
97
107
  TOPIC_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
98
108
  "projects/{project}/topics/{topic}"
99
109
  )
@@ -109,6 +119,17 @@ module Google
109
119
  )
110
120
  end
111
121
 
122
+ # Returns a fully-qualified subscription resource name string.
123
+ # @param project [String]
124
+ # @param subscription [String]
125
+ # @return [String]
126
+ def self.subscription_path project, subscription
127
+ SUBSCRIPTION_PATH_TEMPLATE.render(
128
+ :"project" => project,
129
+ :"subscription" => subscription
130
+ )
131
+ end
132
+
112
133
  # Returns a fully-qualified topic resource name string.
113
134
  # @param project [String]
114
135
  # @param topic [String]
@@ -292,6 +313,14 @@ module Google
292
313
  {'topic' => request.topic}
293
314
  end
294
315
  )
316
+ @list_topic_snapshots = Google::Gax.create_api_call(
317
+ @publisher_stub.method(:list_topic_snapshots),
318
+ defaults["list_topic_snapshots"],
319
+ exception_transformer: exception_transformer,
320
+ params_extractor: proc do |request|
321
+ {'topic' => request.topic}
322
+ end
323
+ )
295
324
  @delete_topic = Google::Gax.create_api_call(
296
325
  @publisher_stub.method(:delete_topic),
297
326
  defaults["delete_topic"],
@@ -324,6 +353,14 @@ module Google
324
353
  {'resource' => request.resource}
325
354
  end
326
355
  )
356
+ @detach_subscription = Google::Gax.create_api_call(
357
+ @publisher_stub.method(:detach_subscription),
358
+ defaults["detach_subscription"],
359
+ exception_transformer: exception_transformer,
360
+ params_extractor: proc do |request|
361
+ {'subscription' => request.subscription}
362
+ end
363
+ )
327
364
  end
328
365
 
329
366
  # Service calls
@@ -395,9 +432,9 @@ module Google
395
432
  # @param update_mask [Google::Protobuf::FieldMask | Hash]
396
433
  # Required. Indicates which fields in the provided topic to update. Must be
397
434
  # specified and non-empty. Note that if `update_mask` contains
398
- # "message_storage_policy" then the new value will be determined based on the
399
- # policy configured at the project or organization level. The
400
- # `message_storage_policy` must not be set in the `topic` provided above.
435
+ # "message_storage_policy" but the `message_storage_policy` is not set in
436
+ # the `topic` provided above, then the updated value is determined by the
437
+ # policy configured at the project or organization level.
401
438
  # A hash of the same form as `Google::Protobuf::FieldMask`
402
439
  # can also be provided.
403
440
  # @param options [Google::Gax::CallOptions]
@@ -560,7 +597,7 @@ module Google
560
597
  @list_topics.call(req, options, &block)
561
598
  end
562
599
 
563
- # Lists the names of the subscriptions on this topic.
600
+ # Lists the names of the attached subscriptions on this topic.
564
601
  #
565
602
  # @param topic [String]
566
603
  # Required. The name of the topic that subscriptions are attached to.
@@ -615,6 +652,66 @@ module Google
615
652
  @list_topic_subscriptions.call(req, options, &block)
616
653
  end
617
654
 
655
+ # Lists the names of the snapshots on this topic. Snapshots are used in
656
+ # <a href="https://cloud.google.com/pubsub/docs/replay-overview">Seek</a>
657
+ # operations, which allow
658
+ # you to manage message acknowledgments in bulk. That is, you can set the
659
+ # acknowledgment state of messages in an existing subscription to the state
660
+ # captured by a snapshot.
661
+ #
662
+ # @param topic [String]
663
+ # Required. The name of the topic that snapshots are attached to.
664
+ # Format is `projects/{project}/topics/{topic}`.
665
+ # @param page_size [Integer]
666
+ # The maximum number of resources contained in the underlying API
667
+ # response. If page streaming is performed per-resource, this
668
+ # parameter does not affect the return value. If page streaming is
669
+ # performed per-page, this determines the maximum number of
670
+ # resources in a page.
671
+ # @param options [Google::Gax::CallOptions]
672
+ # Overrides the default settings for this call, e.g, timeout,
673
+ # retries, etc.
674
+ # @yield [result, operation] Access the result along with the RPC operation
675
+ # @yieldparam result [Google::Gax::PagedEnumerable<String>]
676
+ # @yieldparam operation [GRPC::ActiveCall::Operation]
677
+ # @return [Google::Gax::PagedEnumerable<String>]
678
+ # An enumerable of String instances.
679
+ # See Google::Gax::PagedEnumerable documentation for other
680
+ # operations such as per-page iteration or access to the response
681
+ # object.
682
+ # @raise [Google::Gax::GaxError] if the RPC is aborted.
683
+ # @example
684
+ # require "google/cloud/pubsub"
685
+ #
686
+ # publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
687
+ # formatted_topic = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
688
+ #
689
+ # # Iterate over all results.
690
+ # publisher_client.list_topic_snapshots(formatted_topic).each do |element|
691
+ # # Process element.
692
+ # end
693
+ #
694
+ # # Or iterate over results one page at a time.
695
+ # publisher_client.list_topic_snapshots(formatted_topic).each_page do |page|
696
+ # # Process each page at a time.
697
+ # page.each do |element|
698
+ # # Process element.
699
+ # end
700
+ # end
701
+
702
+ def list_topic_snapshots \
703
+ topic,
704
+ page_size: nil,
705
+ options: nil,
706
+ &block
707
+ req = {
708
+ topic: topic,
709
+ page_size: page_size
710
+ }.delete_if { |_, v| v.nil? }
711
+ req = Google::Gax::to_proto(req, Google::Cloud::PubSub::V1::ListTopicSnapshotsRequest)
712
+ @list_topic_snapshots.call(req, options, &block)
713
+ end
714
+
618
715
  # Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
619
716
  # does not exist. After a topic is deleted, a new topic may be created with
620
717
  # the same name; this is an entirely new topic with none of the old
@@ -653,8 +750,8 @@ module Google
653
750
  # Sets the access control policy on the specified resource. Replaces
654
751
  # any existing policy.
655
752
  #
656
- # Can return Public Errors: NOT_FOUND, INVALID_ARGUMENT and
657
- # PERMISSION_DENIED
753
+ # Can return `NOT_FOUND`, `INVALID_ARGUMENT`, and `PERMISSION_DENIED`
754
+ # errors.
658
755
  #
659
756
  # @param resource [String]
660
757
  # REQUIRED: The resource for which the policy is being specified.
@@ -678,11 +775,13 @@ module Google
678
775
  # require "google/cloud/pubsub"
679
776
  #
680
777
  # publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
681
- # formatted_resource = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
778
+ #
779
+ # # TODO: Initialize `resource`:
780
+ # resource = ''
682
781
  #
683
782
  # # TODO: Initialize `policy`:
684
783
  # policy = {}
685
- # response = publisher_client.set_iam_policy(formatted_resource, policy)
784
+ # response = publisher_client.set_iam_policy(resource, policy)
686
785
 
687
786
  def set_iam_policy \
688
787
  resource,
@@ -720,8 +819,10 @@ module Google
720
819
  # require "google/cloud/pubsub"
721
820
  #
722
821
  # publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
723
- # formatted_resource = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
724
- # response = publisher_client.get_iam_policy(formatted_resource)
822
+ #
823
+ # # TODO: Initialize `resource`:
824
+ # resource = ''
825
+ # response = publisher_client.get_iam_policy(resource)
725
826
 
726
827
  def get_iam_policy \
727
828
  resource,
@@ -738,7 +839,7 @@ module Google
738
839
 
739
840
  # Returns permissions that a caller has on the specified resource. If the
740
841
  # resource does not exist, this will return an empty set of
741
- # permissions, not a NOT_FOUND error.
842
+ # permissions, not a `NOT_FOUND` error.
742
843
  #
743
844
  # Note: This operation is designed to be used for building
744
845
  # permission-aware UIs and command-line tools, not for authorization
@@ -764,11 +865,13 @@ module Google
764
865
  # require "google/cloud/pubsub"
765
866
  #
766
867
  # publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
767
- # formatted_resource = Google::Cloud::PubSub::V1::PublisherClient.topic_path("[PROJECT]", "[TOPIC]")
868
+ #
869
+ # # TODO: Initialize `resource`:
870
+ # resource = ''
768
871
  #
769
872
  # # TODO: Initialize `permissions`:
770
873
  # permissions = []
771
- # response = publisher_client.test_iam_permissions(formatted_resource, permissions)
874
+ # response = publisher_client.test_iam_permissions(resource, permissions)
772
875
 
773
876
  def test_iam_permissions \
774
877
  resource,
@@ -782,6 +885,40 @@ module Google
782
885
  req = Google::Gax::to_proto(req, Google::Iam::V1::TestIamPermissionsRequest)
783
886
  @test_iam_permissions.call(req, options, &block)
784
887
  end
888
+
889
+ # Detaches a subscription from this topic. All messages retained in the
890
+ # subscription are dropped. Subsequent `Pull` and `StreamingPull` requests
891
+ # will return FAILED_PRECONDITION. If the subscription is a push
892
+ # subscription, pushes to the endpoint will stop.
893
+ #
894
+ # @param subscription [String]
895
+ # Required. The subscription to detach.
896
+ # Format is `projects/{project}/subscriptions/{subscription}`.
897
+ # @param options [Google::Gax::CallOptions]
898
+ # Overrides the default settings for this call, e.g, timeout,
899
+ # retries, etc.
900
+ # @yield [result, operation] Access the result along with the RPC operation
901
+ # @yieldparam result [Google::Cloud::PubSub::V1::DetachSubscriptionResponse]
902
+ # @yieldparam operation [GRPC::ActiveCall::Operation]
903
+ # @return [Google::Cloud::PubSub::V1::DetachSubscriptionResponse]
904
+ # @raise [Google::Gax::GaxError] if the RPC is aborted.
905
+ # @example
906
+ # require "google/cloud/pubsub"
907
+ #
908
+ # publisher_client = Google::Cloud::PubSub::Publisher.new(version: :v1)
909
+ # formatted_subscription = Google::Cloud::PubSub::V1::PublisherClient.subscription_path("[PROJECT]", "[SUBSCRIPTION]")
910
+ # response = publisher_client.detach_subscription(formatted_subscription)
911
+
912
+ def detach_subscription \
913
+ subscription,
914
+ options: nil,
915
+ &block
916
+ req = {
917
+ subscription: subscription
918
+ }.delete_if { |_, v| v.nil? }
919
+ req = Google::Gax::to_proto(req, Google::Cloud::PubSub::V1::DetachSubscriptionRequest)
920
+ @detach_subscription.call(req, options, &block)
921
+ end
785
922
  end
786
923
  end
787
924
  end