google-cloud-pubsub 2.8.1 → 2.9.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 5da61231a73b0823ab46134a7e6405ece35e996245f81c3af1c65fef838223f1
4
- data.tar.gz: c81dd4e57f758fa03b118b30f98d6c72e3cf01ad851560064191f9666582d2b7
3
+ metadata.gz: 8394bc5fb6c16d7ce9e7cb3245014813255379c0e7ed8e43031e5426d0815b49
4
+ data.tar.gz: def32abf5611649a5bf1d6b4d5f2f5c13b498a79f286503bfc343d662ecf260b
5
5
  SHA512:
6
- metadata.gz: 3836f7e50294bfb38760821cb056be595b0f35b50da70c52b417ee8b6274c8e95f3f320a52fe28c50ba1005ce1f67553ddc1a054e4eea7fa8099b0207600c832
7
- data.tar.gz: b5bfb8729b9ac7ad067cb51b2812f777377b7b1737e9e1b4e5198aee2fa7fa856b9e9307314ba087094a417ce634ed22ae1096b945876066c9095809e6239f67
6
+ metadata.gz: e385d303a2ebad9b7ffb0510452d146af19de56cafdf8ffda81a23952fce998a2f38be41b95781ea4cc12e55e6f85782afbbbb427d2b39f96ef21477e053bded
7
+ data.tar.gz: 3e758b507919e9a06d8760a4f422eb7b91ddfb832be1a708e98569604ff87688c44a8afb5c1cdbe088194fe9a32d4d2cd08a4c7bfec7a804fa3cf44f87ca359a
data/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Release History
2
2
 
3
+ ### 2.9.2 (2022-04-28)
4
+
5
+ #### Bug Fixes
6
+
7
+ * ignore grpc errors on ack/modack
8
+
9
+ ### 2.9.1 / 2022-01-11
10
+
11
+ #### Documentation
12
+
13
+ * Update contributing docs
14
+ * Add section on gRPC interceptors to the logging docs
15
+
16
+ ### 2.9.0 / 2021-10-28
17
+
18
+ #### Features
19
+
20
+ * Expand timeout type from Integer to Numeric
21
+ * feat: Expand timeout type from Integer to Numeric. This is backwards-compatible.
22
+ * Change timeout from Integer to Numeric in Google::Cloud.pubsub
23
+ * Change timeout from Integer to Numeric in Google::Cloud#pubsub
24
+ * Change timeout from Integer to Numeric in Google::Cloud::PubSub.configure
25
+ * Change timeout from Integer to Numeric in Google::Cloud::PubSub.new
26
+ * fix: Propagate timeout to client RPC configs.
27
+
28
+ #### Documentation
29
+
30
+ * Add documentation for quota_project Configuration attribute
31
+ * Fix documentation for PubSub.configure
32
+ * Remove retries property that does not exist in code.
33
+
3
34
  ### 2.8.1 / 2021-09-22
4
35
 
5
36
  #### Bug Fixes
data/CONTRIBUTING.md CHANGED
@@ -1,187 +1,400 @@
1
1
  # Contributing to Google Cloud Pub/Sub
2
2
 
3
- 1. **Sign one of the contributor license agreements below.**
4
- 2. Fork the repo, develop and test your code changes.
5
- 3. Send a pull request.
3
+ Thank you for your interest in making a contribution to google-cloud-ruby. Community contributions are an essential part
4
+ of open source, and we want to make contributing easy for you. If you have any suggestions for how to improve this
5
+ guide, please [open an issue](https://github.com/googleapis/google-cloud-ruby/issues) and let us know!
6
6
 
7
- ## Contributor License Agreements
7
+ ### Code of Conduct
8
8
 
9
- Before we can accept your pull requests you'll need to sign a Contributor
10
- License Agreement (CLA):
9
+ Please note that this project is covered by a Contributor Code of Conduct. By participating in this project you agree to
10
+ abide by its terms. See {file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
11
11
 
12
- - **If you are an individual writing original source code** and **you own the
13
- intellectual property**, then you'll need to sign an [individual
14
- CLA](https://developers.google.com/open-source/cla/individual).
15
- - **If you work for a company that wants to allow you to contribute your work**,
16
- then you'll need to sign a [corporate
12
+ ## Overview
13
+
14
+ 1. [Open an issue](#open-an-issue)
15
+ 1. [Sign Contributor License Agreement](#sign-contributor-license-agreement)
16
+ 1. [Set up environment](#set-up-environment)
17
+ 1. [Run CI](#run-ci)
18
+ 1. [Make changes](#make-changes)
19
+ 1. [Commit changes](#commit-changes)
20
+ 1. [Run CI again](#run-ci-again)
21
+ 1. [Submit your pull request](#submit-your-pull-request)
22
+
23
+ ## Open an issue
24
+
25
+ Pull requests should generally be directed by an existing issue, otherwise you risk working on something that the
26
+ maintainers might not be able to accept into the project. Please take a look through [the repository
27
+ issues](https://github.com/googleapis/google-cloud-ruby/issues?q=is%3Aissue+label%3A%22api%3A+pubsub%22), and if you
28
+ do not see an existing issue for your problem or feature, please open one using one of the provided templates.
29
+
30
+ ## Sign Contributor License Agreement
31
+
32
+ Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):
33
+
34
+ - **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need
35
+ to sign an [individual CLA](https://developers.google.com/open-source/cla/individual).
36
+ - **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a [corporate
17
37
  CLA](https://developers.google.com/open-source/cla/corporate).
18
38
 
19
- You can sign these electronically (just scroll to the bottom). After that, we'll
20
- be able to accept your pull requests.
39
+ You can sign these electronically. After that, we'll be able to accept your pull requests.
40
+
41
+ ## Set up environment
42
+
43
+ Before you start on a pull request, you should prepare your work environment for development, acceptance testing and the
44
+ interactive console (optional).
21
45
 
22
- ## Setup
46
+ ### Local development setup
23
47
 
24
- In order to use the google-cloud-pubsub console and run the project's tests,
25
- there is a small amount of setup:
48
+ To set up your local development environment:
26
49
 
27
- 1. Install Ruby. google-cloud-pubsub requires Ruby 2.5+. You may choose to
28
- manage your Ruby and gem installations with [RVM](https://rvm.io/),
29
- [rbenv](https://github.com/rbenv/rbenv), or
30
- [chruby](https://github.com/postmodern/chruby).
50
+ 1. Install a [supported version](google-cloud-pubsub.gemspec) (or versions) of Ruby. (You may choose to manage your
51
+ Ruby and gem installations with [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv),
52
+ [chruby](https://github.com/postmodern/chruby) or a similar tool.)
31
53
 
32
- 2. Install [Bundler](http://bundler.io/).
54
+ 1. Install [Bundler](http://bundler.io/).
33
55
 
34
56
  ```sh
35
57
  $ gem install bundler
36
58
  ```
37
59
 
38
- 3. Install the top-level project dependencies.
60
+ 1. [Fork](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks) the
61
+ [google-cloud-ruby](https://github.com/googleapis/google-cloud-ruby) repo, clone your fork, and configure the
62
+ `upstream`
63
+ [remote](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork):
64
+
65
+ ```bash
66
+ git clone https://github.com/<your-username>/google-cloud-ruby.git
67
+ cd google-cloud-ruby
68
+ git remote add upstream git@github.com:googleapis/google-cloud-ruby.git
69
+ ```
70
+
71
+ 1. If your fork and clone are not brand new, get the latest changes from `upstream`:
72
+
73
+ ```bash
74
+ git checkout main
75
+ git pull upstream main
76
+ ```
77
+
78
+ 1. Change to the library's sub-directory in the repo:
39
79
 
40
80
  ```sh
41
- $ bundle install
81
+ $ cd google-cloud-pubsub
42
82
  ```
43
83
 
44
- 4. Install the Pub/Sub dependencies.
84
+ 1. Install (or update) the library dependencies:
45
85
 
46
86
  ```sh
47
- $ cd google-cloud-pubsub/
48
- $ bundle install
87
+ $ bundle update
49
88
  ```
50
89
 
51
- ## Console
90
+ 1. Create a new topic branch off of the `main` branch:
52
91
 
53
- In order to run code interactively, you can automatically load
54
- google-cloud-pubsub and its dependencies in IRB. This requires that your
55
- developer environment has already been configured by following the steps
56
- described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
57
- can be created with:
92
+ ```bash
93
+ git checkout -b <topic-branch>
94
+ ```
58
95
 
59
- ```sh
60
- $ cd google-cloud-pubsub/
61
- $ bundle exec rake console
62
- ```
96
+ ### Acceptance tests setup
97
+
98
+ To set up your acceptance test credentials:
99
+
100
+ 1. If needed, create a Google Cloud project. In the Google Cloud Console, on the project selector page, select or create
101
+ a project.
102
+
103
+ 1. Ensure that billing is enabled for your project.
104
+
105
+ 1. Ensure that the Cloud Pub/Sub API is enabled for your project.
63
106
 
64
- ## Pub/Sub Tests
107
+ 1. Follow the instructions for [Creating a Service Account](AUTHENTICATION.md#creating-a-service-account) in
108
+ `AUTHENTICATION.md`, including downloading and securely storing a JSON key file.
65
109
 
66
- Tests are very important part of google-cloud-pubsub. All contributions
67
- should include tests that ensure the contributed code behaves as expected.
110
+ 1. Set the `GCLOUD_TEST_KEYFILE` environment variable to the path of the JSON key file that you downloaded in the
111
+ previous step:
68
112
 
69
- To run the unit tests, documentation tests, and code style checks together for a
70
- package:
113
+ ``` sh
114
+ $ export GCLOUD_TEST_KEYFILE=/path/to/keyfile.json
115
+ ```
116
+
117
+ If you are already using the `GCLOUD_TEST_KEYFILE` environment variable, and wish to test this library with a
118
+ different key file, you may set the `PUBSUB_TEST_KEYFILE` environment variable instead:
119
+
120
+ ``` sh
121
+ $ export PUBSUB_TEST_KEYFILE=/path/to/keyfile.json
122
+ ```
123
+
124
+ 1. Set the `GCLOUD_TEST_PROJECT` environment variable to your Google Cloud project ID:
125
+
126
+ ``` sh
127
+ $ export GCLOUD_TEST_PROJECT=my-project-id
128
+ ```
129
+
130
+ If you are already using the `GCLOUD_TEST_PROJECT` environment variable, and wish to test this library with a
131
+ different project, you may set the `PUBSUB_TEST_PROJECT` environment variable instead:
132
+
133
+ ``` sh
134
+ $ export PUBSUB_TEST_PROJECT=my-project-id
135
+ ```
136
+
137
+ ### Interactive console setup (optional)
138
+
139
+ To set up your interactive console credentials:
140
+
141
+ 1. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file (see
142
+ above):
143
+
144
+ ``` sh
145
+ $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
146
+ ```
147
+
148
+ If you are already using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, and wish to test this library
149
+ with a different key file, you may set the `PUBSUB_CREDENTIALS` environment variable instead:
150
+
151
+ ``` sh
152
+ $ export PUBSUB_CREDENTIALS=/path/to/keyfile.json
153
+ ```
154
+
155
+ 1. Set the `GOOGLE_CLOUD_PROJECT` environment variable to your Google Cloud project ID:
156
+
157
+ ``` sh
158
+ $ export GOOGLE_CLOUD_PROJECT=my-project-id
159
+ ```
160
+
161
+ If you are already using the `GOOGLE_CLOUD_PROJECT` environment variable, and wish to test this library with a
162
+ different project, you may set the `PUBSUB_PROJECT` environment variable instead:
163
+
164
+ ``` sh
165
+ $ export PUBSUB_PROJECT=my-project-id
166
+ ```
167
+
168
+
169
+ ## Run CI
170
+
171
+ You are now ready to run local CI checks for the library, which you should do **before** you make any changes. Doing so
172
+ ensures that everything is OK with your local environment and the latest dependency versions. You don't want any
173
+ surprises later.
174
+
175
+ If you haven't already done so, change to the library's sub-directory in the repo:
176
+
177
+ ```sh
178
+ $ cd google-cloud-pubsub
179
+ ```
180
+
181
+ To run the code style checks, documentation tests, and unit tests together, use the `ci` task:
71
182
 
72
183
  ``` sh
73
- $ cd google-cloud-pubsub/
74
184
  $ bundle exec rake ci
75
185
  ```
76
186
 
77
- To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
78
- its handy alias, `rake ci:a`.
187
+ To run the command above, plus all acceptance tests, use `rake ci:acceptance` or its handy alias, `rake ci:a`. Keep in
188
+ mind that the acceptance tests typically take longer than the other CI checks and require authentication credentials.
189
+ See the [Acceptance tests](#Acceptance-tests) section below for more information.
79
190
 
80
- ### Pub/Sub Unit Tests
191
+ The Rake tasks aggregated in the commands above can be run individually to streamline your workflow when developing or
192
+ debugging.
81
193
 
194
+ | CI check | Command |
195
+ |-----------------------------------------------|------------------ |
196
+ | [Static code analysis](#Static-code-analysis) | `rake rubocop` |
197
+ | [Documentation tests](#Documentation-tests) | `rake doctest` |
198
+ | [Unit tests](#Unit-tests) | `rake test` |
199
+ | [Acceptance tests](#Acceptance-tests) | `rake acceptance` |
82
200
 
83
- The project uses the [minitest](https://github.com/seattlerb/minitest) library,
84
- including [specs](https://github.com/seattlerb/minitest#specs),
85
- [mocks](https://github.com/seattlerb/minitest#mocks) and
86
- [minitest-autotest](https://github.com/seattlerb/minitest-autotest).
201
+ The subsections below describe the individual CI checks.
87
202
 
88
- To run the Pub/Sub unit tests:
203
+ ### Static code analysis
89
204
 
90
- ``` sh
91
- $ cd google-cloud-pubsub/
92
- $ bundle exec rake test
205
+ The project uses [Rubocop](https://github.com/rubocop/rubocop) configured with the shared
206
+ [googleapis/ruby-style](https://github.com/googleapis/ruby-style) rules to ensure that your code adheres to
207
+ Google's Ruby style. The style is largely based on [The Ruby Style
208
+ Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions:
209
+
210
+ * Avoid parentheses when possible, including in method definitions.
211
+ * Use double-quoted strings.
212
+
213
+ You can check your code against these rules by running the Rubocop Rake task:
214
+
215
+ ```sh
216
+ $ bundle exec rake rubocop
93
217
  ```
94
218
 
95
- ### Pub/Sub Documentation Tests
219
+ In the rare case that you need to override the existing Rubocop configuration for this library in order to accommodate
220
+ your changes, you can do so by updating [.rubocop.yml](.rubocop.yml).
96
221
 
97
- The project tests the code examples in the gem's
98
- [YARD](https://github.com/lsegal/yard)-based documentation.
222
+ ### Documentation tests
99
223
 
100
- The example testing functions in a way that is very similar to unit testing, and
101
- in fact the library providing it,
102
- [yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
103
- project's unit test library, [minitest](https://github.com/seattlerb/minitest).
224
+ When adding a new feature, you should almost always add one or more in-line documentation code examples demonstrating
225
+ the use of the feature, using [YARD](https://github.com/lsegal/yard)'s
226
+ [`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag. Be sure to write a complete, executable
227
+ example that includes the library `require` statement and client initialization.
104
228
 
105
- To run the Pub/Sub documentation tests:
229
+ The project uses [yard-doctest](https://github.com/p0deje/yard-doctest) to execute each sample as a unit test:
106
230
 
107
231
  ``` sh
108
- $ cd google-cloud-pubsub/
109
232
  $ bundle exec rake doctest
110
233
  ```
111
234
 
112
- If you add, remove or modify documentation examples when working on a pull
113
- request, you may need to update the setup for the tests. The stubs and mocks
114
- required to run the tests are located in `support/doctest_helper.rb`. Please
115
- note that much of the setup is matched by the title of the
116
- [`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
117
- If you alter an example's title, you may encounter breaking tests.
235
+ If you add, remove or modify documentation examples, you may need to update the setup for the tests. The fixtures, stubs
236
+ and mocks required to run the tests are located in [support/doctest_helper.rb](support/doctest_helper.rb). Please note
237
+ that much of the setup is matched to its corresponding example by the title of the `@example` tag. If you alter an
238
+ example's title, you may encounter broken tests.
118
239
 
119
- ### Pub/Sub Acceptance Tests
240
+ There are generally no assertions or mock verifications in these tests. They simply check that the examples are
241
+ syntactically correct and execute against the library source code without error.
120
242
 
121
- The Pub/Sub acceptance tests interact with the live service API. Follow the
122
- instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
123
- the Pub/Sub API. Occasionally, some API features may not yet be generally
124
- available, making it difficult for some contributors to successfully run the
125
- entire acceptance test suite. However, please ensure that you do successfully
126
- run acceptance tests for any code areas covered by your pull request.
243
+ ### Unit tests
127
244
 
128
- To run the acceptance tests, first create and configure a project in the Google
129
- Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
130
- the KEYFILE location on your system.
245
+ The project uses the [minitest](https://github.com/seattlerb/minitest) library, including
246
+ [specs](https://github.com/seattlerb/minitest#specs-), [mocks](https://github.com/seattlerb/minitest#mocks-),
247
+ [minitest-autotest](https://github.com/seattlerb/minitest-autotest), and
248
+ [minitest-focus](https://github.com/seattlerb/minitest-focus).
131
249
 
132
- Before you can run the Pub/Sub acceptance tests, you must first create indexes
133
- used in the tests.
134
-
135
- #### Running the Pub/Sub acceptance tests
136
-
137
- To run the Pub/Sub acceptance tests:
250
+ To run the unit tests:
138
251
 
139
252
  ``` sh
140
- $ cd google-cloud-pubsub/
141
- $ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
253
+ $ bundle exec rake test
142
254
  ```
143
255
 
144
- Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
145
- `GCLOUD_TEST_KEYFILE` environment variables:
256
+ Although the unit tests are intended to run quickly, during development or debugging you may want to isolate one or more
257
+ of the tests by placing the `focus` keyword just above the test declaration. (See
258
+ [minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
146
259
 
147
- ``` sh
148
- $ cd google-cloud-pubsub/
149
- $ export GCLOUD_TEST_PROJECT=\\{my-project-id}
150
- $ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
151
- $ bundle exec rake acceptance
152
- ```
260
+ ### Acceptance Tests
261
+
262
+ The acceptance tests (a.k.a. integration tests) ensure that the library works correctly against the live service API.
263
+ To configure your Google Cloud project, see [Acceptance tests setup](#acceptance-tests-setup) above.
264
+
265
+ **Warning: You may incur charges while running the acceptance tests against your Google Cloud project.**
153
266
 
154
- If you want to use a different project and credentials for acceptance tests, you
155
- can use the more specific `PUBSUB_TEST_PROJECT` and `PUBSUB_TEST_KEYFILE`
156
- environment variables:
267
+ Like the unit tests, the acceptance tests are based on the [minitest](https://github.com/seattlerb/minitest) library,
268
+ including [specs](https://github.com/seattlerb/minitest#specs-) and
269
+ [minitest-focus](https://github.com/seattlerb/minitest-focus). Mocks are not generally used in acceptance tests.
270
+
271
+ Because the acceptance test suite is often time-consuming to run in its entirety, during development or debugging you
272
+ may want to isolate one or more of the tests by placing the `focus` keyword just above the test declaration. (See
273
+ [minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
274
+
275
+ To run the acceptance tests:
157
276
 
158
277
  ``` sh
159
- $ cd google-cloud-pubsub/
160
- $ export PUBSUB_TEST_PROJECT=\\{my-project-id}
161
- $ export PUBSUB_TEST_KEYFILE=\\{/path/to/keyfile.json}
162
278
  $ bundle exec rake acceptance
163
279
  ```
164
280
 
165
- ## Coding Style
281
+ Some acceptance tests may depend on API features that are not yet generally available, and will fail unless your project
282
+ is added to an internal allowlist. There may also be tests that usually pass but fail occasionally due to issues like
283
+ eventual consistency. However, please ensure that you do successfully run acceptance tests for any code areas covered by
284
+ your pull request.
285
+
286
+ ## Make changes
166
287
 
167
- Please follow the established coding style in the library. The style is is
168
- largely based on [The Ruby Style
169
- Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
170
- on seattle-style:
288
+ All contributions should include new or updated tests to ensure that the contributed code behaves as expected.
171
289
 
172
- * Avoid parenthesis when possible, including in method definitions.
173
- * Always use double quotes strings. ([Option
174
- B](https://github.com/bbatsov/ruby-style-guide#strings))
290
+ When starting work on a new feature, it often makes sense to begin with a basic acceptance test to ensure that the new
291
+ feature is present in the live service API and is available to your project. To run your new test exclusively,
292
+ temporarily add the `focus` keyword just above the test declaration. (See
293
+ [minitest-focus](https://github.com/seattlerb/minitest-focus) for details.) Also, the acceptance tests have a retry
294
+ mechanism that can sometimes make it hard to see the correct error when things go wrong. To disable retries while
295
+ debugging errors, temporarily comment out or remove the `run_one_method` method definition in
296
+ [acceptance/pubsub_helper.rb](acceptance/pubsub_helper.rb).
175
297
 
176
- You can check your code against these rules by running Rubocop like so:
298
+ When you are done developing, be sure to remove any usages of the `focus` keyword from your tests and restore the
299
+ `run_one_method` method definition if you removed it.
300
+
301
+ ### Console
302
+
303
+ The project includes a Rake task that automatically loads `google-cloud-pubsub` and its dependencies in IRB. To
304
+ configure your Google Cloud project for IRB, see [Interactive console setup](#interactive-console-setup-optional) above.
305
+
306
+ **Warning: You may incur charges while using the library with your Google Cloud project.**
307
+
308
+ If you haven't already done so, change to the library's sub-directory in the repo:
177
309
 
178
310
  ```sh
179
- $ cd google-cloud-pubsub/
180
- $ bundle exec rake rubocop
311
+ $ cd google-cloud-pubsub
312
+ ```
313
+
314
+ The preloaded IRB console can be used as follows:
315
+
316
+ ```sh
317
+ $ bundle exec rake console
318
+ irb(main):001:0> require "google/cloud/pubsub"
319
+ => true
320
+ irb(main):002:0> pubsub = Google::Cloud::PubSub.new
181
321
  ```
182
322
 
183
- ## Code of Conduct
323
+ Using the console provides an interactive alternative to acceptance testing that may make it easier to explore usage and
324
+ debug problems.
325
+
326
+ ## Commit changes
327
+
328
+ Commit your changes using [conventional commits](https://www.conventionalcommits.org/), making sure to include the
329
+ associated GitHub issue number. Below is an example of a `feat` type commit that will result in a semver `minor`
330
+ release. Notice how it is scoped to the short name of the library, contains a bulleted list of public API changes, and
331
+ ends with the `closes` GitHub keyword. If this is the only new commit in your branch when you open your pull request,
332
+ the commit body including the `closes` phrase will be copied to your PR description. If you have multiple commits, you
333
+ should copy the body of this anchor commit manually to the PR description, so that GitHub will [automatically close the
334
+ related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
335
+
336
+ ```bash
337
+ git commit -am "feat(pubsub): Add my new feature
338
+
339
+ * Add MyClass#my_method
340
+
341
+ closes: #123"
342
+ ```
343
+
344
+ The messages for any subsequent commits you may add do not necessarily need to follow the conventional commits format,
345
+ as these messages will be manually dropped or added as bullet points to the original message when the PR is squashed and
346
+ merged.
347
+
348
+ ## Run CI again
349
+
350
+
351
+ 1. If you haven't already done so, change to the library's sub-directory in the repo:
352
+
353
+ ```sh
354
+ $ cd google-cloud-pubsub
355
+ ```
356
+
357
+ 1. Rebase your topic branch on the upstream `main` branch:
358
+
359
+ ```bash
360
+ git pull --rebase upstream main
361
+ ```
362
+
363
+ 1. Run the `ci` task:
364
+
365
+ ``` sh
366
+ $ bundle exec rake ci
367
+ ```
368
+
369
+ 1. Run the `acceptance` task:
370
+
371
+ ``` sh
372
+ $ bundle exec rake acceptance
373
+ ```
374
+
375
+ Ensure that everything is passing in `rake ci` and `rake acceptance`, or at least that `rake ci` is green and you
376
+ haven't broken anything new in `rake acceptance`, before you open your pull request.
377
+
378
+ ## Submit your pull request
379
+
380
+ 1. Rebase your topic branch on the upstream `main` branch:
381
+
382
+ ```bash
383
+ git pull --rebase upstream main
384
+ ```
385
+
386
+ 1. Push your topic branch to your fork:
387
+
388
+ ```bash
389
+ git push origin -u
390
+ ```
391
+
392
+ 1. Open a [pull
393
+ request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
394
+ using the first line of your conventional commit as the title, and with the associated GitHub issue in the
395
+ description. By convention in this project, the assignee of the pull request will be the maintainer who will merge it
396
+ once it is approved. If you are a maintainer of the project, typically you should assign the pull request to
397
+ yourself.
398
+
399
+ 1. Ensure that all of the GitHub checks are passing.
184
400
 
185
- Please note that this project is released with a Contributor Code of Conduct. By
186
- participating in this project you agree to abide by its terms. See
187
- {file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
data/LOGGING.md CHANGED
@@ -1,4 +1,6 @@
1
- # Enabling gRPC Logging
1
+ # Logging
2
+
3
+ ## Enabling gRPC Logging
2
4
 
3
5
  To enable logging for this library, set the logger for the underlying
4
6
  [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
@@ -17,6 +19,7 @@ Configuring a Ruby stdlib logger:
17
19
 
18
20
  ```ruby
19
21
  require "logger"
22
+ require "grpc"
20
23
 
21
24
  module MyLogger
22
25
  LOGGER = Logger.new $stderr, level: Logger::WARN
@@ -30,3 +33,92 @@ module GRPC
30
33
  extend MyLogger
31
34
  end
32
35
  ```
36
+
37
+ ## Adding gRPC interceptors
38
+
39
+ [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) accepts [Ruby-language
40
+ interceptors](https://github.com/grpc/proposal/blob/master/L11-ruby-interceptors.md) that allow you to insert your own
41
+ custom logging into a client's RPC calls. (gRPC interceptors are also useful for auth, metrics, tracing and similar
42
+ use cases.)
43
+
44
+ This library performs RPCs using the following [gapic](https://github.com/googleapis/gapic-generator-ruby) clients from
45
+ the underlying
46
+ [google-cloud-pubsub-v1](https://github.com/googleapis/google-cloud-ruby/tree/main/google-cloud-pubsub-v1) library:
47
+
48
+ * [`Google::Cloud::PubSub::V1::IAMPolicy::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/IAMPolicy/Client.html)
49
+ * [`Google::Cloud::PubSub::V1::Publisher::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/Publisher/Client.html)
50
+ * [`Google::Cloud::PubSub::V1::SchemaService::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/SchemaService/Client.html)
51
+ * [`Google::Cloud::PubSub::V1::Subscriber::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/Subscriber/Client.html)
52
+
53
+ To add a gRPC interceptor to one or more of these clients, first implement your logic as a subclass of
54
+ [`GRPC::ClientInterceptor`](https://www.rubydoc.info/gems/grpc/GRPC/ClientInterceptor). The example below logs all four
55
+ types of gRPC calls (unary, client streaming, server streaming, and bi-directional streaming.) It also demonstrates how
56
+ to set a metadata field.
57
+
58
+ ```ruby
59
+ require "grpc"
60
+ require "logger"
61
+ require "securerandom"
62
+
63
+ class MyInterceptor < GRPC::ClientInterceptor
64
+ attr_reader :name
65
+
66
+ def initialize name
67
+ @name = name
68
+ end
69
+
70
+ def request_response(request:, call:, method:, metadata:)
71
+ logger.info "[#{name}] Sending unary request/response to #{method}"
72
+ metadata["request_id"] = generate_request_id
73
+ yield
74
+ end
75
+
76
+ def client_streamer(requests:, call:, method:, metadata:)
77
+ logger.info "[#{name}] Sending client streamer to #{method}"
78
+ metadata["request_id"] = generate_request_id
79
+ yield
80
+ end
81
+
82
+ def server_streamer(request:, call:, method:, metadata:)
83
+ logger.info "[#{name}] Sending server streamer to #{method}"
84
+ metadata["request_id"] = generate_request_id
85
+ yield
86
+ end
87
+
88
+ def bidi_streamer(requests:, call:, method:, metadata:)
89
+ logger.info "[#{name}] Sending bidi streamer to #{method}"
90
+ metadata["request_id"] = generate_request_id
91
+ yield
92
+ end
93
+
94
+ private
95
+
96
+ def logger
97
+ @logger ||= Logger.new(STDOUT)
98
+ end
99
+
100
+ def generate_request_id
101
+ SecureRandom.uuid
102
+ end
103
+ end
104
+ ```
105
+
106
+ Next, use the block yielded by a `Client.configure` method to add an instance of your class to the `interceptors`
107
+ configuration of one or more of the generated clients listed above.
108
+
109
+ Note that the `Google::Cloud::PubSub::V1` configurations must be performed **before** the `Google::Cloud::PubSub` client
110
+ is instantiated.
111
+
112
+ ```ruby
113
+ require "google/cloud/pubsub"
114
+
115
+ Google::Cloud::PubSub::V1::Publisher::Client.configure do |config|
116
+ config.interceptors = [MyInterceptor.new("MyPublisherInterceptor")]
117
+ end
118
+
119
+ Google::Cloud::PubSub::V1::Subscriber::Client.configure do |config|
120
+ config.interceptors = [MyInterceptor.new("MySubscriberInterceptor")]
121
+ end
122
+
123
+ pubsub = Google::Cloud::PubSub.new
124
+ ```
data/OVERVIEW.md CHANGED
@@ -452,7 +452,7 @@ if your account has limited access to the Pub/Sub API. In particular, the role
452
452
  `roles/pubsub.subscriber` does not have the permission
453
453
  `pubsub.subscriptions.get`, which is required to retrieve a subscription
454
454
  resource. See [Access Control -
455
- Roles](https://cloud.google.com/pubsub/docs/access-control#tbl_roles) for the
455
+ Roles](https://cloud.google.com/pubsub/docs/access-control#roles) for the
456
456
  complete list of Pub/Sub roles and permissions.
457
457
 
458
458
  ## Creating a snapshot and using seek
@@ -51,7 +51,7 @@ module Google
51
51
  return mocked_subscriber if mocked_subscriber
52
52
  @subscriber ||= V1::Subscriber::Client.new do |config|
53
53
  config.credentials = credentials if credentials
54
- config.timeout = timeout if timeout
54
+ override_client_config_timeouts config if timeout
55
55
  config.endpoint = host if host
56
56
  config.lib_name = "gccl"
57
57
  config.lib_version = Google::Cloud::PubSub::VERSION
@@ -64,7 +64,7 @@ module Google
64
64
  return mocked_publisher if mocked_publisher
65
65
  @publisher ||= V1::Publisher::Client.new do |config|
66
66
  config.credentials = credentials if credentials
67
- config.timeout = timeout if timeout
67
+ override_client_config_timeouts config if timeout
68
68
  config.endpoint = host if host
69
69
  config.lib_name = "gccl"
70
70
  config.lib_version = Google::Cloud::PubSub::VERSION
@@ -77,7 +77,7 @@ module Google
77
77
  return mocked_iam if mocked_iam
78
78
  @iam ||= V1::IAMPolicy::Client.new do |config|
79
79
  config.credentials = credentials if credentials
80
- config.timeout = timeout if timeout
80
+ override_client_config_timeouts config if timeout
81
81
  config.endpoint = host if host
82
82
  config.lib_name = "gccl"
83
83
  config.lib_version = Google::Cloud::PubSub::VERSION
@@ -90,7 +90,7 @@ module Google
90
90
  return mocked_schemas if mocked_schemas
91
91
  @schemas ||= V1::SchemaService::Client.new do |config|
92
92
  config.credentials = credentials if credentials
93
- config.timeout = timeout if timeout
93
+ override_client_config_timeouts config if timeout
94
94
  config.endpoint = host if host
95
95
  config.lib_name = "gccl"
96
96
  config.lib_version = Google::Cloud::PubSub::VERSION
@@ -255,7 +255,11 @@ module Google
255
255
  ##
256
256
  # Acknowledges receipt of a message.
257
257
  def acknowledge subscription, *ack_ids
258
- subscriber.acknowledge subscription: subscription_path(subscription), ack_ids: ack_ids
258
+ begin
259
+ subscriber.acknowledge subscription: subscription_path(subscription), ack_ids: ack_ids
260
+ rescue StandardError => e
261
+ raise e unless e.cause.is_a? GRPC::BadStatus
262
+ end
259
263
  end
260
264
 
261
265
  ##
@@ -275,9 +279,13 @@ module Google
275
279
  ##
276
280
  # Modifies the ack deadline for a specific message.
277
281
  def modify_ack_deadline subscription, ids, deadline
278
- subscriber.modify_ack_deadline subscription: subscription_path(subscription),
279
- ack_ids: Array(ids),
280
- ack_deadline_seconds: deadline
282
+ begin
283
+ subscriber.modify_ack_deadline subscription: subscription_path(subscription),
284
+ ack_ids: Array(ids),
285
+ ack_deadline_seconds: deadline
286
+ rescue StandardError => e
287
+ raise e unless e.cause.is_a? GRPC::BadStatus
288
+ end
281
289
  end
282
290
 
283
291
  ##
@@ -461,6 +469,18 @@ module Google
461
469
 
462
470
  protected
463
471
 
472
+ # Set the timeout in the client config.
473
+ # Override the default timeout in each individual RPC config as well, since when they are non-nil, these
474
+ # defaults have precedence over the top-level config.timeout. See Gapic::CallOptions#apply_defaults.
475
+ def override_client_config_timeouts config
476
+ config.timeout = timeout
477
+ rpc_names = config.rpcs.methods - Object.methods
478
+ rpc_names.each do |rpc_name|
479
+ rpc = config.rpcs.send rpc_name
480
+ rpc.timeout = timeout if rpc.respond_to? :timeout=
481
+ end
482
+ end
483
+
464
484
  def a_time? obj
465
485
  return false unless obj.respond_to? :to_time
466
486
  # Rails' String#to_time returns nil if the string doesn't parse.
@@ -425,7 +425,7 @@ module Google
425
425
  # Sets the {Topic} to which dead letter messages for the subscription should be published. Dead lettering is
426
426
  # done on a best effort basis. The same message might be dead lettered multiple times.
427
427
  # The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
428
- # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
428
+ # `service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
429
429
  # topic.
430
430
  #
431
431
  # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached
@@ -410,7 +410,7 @@ module Google
410
410
  # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
411
411
  # published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
412
412
  # times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
413
- # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
413
+ # `service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
414
414
  # this topic.
415
415
  #
416
416
  # The operation will fail if the topic does not exist. Users should ensure that there is a subscription
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module PubSub
19
- VERSION = "2.8.1".freeze
19
+ VERSION = "2.9.2".freeze
20
20
  end
21
21
 
22
22
  Pubsub = PubSub unless const_defined? :Pubsub
@@ -54,7 +54,7 @@ module Google
54
54
  # The default scope is:
55
55
  #
56
56
  # * `https://www.googleapis.com/auth/pubsub`
57
- # @param [Integer] timeout Default timeout to use in requests. Optional.
57
+ # @param [Numeric] timeout Default timeout to use in requests. Optional.
58
58
  # @param [String] endpoint Override of the endpoint host name. Optional.
59
59
  # If the param is nil, uses the default endpoint.
60
60
  # @param [String] emulator_host Pub/Sub emulator host. Optional.
@@ -121,9 +121,9 @@ module Google
121
121
  # parameter `keyfile` is considered deprecated, but may also be used.)
122
122
  # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
123
123
  # the set of resources and operations that the connection can access.
124
- # * `retries` - (Integer) Number of times to retry requests on server
125
- # error.
126
- # * `timeout` - (Integer) Default timeout to use in requests.
124
+ # * `quota_project` - (String) The project ID for a project that can be
125
+ # used by client libraries for quota and billing purposes.
126
+ # * `timeout` - (Numeric) Default timeout to use in requests.
127
127
  # * `endpoint` - (String) Override of the endpoint host name, or `nil`
128
128
  # to use the default endpoint.
129
129
  # * `emulator_host` - (String) Host name of the emulator. Defaults to
@@ -41,7 +41,7 @@ module Google
41
41
  # The default scope is:
42
42
  #
43
43
  # * `https://www.googleapis.com/auth/pubsub`
44
- # @param [Integer] timeout Default timeout to use in requests. Optional.
44
+ # @param [Numeric] timeout Default timeout to use in requests. Optional.
45
45
  #
46
46
  # @return [Google::Cloud::PubSub::Project]
47
47
  #
@@ -87,7 +87,7 @@ module Google
87
87
  # The default scope is:
88
88
  #
89
89
  # * `https://www.googleapis.com/auth/pubsub`
90
- # @param [Integer] timeout Default timeout to use in requests. Optional.
90
+ # @param [Numeric] timeout Default timeout to use in requests. Optional.
91
91
  #
92
92
  # @return [Google::Cloud::PubSub::Project]
93
93
  #
@@ -133,7 +133,7 @@ Google::Cloud.configure.add_config! :pubsub do |config|
133
133
  config.add_alias! :keyfile, :credentials
134
134
  config.add_field! :scope, default_scopes, match: [String, Array]
135
135
  config.add_field! :quota_project, nil, match: String
136
- config.add_field! :timeout, nil, match: Integer
136
+ config.add_field! :timeout, nil, match: Numeric
137
137
  config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true
138
138
  config.add_field! :on_error, nil, match: Proc
139
139
  config.add_field! :endpoint, "pubsub.googleapis.com", match: String
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: google-cloud-pubsub
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.8.1
4
+ version: 2.9.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Moore
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2021-09-22 00:00:00.000000000 Z
12
+ date: 2022-04-29 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: concurrent-ruby
@@ -276,7 +276,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
276
276
  - !ruby/object:Gem::Version
277
277
  version: '0'
278
278
  requirements: []
279
- rubygems_version: 3.2.17
279
+ rubygems_version: 3.3.5
280
280
  signing_key:
281
281
  specification_version: 4
282
282
  summary: API Client library for Google Cloud Pub/Sub