google-cloud-pubsub 0.20.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 (49) hide show
  1. checksums.yaml +5 -5
  2. data/.yardopts +18 -0
  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 +201 -0
  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 +82 -20
  19. data/lib/google/cloud/pubsub/policy.rb +40 -61
  20. data/lib/google/cloud/pubsub/project.rb +405 -265
  21. data/lib/google/cloud/pubsub/publish_result.rb +103 -0
  22. data/lib/google/cloud/pubsub/received_message.rb +165 -30
  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 +304 -162
  27. data/lib/google/cloud/pubsub/snapshot/list.rb +178 -0
  28. data/lib/google/cloud/pubsub/snapshot.rb +205 -0
  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 +38 -43
  36. data/lib/google/cloud/pubsub/subscription/push_config.rb +268 -0
  37. data/lib/google/cloud/pubsub/subscription.rb +1040 -210
  38. data/lib/google/cloud/pubsub/topic/list.rb +32 -37
  39. data/lib/google/cloud/pubsub/topic.rb +726 -177
  40. data/lib/google/cloud/pubsub/version.rb +6 -4
  41. data/lib/google/cloud/pubsub.rb +138 -413
  42. data/lib/google-cloud-pubsub.rb +60 -42
  43. metadata +88 -39
  44. data/lib/google/cloud/pubsub/topic/publisher.rb +0 -87
  45. data/lib/google/iam/v1/iam_policy.rb +0 -33
  46. data/lib/google/iam/v1/iam_policy_services.rb +0 -30
  47. data/lib/google/iam/v1/policy.rb +0 -25
  48. data/lib/google/pubsub/v1/pubsub_pb.rb +0 -129
  49. data/lib/google/pubsub/v1/pubsub_services_pb.rb +0 -117
@@ -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 Subscription
22
22
  ##
23
23
  # Subscription::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 subscriptions
27
27
  # that match the request and this value should be passed to
28
- # the next {Google::Cloud::Pubsub::Topic#subscriptions} to continue.
28
+ # the next {Google::Cloud::PubSub::Topic#subscriptions} to continue.
29
29
  attr_accessor :token
30
30
 
31
31
  ##
@@ -44,10 +44,9 @@ module Google
44
44
  # @return [Boolean]
45
45
  #
46
46
  # @example
47
- # require "google/cloud"
47
+ # require "google/cloud/pubsub"
48
48
  #
49
- # gcloud = Google::Cloud.new
50
- # pubsub = gcloud.pubsub
49
+ # pubsub = Google::Cloud::PubSub.new
51
50
  #
52
51
  # subscriptions = pubsub.subscriptions
53
52
  # if subscriptions.next?
@@ -64,10 +63,9 @@ module Google
64
63
  # @return [Subscription::List]
65
64
  #
66
65
  # @example
67
- # require "google/cloud"
66
+ # require "google/cloud/pubsub"
68
67
  #
69
- # gcloud = Google::Cloud.new
70
- # pubsub = gcloud.pubsub
68
+ # pubsub = Google::Cloud::PubSub.new
71
69
  #
72
70
  # subscriptions = pubsub.subscriptions
73
71
  # if subscriptions.next?
@@ -85,15 +83,15 @@ module Google
85
83
  end
86
84
 
87
85
  ##
88
- # Retrieves all subscriptions by repeatedly loading {#next} until
86
+ # Retrieves remaining results by repeatedly invoking {#next} until
89
87
  # {#next?} returns `false`. Calls the given block once for each
90
- # subscription, which is passed as the parameter.
88
+ # result, which is passed as the argument to the block.
91
89
  #
92
90
  # An Enumerator is returned if no block is given.
93
91
  #
94
- # This method may make several API calls until all subscriptions are
95
- # retrieved. Be sure to use as narrow a search criteria as possible.
96
- # Please use with caution.
92
+ # This method will make repeated API calls until all remaining results
93
+ # are retrieved. (Unlike `#each`, for example, which merely iterates
94
+ # over the results returned by a single API call.) Use with caution.
97
95
  #
98
96
  # @param [Integer] request_limit The upper limit of API requests to
99
97
  # make to load all subscriptions. Default is no limit.
@@ -103,10 +101,9 @@ module Google
103
101
  # @return [Enumerator]
104
102
  #
105
103
  # @example Iterating each subscription by passing a block:
106
- # require "google/cloud"
104
+ # require "google/cloud/pubsub"
107
105
  #
108
- # gcloud = Google::Cloud.new
109
- # pubsub = gcloud.pubsub
106
+ # pubsub = Google::Cloud::PubSub.new
110
107
  #
111
108
  # subscriptions = pubsub.subscriptions
112
109
  # subscriptions.all do |subscription|
@@ -114,10 +111,9 @@ module Google
114
111
  # end
115
112
  #
116
113
  # @example Using the enumerator by not passing a block:
117
- # require "google/cloud"
114
+ # require "google/cloud/pubsub"
118
115
  #
119
- # gcloud = Google::Cloud.new
120
- # pubsub = gcloud.pubsub
116
+ # pubsub = Google::Cloud::PubSub.new
121
117
  #
122
118
  # subscriptions = pubsub.subscriptions
123
119
  # all_names = subscriptions.all.map do |subscription|
@@ -125,27 +121,24 @@ module Google
125
121
  # end
126
122
  #
127
123
  # @example Limit the number of API calls made:
128
- # require "google/cloud"
124
+ # require "google/cloud/pubsub"
129
125
  #
130
- # gcloud = Google::Cloud.new
131
- # pubsub = gcloud.pubsub
126
+ # pubsub = Google::Cloud::PubSub.new
132
127
  #
133
128
  # subscriptions = pubsub.subscriptions
134
129
  # subscriptions.all(request_limit: 10) do |subscription|
135
130
  # puts subscription.name
136
131
  # end
137
132
  #
138
- def all request_limit: nil
133
+ def all request_limit: nil, &block
139
134
  request_limit = request_limit.to_i if request_limit
140
- unless block_given?
141
- return enum_for(:all, request_limit: request_limit)
142
- end
135
+ return enum_for :all, request_limit: request_limit unless block_given?
143
136
  results = self
144
137
  loop do
145
- results.each { |r| yield r }
138
+ results.each(&block)
146
139
  if request_limit
147
140
  request_limit -= 1
148
- break if request_limit < 0
141
+ break if request_limit.negative?
149
142
  end
150
143
  break unless results.next?
151
144
  results = results.next
@@ -154,32 +147,32 @@ module Google
154
147
 
155
148
  ##
156
149
  # @private New Subscriptions::List from a
157
- # Google::Pubsub::V1::ListSubscriptionsRequest object.
150
+ # Google::Cloud::PubSub::V1::ListSubscriptionsRequest object.
158
151
  def self.from_grpc grpc_list, service, max = nil
159
152
  subs = new(Array(grpc_list.subscriptions).map do |grpc|
160
153
  Subscription.from_grpc grpc, service
161
154
  end)
162
155
  token = grpc_list.next_page_token
163
- token = nil if token == ""
164
- subs.instance_variable_set "@token", token
165
- subs.instance_variable_set "@service", service
166
- subs.instance_variable_set "@max", max
156
+ token = nil if token == "".freeze
157
+ subs.instance_variable_set :@token, token
158
+ subs.instance_variable_set :@service, service
159
+ subs.instance_variable_set :@max, max
167
160
  subs
168
161
  end
169
162
 
170
163
  ##
171
164
  # @private New Subscriptions::List from a
172
- # Google::Pubsub::V1::ListTopicSubscriptionsResponse object.
165
+ # Google::Cloud::PubSub::V1::ListTopicSubscriptionsResponse object.
173
166
  def self.from_topic_grpc grpc_list, service, topic, max = nil
174
167
  subs = new(Array(grpc_list.subscriptions).map do |grpc|
175
- Subscription.new_lazy grpc, service
168
+ Subscription.from_name grpc, service
176
169
  end)
177
170
  token = grpc_list.next_page_token
178
- token = nil if token == ""
179
- subs.instance_variable_set "@token", token
180
- subs.instance_variable_set "@service", service
181
- subs.instance_variable_set "@topic", topic
182
- subs.instance_variable_set "@max", max
171
+ token = nil if token == "".freeze
172
+ subs.instance_variable_set :@token, token
173
+ subs.instance_variable_set :@service, service
174
+ subs.instance_variable_set :@topic, topic
175
+ subs.instance_variable_set :@max, max
183
176
  subs
184
177
  end
185
178
 
@@ -189,7 +182,7 @@ module Google
189
182
  # @private Raise an error unless an active connection to the service
190
183
  # is available.
191
184
  def ensure_service!
192
- fail "Must have active connection to service" unless @service
185
+ raise "Must have active connection to service" unless @service
193
186
  end
194
187
 
195
188
  def next_subscriptions
@@ -206,5 +199,7 @@ module Google
206
199
  end
207
200
  end
208
201
  end
202
+
203
+ Pubsub = PubSub unless const_defined? :Pubsub
209
204
  end
210
205
  end
@@ -0,0 +1,268 @@
1
+ # Copyright 2019 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google/pubsub/v1/pubsub_pb"
17
+
18
+ module Google
19
+ module Cloud
20
+ module PubSub
21
+ class Subscription
22
+ ##
23
+ # Configuration for a push delivery endpoint.
24
+ #
25
+ # @example Create a push config:
26
+ # require "google/cloud/pubsub"
27
+ #
28
+ # pubsub = Google::Cloud::PubSub.new
29
+ # topic = pubsub.topic "my-topic"
30
+ #
31
+ # push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: "http://example.net/callback"
32
+ # push_config.set_oidc_token "service-account@example.net", "audience-header-value"
33
+ #
34
+ # sub = topic.subscribe "my-subscription", push_config: push_config
35
+ #
36
+ # @example Read a push config:
37
+ # require "google/cloud/pubsub"
38
+ #
39
+ # pubsub = Google::Cloud::PubSub.new
40
+ #
41
+ # sub = pubsub.subscription "my-topic-sub"
42
+ # sub.push_config.endpoint #=> "http://example.com/callback"
43
+ # sub.push_config.authentication.email #=> "user@example.com"
44
+ # sub.push_config.authentication.audience #=> "client-12345"
45
+ #
46
+ # @example Update a push config:
47
+ # require "google/cloud/pubsub"
48
+ #
49
+ # pubsub = Google::Cloud::PubSub.new
50
+ # sub = pubsub.subscription "my-subscription"
51
+ #
52
+ # sub.push_config do |pc|
53
+ # pc.endpoint = "http://example.net/callback"
54
+ # pc.set_oidc_token "user@example.net", "client-67890"
55
+ # end
56
+ #
57
+ class PushConfig
58
+ ##
59
+ # Creates a new push configuration.
60
+ #
61
+ # @param [String] endpoint A URL locating the endpoint to which messages should be pushed. For
62
+ # example, a Webhook endpoint might use `https://example.com/push`.
63
+ # @param [String] email The service account email to be used for generating the OIDC token.
64
+ # The caller must have the `iam.serviceAccounts.actAs` permission for the service account.
65
+ # @param [String] audience The audience to be used when generating OIDC token. The audience claim identifies
66
+ # the recipients that the JWT is intended for. The audience value is a single case-sensitive string. Having
67
+ # multiple values (array) for the audience field is not supported. More info about the OIDC JWT token
68
+ # audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint`
69
+ # URL will be used.
70
+ #
71
+ def initialize endpoint: nil, email: nil, audience: nil
72
+ @grpc = Google::Cloud::PubSub::V1::PushConfig.new
73
+
74
+ self.endpoint = endpoint unless endpoint.nil?
75
+
76
+ raise ArgumentError, "audience provided without email. Authentication is invalid" if audience && !email
77
+
78
+ set_oidc_token email, audience if email
79
+ end
80
+
81
+ ##
82
+ # A URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might use
83
+ # `https://example.com/push`.
84
+ #
85
+ # @return [String]
86
+ def endpoint
87
+ @grpc.push_endpoint
88
+ end
89
+
90
+ ##
91
+ # Sets the URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might
92
+ # use `https://example.com/push`.
93
+ #
94
+ # @param [String, nil] new_endpoint New URL value
95
+ def endpoint= new_endpoint
96
+ @grpc.push_endpoint = String new_endpoint
97
+ end
98
+
99
+ ##
100
+ # The authentication method used by push endpoints to verify the source of push requests.
101
+ #
102
+ # @return [OidcToken, nil] An OIDC JWT token if specified, `nil`
103
+ # otherwise.
104
+ def authentication
105
+ return nil unless @grpc.authentication_method == :oidc_token
106
+
107
+ OidcToken.from_grpc @grpc.oidc_token
108
+ end
109
+
110
+ ##
111
+ # Sets the authentication method used by push endpoints to verify the source of push requests.
112
+ #
113
+ # @param [OidcToken, nil] new_auth An authentication value.
114
+ def authentication= new_auth
115
+ if new_auth.nil?
116
+ @grpc.oidc_token = nil
117
+ else
118
+ raise ArgumentError unless new_auth.is_a? OidcToken
119
+
120
+ @grpc.oidc_token = new_auth.to_grpc
121
+ end
122
+ end
123
+
124
+ ##
125
+ # Checks whether authentication is an {OidcToken}.
126
+ #
127
+ # @return [Boolean]
128
+ def oidc_token?
129
+ authentication.is_a? OidcToken
130
+ end
131
+
132
+ ##
133
+ # Sets the authentication method to use an {OidcToken}.
134
+ #
135
+ # @param [String] email Service account email.
136
+ # @param [String] audience Audience to be used.
137
+ def set_oidc_token email, audience
138
+ oidc_token = OidcToken.new.tap do |token|
139
+ token.email = email
140
+ token.audience = audience
141
+ end
142
+ self.authentication = oidc_token
143
+ end
144
+
145
+ ##
146
+ # The format of the pushed message. This attribute indicates the version of the data expected by the endpoint.
147
+ # This controls the shape of the pushed message (i.e., its fields and metadata). The endpoint version is based
148
+ # on the version of the Pub/Sub API.
149
+ #
150
+ # If not present during the Subscription creation, it will default to the version of the API used to make such
151
+ # call.
152
+ #
153
+ # The possible values for this attribute are:
154
+ #
155
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub
156
+ # API.
157
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub
158
+ # API.
159
+ #
160
+ # @return [String]
161
+ def version
162
+ @grpc.attributes["x-goog-version"]
163
+ end
164
+
165
+ ##
166
+ # Sets the format of the pushed message.
167
+ #
168
+ # The possible values for this attribute are:
169
+ #
170
+ # * `v1beta1`: uses the push format defined in the v1beta1 Pub/Sub
171
+ # API.
172
+ # * `v1` or `v1beta2`: uses the push format defined in the v1 Pub/Sub
173
+ # API.
174
+ #
175
+ # @param [String, nil] new_version The new version value.
176
+ def version= new_version
177
+ if new_version.nil?
178
+ @grpc.attributes.delete "x-goog-version"
179
+ else
180
+ @grpc.attributes["x-goog-version"] = new_version
181
+ end
182
+ end
183
+
184
+ ##
185
+ # @private
186
+ def to_grpc
187
+ @grpc
188
+ end
189
+
190
+ ##
191
+ # @private
192
+ def self.from_grpc grpc
193
+ new.tap do |pc|
194
+ pc.instance_variable_set :@grpc, grpc.dup if grpc
195
+ end
196
+ end
197
+
198
+ ##
199
+ # Contains information needed for generating an [OpenID Connect
200
+ # token](https://developers.google.com/identity/protocols/OpenIDConnect).
201
+ class OidcToken
202
+ ##
203
+ # @private
204
+ def initialize
205
+ @grpc = Google::Cloud::PubSub::V1::PushConfig::OidcToken.new
206
+ end
207
+
208
+ ##
209
+ # The service account email to be used for generating the OIDC token. The caller must have the
210
+ # `iam.serviceAccounts.actAs` permission for the service account.
211
+ #
212
+ # @return [String]
213
+ def email
214
+ @grpc.service_account_email
215
+ end
216
+
217
+ ##
218
+ # Sets the service account email to be used for generating the OIDC token. The caller must have the
219
+ # `iam.serviceAccounts.actAs` permission for the service account.
220
+ #
221
+ # @param [String] new_email New service account email value.
222
+ def email= new_email
223
+ @grpc.service_account_email = new_email
224
+ end
225
+
226
+ ##
227
+ # The audience to be used when generating OIDC token. The audience claim identifies the recipients that
228
+ # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
229
+ # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
230
+ # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
231
+ #
232
+ # @return [String]
233
+ def audience
234
+ @grpc.audience
235
+ end
236
+
237
+ ##
238
+ # Sets the audience to be used when generating OIDC token. The audience claim identifies the recipients that
239
+ # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
240
+ # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
241
+ # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
242
+ #
243
+ # @param [String] new_audience New audience value.
244
+ def audience= new_audience
245
+ @grpc.audience = new_audience
246
+ end
247
+
248
+ ##
249
+ # @private
250
+ def to_grpc
251
+ @grpc
252
+ end
253
+
254
+ ##
255
+ # @private
256
+ def self.from_grpc grpc
257
+ grpc ||= Google::Cloud::PubSub::V1::PushConfig::OidcToken.new
258
+
259
+ new.tap do |pc|
260
+ pc.instance_variable_set :@grpc, grpc.dup
261
+ end
262
+ end
263
+ end
264
+ end
265
+ end
266
+ end
267
+ end
268
+ end