google-cloud-pubsub 0.26.0 → 2.6.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct. By adopting this Code of Conduct, project
+maintainers commit themselves to fairly and consistently applying these
+principles to every aspect of managing this project. Project maintainers who do
+not follow or enforce the Code of Conduct may be permanently removed from the
+project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting one or more of the project
+maintainers.
+
+This Code of Conduct is adapted from the [Contributor
+Covenant](http://contributor-covenant.org), version 1.2.0, available at
+[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)

data/CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# 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.
+
+## Contributor License Agreements
+
+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.
+
+## Setup
+
+In order to use the google-cloud-pubsub console and run the project's tests,
+there is a small amount of setup:
+
+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).
+
+2. Install [Bundler](http://bundler.io/).
+
+   ```sh
+   $ gem install bundler
+   ```
+
+3. Install the top-level project dependencies.
+
+   ```sh
+   $ bundle install
+   ```
+
+4. Install the Pub/Sub dependencies.
+
+   ```sh
+   $ cd google-cloud-pubsub/
+   $ bundle install
+   ```
+
+## Console
+
+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:
+
+```sh
+$ cd google-cloud-pubsub/
+$ bundle exec rake console
+```
+
+## Pub/Sub Tests
+
+Tests are very important part of google-cloud-pubsub. All contributions
+should include tests that ensure the contributed code behaves as expected.
+
+To run the unit tests, documentation tests, and code style checks together for a
+package:
+
+``` 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`.
+
+### Pub/Sub Unit Tests
+
+
+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).
+
+To run the Pub/Sub unit tests:
+
+``` sh
+$ cd google-cloud-pubsub/
+$ bundle exec rake test
+```
+
+### Pub/Sub Documentation Tests
+
+The project tests the code examples in the gem's
+[YARD](https://github.com/lsegal/yard)-based documentation.
+
+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).
+
+To run the Pub/Sub documentation tests:
+
+``` 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.
+
+### Pub/Sub Acceptance Tests
+
+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.
+
+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.
+
+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:
+
+``` sh
+$ cd google-cloud-pubsub/
+$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
+```
+
+Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
+`GCLOUD_TEST_KEYFILE` environment variables:
+
+``` sh
+$ cd google-cloud-pubsub/
+$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
+$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+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:
+
+``` 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
+
+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:
+
+* Avoid parenthesis when possible, including in method definitions.
+* Always use double quotes strings. ([Option
+  B](https://github.com/bbatsov/ruby-style-guide#strings))
+
+You can check your code against these rules by running Rubocop like so:
+
+```sh
+$ cd google-cloud-pubsub/
+$ bundle exec rake rubocop
+```
+
+## Code of Conduct
+
+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/EMULATOR.md

@@ -0,0 +1,37 @@
+# Google Cloud Pub/Sub Emulator
+
+To develop and test your application locally, you can use the [Google Cloud
+Pub/Sub Emulator](https://cloud.google.com/pubsub/emulator), which provides
+[local emulation](https://cloud.google.com/sdk/gcloud/reference/beta/emulators/)
+of the production Google Cloud Pub/Sub environment. You can start the Google
+Cloud Pub/Sub emulator using the `gcloud` command-line tool.
+
+To configure your ruby code to use the emulator, set the `PUBSUB_EMULATOR_HOST`
+environment variable to the host and port where the emulator is running. The
+value can be set as an environment variable in the shell running the ruby code,
+or can be set directly in the ruby code as shown below.
+
+```ruby
+require "google/cloud/pubsub"
+
+# Make Pub/Sub use the emulator
+ENV["PUBSUB_EMULATOR_HOST"] = "localhost:8918"
+
+pubsub = Google::Cloud::PubSub.new project_id:"emulator-project-id"
+
+# Get a topic in the current project
+my_topic = pubsub.new_topic "my-topic"
+my_topic.name #=> "projects/emulator-project-id/topics/my-topic"
+```
+
+Or by providing the `emulator_host` argument:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new emulator_host: "localhost:8918"
+
+# Get a topic in the current project
+my_topic = pubsub.new_topic "my-topic"
+my_topic.name #=> "projects/emulator-project-id/topics/my-topic"
+```

data/LICENSE

@@ -1,6 +1,6 @@
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -192,7 +192,7 @@
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
-       http://www.apache.org/licenses/LICENSE-2.0
+       https://www.apache.org/licenses/LICENSE-2.0
 
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,

data/LOGGING.md

@@ -0,0 +1,32 @@
+# 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
+that you set may be a Ruby stdlib
+[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
+shown below, or a
+[`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
+that will write logs to [Stackdriver
+Logging](https://cloud.google.com/logging/). See
+[grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+and the gRPC
+[spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
+for additional information.
+
+Configuring a Ruby stdlib logger:
+
+```ruby
+require "logger"
+
+module MyLogger
+  LOGGER = Logger.new $stderr, level: Logger::WARN
+  def logger
+    LOGGER
+  end
+end
+
+# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+module GRPC
+  extend MyLogger
+end
+```

data/OVERVIEW.md

@@ -0,0 +1,528 @@
+# Google Cloud Pub/Sub
+
+Google Cloud Pub/Sub is designed to provide reliable, many-to-many, asynchronous
+messaging between applications. Publisher applications can send messages to a
+"topic" and other applications can subscribe to that topic to receive the
+messages. By decoupling senders and receivers, Google Cloud Pub/Sub allows
+developers to communicate between independently written applications.
+
+The goal of google-cloud is to provide an API that is comfortable to Rubyists.
+Your authentication credentials are detected automatically in Google Cloud
+Platform (GCP), including Google Compute Engine (GCE), Google Kubernetes Engine
+(GKE), Google App Engine (GAE), Google Cloud Functions (GCF) and Cloud Run. In
+other environments you can configure authentication easily, either directly in
+your code or via environment variables. Read more about the options for
+connecting in the {file:AUTHENTICATION.md Authentication Guide}.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+topic.publish "task completed"
+```
+
+To learn more about Pub/Sub, read the [Google Cloud Pub/Sub Overview
+](https://cloud.google.com/pubsub/overview).
+
+## Retrieving Topics
+
+A Topic is a named resource to which messages are sent by publishers. A Topic is
+found by its name. (See {Google::Cloud::PubSub::Project#topic Project#topic})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+topic = pubsub.topic "my-topic"
+```
+
+## Creating a Topic
+
+A Topic is created from a Project. (See
+{Google::Cloud::PubSub::Project#create_topic Project#create_topic})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+topic = pubsub.create_topic "my-topic"
+```
+
+## Retrieving Subscriptions
+
+A Subscription is a named resource representing the stream of messages from a
+single, specific Topic, to be delivered to the subscribing application. A
+Subscription is found by its name. (See
+{Google::Cloud::PubSub::Topic#subscription Topic#subscription})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+subscription = topic.subscription "my-topic-subscription"
+puts subscription.name
+```
+
+## Creating a Subscription
+
+A Subscription is created from a Topic. (See
+{Google::Cloud::PubSub::Topic#subscribe Topic#subscribe})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+sub = topic.subscribe "my-topic-sub"
+puts sub.name # => "my-topic-sub"
+```
+
+The subscription can be created that specifies the number of seconds to wait to
+be acknowledged as well as an endpoint URL to push the messages to:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+sub = topic.subscribe "my-topic-sub",
+                      deadline: 120,
+                      endpoint: "https://example.com/push"
+```
+
+## Publishing Messages
+
+Messages are published to a topic. Any message published to a topic without a
+subscription will be lost. Ensure the topic has a subscription before
+publishing. (See {Google::Cloud::PubSub::Topic#publish Topic#publish})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+msg = topic.publish "task completed"
+```
+
+Messages can also be published with attributes:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+msg = topic.publish "task completed",
+                    foo: :bar,
+                    this: :that
+```
+
+Messages can also be published in batches asynchronously using `publish_async`.
+(See {Google::Cloud::PubSub::Topic#publish_async Topic#publish_async} and
+{Google::Cloud::PubSub::AsyncPublisher AsyncPublisher})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+topic.publish_async "task completed" do |result|
+  if result.succeeded?
+    log_publish_success result.data
+  else
+    log_publish_failure result.data, result.error
+  end
+end
+
+topic.async_publisher.stop!
+```
+
+Or multiple messages can be published in batches at the same time by passing a
+block to `publish`. (See {Google::Cloud::PubSub::BatchPublisher BatchPublisher})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-topic"
+msgs = topic.publish do |batch|
+  batch.publish "task 1 completed", foo: :bar
+  batch.publish "task 2 completed", foo: :baz
+  batch.publish "task 3 completed", foo: :bif
+end
+```
+
+## Receiving Messages
+
+Messages can be streamed from a subscription with a subscriber object that is
+created using `listen`. (See {Google::Cloud::PubSub::Subscription#listen
+Subscription#listen} and {Google::Cloud::PubSub::Subscriber Subscriber})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+
+# Create a subscriber to listen for available messages.
+# By default, this block will be called on 8 concurrent threads
+# but this can be tuned with the `threads` option.
+# The `streams` and `inventory` parameters allow further tuning.
+subscriber = sub.listen threads: { callback: 16 } do |received_message|
+  # process message
+  puts "Data: #{received_message.message.data}, published at #{received_message.message.published_at}"
+  received_message.acknowledge!
+end
+
+# Handle exceptions from listener
+subscriber.on_error do |exception|
+  puts "Exception: #{exception.class} #{exception.message}"
+end
+
+# Gracefully shut down the subscriber on program exit, blocking until
+# all received messages have been processed or 10 seconds have passed
+at_exit do
+  subscriber.stop!(10)
+end
+
+# Start background threads that will call the block passed to listen.
+subscriber.start
+
+# Block, letting processing threads continue in the background
+sleep
+```
+
+Messages also can be pulled directly in a one-time operation. (See
+{Google::Cloud::PubSub::Subscription#pull Subscription#pull})
+
+The `immediate: false` option is recommended to avoid adverse impacts on the
+performance of pull operations.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+received_messages = sub.pull immediate: false
+```
+
+A maximum number of messages to pull can be specified:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+received_messages = sub.pull immediate: false, max: 10
+```
+
+## Acknowledging a Message
+
+Messages that are received can be acknowledged in Pub/Sub, marking the message
+to be removed so it cannot be pulled again.
+
+A Message that can be acknowledged is called a ReceivedMessage. ReceivedMessages
+can be acknowledged one at a time: (See
+{Google::Cloud::PubSub::ReceivedMessage#acknowledge!
+ReceivedMessage#acknowledge!})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+
+subscriber = sub.listen do |received_message|
+  # process message
+  received_message.acknowledge!
+end
+
+# Start background threads that will call the block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop!
+```
+
+Or, multiple messages can be acknowledged in a single API call: (See
+{Google::Cloud::PubSub::Subscription#acknowledge Subscription#acknowledge})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+received_messages = sub.pull immediate: false
+sub.acknowledge received_messages
+```
+
+## Modifying a Deadline
+
+A message must be acknowledged after it is pulled, or Pub/Sub will mark the
+message for redelivery. The message acknowledgement deadline can delayed if more
+time is needed. This will allow more time to process the message before the
+message is marked for redelivery. (See
+{Google::Cloud::PubSub::ReceivedMessage#modify_ack_deadline!
+ReceivedMessage#modify_ack_deadline!})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+subscriber = sub.listen do |received_message|
+  puts received_message.message.data
+
+  # Delay for 2 minutes
+  received_message.modify_ack_deadline! 120
+end
+
+# Start background threads that will call the block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop!
+```
+
+The message can also be made available for immediate redelivery:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+subscriber = sub.listen do |received_message|
+  puts received_message.message.data
+
+  # Mark for redelivery
+  received_message.reject!
+end
+
+# Start background threads that will call the block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop!
+```
+
+Multiple messages can be delayed or made available for immediate redelivery:
+(See {Google::Cloud::PubSub::Subscription#modify_ack_deadline
+Subscription#modify_ack_deadline})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+received_messages = sub.pull immediate: false
+sub.modify_ack_deadline 120, received_messages
+```
+
+## Using Ordering Keys
+
+Google Cloud Pub/Sub ordering keys provide the ability to ensure related
+messages are sent to subscribers in the order in which they were published.
+Messages can be tagged with an ordering key, a string that identifies related
+messages for which publish order should be respected. The service guarantees
+that, for a given ordering key and publisher, messages are sent to subscribers
+in the order in which they were published. Ordering does not require sacrificing
+high throughput or scalability, as the service automatically distributes
+messages for different ordering keys across subscribers.
+
+Note: At the time of this release, ordering keys are not yet publicly enabled
+and requires special project enablements.
+
+### Publishing Ordered Messages
+
+To use ordering keys when publishing messages, a call to
+{Google::Cloud::PubSub::Topic#enable_message_ordering!
+Topic#enable_message_ordering!} must be made and the `ordering_key` argument
+must be provided when calling {Google::Cloud::PubSub::Topic#publish_async
+Topic#publish_async}.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+topic = pubsub.topic "my-ordered-topic"
+
+# Ensure that message ordering is enabled.
+topic.enable_message_ordering!
+
+# Publish an ordered message with an ordering key.
+topic.publish_async "task completed",
+                    ordering_key: "task-key"
+
+# Shut down the publisher when ready to stop publishing messages.
+topic.async_publisher.stop!
+```
+
+### Handling errors with Ordered Keys
+
+Ordered messages that fail to publish to the Pub/Sub API due to error will put
+the `ordering_key` in a failed state, and future calls to
+{Google::Cloud::PubSub::Topic#publish_async Topic#publish_async} with the
+`ordering_key` will raise {Google::Cloud::PubSub::OrderingKeyError
+OrderingKeyError}. To allow future messages with the `ordering_key` to be
+published, the `ordering_key` must be passed to
+{Google::Cloud::PubSub::Topic#resume_publish Topic#resume_publish}.
+
+### Receiving Ordered Messages
+
+To use ordering keys when subscribing to messages, the subscription must be
+created with message ordering enabled (See
+{Google::Cloud::PubSub::Topic#subscribe Topic#subscribe} and
+{Google::Cloud::PubSub::Subscription#message_ordering?
+Subscription#message_ordering?}) before calling
+{Google::Cloud::PubSub::Subscription#listen Subscription#listen}. When enabled,
+the subscriber will deliver messages with the same `ordering_key` in the order
+they were published.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-ordered-topic-sub"
+sub.message_ordering? #=> true
+
+subscriber = sub.listen do |received_message|
+  # Messsages with the same ordering_key are received
+  # in the order in which they were published.
+  received_message.acknowledge!
+end
+
+# Start background threads that will call block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop!
+```
+
+## Minimizing API calls before receiving and acknowledging messages
+
+A subscription object can be created without making any API calls by providing
+the `skip_lookup` argument to {Google::Cloud::PubSub::Project#subscription
+Project#subscription} or {Google::Cloud::PubSub::Topic#subscription
+Topic#subscription}. A subscriber object can also be created without an API call
+by providing the `deadline` optional argument to
+{Google::Cloud::PubSub::Subscription#listen Subscription#listen}:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+# No API call is made to retrieve the subscription resource.
+sub = pubsub.subscription "my-topic-sub", skip_lookup: true
+
+# No API call is made to retrieve the subscription deadline.
+subscriber = sub.listen deadline: 60 do |received_message|
+  # process message
+  received_message.acknowledge!
+end
+
+# Start background threads that will call block passed to listen.
+subscriber.start
+
+# Shut down the subscriber when ready to stop receiving messages.
+subscriber.stop!
+```
+
+Skipping API calls may be used to avoid `Google::Cloud::PermissionDeniedError`
+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
+complete list of Pub/Sub roles and permissions.
+
+## Creating a snapshot and using seek
+
+You can create a snapshot to retain the existing backlog on a subscription. The
+snapshot will hold the messages in the subscription's backlog that are
+unacknowledged upon the successful completion of the `create_snapshot`
+operation.
+
+Later, you can use `seek` to reset the subscription's backlog to the snapshot.
+
+(See {Google::Cloud::PubSub::Subscription#create_snapshot
+Subscription#create_snapshot} and {Google::Cloud::PubSub::Subscription#seek
+Subscription#seek})
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new
+
+sub = pubsub.subscription "my-topic-sub"
+
+snapshot = sub.create_snapshot
+
+received_messages = sub.pull immediate: false
+sub.acknowledge received_messages
+
+sub.seek snapshot
+```
+
+## Working Across Projects
+
+All calls to the Pub/Sub service use the same project and credentials provided
+to the {Google::Cloud::PubSub.new PubSub.new} method. However, it is common to
+reference topics or subscriptions in other projects, which can be achieved by
+using the `project` option. The main credentials must have permissions to the
+topics and subscriptions in other projects.
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new # my-project
+
+# Get a topic in the current project
+my_topic = pubsub.topic "my-topic"
+my_topic.name #=> "projects/my-project/topics/my-topic"
+# Get a topic in another project
+other_topic = pubsub.topic "other-topic", project: "other-project-id"
+other_topic.name #=> "projects/other-project-id/topics/other-topic"
+```
+
+It is possible to create a subscription in the current project that pulls
+from a topic in another project:
+
+```ruby
+require "google/cloud/pubsub"
+
+pubsub = Google::Cloud::PubSub.new # my-project
+
+# Get a topic in another project
+topic = pubsub.topic "other-topic", project: "other-project-id"
+# Create a subscription in the current project that pulls from
+# the topic in another project
+sub = topic.subscribe "my-sub"
+sub.name #=> "projects/my-project/subscriptions/my-sub"
+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
+{file:LOGGING.md Logging guide}.