google-cloud-pubsub 0.26.0 → 2.6.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.
Files changed (56) hide show
  1. checksums.yaml +5 -5
  2. data/.yardopts +12 -2
  3. data/AUTHENTICATION.md +178 -0
  4. data/CHANGELOG.md +659 -0
  5. data/CODE_OF_CONDUCT.md +40 -0
  6. data/CONTRIBUTING.md +187 -0
  7. data/EMULATOR.md +37 -0
  8. data/LICENSE +2 -2
  9. data/LOGGING.md +32 -0
  10. data/OVERVIEW.md +528 -0
  11. data/TROUBLESHOOTING.md +31 -0
  12. data/lib/google/cloud/pubsub/async_publisher/batch.rb +310 -0
  13. data/lib/google/cloud/pubsub/async_publisher.rb +402 -0
  14. data/lib/google/cloud/pubsub/batch_publisher.rb +100 -0
  15. data/lib/google/cloud/pubsub/convert.rb +91 -0
  16. data/lib/google/cloud/pubsub/credentials.rb +26 -10
  17. data/lib/google/cloud/pubsub/errors.rb +85 -0
  18. data/lib/google/cloud/pubsub/message.rb +80 -17
  19. data/lib/google/cloud/pubsub/policy.rb +17 -14
  20. data/lib/google/cloud/pubsub/project.rb +364 -250
  21. data/lib/google/cloud/pubsub/publish_result.rb +103 -0
  22. data/lib/google/cloud/pubsub/received_message.rb +162 -24
  23. data/lib/google/cloud/pubsub/retry_policy.rb +88 -0
  24. data/lib/google/cloud/pubsub/schema/list.rb +180 -0
  25. data/lib/google/cloud/pubsub/schema.rb +310 -0
  26. data/lib/google/cloud/pubsub/service.rb +281 -265
  27. data/lib/google/cloud/pubsub/snapshot/list.rb +21 -21
  28. data/lib/google/cloud/pubsub/snapshot.rb +55 -15
  29. data/lib/google/cloud/pubsub/subscriber/enumerator_queue.rb +54 -0
  30. data/lib/google/cloud/pubsub/subscriber/inventory.rb +173 -0
  31. data/lib/google/cloud/pubsub/subscriber/sequencer.rb +115 -0
  32. data/lib/google/cloud/pubsub/subscriber/stream.rb +400 -0
  33. data/lib/google/cloud/pubsub/subscriber/timed_unary_buffer.rb +230 -0
  34. data/lib/google/cloud/pubsub/subscriber.rb +417 -0
  35. data/lib/google/cloud/pubsub/subscription/list.rb +28 -28
  36. data/lib/google/cloud/pubsub/subscription/push_config.rb +268 -0
  37. data/lib/google/cloud/pubsub/subscription.rb +900 -172
  38. data/lib/google/cloud/pubsub/topic/list.rb +21 -21
  39. data/lib/google/cloud/pubsub/topic.rb +674 -95
  40. data/lib/google/cloud/pubsub/version.rb +6 -4
  41. data/lib/google/cloud/pubsub.rb +104 -439
  42. data/lib/google-cloud-pubsub.rb +60 -29
  43. metadata +88 -50
  44. data/README.md +0 -69
  45. data/lib/google/cloud/pubsub/topic/publisher.rb +0 -86
  46. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/duration.rb +0 -77
  47. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/field_mask.rb +0 -223
  48. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/timestamp.rb +0 -81
  49. data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb +0 -503
  50. data/lib/google/cloud/pubsub/v1/publisher_client.rb +0 -605
  51. data/lib/google/cloud/pubsub/v1/publisher_client_config.json +0 -96
  52. data/lib/google/cloud/pubsub/v1/subscriber_client.rb +0 -1104
  53. data/lib/google/cloud/pubsub/v1/subscriber_client_config.json +0 -127
  54. data/lib/google/cloud/pubsub/v1.rb +0 -17
  55. data/lib/google/pubsub/v1/pubsub_pb.rb +0 -187
  56. data/lib/google/pubsub/v1/pubsub_services_pb.rb +0 -159
@@ -1,10 +1,10 @@
1
- # Copyright 2015 Google Inc. All rights reserved.
1
+ # Copyright 2015 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
5
5
  # You may obtain a copy of the License at
6
6
  #
7
- # http://www.apache.org/licenses/LICENSE-2.0
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
8
  #
9
9
  # Unless required by applicable law or agreed to in writing, software
10
10
  # distributed under the License is distributed on an "AS IS" BASIS,
@@ -17,7 +17,7 @@ require "delegate"
17
17
 
18
18
  module Google
19
19
  module Cloud
20
- module Pubsub
20
+ module PubSub
21
21
  class Topic
22
22
  ##
23
23
  # Topic::List is a special case Array with additional values.
@@ -25,7 +25,7 @@ module Google
25
25
  ##
26
26
  # If not empty, indicates that there are more topics
27
27
  # that match the request and this value should be passed to
28
- # the next {Google::Cloud::Pubsub::Project#topics} to continue.
28
+ # the next {Google::Cloud::PubSub::Project#topics} to continue.
29
29
  attr_accessor :token
30
30
 
31
31
  ##
@@ -42,7 +42,7 @@ module Google
42
42
  # @example
43
43
  # require "google/cloud/pubsub"
44
44
  #
45
- # pubsub = Google::Cloud::Pubsub.new
45
+ # pubsub = Google::Cloud::PubSub.new
46
46
  #
47
47
  # topics = pubsub.topics
48
48
  # if topics.next?
@@ -61,7 +61,7 @@ module Google
61
61
  # @example
62
62
  # require "google/cloud/pubsub"
63
63
  #
64
- # pubsub = Google::Cloud::Pubsub.new
64
+ # pubsub = Google::Cloud::PubSub.new
65
65
  #
66
66
  # topics = pubsub.topics
67
67
  # if topics.next?
@@ -97,7 +97,7 @@ module Google
97
97
  # @example Iterating each topic by passing a block:
98
98
  # require "google/cloud/pubsub"
99
99
  #
100
- # pubsub = Google::Cloud::Pubsub.new
100
+ # pubsub = Google::Cloud::PubSub.new
101
101
  #
102
102
  # topics = pubsub.topics
103
103
  # topics.all do |topic|
@@ -107,7 +107,7 @@ module Google
107
107
  # @example Using the enumerator by not passing a block:
108
108
  # require "google/cloud/pubsub"
109
109
  #
110
- # pubsub = Google::Cloud::Pubsub.new
110
+ # pubsub = Google::Cloud::PubSub.new
111
111
  #
112
112
  # topics = pubsub.topics
113
113
  # all_names = topics.all.map do |topic|
@@ -117,24 +117,22 @@ module Google
117
117
  # @example Limit the number of API calls made:
118
118
  # require "google/cloud/pubsub"
119
119
  #
120
- # pubsub = Google::Cloud::Pubsub.new
120
+ # pubsub = Google::Cloud::PubSub.new
121
121
  #
122
122
  # topics = pubsub.topics
123
123
  # topics.all(request_limit: 10) do |topic|
124
124
  # puts topic.name
125
125
  # end
126
126
  #
127
- def all request_limit: nil
127
+ def all request_limit: nil, &block
128
128
  request_limit = request_limit.to_i if request_limit
129
- unless block_given?
130
- return enum_for(:all, request_limit: request_limit)
131
- end
129
+ return enum_for :all, request_limit: request_limit unless block_given?
132
130
  results = self
133
131
  loop do
134
- results.each { |r| yield r }
132
+ results.each(&block)
135
133
  if request_limit
136
134
  request_limit -= 1
137
- break if request_limit < 0
135
+ break if request_limit.negative?
138
136
  end
139
137
  break unless results.next?
140
138
  results = results.next
@@ -143,16 +141,16 @@ module Google
143
141
 
144
142
  ##
145
143
  # @private New Topic::List from a
146
- # Google::Pubsub::V1::ListTopicsResponse object.
144
+ # Google::Cloud::PubSub::V1::ListTopicsResponse object.
147
145
  def self.from_grpc grpc_list, service, max = nil
148
146
  topics = new(Array(grpc_list.topics).map do |grpc|
149
147
  Topic.from_grpc grpc, service
150
148
  end)
151
149
  token = grpc_list.next_page_token
152
- token = nil if token == ""
153
- topics.instance_variable_set "@token", token
154
- topics.instance_variable_set "@service", service
155
- topics.instance_variable_set "@max", max
150
+ token = nil if token == "".freeze
151
+ topics.instance_variable_set :@token, token
152
+ topics.instance_variable_set :@service, service
153
+ topics.instance_variable_set :@max, max
156
154
  topics
157
155
  end
158
156
 
@@ -162,10 +160,12 @@ module Google
162
160
  # @private Raise an error unless an active connection to the service
163
161
  # is available.
164
162
  def ensure_service!
165
- fail "Must have active connection to service" unless @service
163
+ raise "Must have active connection to service" unless @service
166
164
  end
167
165
  end
168
166
  end
169
167
  end
168
+
169
+ Pubsub = PubSub unless const_defined? :Pubsub
170
170
  end
171
171
  end
@@ -1,10 +1,10 @@
1
- # Copyright 2015 Google Inc. All rights reserved.
1
+ # Copyright 2015 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
5
5
  # You may obtain a copy of the License at
6
6
  #
7
- # http://www.apache.org/licenses/LICENSE-2.0
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
8
  #
9
9
  # Unless required by applicable law or agreed to in writing, software
10
10
  # distributed under the License is distributed on an "AS IS" BASIS,
@@ -14,23 +14,27 @@
14
14
 
15
15
 
16
16
  require "google/cloud/errors"
17
- require "google/cloud/pubsub/topic/publisher"
18
17
  require "google/cloud/pubsub/topic/list"
18
+ require "google/cloud/pubsub/async_publisher"
19
+ require "google/cloud/pubsub/batch_publisher"
19
20
  require "google/cloud/pubsub/subscription"
20
21
  require "google/cloud/pubsub/policy"
22
+ require "google/cloud/pubsub/retry_policy"
21
23
 
22
24
  module Google
23
25
  module Cloud
24
- module Pubsub
26
+ module PubSub
25
27
  ##
26
28
  # # Topic
27
29
  #
28
30
  # A named resource to which messages are published.
29
31
  #
32
+ # See {Project#create_topic} and {Project#topic}.
33
+ #
30
34
  # @example
31
35
  # require "google/cloud/pubsub"
32
36
  #
33
- # pubsub = Google::Cloud::Pubsub.new
37
+ # pubsub = Google::Cloud::PubSub.new
34
38
  #
35
39
  # topic = pubsub.topic "my-topic"
36
40
  # topic.publish "task completed"
@@ -41,33 +45,264 @@ module Google
41
45
  attr_accessor :service
42
46
 
43
47
  ##
44
- # @private The Google::Pubsub::V1::Topic object.
48
+ # @private The Google::Cloud::PubSub::V1::Topic object.
45
49
  attr_accessor :grpc
46
50
 
47
51
  ##
48
52
  # @private Create an empty {Topic} object.
49
53
  def initialize
50
54
  @service = nil
51
- @grpc = Google::Pubsub::V1::Topic.new
52
- @name = nil
55
+ @grpc = nil
56
+ @resource_name = nil
53
57
  @exists = nil
58
+ @async_opts = {}
54
59
  end
55
60
 
56
61
  ##
57
- # @private New lazy {Topic} object without making an HTTP request.
58
- def self.new_lazy name, service, options = {}
59
- new.tap do |t|
60
- t.grpc = nil
61
- t.service = service
62
- t.instance_variable_set "@name", service.topic_path(name, options)
63
- end
62
+ # AsyncPublisher object used to publish multiple messages in batches.
63
+ #
64
+ # @return [AsyncPublisher] Returns publisher object if calls to
65
+ # {#publish_async} have been made, returns `nil` otherwise.
66
+ #
67
+ # @example
68
+ # require "google/cloud/pubsub"
69
+ #
70
+ # pubsub = Google::Cloud::PubSub.new
71
+ #
72
+ # topic = pubsub.topic "my-topic"
73
+ # topic.publish_async "task completed" do |result|
74
+ # if result.succeeded?
75
+ # log_publish_success result.data
76
+ # else
77
+ # log_publish_failure result.data, result.error
78
+ # end
79
+ # end
80
+ #
81
+ # topic.async_publisher.stop!
82
+ #
83
+ def async_publisher
84
+ @async_publisher
64
85
  end
65
86
 
66
87
  ##
67
- # The name of the topic in the form of
68
- # "/projects/project-identifier/topics/topic-name".
88
+ # The name of the topic.
89
+ #
90
+ # @return [String] A fully-qualified topic name in the form
91
+ # `projects/{project_id}/topics/{topic_id}`.
92
+ #
69
93
  def name
70
- @grpc ? @grpc.name : @name
94
+ return @resource_name if reference?
95
+ @grpc.name
96
+ end
97
+
98
+ ##
99
+ # A hash of user-provided labels associated with this topic. Labels can
100
+ # be used to organize and group topics. See [Creating and Managing
101
+ # Labels](https://cloud.google.com/pubsub/docs/labels).
102
+ #
103
+ # The returned hash is frozen and changes are not allowed. Use
104
+ # {#labels=} to update the labels for this topic.
105
+ #
106
+ # Makes an API call to retrieve the labels values when called on a
107
+ # reference object. See {#reference?}.
108
+ #
109
+ # @return [Hash] The frozen labels hash.
110
+ #
111
+ def labels
112
+ ensure_grpc!
113
+ @grpc.labels.to_h.freeze
114
+ end
115
+
116
+ ##
117
+ # Sets the hash of user-provided labels associated with this
118
+ # topic. Labels can be used to organize and group topics.
119
+ # Label keys and values can be no longer than 63 characters, can only
120
+ # contain lowercase letters, numeric characters, underscores and dashes.
121
+ # International characters are allowed. Label values are optional. Label
122
+ # keys must start with a letter and each label in the list must have a
123
+ # different key. See [Creating and Managing
124
+ # Labels](https://cloud.google.com/pubsub/docs/labels).
125
+ #
126
+ # @param [Hash] new_labels The new labels hash.
127
+ #
128
+ def labels= new_labels
129
+ raise ArgumentError, "Value must be a Hash" if new_labels.nil?
130
+ update_grpc = Google::Cloud::PubSub::V1::Topic.new name: name, labels: new_labels
131
+ @grpc = service.update_topic update_grpc, :labels
132
+ @resource_name = nil
133
+ end
134
+
135
+ ##
136
+ # The Cloud KMS encryption key that will be used to protect access
137
+ # to messages published on this topic.
138
+ # For example: `projects/a/locations/b/keyRings/c/cryptoKeys/d`
139
+ # The default value is `nil`, which means default encryption is used.
140
+ #
141
+ # Makes an API call to retrieve the KMS encryption key when called on a
142
+ # reference object. See {#reference?}.
143
+ #
144
+ # @return [String]
145
+ #
146
+ # @example
147
+ # require "google/cloud/pubsub"
148
+ #
149
+ # pubsub = Google::Cloud::PubSub.new
150
+ #
151
+ # topic = pubsub.topic "my-topic"
152
+ #
153
+ # topic.kms_key #=> "projects/a/locations/b/keyRings/c/cryptoKeys/d"
154
+ #
155
+ def kms_key
156
+ ensure_grpc!
157
+ @grpc.kms_key_name
158
+ end
159
+
160
+ ##
161
+ # Set the Cloud KMS encryption key that will be used to protect access
162
+ # to messages published on this topic.
163
+ # For example: `projects/a/locations/b/keyRings/c/cryptoKeys/d`
164
+ # The default value is `nil`, which means default encryption is used.
165
+ #
166
+ # @param [String] new_kms_key_name New Cloud KMS key name
167
+ #
168
+ # @example
169
+ # require "google/cloud/pubsub"
170
+ #
171
+ # pubsub = Google::Cloud::PubSub.new
172
+ #
173
+ # topic = pubsub.topic "my-topic"
174
+ #
175
+ # key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
176
+ # topic.kms_key = key_name
177
+ #
178
+ def kms_key= new_kms_key_name
179
+ update_grpc = Google::Cloud::PubSub::V1::Topic.new name: name, kms_key_name: new_kms_key_name
180
+ @grpc = service.update_topic update_grpc, :kms_key_name
181
+ @resource_name = nil
182
+ end
183
+
184
+ ##
185
+ # The list of GCP region IDs where messages that are published to the
186
+ # topic may be persisted in storage.
187
+ #
188
+ # Messages published by publishers running in non-allowed GCP regions
189
+ # (or running outside of GCP altogether) will be routed for storage in
190
+ # one of the allowed regions. An empty list indicates a misconfiguration
191
+ # at the project or organization level, which will result in all publish
192
+ # operations failing.
193
+ #
194
+ # Makes an API call to retrieve the list of GCP region IDs values when
195
+ # called on a reference object. See {#reference?}.
196
+ #
197
+ # @return [Array<String>]
198
+ #
199
+ # @example
200
+ # require "google/cloud/pubsub"
201
+ #
202
+ # pubsub = Google::Cloud::PubSub.new
203
+ #
204
+ # topic = pubsub.topic "my-topic"
205
+ #
206
+ # topic.persistence_regions #=> ["us-central1", "us-central2"]
207
+ #
208
+ def persistence_regions
209
+ ensure_grpc!
210
+ return [] if @grpc.message_storage_policy.nil?
211
+ Array @grpc.message_storage_policy.allowed_persistence_regions
212
+ end
213
+
214
+ ##
215
+ # Sets the list of GCP region IDs where messages that are published to
216
+ # the topic may be persisted in storage.
217
+ #
218
+ # @param [Array<String>] new_persistence_regions
219
+ #
220
+ # @example
221
+ # require "google/cloud/pubsub"
222
+ #
223
+ # pubsub = Google::Cloud::PubSub.new
224
+ #
225
+ # topic = pubsub.topic "my-topic"
226
+ #
227
+ # topic.persistence_regions = ["us-central1", "us-central2"]
228
+ #
229
+ def persistence_regions= new_persistence_regions
230
+ update_grpc = Google::Cloud::PubSub::V1::Topic.new \
231
+ name: name, message_storage_policy: { allowed_persistence_regions: Array(new_persistence_regions) }
232
+ @grpc = service.update_topic update_grpc, :message_storage_policy
233
+ @resource_name = nil
234
+ end
235
+
236
+ ##
237
+ # The name of the schema that messages published should be validated against, if schema settings are configured
238
+ # for the topic. The value is a fully-qualified schema name in the form
239
+ # `projects/{project_id}/schemas/{schema_id}`. If present, {#message_encoding} should also be present. The value
240
+ # of this field will be `_deleted-schema_` if the schema has been deleted.
241
+ #
242
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
243
+ #
244
+ # @return [String, nil] The schema name, or `nil` if schema settings are not configured for the topic.
245
+ #
246
+ # @example
247
+ # require "google/cloud/pubsub"
248
+ #
249
+ # pubsub = Google::Cloud::PubSub.new
250
+ #
251
+ # topic = pubsub.topic "my-topic"
252
+ #
253
+ # topic.schema_name #=> "projects/my-project/schemas/my-schema"
254
+ #
255
+ def schema_name
256
+ ensure_grpc!
257
+ @grpc.schema_settings&.schema
258
+ end
259
+
260
+ ##
261
+ # The encoding of messages validated against the schema identified by {#schema_name}. If present, {#schema_name}
262
+ # should also be present. Values include:
263
+ #
264
+ # * `JSON` - JSON encoding.
265
+ # * `BINARY` - Binary encoding, as defined by the schema type. For some schema types, binary encoding may not be
266
+ # available.
267
+ #
268
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
269
+ #
270
+ # @return [Symbol, nil] The schema encoding, or `nil` if schema settings are not configured for the topic.
271
+ #
272
+ # @example
273
+ # require "google/cloud/pubsub"
274
+ #
275
+ # pubsub = Google::Cloud::PubSub.new
276
+ #
277
+ # topic = pubsub.topic "my-topic"
278
+ #
279
+ # topic.message_encoding #=> :JSON
280
+ #
281
+ def message_encoding
282
+ ensure_grpc!
283
+ @grpc.schema_settings&.encoding
284
+ end
285
+
286
+ ##
287
+ # Checks if the encoding of messages in the schema settings is `BINARY`. See {#message_encoding}.
288
+ #
289
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
290
+ #
291
+ # @return [Boolean] `true` when `BINARY`, `false` if not `BINARY` or schema settings is not set.
292
+ #
293
+ def message_encoding_binary?
294
+ message_encoding.to_s.upcase == "BINARY"
295
+ end
296
+
297
+ ##
298
+ # Checks if the encoding of messages in the schema settings is `JSON`. See {#message_encoding}.
299
+ #
300
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
301
+ #
302
+ # @return [Boolean] `true` when `JSON`, `false` if not `JSON` or schema settings is not set.
303
+ #
304
+ def message_encoding_json?
305
+ message_encoding.to_s.upcase == "JSON"
71
306
  end
72
307
 
73
308
  ##
@@ -78,7 +313,7 @@ module Google
78
313
  # @example
79
314
  # require "google/cloud/pubsub"
80
315
  #
81
- # pubsub = Google::Cloud::Pubsub.new
316
+ # pubsub = Google::Cloud::PubSub.new
82
317
  #
83
318
  # topic = pubsub.topic "my-topic"
84
319
  # topic.delete
@@ -92,76 +327,189 @@ module Google
92
327
  ##
93
328
  # Creates a new {Subscription} object on the current Topic.
94
329
  #
95
- # @param [String] subscription_name Name of the new subscription. Must
96
- # start with a letter, and contain only letters ([A-Za-z]), numbers
97
- # ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
98
- # (+) or percent signs (%). It must be between 3 and 255 characters in
99
- # length, and it must not start with "goog". Required.
330
+ # @param [String] subscription_name Name of the new subscription. Required.
331
+ # The value can be a simple subscription ID (relative name), in which
332
+ # case the current project ID will be supplied, or a fully-qualified
333
+ # subscription name in the form
334
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
335
+ #
336
+ # The subscription ID (relative name) must start with a letter, and
337
+ # contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
338
+ # underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
339
+ # signs (`%`). It must be between 3 and 255 characters in length, and
340
+ # it must not start with `goog`.
100
341
  # @param [Integer] deadline The maximum number of seconds after a
101
342
  # subscriber receives a message before the subscriber should
102
343
  # acknowledge the message.
103
344
  # @param [Boolean] retain_acked Indicates whether to retain acknowledged
104
345
  # messages. If `true`, then messages are not expunged from the
105
346
  # subscription's backlog, even if they are acknowledged, until they
106
- # fall out of the `retention_duration` window. Default is `false`.
347
+ # fall out of the `retention` window. Default is `false`.
107
348
  # @param [Numeric] retention How long to retain unacknowledged messages
108
349
  # in the subscription's backlog, from the moment a message is
109
350
  # published. If `retain_acked` is `true`, then this also configures
110
351
  # the retention of acknowledged messages, and thus configures how far
111
- # back in time a {#seek} can be done. Cannot be more than 604,800
112
- # seconds (7 days) or less than 600 seconds (10 minutes). Default is
113
- # 604,800 seconds (7 days).
352
+ # back in time a {Subscription#seek} can be done. Cannot be more than
353
+ # 604,800 seconds (7 days) or less than 600 seconds (10 minutes).
354
+ # Default is 604,800 seconds (7 days).
114
355
  # @param [String] endpoint A URL locating the endpoint to which messages
115
- # should be pushed.
116
- #
117
- # @return [Google::Cloud::Pubsub::Subscription]
356
+ # should be pushed. The parameters `push_config` and `endpoint` should not both be provided.
357
+ # @param [Google::Cloud::PubSub::Subscription::PushConfig] push_config The configuration for a push delivery
358
+ # endpoint that should contain the endpoint, and can contain authentication data (OIDC token authentication).
359
+ # The parameters `push_config` and `endpoint` should not both be provided.
360
+ # @param [Hash] labels A hash of user-provided labels associated with
361
+ # the subscription. You can use these to organize and group your
362
+ # subscriptions. Label keys and values can be no longer than 63
363
+ # characters, can only contain lowercase letters, numeric characters,
364
+ # underscores and dashes. International characters are allowed. Label
365
+ # values are optional. Label keys must start with a letter and each
366
+ # label in the list must have a different key. See [Creating and
367
+ # Managing Labels](https://cloud.google.com/pubsub/docs/labels).
368
+ # @param [Boolean] message_ordering Whether to enable message ordering
369
+ # on the subscription.
370
+ # @param [String] filter An expression written in the Cloud Pub/Sub filter language. If non-empty, then only
371
+ # {Message} instances whose `attributes` field matches the filter are delivered on this subscription. If
372
+ # empty, then no messages are filtered out. Optional.
373
+ # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
374
+ # published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
375
+ # times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
376
+ # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
377
+ # this topic.
378
+ #
379
+ # The operation will fail if the topic does not exist. Users should ensure that there is a subscription
380
+ # attached to this topic since messages published to a topic with no subscriptions are lost.
381
+ # @param [Integer] dead_letter_max_delivery_attempts The maximum number of delivery attempts for any message in
382
+ # the subscription's dead letter policy. Dead lettering is done on a best effort basis. The same message might
383
+ # be dead lettered multiple times. The value must be between 5 and 100. If this parameter is 0, a default
384
+ # value of 5 is used. The `dead_letter_topic` must also be set.
385
+ # @param [RetryPolicy] retry_policy A policy that specifies how Cloud Pub/Sub retries message delivery for
386
+ # this subscription. If not set, the default retry policy is applied. This generally implies that messages
387
+ # will be retried as soon as possible for healthy subscribers. Retry Policy will be triggered on NACKs or
388
+ # acknowledgement deadline exceeded events for a given message.
389
+ #
390
+ # @return [Google::Cloud::PubSub::Subscription]
118
391
  #
119
392
  # @example
120
393
  # require "google/cloud/pubsub"
121
394
  #
122
- # pubsub = Google::Cloud::Pubsub.new
395
+ # pubsub = Google::Cloud::PubSub.new
123
396
  #
124
397
  # topic = pubsub.topic "my-topic"
125
398
  # sub = topic.subscribe "my-topic-sub"
126
399
  # sub.name # => "my-topic-sub"
127
400
  #
128
- # @example Wait 2 minutes for acknowledgement and push all to endpoint:
401
+ # @example Wait 2 minutes for acknowledgement:
402
+ # require "google/cloud/pubsub"
403
+ #
404
+ # pubsub = Google::Cloud::PubSub.new
405
+ #
406
+ # topic = pubsub.topic "my-topic"
407
+ # sub = topic.subscribe "my-topic-sub",
408
+ # deadline: 120
409
+ #
410
+ # @example Configure a push endpoint:
411
+ # require "google/cloud/pubsub"
412
+ #
413
+ # pubsub = Google::Cloud::PubSub.new
414
+ # topic = pubsub.topic "my-topic"
415
+ #
416
+ # push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: "http://example.net/callback"
417
+ # push_config.set_oidc_token "service-account@example.net", "audience-header-value"
418
+ #
419
+ # sub = topic.subscribe "my-subscription", push_config: push_config
420
+ #
421
+ # @example Configure a Dead Letter Queues policy:
129
422
  # require "google/cloud/pubsub"
130
423
  #
131
- # pubsub = Google::Cloud::Pubsub.new
424
+ # pubsub = Google::Cloud::PubSub.new
425
+ #
426
+ # # Dead Letter Queue (DLQ) testing requires IAM bindings to the Cloud Pub/Sub service account that is
427
+ # # automatically created and managed by the service team in a private project.
428
+ # my_project_number = "000000000000"
429
+ # service_account_email = "serviceAccount:service-#{my_project_number}@gcp-sa-pubsub.iam.gserviceaccount.com"
430
+ #
431
+ # dead_letter_topic = pubsub.topic "my-dead-letter-topic"
432
+ # dead_letter_subscription = dead_letter_topic.subscribe "my-dead-letter-sub"
433
+ #
434
+ # dead_letter_topic.policy { |p| p.add "roles/pubsub.publisher", service_account_email }
435
+ # dead_letter_subscription.policy { |p| p.add "roles/pubsub.subscriber", service_account_email }
132
436
  #
133
437
  # topic = pubsub.topic "my-topic"
134
438
  # sub = topic.subscribe "my-topic-sub",
135
- # deadline: 120,
136
- # endpoint: "https://example.com/push"
439
+ # dead_letter_topic: dead_letter_topic,
440
+ # dead_letter_max_delivery_attempts: 10
137
441
  #
138
- def subscribe subscription_name, deadline: nil, retain_acked: false,
139
- retention: nil, endpoint: nil
442
+ # @example Configure a Retry Policy:
443
+ # require "google/cloud/pubsub"
444
+ #
445
+ # pubsub = Google::Cloud::PubSub.new
446
+ #
447
+ # topic = pubsub.topic "my-topic"
448
+ #
449
+ # retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
450
+ # sub = topic.subscribe "my-topic-sub", retry_policy: retry_policy
451
+ #
452
+ def subscribe subscription_name,
453
+ deadline: nil,
454
+ retain_acked: false,
455
+ retention: nil,
456
+ endpoint: nil,
457
+ push_config: nil,
458
+ labels: nil,
459
+ message_ordering: nil,
460
+ filter: nil,
461
+ dead_letter_topic: nil,
462
+ dead_letter_max_delivery_attempts: nil,
463
+ retry_policy: nil
140
464
  ensure_service!
141
- options = { deadline: deadline, retain_acked: retain_acked,
142
- retention: retention, endpoint: endpoint }
465
+ if push_config && endpoint
466
+ raise ArgumentError, "endpoint and push_config were both provided. Please provide only one."
467
+ end
468
+ push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: endpoint if endpoint
469
+
470
+ options = {
471
+ deadline: deadline,
472
+ retain_acked: retain_acked,
473
+ retention: retention,
474
+ labels: labels,
475
+ message_ordering: message_ordering,
476
+ filter: filter,
477
+ dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts
478
+ }
479
+
480
+ options[:dead_letter_topic_name] = dead_letter_topic.name if dead_letter_topic
481
+ if options[:dead_letter_max_delivery_attempts] && !options[:dead_letter_topic_name]
482
+ # Service error message "3:Invalid resource name given (name=)." does not identify param.
483
+ raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
484
+ end
485
+ options[:push_config] = push_config.to_grpc if push_config
486
+ options[:retry_policy] = retry_policy.to_grpc if retry_policy
143
487
  grpc = service.create_subscription name, subscription_name, options
144
488
  Subscription.from_grpc grpc, service
145
489
  end
146
- alias_method :create_subscription, :subscribe
147
- alias_method :new_subscription, :subscribe
490
+ alias create_subscription subscribe
491
+ alias new_subscription subscribe
148
492
 
149
493
  ##
150
494
  # Retrieves subscription by name.
151
495
  #
152
- # @param [String] subscription_name Name of a subscription.
496
+ # @param [String] subscription_name Name of a subscription. The value
497
+ # can be a simple subscription ID (relative name), in which case the
498
+ # current project ID will be supplied, or a fully-qualified
499
+ # subscription name in the form
500
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
153
501
  # @param [Boolean] skip_lookup Optionally create a {Subscription} object
154
502
  # without verifying the subscription resource exists on the Pub/Sub
155
503
  # service. Calls made on this object will raise errors if the service
156
504
  # resource does not exist. Default is `false`.
157
505
  #
158
- # @return [Google::Cloud::Pubsub::Subscription, nil] Returns `nil` if
506
+ # @return [Google::Cloud::PubSub::Subscription, nil] Returns `nil` if
159
507
  # the subscription does not exist.
160
508
  #
161
509
  # @example
162
510
  # require "google/cloud/pubsub"
163
511
  #
164
- # pubsub = Google::Cloud::Pubsub.new
512
+ # pubsub = Google::Cloud::PubSub.new
165
513
  #
166
514
  # topic = pubsub.topic "my-topic"
167
515
  #
@@ -171,7 +519,7 @@ module Google
171
519
  # @example Skip the lookup against the service with `skip_lookup`:
172
520
  # require "google/cloud/pubsub"
173
521
  #
174
- # pubsub = Google::Cloud::Pubsub.new
522
+ # pubsub = Google::Cloud::PubSub.new
175
523
  #
176
524
  # topic = pubsub.topic "my-topic"
177
525
  #
@@ -181,14 +529,14 @@ module Google
181
529
  #
182
530
  def subscription subscription_name, skip_lookup: nil
183
531
  ensure_service!
184
- return Subscription.new_lazy subscription_name, service if skip_lookup
532
+ return Subscription.from_name subscription_name, service if skip_lookup
185
533
  grpc = service.get_subscription subscription_name
186
534
  Subscription.from_grpc grpc, service
187
535
  rescue Google::Cloud::NotFoundError
188
536
  nil
189
537
  end
190
- alias_method :get_subscription, :subscription
191
- alias_method :find_subscription, :subscription
538
+ alias get_subscription subscription
539
+ alias find_subscription subscription
192
540
 
193
541
  ##
194
542
  # Retrieves a list of subscription names for the given project.
@@ -203,7 +551,7 @@ module Google
203
551
  # @example
204
552
  # require "google/cloud/pubsub"
205
553
  #
206
- # pubsub = Google::Cloud::Pubsub.new
554
+ # pubsub = Google::Cloud::PubSub.new
207
555
  #
208
556
  # topic = pubsub.topic "my-topic"
209
557
  # subscriptions = topic.subscriptions
@@ -214,7 +562,7 @@ module Google
214
562
  # @example Retrieve all subscriptions: (See {Subscription::List#all})
215
563
  # require "google/cloud/pubsub"
216
564
  #
217
- # pubsub = Google::Cloud::Pubsub.new
565
+ # pubsub = Google::Cloud::PubSub.new
218
566
  #
219
567
  # topic = pubsub.topic "my-topic"
220
568
  # subscriptions = topic.subscriptions
@@ -228,17 +576,24 @@ module Google
228
576
  grpc = service.list_topics_subscriptions name, options
229
577
  Subscription::List.from_topic_grpc grpc, service, name, max
230
578
  end
231
- alias_method :find_subscriptions, :subscriptions
232
- alias_method :list_subscriptions, :subscriptions
579
+ alias find_subscriptions subscriptions
580
+ alias list_subscriptions subscriptions
233
581
 
234
582
  ##
235
583
  # Publishes one or more messages to the topic.
236
584
  #
237
- # @param [String, File] data The message data.
585
+ # The message payload must not be empty; it must contain either a
586
+ # non-empty data field, or at least one attribute.
587
+ #
588
+ # @param [String, File] data The message payload. This will be converted
589
+ # to bytes encoded as ASCII-8BIT.
238
590
  # @param [Hash] attributes Optional attributes for the message.
239
- # @yield [publisher] a block for publishing multiple messages in one
591
+ # @param [String] ordering_key Identifies related messages for which
592
+ # publish order should be respected.
593
+ # @yield [batch] a block for publishing multiple messages in one
240
594
  # request
241
- # @yieldparam [Topic::Publisher] publisher the topic publisher object
595
+ # @yieldparam [BatchPublisher] batch the topic batch publisher
596
+ # object
242
597
  #
243
598
  # @return [Message, Array<Message>] Returns the published message when
244
599
  # called without a block, or an array of messages when called with a
@@ -247,7 +602,7 @@ module Google
247
602
  # @example
248
603
  # require "google/cloud/pubsub"
249
604
  #
250
- # pubsub = Google::Cloud::Pubsub.new
605
+ # pubsub = Google::Cloud::PubSub.new
251
606
  #
252
607
  # topic = pubsub.topic "my-topic"
253
608
  # msg = topic.publish "task completed"
@@ -255,15 +610,16 @@ module Google
255
610
  # @example A message can be published using a File object:
256
611
  # require "google/cloud/pubsub"
257
612
  #
258
- # pubsub = Google::Cloud::Pubsub.new
613
+ # pubsub = Google::Cloud::PubSub.new
259
614
  #
260
615
  # topic = pubsub.topic "my-topic"
261
- # msg = topic.publish File.open("message.txt")
616
+ # file = File.open "message.txt", mode: "rb"
617
+ # msg = topic.publish file
262
618
  #
263
619
  # @example Additionally, a message can be published with attributes:
264
620
  # require "google/cloud/pubsub"
265
621
  #
266
- # pubsub = Google::Cloud::Pubsub.new
622
+ # pubsub = Google::Cloud::PubSub.new
267
623
  #
268
624
  # topic = pubsub.topic "my-topic"
269
625
  # msg = topic.publish "task completed",
@@ -273,7 +629,7 @@ module Google
273
629
  # @example Multiple messages can be sent at the same time using a block:
274
630
  # require "google/cloud/pubsub"
275
631
  #
276
- # pubsub = Google::Cloud::Pubsub.new
632
+ # pubsub = Google::Cloud::PubSub.new
277
633
  #
278
634
  # topic = pubsub.topic "my-topic"
279
635
  # msgs = topic.publish do |t|
@@ -282,12 +638,180 @@ module Google
282
638
  # t.publish "task 3 completed", foo: :bif
283
639
  # end
284
640
  #
285
- def publish data = nil, attributes = {}
641
+ # @example Ordered messages are supported using ordering_key:
642
+ # require "google/cloud/pubsub"
643
+ #
644
+ # pubsub = Google::Cloud::PubSub.new
645
+ #
646
+ # topic = pubsub.topic "my-ordered-topic"
647
+ #
648
+ # # Ensure that message ordering is enabled.
649
+ # topic.enable_message_ordering!
650
+ #
651
+ # # Publish an ordered message with an ordering key.
652
+ # topic.publish "task completed",
653
+ # ordering_key: "task-key"
654
+ #
655
+ def publish data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &block
286
656
  ensure_service!
287
- publisher = Publisher.new data, attributes
288
- yield publisher if block_given?
289
- return nil if publisher.messages.count.zero?
290
- publish_batch_messages publisher
657
+ batch = BatchPublisher.new data, attributes, ordering_key, extra_attrs
658
+ block&.call batch
659
+ return nil if batch.messages.count.zero?
660
+ publish_batch_messages batch
661
+ end
662
+
663
+ ##
664
+ # Publishes a message asynchronously to the topic using
665
+ # {#async_publisher}.
666
+ #
667
+ # The message payload must not be empty; it must contain either a
668
+ # non-empty data field, or at least one attribute.
669
+ #
670
+ # Google Cloud Pub/Sub ordering keys provide the ability to ensure
671
+ # related messages are sent to subscribers in the order in which they
672
+ # were published. Messages can be tagged with an ordering key, a string
673
+ # that identifies related messages for which publish order should be
674
+ # respected. The service guarantees that, for a given ordering key and
675
+ # publisher, messages are sent to subscribers in the order in which they
676
+ # were published. Ordering does not require sacrificing high throughput
677
+ # or scalability, as the service automatically distributes messages for
678
+ # different ordering keys across subscribers.
679
+ #
680
+ # To use ordering keys, specify `ordering_key`. Before specifying
681
+ # `ordering_key` on a message a call to `#enable_message_ordering!` must
682
+ # be made or an error will be raised.
683
+ #
684
+ # @note At the time of this release, ordering keys are not yet publicly
685
+ # enabled and requires special project enablements.
686
+ #
687
+ # @param [String, File] data The message payload. This will be converted
688
+ # to bytes encoded as ASCII-8BIT.
689
+ # @param [Hash] attributes Optional attributes for the message.
690
+ # @param [String] ordering_key Identifies related messages for which
691
+ # publish order should be respected.
692
+ # @yield [result] the callback for when the message has been published
693
+ # @yieldparam [PublishResult] result the result of the asynchronous
694
+ # publish
695
+ # @raise [Google::Cloud::PubSub::AsyncPublisherStopped] when the
696
+ # publisher is stopped. (See {AsyncPublisher#stop} and
697
+ # {AsyncPublisher#stopped?}.)
698
+ # @raise [Google::Cloud::PubSub::OrderedMessagesDisabled] when
699
+ # publishing a message with an `ordering_key` but ordered messages are
700
+ # not enabled. (See {#message_ordering?} and
701
+ # {#enable_message_ordering!}.)
702
+ # @raise [Google::Cloud::PubSub::OrderingKeyError] when publishing a
703
+ # message with an `ordering_key` that has already failed when
704
+ # publishing. Use {#resume_publish} to allow this `ordering_key` to be
705
+ # published again.
706
+ #
707
+ # @example
708
+ # require "google/cloud/pubsub"
709
+ #
710
+ # pubsub = Google::Cloud::PubSub.new
711
+ #
712
+ # topic = pubsub.topic "my-topic"
713
+ # topic.publish_async "task completed" do |result|
714
+ # if result.succeeded?
715
+ # log_publish_success result.data
716
+ # else
717
+ # log_publish_failure result.data, result.error
718
+ # end
719
+ # end
720
+ #
721
+ # # Shut down the publisher when ready to stop publishing messages.
722
+ # topic.async_publisher.stop!
723
+ #
724
+ # @example A message can be published using a File object:
725
+ # require "google/cloud/pubsub"
726
+ #
727
+ # pubsub = Google::Cloud::PubSub.new
728
+ #
729
+ # topic = pubsub.topic "my-topic"
730
+ # file = File.open "message.txt", mode: "rb"
731
+ # topic.publish_async file
732
+ #
733
+ # # Shut down the publisher when ready to stop publishing messages.
734
+ # topic.async_publisher.stop!
735
+ #
736
+ # @example Additionally, a message can be published with attributes:
737
+ # require "google/cloud/pubsub"
738
+ #
739
+ # pubsub = Google::Cloud::PubSub.new
740
+ #
741
+ # topic = pubsub.topic "my-topic"
742
+ # topic.publish_async "task completed",
743
+ # foo: :bar, this: :that
744
+ #
745
+ # # Shut down the publisher when ready to stop publishing messages.
746
+ # topic.async_publisher.stop!
747
+ #
748
+ # @example Ordered messages are supported using ordering_key:
749
+ # require "google/cloud/pubsub"
750
+ #
751
+ # pubsub = Google::Cloud::PubSub.new
752
+ #
753
+ # topic = pubsub.topic "my-ordered-topic"
754
+ #
755
+ # # Ensure that message ordering is enabled.
756
+ # topic.enable_message_ordering!
757
+ #
758
+ # # Publish an ordered message with an ordering key.
759
+ # topic.publish_async "task completed",
760
+ # ordering_key: "task-key"
761
+ #
762
+ # # Shut down the publisher when ready to stop publishing messages.
763
+ # topic.async_publisher.stop!
764
+ #
765
+ def publish_async data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &callback
766
+ ensure_service!
767
+
768
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
769
+ @async_publisher.publish data, attributes, ordering_key: ordering_key, **extra_attrs, &callback
770
+ end
771
+
772
+ ##
773
+ # Enables message ordering for messages with ordering keys on the
774
+ # {#async_publisher}. When enabled, messages published with the same
775
+ # `ordering_key` will be delivered in the order they were published.
776
+ #
777
+ # @note At the time of this release, ordering keys are not yet publicly
778
+ # enabled and requires special project enablements.
779
+ #
780
+ # See {#message_ordering?}. See {#publish_async},
781
+ # {Subscription#listen}, and {Message#ordering_key}.
782
+ #
783
+ def enable_message_ordering!
784
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
785
+ @async_publisher.enable_message_ordering!
786
+ end
787
+
788
+ ##
789
+ # Whether message ordering for messages with ordering keys has been
790
+ # enabled on the {#async_publisher}. When enabled, messages published
791
+ # with the same `ordering_key` will be delivered in the order they were
792
+ # published. When disabled, messages may be delivered in any order.
793
+ #
794
+ # See {#enable_message_ordering!}. See {#publish_async},
795
+ # {Subscription#listen}, and {Message#ordering_key}.
796
+ #
797
+ # @return [Boolean]
798
+ #
799
+ def message_ordering?
800
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
801
+ @async_publisher.message_ordering?
802
+ end
803
+
804
+ ##
805
+ # Resume publishing ordered messages for the provided ordering key.
806
+ #
807
+ # @param [String] ordering_key Identifies related messages for which
808
+ # publish order should be respected.
809
+ #
810
+ # @return [boolean] `true` when resumed, `false` otherwise.
811
+ #
812
+ def resume_publish ordering_key
813
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
814
+ @async_publisher.resume_publish ordering_key
291
815
  end
292
816
 
293
817
  ##
@@ -309,7 +833,7 @@ module Google
309
833
  # @example
310
834
  # require "google/cloud/pubsub"
311
835
  #
312
- # pubsub = Google::Cloud::Pubsub.new
836
+ # pubsub = Google::Cloud::PubSub.new
313
837
  # topic = pubsub.topic "my-topic"
314
838
  #
315
839
  # policy = topic.policy
@@ -317,7 +841,7 @@ module Google
317
841
  # @example Update the policy by passing a block:
318
842
  # require "google/cloud/pubsub"
319
843
  #
320
- # pubsub = Google::Cloud::Pubsub.new
844
+ # pubsub = Google::Cloud::PubSub.new
321
845
  # topic = pubsub.topic "my-topic"
322
846
  #
323
847
  # topic.policy do |p|
@@ -330,13 +854,13 @@ module Google
330
854
  policy = Policy.from_grpc grpc
331
855
  return policy unless block_given?
332
856
  yield policy
333
- self.policy = policy
857
+ update_policy policy
334
858
  end
335
859
 
336
860
  ##
337
861
  # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
338
862
  # policy for this topic. The policy should be read from {#policy}. See
339
- # {Google::Cloud::Pubsub::Policy} for an explanation of the policy
863
+ # {Google::Cloud::PubSub::Policy} for an explanation of the policy
340
864
  # `etag` property and how to modify policies.
341
865
  #
342
866
  # You can also update the policy by passing a block to {#policy}, which
@@ -353,20 +877,21 @@ module Google
353
877
  # @example
354
878
  # require "google/cloud/pubsub"
355
879
  #
356
- # pubsub = Google::Cloud::Pubsub.new
880
+ # pubsub = Google::Cloud::PubSub.new
357
881
  # topic = pubsub.topic "my-topic"
358
882
  #
359
883
  # policy = topic.policy # API call
360
884
  #
361
885
  # policy.add "roles/owner", "user:owner@example.com"
362
886
  #
363
- # topic.policy = policy # API call
887
+ # topic.update_policy policy # API call
364
888
  #
365
- def policy= new_policy
889
+ def update_policy new_policy
366
890
  ensure_service!
367
891
  grpc = service.set_topic_policy name, new_policy.to_grpc
368
892
  @policy = Policy.from_grpc grpc
369
893
  end
894
+ alias policy= update_policy
370
895
 
371
896
  ##
372
897
  # Tests the specified permissions against the [Cloud
@@ -394,7 +919,7 @@ module Google
394
919
  # @example
395
920
  # require "google/cloud/pubsub"
396
921
  #
397
- # pubsub = Google::Cloud::Pubsub.new
922
+ # pubsub = Google::Cloud::PubSub.new
398
923
  # topic = pubsub.topic "my-topic"
399
924
  # perms = topic.test_permissions "pubsub.topics.get",
400
925
  # "pubsub.topics.publish"
@@ -415,42 +940,97 @@ module Google
415
940
  # @example
416
941
  # require "google/cloud/pubsub"
417
942
  #
418
- # pubsub = Google::Cloud::Pubsub.new
943
+ # pubsub = Google::Cloud::PubSub.new
419
944
  #
420
945
  # topic = pubsub.topic "my-topic"
421
946
  # topic.exists? #=> true
422
947
  #
423
948
  def exists?
424
- # Always true if we have a grpc object
425
- return true unless @grpc.nil?
949
+ # Always true if the object is not set as reference
950
+ return true unless reference?
426
951
  # If we have a value, return it
427
952
  return @exists unless @exists.nil?
428
953
  ensure_grpc!
429
- @exists = !@grpc.nil?
954
+ @exists = true
955
+ rescue Google::Cloud::NotFoundError
956
+ @exists = false
430
957
  end
431
958
 
432
959
  ##
433
- # @private
434
- # Determines whether the topic object was created with an HTTP call.
960
+ # Determines whether the topic object was created without retrieving the
961
+ # resource representation from the Pub/Sub service.
962
+ #
963
+ # @return [Boolean] `true` when the topic was created without a resource
964
+ # representation, `false` otherwise.
435
965
  #
436
966
  # @example
437
967
  # require "google/cloud/pubsub"
438
968
  #
439
- # pubsub = Google::Cloud::Pubsub.new
969
+ # pubsub = Google::Cloud::PubSub.new
440
970
  #
441
- # topic = pubsub.topic "my-topic"
442
- # topic.lazy? #=> false
971
+ # topic = pubsub.topic "my-topic", skip_lookup: true
972
+ # topic.reference? #=> true
443
973
  #
444
- def lazy?
974
+ def reference?
445
975
  @grpc.nil?
446
976
  end
447
977
 
448
978
  ##
449
- # @private New Topic from a Google::Pubsub::V1::Topic object.
450
- def self.from_grpc grpc, service
451
- new.tap do |f|
452
- f.grpc = grpc
453
- f.service = service
979
+ # Determines whether the topic object was created with a resource
980
+ # representation from the Pub/Sub service.
981
+ #
982
+ # @return [Boolean] `true` when the topic was created with a resource
983
+ # representation, `false` otherwise.
984
+ #
985
+ # @example
986
+ # require "google/cloud/pubsub"
987
+ #
988
+ # pubsub = Google::Cloud::PubSub.new
989
+ #
990
+ # topic = pubsub.topic "my-topic"
991
+ # topic.resource? #=> true
992
+ #
993
+ def resource?
994
+ !@grpc.nil?
995
+ end
996
+
997
+ ##
998
+ # Reloads the topic with current data from the Pub/Sub service.
999
+ #
1000
+ # @return [Google::Cloud::PubSub::Topic] Returns the reloaded topic
1001
+ #
1002
+ # @example
1003
+ # require "google/cloud/pubsub"
1004
+ #
1005
+ # pubsub = Google::Cloud::PubSub.new
1006
+ #
1007
+ # topic = pubsub.topic "my-topic"
1008
+ # topic.reload!
1009
+ #
1010
+ def reload!
1011
+ ensure_service!
1012
+ @grpc = service.get_topic name
1013
+ @resource_name = nil
1014
+ self
1015
+ end
1016
+ alias refresh! reload!
1017
+
1018
+ ##
1019
+ # @private New Topic from a Google::Cloud::PubSub::V1::Topic object.
1020
+ def self.from_grpc grpc, service, async: nil
1021
+ new.tap do |t|
1022
+ t.grpc = grpc
1023
+ t.service = service
1024
+ t.instance_variable_set :@async_opts, async if async
1025
+ end
1026
+ end
1027
+
1028
+ ##
1029
+ # @private New reference {Topic} object without making an HTTP request.
1030
+ def self.from_name name, service, options = {}
1031
+ name = service.topic_path name, options
1032
+ from_grpc(nil, service).tap do |t|
1033
+ t.instance_variable_set :@resource_name, name
454
1034
  end
455
1035
  end
456
1036
 
@@ -460,17 +1040,14 @@ module Google
460
1040
  # @private Raise an error unless an active connection to the service is
461
1041
  # available.
462
1042
  def ensure_service!
463
- fail "Must have active connection to service" unless service
1043
+ raise "Must have active connection to service" unless service
464
1044
  end
465
1045
 
466
1046
  ##
467
- # Ensures a Google::Pubsub::V1::Topic object exists.
1047
+ # Ensures a Google::Cloud::PubSub::V1::Topic object exists.
468
1048
  def ensure_grpc!
469
1049
  ensure_service!
470
- return @grpc if @grpc
471
- @grpc = service.get_topic @name
472
- rescue Google::Cloud::NotFoundError
473
- nil
1050
+ reload! if reference?
474
1051
  end
475
1052
 
476
1053
  ##
@@ -481,5 +1058,7 @@ module Google
481
1058
  end
482
1059
  end
483
1060
  end
1061
+
1062
+ Pubsub = PubSub unless const_defined? :Pubsub
484
1063
  end
485
1064
  end