google-cloud-pubsub 2.7.1 → 2.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55eb80f365cf82b22f7cb9383a88155e0c79e0d5c1e897f2c7ee6cb974e2989b
-  data.tar.gz: 4417a272576757638dbe5b122e832412303f55761fb6d4d9ae24706ecdc9842f
+  metadata.gz: b184f3a91a168ccf824158c3b3d394c3bc92802f8086219c2f08b5f4c26217f7
+  data.tar.gz: 06a0cbe8c150187217d4926f4c31c786359299b792bad5b8e00c5213231a3eaf
 SHA512:
-  metadata.gz: 8c1a8a9c9e62d737a468fbaca9c3909be1c608ec64d223f7ade2a478870c4e275cfad10e8c743dd213ce2f3d9084271f29cca6ba91205cda224177897d174016
-  data.tar.gz: 96cd5e4e593894f6c98401c9dff2ca99d7be2acdbb37504f5f53ab72cda2c9e29bde031facd7d779947deb892454716bc151f31d67eddf58b3f8944e46e66018
+  metadata.gz: 86f12e34cb73f559ccd778ef42c5bc31b0e1609b3d8d40be473a2f2a389949978dba7051d77747623408fa84ce18d347ad0509725239e7f257e5a943312f6d05
+  data.tar.gz: 982195c58d4909f682dbcff79529b33570f6808459f813ffa0fecedec9fb3e6c81f811f7ecc01ff986b934abf686646839db80aac1da2fb028e7224a17885453

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Release History
 
+### 2.9.1 / 2022-01-11
+
+#### Documentation
+
+* Update contributing docs
+* Add section on gRPC interceptors to the logging docs
+
+### 2.9.0 / 2021-10-28
+
+#### Features
+
+* Expand timeout type from Integer to Numeric
+  * feat: Expand timeout type from Integer to Numeric. This is backwards-compatible.
+    * Change timeout from Integer to Numeric in Google::Cloud.pubsub
+    * Change timeout from Integer to Numeric in Google::Cloud#pubsub
+    * Change timeout from Integer to Numeric in Google::Cloud::PubSub.configure
+    * Change timeout from Integer to Numeric in Google::Cloud::PubSub.new
+  * fix: Propagate timeout to client RPC configs.
+
+#### Documentation
+
+* Add documentation for quota_project Configuration attribute
+* Fix documentation for PubSub.configure
+  * Remove retries property that does not exist in code.
+
+### 2.8.1 / 2021-09-22
+
+#### Bug Fixes
+
+* Change IAM and Schema client metadata hash keys to symbols
+
+#### Documentation
+
+* Fix typo in Emulator guide links
+
+### 2.8.0 / 2021-08-30
+
+#### Features
+
+* Add Pub/Sub topic retention fields
+  * Add retention to Project#create_topic
+  * Add Topic#retention
+  * Add Topic#retention=
+  * Add Subscription#topic_retention
+
 ### 2.7.1 / 2021-07-08
 
 #### Documentation

data/CONTRIBUTING.md

@@ -1,187 +1,400 @@
 # Contributing to Google Cloud Pub/Sub
 
-1. **Sign one of the contributor license agreements below.**
-2. Fork the repo, develop and test your code changes.
-3. Send a pull request.
+Thank you for your interest in making a contribution to google-cloud-ruby. Community contributions are an essential part
+of open source, and we want to make contributing easy for you. If you have any suggestions for how to improve this
+guide, please [open an issue](https://github.com/googleapis/google-cloud-ruby/issues) and let us know!
 
-## Contributor License Agreements
+### Code of Conduct
 
-Before we can accept your pull requests you'll need to sign a Contributor
-License Agreement (CLA):
+Please note that this project is covered by a Contributor Code of Conduct. By participating in this project you agree to
+abide by its terms. See {file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
 
-- **If you are an individual writing original source code** and **you own the
-  intellectual property**, then you'll need to sign an [individual
-  CLA](https://developers.google.com/open-source/cla/individual).
-- **If you work for a company that wants to allow you to contribute your work**,
-  then you'll need to sign a [corporate
+## Overview
+
+1. [Open an issue](#open-an-issue)
+1. [Sign Contributor License Agreement](#sign-contributor-license-agreement)
+1. [Set up environment](#set-up-environment)
+1. [Run CI](#run-ci)
+1. [Make changes](#make-changes)
+1. [Commit changes](#commit-changes)
+1. [Run CI again](#run-ci-again)
+1. [Submit your pull request](#submit-your-pull-request)
+
+## Open an issue
+
+Pull requests should generally be directed by an existing issue, otherwise you risk working on something that the
+maintainers might not be able to accept into the project. Please take a look through [the repository
+issues](https://github.com/googleapis/google-cloud-ruby/issues?q=is%3Aissue+label%3A%22api%3A+pubsub%22), and if you
+do not see an existing issue for your problem or feature, please open one using one of the provided templates.
+
+## Sign Contributor License Agreement
+
+Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):
+
+- **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need
+  to sign an [individual CLA](https://developers.google.com/open-source/cla/individual).
+- **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a [corporate
   CLA](https://developers.google.com/open-source/cla/corporate).
 
-You can sign these electronically (just scroll to the bottom). After that, we'll
-be able to accept your pull requests.
+You can sign these electronically. After that, we'll be able to accept your pull requests.
+
+## Set up environment
+
+Before you start on a pull request, you should prepare your work environment for development, acceptance testing and the
+interactive console (optional).
 
-## Setup
+### Local development setup
 
-In order to use the google-cloud-pubsub console and run the project's tests,
-there is a small amount of setup:
+To set up your local development environment:
 
-1. Install Ruby. google-cloud-pubsub requires Ruby 2.5+. You may choose to
-   manage your Ruby and gem installations with [RVM](https://rvm.io/),
-   [rbenv](https://github.com/rbenv/rbenv), or
-   [chruby](https://github.com/postmodern/chruby).
+1. Install a [supported version](google-cloud-pubsub.gemspec) (or versions) of Ruby. (You may choose to manage your
+   Ruby and gem installations with [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv),
+   [chruby](https://github.com/postmodern/chruby) or a similar tool.)
 
-2. Install [Bundler](http://bundler.io/).
+1. Install [Bundler](http://bundler.io/).
 
    ```sh
    $ gem install bundler
    ```
 
-3. Install the top-level project dependencies.
+1. [Fork](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks) the
+   [google-cloud-ruby](https://github.com/googleapis/google-cloud-ruby) repo, clone your fork, and configure the
+   `upstream`
+   [remote](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork):
+
+   ```bash
+   git clone https://github.com/<your-username>/google-cloud-ruby.git
+   cd google-cloud-ruby
+   git remote add upstream git@github.com:googleapis/google-cloud-ruby.git
+   ```
+
+1. If your fork and clone are not brand new, get the latest changes from `upstream`:
+
+   ```bash
+   git checkout main
+   git pull upstream main
+   ```
+
+1. Change to the library's sub-directory in the repo:
 
    ```sh
-   $ bundle install
+   $ cd google-cloud-pubsub
    ```
 
-4. Install the Pub/Sub dependencies.
+1. Install (or update) the library dependencies:
 
    ```sh
-   $ cd google-cloud-pubsub/
-   $ bundle install
+   $ bundle update
    ```
 
-## Console
+1. Create a new topic branch off of the `main` branch:
 
-In order to run code interactively, you can automatically load
-google-cloud-pubsub and its dependencies in IRB. This requires that your
-developer environment has already been configured by following the steps
-described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
-can be created with:
+   ```bash
+   git checkout -b <topic-branch>
+   ```
 
-```sh
-$ cd google-cloud-pubsub/
-$ bundle exec rake console
-```
+### Acceptance tests setup
+
+To set up your acceptance test credentials:
+
+1. If needed, create a Google Cloud project. In the Google Cloud Console, on the project selector page, select or create
+   a project.
+
+1. Ensure that billing is enabled for your project.
+
+1. Ensure that the Cloud Pub/Sub API is enabled for your project.
 
-## Pub/Sub Tests
+1. Follow the instructions for [Creating a Service Account](AUTHENTICATION.md#creating-a-service-account) in
+   `AUTHENTICATION.md`, including downloading and securely storing a JSON key file. 
 
-Tests are very important part of google-cloud-pubsub. All contributions
-should include tests that ensure the contributed code behaves as expected.
+1. Set the `GCLOUD_TEST_KEYFILE` environment variable to the path of the JSON key file that you downloaded in the
+   previous step:
 
-To run the unit tests, documentation tests, and code style checks together for a
-package:
+   ``` sh
+   $ export GCLOUD_TEST_KEYFILE=/path/to/keyfile.json
+   ```
+
+   If you are already using the `GCLOUD_TEST_KEYFILE` environment variable, and wish to test this library with a
+   different key file, you may set the `PUBSUB_TEST_KEYFILE` environment variable instead:
+
+   ``` sh
+   $ export PUBSUB_TEST_KEYFILE=/path/to/keyfile.json
+   ```
+
+1. Set the `GCLOUD_TEST_PROJECT` environment variable to your Google Cloud project ID:
+
+   ``` sh
+   $ export GCLOUD_TEST_PROJECT=my-project-id
+   ```
+
+   If you are already using the `GCLOUD_TEST_PROJECT` environment variable, and wish to test this library with a
+   different project, you may set the `PUBSUB_TEST_PROJECT` environment variable instead:
+
+   ``` sh
+   $ export PUBSUB_TEST_PROJECT=my-project-id
+   ```
+
+### Interactive console setup (optional)
+
+To set up your interactive console credentials:
+
+1. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file (see
+   above):
+
+   ``` sh
+   $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
+   ```
+
+   If you are already using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, and wish to test this library
+   with a different key file, you may set the `PUBSUB_CREDENTIALS` environment variable instead:
+
+   ``` sh
+   $ export PUBSUB_CREDENTIALS=/path/to/keyfile.json
+   ```
+
+1. Set the `GOOGLE_CLOUD_PROJECT` environment variable to your Google Cloud project ID:
+
+   ``` sh
+   $ export GOOGLE_CLOUD_PROJECT=my-project-id
+   ```
+
+   If you are already using the `GOOGLE_CLOUD_PROJECT` environment variable, and wish to test this library with a
+   different project, you may set the `PUBSUB_PROJECT` environment variable instead:
+
+   ``` sh
+   $ export PUBSUB_PROJECT=my-project-id
+   ```
+
+
+## Run CI
+
+You are now ready to run local CI checks for the library, which you should do **before** you make any changes. Doing so
+ensures that everything is OK with your local environment and the latest dependency versions. You don't want any
+surprises later.
+
+If you haven't already done so, change to the library's sub-directory in the repo:
+
+```sh
+$ cd google-cloud-pubsub
+```
+
+To run the code style checks, documentation tests, and unit tests together, use the `ci` task:
 
 ``` sh
-$ cd google-cloud-pubsub/
 $ bundle exec rake ci
 ```
 
-To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
-its handy alias, `rake ci:a`.
+To run the command above, plus all acceptance tests, use `rake ci:acceptance` or its handy alias, `rake ci:a`. Keep in
+mind that the acceptance tests typically take longer than the other CI checks and require authentication credentials.
+See the [Acceptance tests](#Acceptance-tests) section below for more information.
 
-### Pub/Sub Unit Tests
+The Rake tasks aggregated in the commands above can be run individually to streamline your workflow when developing or
+debugging.
 
+| CI check                                      | Command           |
+|-----------------------------------------------|------------------ |
+| [Static code analysis](#Static-code-analysis) | `rake rubocop`    |
+| [Documentation tests](#Documentation-tests)   | `rake doctest`    |
+| [Unit tests](#Unit-tests)                     | `rake test`       |
+| [Acceptance tests](#Acceptance-tests)         | `rake acceptance` |
 
-The project uses the [minitest](https://github.com/seattlerb/minitest) library,
-including [specs](https://github.com/seattlerb/minitest#specs),
-[mocks](https://github.com/seattlerb/minitest#mocks) and
-[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
+The subsections below describe the individual CI checks.
 
-To run the Pub/Sub unit tests:
+### Static code analysis
 
-``` sh
-$ cd google-cloud-pubsub/
-$ bundle exec rake test
+The project uses [Rubocop](https://github.com/rubocop/rubocop) configured with the shared
+[googleapis/ruby-style](https://github.com/googleapis/ruby-style) rules to ensure that your code adheres to
+Google's Ruby style. The style is largely based on [The Ruby Style
+Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions:
+
+* Avoid parentheses when possible, including in method definitions.
+* Use double-quoted strings.
+
+You can check your code against these rules by running the Rubocop Rake task:
+
+```sh
+$ bundle exec rake rubocop
 ```
 
-### Pub/Sub Documentation Tests
+In the rare case that you need to override the existing Rubocop configuration for this library in order to accommodate
+your changes, you can do so by updating [.rubocop.yml](.rubocop.yml).
 
-The project tests the code examples in the gem's
-[YARD](https://github.com/lsegal/yard)-based documentation.
+### Documentation tests
 
-The example testing functions in a way that is very similar to unit testing, and
-in fact the library providing it,
-[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
-project's unit test library, [minitest](https://github.com/seattlerb/minitest).
+When adding a new feature, you should almost always add one or more in-line documentation code examples demonstrating
+the use of the feature, using [YARD](https://github.com/lsegal/yard)'s
+[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag. Be sure to write a complete, executable
+example that includes the library `require` statement and client initialization.
 
-To run the Pub/Sub documentation tests:
+The project uses [yard-doctest](https://github.com/p0deje/yard-doctest) to execute each sample as a unit test:
 
 ``` sh
-$ cd google-cloud-pubsub/
 $ bundle exec rake doctest
 ```
 
-If you add, remove or modify documentation examples when working on a pull
-request, you may need to update the setup for the tests. The stubs and mocks
-required to run the tests are located in `support/doctest_helper.rb`. Please
-note that much of the setup is matched by the title of the
-[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
-If you alter an example's title, you may encounter breaking tests.
+If you add, remove or modify documentation examples, you may need to update the setup for the tests. The fixtures, stubs
+and mocks required to run the tests are located in [support/doctest_helper.rb](support/doctest_helper.rb). Please note
+that much of the setup is matched to its corresponding example by the title of the `@example` tag. If you alter an
+example's title, you may encounter broken tests.
 
-### Pub/Sub Acceptance Tests
+There are generally no assertions or mock verifications in these tests. They simply check that the examples are
+syntactically correct and execute against the library source code without error.
 
-The Pub/Sub acceptance tests interact with the live service API. Follow the
-instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
-the Pub/Sub API. Occasionally, some API features may not yet be generally
-available, making it difficult for some contributors to successfully run the
-entire acceptance test suite. However, please ensure that you do successfully
-run acceptance tests for any code areas covered by your pull request.
+### Unit tests
 
-To run the acceptance tests, first create and configure a project in the Google
-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
-the KEYFILE location on your system.
+The project uses the [minitest](https://github.com/seattlerb/minitest) library, including
+[specs](https://github.com/seattlerb/minitest#specs-), [mocks](https://github.com/seattlerb/minitest#mocks-),
+[minitest-autotest](https://github.com/seattlerb/minitest-autotest), and
+[minitest-focus](https://github.com/seattlerb/minitest-focus).
 
-Before you can run the Pub/Sub acceptance tests, you must first create indexes
-used in the tests.
-
-#### Running the Pub/Sub acceptance tests
-
-To run the Pub/Sub acceptance tests:
+To run the unit tests:
 
 ``` sh
-$ cd google-cloud-pubsub/
-$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
+$ bundle exec rake test
 ```
 
-Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
-`GCLOUD_TEST_KEYFILE` environment variables:
+Although the unit tests are intended to run quickly, during development or debugging you may want to isolate one or more
+of the tests by placing the `focus` keyword just above the test declaration. (See
+[minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
 
-``` sh
-$ cd google-cloud-pubsub/
-$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
-$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
-$ bundle exec rake acceptance
-```
+### Acceptance Tests
+
+The acceptance tests (a.k.a. integration tests) ensure that the library works correctly against the live service API.
+To configure your Google Cloud project, see [Acceptance tests setup](#acceptance-tests-setup) above.
+
+**Warning: You may incur charges while running the acceptance tests against your Google Cloud project.**
 
-If you want to use a different project and credentials for acceptance tests, you
-can use the more specific `PUBSUB_TEST_PROJECT`  and `PUBSUB_TEST_KEYFILE`
-environment variables:
+Like the unit tests, the acceptance tests are based on the [minitest](https://github.com/seattlerb/minitest) library,
+including [specs](https://github.com/seattlerb/minitest#specs-) and
+[minitest-focus](https://github.com/seattlerb/minitest-focus). Mocks are not generally used in acceptance tests.
+
+Because the acceptance test suite is often time-consuming to run in its entirety, during development or debugging you
+may want to isolate one or more of the tests by placing the `focus` keyword just above the test declaration. (See
+[minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
+
+To run the acceptance tests:
 
 ``` sh
-$ cd google-cloud-pubsub/
-$ export PUBSUB_TEST_PROJECT=\\{my-project-id}
-$ export PUBSUB_TEST_KEYFILE=\\{/path/to/keyfile.json}
 $ bundle exec rake acceptance
 ```
 
-## Coding Style
+Some acceptance tests may depend on API features that are not yet generally available, and will fail unless your project
+is added to an internal allowlist. There may also be tests that usually pass but fail occasionally due to issues like
+eventual consistency. However, please ensure that you do successfully run acceptance tests for any code areas covered by
+your pull request.
+
+## Make changes
 
-Please follow the established coding style in the library. The style is is
-largely based on [The Ruby Style
-Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
-on seattle-style:
+All contributions should include new or updated tests to ensure that the contributed code behaves as expected.
 
-* Avoid parenthesis when possible, including in method definitions.
-* Always use double quotes strings. ([Option
-  B](https://github.com/bbatsov/ruby-style-guide#strings))
+When starting work on a new feature, it often makes sense to begin with a basic acceptance test to ensure that the new
+feature is present in the live service API and is available to your project. To run your new test exclusively,
+temporarily add the `focus` keyword just above the test declaration. (See
+[minitest-focus](https://github.com/seattlerb/minitest-focus) for details.) Also, the acceptance tests have a retry
+mechanism that can sometimes make it hard to see the correct error when things go wrong. To disable retries while
+debugging errors, temporarily comment out or remove the `run_one_method` method definition in
+[acceptance/pubsub_helper.rb](acceptance/pubsub_helper.rb).
 
-You can check your code against these rules by running Rubocop like so:
+When you are done developing, be sure to remove any usages of the `focus` keyword from your tests and restore the
+`run_one_method` method definition if you removed it.
+
+### Console
+
+The project includes a Rake task that automatically loads `google-cloud-pubsub` and its dependencies in IRB. To
+configure your Google Cloud project for IRB, see [Interactive console setup](#interactive-console-setup-optional) above.
+
+**Warning: You may incur charges while using the library with your Google Cloud project.**
+
+If you haven't already done so, change to the library's sub-directory in the repo:
 
 ```sh
-$ cd google-cloud-pubsub/
-$ bundle exec rake rubocop
+$ cd google-cloud-pubsub
+```
+
+The preloaded IRB console can be used as follows:
+
+```sh
+$ bundle exec rake console
+irb(main):001:0> require "google/cloud/pubsub"
+=> true
+irb(main):002:0> pubsub = Google::Cloud::PubSub.new
 ```
 
-## Code of Conduct
+Using the console provides an interactive alternative to acceptance testing that may make it easier to explore usage and
+debug problems.
+
+## Commit changes
+
+Commit your changes using [conventional commits](https://www.conventionalcommits.org/), making sure to include the
+associated GitHub issue number. Below is an example of a `feat` type commit that will result in a semver `minor`
+release. Notice how it is scoped to the short name of the library, contains a bulleted list of public API changes, and
+ends with the `closes` GitHub keyword. If this is the only new commit in your branch when you open your pull request,
+the commit body including the `closes` phrase will be copied to your PR description. If you have multiple commits, you
+should copy the body of this anchor commit manually to the PR description, so that GitHub will [automatically close the
+related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+
+```bash
+git commit -am "feat(pubsub): Add my new feature
+
+* Add MyClass#my_method
+
+closes: #123"
+```
+
+The messages for any subsequent commits you may add do not necessarily need to follow the conventional commits format,
+as these messages will be manually dropped or added as bullet points to the original message when the PR is squashed and
+merged.
+
+## Run CI again
+
+
+1. If you haven't already done so, change to the library's sub-directory in the repo:
+
+   ```sh
+   $ cd google-cloud-pubsub
+   ```
+
+1. Rebase your topic branch on the upstream `main` branch:
+
+   ```bash
+   git pull --rebase upstream main
+   ```
+
+1. Run the `ci` task:
+
+   ``` sh
+   $ bundle exec rake ci
+   ```
+
+1. Run the `acceptance` task:
+
+   ``` sh
+   $ bundle exec rake acceptance
+   ```
+
+Ensure that everything is passing in `rake ci` and `rake acceptance`, or at least that `rake ci` is green and you
+haven't broken anything new in `rake acceptance`, before you open your pull request.
+
+## Submit your pull request
+
+1. Rebase your topic branch on the upstream `main` branch:
+
+   ```bash
+   git pull --rebase upstream main
+   ```
+
+1. Push your topic branch to your fork:
+
+   ```bash
+   git push origin -u
+   ```
+
+1. Open a [pull
+   request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+   using the first line of your conventional commit as the title, and with the associated GitHub issue in the
+   description. By convention in this project, the assignee of the pull request will be the maintainer who will merge it
+   once it is approved. If you are a maintainer of the project, typically you should assign the pull request to
+   yourself.
+
+1. Ensure that all of the GitHub checks are passing.
 
-Please note that this project is released with a Contributor Code of Conduct. By
-participating in this project you agree to abide by its terms. See
-{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.

data/LOGGING.md

@@ -1,4 +1,6 @@
-# Enabling gRPC Logging
+# Logging
+
+## Enabling gRPC Logging
 
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
@@ -17,6 +19,7 @@ Configuring a Ruby stdlib logger:
 
 ```ruby
 require "logger"
+require "grpc"
 
 module MyLogger
   LOGGER = Logger.new $stderr, level: Logger::WARN
@@ -30,3 +33,92 @@ module GRPC
   extend MyLogger
 end
 ```
+
+## Adding gRPC interceptors
+
+[gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) accepts [Ruby-language
+interceptors](https://github.com/grpc/proposal/blob/master/L11-ruby-interceptors.md) that allow you to insert your own
+custom logging into a client's RPC calls. (gRPC interceptors are also useful for auth, metrics, tracing and similar
+use cases.)
+
+This library performs RPCs using the following [gapic](https://github.com/googleapis/gapic-generator-ruby) clients from
+the underlying
+[google-cloud-pubsub-v1](https://github.com/googleapis/google-cloud-ruby/tree/main/google-cloud-pubsub-v1) library:
+
+* [`Google::Cloud::PubSub::V1::IAMPolicy::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/IAMPolicy/Client.html)
+* [`Google::Cloud::PubSub::V1::Publisher::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/Publisher/Client.html)
+* [`Google::Cloud::PubSub::V1::SchemaService::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/SchemaService/Client.html)
+* [`Google::Cloud::PubSub::V1::Subscriber::Client`](https://googleapis.dev/ruby/google-cloud-pubsub-v1/latest/Google/Cloud/PubSub/V1/Subscriber/Client.html)
+
+To add a gRPC interceptor to one or more of these clients, first implement your logic as a subclass of
+[`GRPC::ClientInterceptor`](https://www.rubydoc.info/gems/grpc/GRPC/ClientInterceptor). The example below logs all four
+types of gRPC calls (unary, client streaming, server streaming, and bi-directional streaming.) It also demonstrates how
+to set a metadata field.
+
+```ruby
+require "grpc"
+require "logger"
+require "securerandom"
+
+class MyInterceptor < GRPC::ClientInterceptor
+  attr_reader :name
+
+  def initialize name
+    @name = name
+  end
+
+  def request_response(request:, call:, method:, metadata:)
+    logger.info "[#{name}] Sending unary request/response to #{method}"
+    metadata["request_id"] = generate_request_id
+    yield
+  end
+
+  def client_streamer(requests:, call:, method:, metadata:)
+    logger.info "[#{name}] Sending client streamer to #{method}"
+    metadata["request_id"] = generate_request_id
+    yield
+  end
+
+  def server_streamer(request:, call:, method:, metadata:)
+    logger.info "[#{name}] Sending server streamer to #{method}"
+    metadata["request_id"] = generate_request_id
+    yield
+  end
+
+  def bidi_streamer(requests:, call:, method:, metadata:)
+    logger.info "[#{name}] Sending bidi streamer to #{method}"
+    metadata["request_id"] = generate_request_id
+    yield
+  end
+
+  private
+
+  def logger
+    @logger ||= Logger.new(STDOUT)
+  end
+
+  def generate_request_id
+    SecureRandom.uuid
+  end
+end
+```
+
+Next, use the block yielded by a `Client.configure` method to add an instance of your class to the `interceptors`
+configuration of one or more of the generated clients listed above.
+
+Note that the `Google::Cloud::PubSub::V1` configurations must be performed **before** the `Google::Cloud::PubSub` client
+is instantiated.
+
+```ruby
+require "google/cloud/pubsub"
+
+Google::Cloud::PubSub::V1::Publisher::Client.configure do |config|
+  config.interceptors = [MyInterceptor.new("MyPublisherInterceptor")]
+end
+
+Google::Cloud::PubSub::V1::Subscriber::Client.configure do |config|
+  config.interceptors = [MyInterceptor.new("MySubscriberInterceptor")]
+end
+
+pubsub = Google::Cloud::PubSub.new
+```

data/OVERVIEW.md

@@ -452,7 +452,7 @@ if your account has limited access to the Pub/Sub API. In particular, the role
 `roles/pubsub.subscriber` does not have the permission
 `pubsub.subscriptions.get`, which is required to retrieve a subscription
 resource. See [Access Control -
-Roles](https://cloud.google.com/pubsub/docs/access-control#tbl_roles) for the
+Roles](https://cloud.google.com/pubsub/docs/access-control#roles) for the
 complete list of Pub/Sub roles and permissions.
 
 ## Creating a snapshot and using seek
@@ -524,5 +524,5 @@ sub.topic.name #=> "projects/other-project-id/topics/other-topic"
 ## Additional information
 
 Google Cloud Pub/Sub can be configured to use an emulator or to enable gRPC's
-logging. To learn more, see the {file:EMULATOR.md Emulator guide}} and
+logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
 {file:LOGGING.md Logging guide}.

data/lib/google/cloud/pubsub/project.rb

@@ -238,6 +238,14 @@ module Google
         #   * `JSON` - JSON encoding.
         #   * `BINARY` - Binary encoding, as defined by the schema type. For some
         #     schema types, binary encoding may not be available.
+        # @param [Numeric] retention Indicates the minimum number of seconds to retain a message
+        #   after it is published to the topic. If this field is set, messages published
+        #   to the topic within the `retention` number of seconds are always available to
+        #   subscribers. For instance, it allows any attached subscription to [seek to a
+        #   timestamp](https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
+        #   that is up to `retention` number of seconds in the past. If this field is
+        #   not set, message retention is controlled by settings on individual
+        #   subscriptions. Cannot be less than 600 (10 minutes) or more than 604,800 (7 days).
         #
         # @return [Google::Cloud::PubSub::Topic]
         #
@@ -253,14 +261,16 @@ module Google
                          persistence_regions: nil,
                          async: nil,
                          schema_name: nil,
-                         message_encoding: nil
+                         message_encoding: nil,
+                         retention: nil
           ensure_service!
           grpc = service.create_topic topic_name,
                                       labels:              labels,
                                       kms_key_name:        kms_key,
                                       persistence_regions: persistence_regions,
                                       schema_name:         schema_name,
-                                      message_encoding:    message_encoding
+                                      message_encoding:    message_encoding,
+                                      retention:           retention
           Topic.from_grpc grpc, service, async: async
         end
         alias new_topic create_topic

data/lib/google/cloud/pubsub/service.rb

@@ -51,7 +51,7 @@ module Google
           return mocked_subscriber if mocked_subscriber
           @subscriber ||= V1::Subscriber::Client.new do |config|
             config.credentials = credentials if credentials
-            config.timeout = timeout if timeout
+            override_client_config_timeouts config if timeout
             config.endpoint = host if host
             config.lib_name = "gccl"
             config.lib_version = Google::Cloud::PubSub::VERSION
@@ -64,7 +64,7 @@ module Google
           return mocked_publisher if mocked_publisher
           @publisher ||= V1::Publisher::Client.new do |config|
             config.credentials = credentials if credentials
-            config.timeout = timeout if timeout
+            override_client_config_timeouts config if timeout
             config.endpoint = host if host
             config.lib_name = "gccl"
             config.lib_version = Google::Cloud::PubSub::VERSION
@@ -77,11 +77,11 @@ module Google
           return mocked_iam if mocked_iam
           @iam ||= V1::IAMPolicy::Client.new do |config|
             config.credentials = credentials if credentials
-            config.timeout = timeout if timeout
+            override_client_config_timeouts config if timeout
             config.endpoint = host if host
             config.lib_name = "gccl"
             config.lib_version = Google::Cloud::PubSub::VERSION
-            config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
           end
         end
         attr_accessor :mocked_iam
@@ -90,11 +90,11 @@ module Google
           return mocked_schemas if mocked_schemas
           @schemas ||= V1::SchemaService::Client.new do |config|
             config.credentials = credentials if credentials
-            config.timeout = timeout if timeout
+            override_client_config_timeouts config if timeout
             config.endpoint = host if host
             config.lib_name = "gccl"
             config.lib_version = Google::Cloud::PubSub::VERSION
-            config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
           end
         end
         attr_accessor :mocked_schemas
@@ -127,6 +127,7 @@ module Google
                          persistence_regions: nil,
                          schema_name: nil,
                          message_encoding: nil,
+                         retention: nil,
                          options: {}
           if persistence_regions
             message_storage_policy = Google::Cloud::PubSub::V1::MessageStoragePolicy.new(
@@ -145,11 +146,12 @@ module Google
           end
 
           publisher.create_topic \
-            name:                   topic_path(topic_name, options),
-            labels:                 labels,
-            kms_key_name:           kms_key_name,
-            message_storage_policy: message_storage_policy,
-            schema_settings:        schema_settings
+            name:                       topic_path(topic_name, options),
+            labels:                     labels,
+            kms_key_name:               kms_key_name,
+            message_storage_policy:     message_storage_policy,
+            schema_settings:            schema_settings,
+            message_retention_duration: Convert.number_to_duration(retention)
         end
 
         def update_topic topic_obj, *fields
@@ -459,6 +461,18 @@ module Google
 
         protected
 
+        # Set the timeout in the client config.
+        # Override the default timeout in each individual RPC config as well, since when they are non-nil, these
+        # defaults have precedence over the top-level config.timeout. See Gapic::CallOptions#apply_defaults.
+        def override_client_config_timeouts config
+          config.timeout = timeout
+          rpc_names = config.rpcs.methods - Object.methods
+          rpc_names.each do |rpc_name|
+            rpc = config.rpcs.send rpc_name
+            rpc.timeout = timeout if rpc.respond_to? :timeout=
+          end
+        end
+
         def a_time? obj
           return false unless obj.respond_to? :to_time
           # Rails' String#to_time returns nil if the string doesn't parse.

data/lib/google/cloud/pubsub/subscription.rb

@@ -168,9 +168,8 @@ module Google
         # backlog, from the moment a message is published. If
         # {#retain_acked} is `true`, then this also configures the retention of
         # acknowledged messages, and thus configures how far back in time a
-        # {#seek} can be done. Cannot be more than 604,800 seconds (7 days) or
-        # less than 600 seconds (10 minutes). Default is 604,800 seconds (7
-        # days).
+        # {#seek} can be done. Cannot be less than 600 (10 minutes) or more
+        # than 604,800 (7 days). Default is 604,800 seconds (7 days).
         #
         # Makes an API call to retrieve the retention value when called on a
         # reference object. See {#reference?}.
@@ -195,6 +194,24 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # Indicates the minimum duration for which a message is retained after
+        # it is published to the subscription's topic. If this field is set,
+        # messages published to the subscription's topic in the last
+        # `topic_message_retention_duration` are always available to subscribers.
+        # Output only. See {Topic#retention}.
+        #
+        # Makes an API call to retrieve the retention value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Numeric, nil] The topic message retention duration in seconds,
+        #   or `nil` if not set.
+        #
+        def topic_retention
+          ensure_grpc!
+          Convert.duration_to_number @grpc.topic_message_retention_duration
+        end
+
         ##
         # Returns the URL locating the endpoint to which messages should be
         # pushed. For example, a Webhook endpoint might use
@@ -408,7 +425,7 @@ module Google
         # Sets the {Topic} to which dead letter messages for the subscription should be published. Dead lettering is
         # done on a best effort basis. The same message might be dead lettered multiple times.
         # The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
-        # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
+        # `service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
         # topic.
         #
         # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached

data/lib/google/cloud/pubsub/topic.rb

@@ -305,6 +305,43 @@ module Google
           message_encoding.to_s.upcase == "JSON"
         end
 
+        ##
+        # Indicates the minimum number of seconds to retain a message after it is
+        # published to the topic. If this field is set, messages published to the topic
+        # within the `retention` number of seconds are always available to subscribers.
+        # For instance, it allows any attached subscription to [seek to a
+        # timestamp](https://cloud.google.com/pubsub/docs/replay-overview#seek_to_a_time)
+        # that is up to `retention` number of seconds in the past. If this field is
+        # not set, message retention is controlled by settings on individual
+        # subscriptions. Cannot be less than 600 (10 minutes) or more than 604,800 (7 days).
+        # See {#retention=}.
+        #
+        # Makes an API call to retrieve the retention value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Numeric, nil] The message retention duration in seconds, or `nil` if not set.
+        #
+        def retention
+          ensure_grpc!
+          Convert.duration_to_number @grpc.message_retention_duration
+        end
+
+        ##
+        # Sets the message retention duration in seconds. If set to a positive duration
+        # between 600 (10 minutes) and 604,800 (7 days), inclusive, the message retention
+        # duration is changed. If set to `nil`, this clears message retention duration
+        # from the topic. See {#retention}.
+        #
+        # @param [Numeric, nil] new_retention The new message retention duration value.
+        #
+        def retention= new_retention
+          new_retention_duration = Convert.number_to_duration new_retention
+          update_grpc = Google::Cloud::PubSub::V1::Topic.new name: name,
+                                                             message_retention_duration: new_retention_duration
+          @grpc = service.update_topic update_grpc, :message_retention_duration
+          @resource_name = nil
+        end
+
         ##
         # Permanently deletes the topic.
         #
@@ -373,7 +410,7 @@ module Google
         # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
         #   published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
         #   times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
-        #   `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
+        #   `service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
         #   this topic.
         #
         #   The operation will fail if the topic does not exist. Users should ensure that there is a subscription

data/lib/google/cloud/pubsub/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "2.7.1".freeze
+      VERSION = "2.9.1".freeze
     end
 
     Pubsub = PubSub unless const_defined? :Pubsub

data/lib/google/cloud/pubsub.rb

@@ -54,7 +54,7 @@ module Google
       #   The default scope is:
       #
       #   * `https://www.googleapis.com/auth/pubsub`
-      # @param [Integer] timeout Default timeout to use in requests. Optional.
+      # @param [Numeric] timeout Default timeout to use in requests. Optional.
       # @param [String] endpoint Override of the endpoint host name. Optional.
       #   If the param is nil, uses the default endpoint.
       # @param [String] emulator_host Pub/Sub emulator host. Optional.
@@ -121,9 +121,9 @@ module Google
       #   parameter `keyfile` is considered deprecated, but may also be used.)
       # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
-      # * `retries` - (Integer) Number of times to retry requests on server
-      #   error.
-      # * `timeout` - (Integer) Default timeout to use in requests.
+      # * `quota_project` - (String) The project ID for a project that can be
+      #   used by client libraries for quota and billing purposes.
+      # * `timeout` - (Numeric) Default timeout to use in requests.
       # * `endpoint` - (String) Override of the endpoint host name, or `nil`
       #   to use the default endpoint.
       # * `emulator_host` - (String) Host name of the emulator. Defaults to

data/lib/google-cloud-pubsub.rb

@@ -41,7 +41,7 @@ module Google
     #   The default scope is:
     #
     #   * `https://www.googleapis.com/auth/pubsub`
-    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [Numeric] timeout Default timeout to use in requests. Optional.
     #
     # @return [Google::Cloud::PubSub::Project]
     #
@@ -87,7 +87,7 @@ module Google
     #   The default scope is:
     #
     #   * `https://www.googleapis.com/auth/pubsub`
-    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [Numeric] timeout Default timeout to use in requests. Optional.
     #
     # @return [Google::Cloud::PubSub::Project]
     #
@@ -133,7 +133,7 @@ Google::Cloud.configure.add_config! :pubsub do |config|
   config.add_alias! :keyfile, :credentials
   config.add_field! :scope, default_scopes, match: [String, Array]
   config.add_field! :quota_project, nil, match: String
-  config.add_field! :timeout, nil, match: Integer
+  config.add_field! :timeout, nil, match: Numeric
   config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true
   config.add_field! :on_error, nil, match: Proc
   config.add_field! :endpoint, "pubsub.googleapis.com", match: String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: 2.9.1
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-08 00:00:00.000000000 Z
+date: 2022-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -276,7 +276,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.17
+rubygems_version: 3.3.4
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Pub/Sub