google-cloud-pubsub 2.9.0 → 2.9.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +7 -0
- data/CONTRIBUTING.md +328 -115
- data/LOGGING.md +93 -1
- data/OVERVIEW.md +1 -1
- data/lib/google/cloud/pubsub/subscription.rb +1 -1
- data/lib/google/cloud/pubsub/topic.rb +1 -1
- data/lib/google/cloud/pubsub/version.rb +1 -1
- metadata +3 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b184f3a91a168ccf824158c3b3d394c3bc92802f8086219c2f08b5f4c26217f7
|
|
4
|
+
data.tar.gz: 06a0cbe8c150187217d4926f4c31c786359299b792bad5b8e00c5213231a3eaf
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 86f12e34cb73f559ccd778ef42c5bc31b0e1609b3d8d40be473a2f2a389949978dba7051d77747623408fa84ce18d347ad0509725239e7f257e5a943312f6d05
|
|
7
|
+
data.tar.gz: 982195c58d4909f682dbcff79529b33570f6808459f813ffa0fecedec9fb3e6c81f811f7ecc01ff986b934abf686646839db80aac1da2fb028e7224a17885453
|
data/CHANGELOG.md
CHANGED
data/CONTRIBUTING.md
CHANGED
|
@@ -1,187 +1,400 @@
|
|
|
1
1
|
# Contributing to Google Cloud Pub/Sub
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
### Code of Conduct
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
|
20
|
-
|
|
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
|
-
|
|
46
|
+
### Local development setup
|
|
23
47
|
|
|
24
|
-
|
|
25
|
-
there is a small amount of setup:
|
|
48
|
+
To set up your local development environment:
|
|
26
49
|
|
|
27
|
-
1. Install
|
|
28
|
-
|
|
29
|
-
[
|
|
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
|
-
|
|
54
|
+
1. Install [Bundler](http://bundler.io/).
|
|
33
55
|
|
|
34
56
|
```sh
|
|
35
57
|
$ gem install bundler
|
|
36
58
|
```
|
|
37
59
|
|
|
38
|
-
|
|
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
|
-
$
|
|
81
|
+
$ cd google-cloud-pubsub
|
|
42
82
|
```
|
|
43
83
|
|
|
44
|
-
|
|
84
|
+
1. Install (or update) the library dependencies:
|
|
45
85
|
|
|
46
86
|
```sh
|
|
47
|
-
$
|
|
48
|
-
$ bundle install
|
|
87
|
+
$ bundle update
|
|
49
88
|
```
|
|
50
89
|
|
|
51
|
-
|
|
90
|
+
1. Create a new topic branch off of the `main` branch:
|
|
52
91
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
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
|
-
|
|
67
|
-
|
|
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
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
203
|
+
### Static code analysis
|
|
89
204
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
98
|
-
[YARD](https://github.com/lsegal/yard)-based documentation.
|
|
222
|
+
### Documentation tests
|
|
99
223
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
[
|
|
103
|
-
|
|
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
|
-
|
|
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
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
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
|
-
$
|
|
141
|
-
$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
|
|
253
|
+
$ bundle exec rake test
|
|
142
254
|
```
|
|
143
255
|
|
|
144
|
-
|
|
145
|
-
`
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
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#
|
|
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
|
|
@@ -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
|
|
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
|
|
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
|
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.9.
|
|
4
|
+
version: 2.9.1
|
|
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:
|
|
12
|
+
date: 2022-01-11 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.
|
|
279
|
+
rubygems_version: 3.3.4
|
|
280
280
|
signing_key:
|
|
281
281
|
specification_version: 4
|
|
282
282
|
summary: API Client library for Google Cloud Pub/Sub
|