google-cloud-pubsub 0.20.0 → 2.6.1

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

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # 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,
@@ -15,8 +15,10 @@
 
 module Google
   module Cloud
-    module Pubsub
-      VERSION = "0.20.0"
+    module PubSub
+      VERSION = "2.6.1".freeze
     end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end

data/lib/google/cloud/pubsub.rb

@@ -1,10 +1,10 @@
-# Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2015 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # 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,
@@ -15,6 +15,8 @@
 
 require "google-cloud-pubsub"
 require "google/cloud/pubsub/project"
+require "google/cloud/config"
+require "google/cloud/env"
 
 module Google
   module Cloud
@@ -28,418 +30,141 @@ module Google
     # Cloud Pub/Sub allows developers to communicate between independently
     # written applications.
     #
-    # The goal of google-cloud is to provide a API that is comfortable to
-    # Rubyists. Authentication is handled by {Google::Cloud#pubsub}. You can
-    # provide the project and credential information to connect to the Pub/Sub
-    # service, or if you are running on Google Compute Engine this configuration
-    # is taken care of for you.
+    # See {file:OVERVIEW.md Google Cloud Pub/Sub Overview}.
     #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # 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})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    # topic = pubsub.topic "my-topic"
-    # ```
-    #
-    # ## Creating a Topic
-    #
-    # A Topic is created from a Project. (See
-    # {Google::Cloud::Pubsub::Project#create_topic})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    # 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})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # 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} and
-    # {Google::Cloud::Pubsub::Project#subscribe})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # 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"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # 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} and
-    # {Google::Cloud::Pubsub::Project#publish})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # topic = pubsub.topic "my-topic"
-    # msg = topic.publish "new-message"
-    # ```
-    #
-    # Messages can also be published with attributes:
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # topic = pubsub.topic "my-topic"
-    # msg = topic.publish "new-message",
-    #                     foo: :bar,
-    #                     this: :that
-    # ```
-    #
-    # Multiple messages can be published at the same time by passing a block:
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # topic = pubsub.topic "my-topic"
-    # msgs = topic.publish do |batch|
-    #   batch.publish "new-message-1", foo: :bar
-    #   batch.publish "new-message-2", foo: :baz
-    #   batch.publish "new-message-3", foo: :bif
-    # end
-    # ```
-    #
-    # ## Pulling Messages
-    #
-    # Messages are pulled from a Subscription. (See
-    # {Google::Cloud::Pubsub::Subscription#pull})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # msgs = sub.pull
-    # ```
-    #
-    # A maximum number of messages returned can also be specified:
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub", max: 10
-    # msgs = sub.pull
-    # ```
-    #
-    # The request for messages can also block until messages are available.
-    # (See {Google::Cloud::Pubsub::Subscription#wait_for_messages})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # msgs = sub.wait_for_messages
-    # ```
-    #
-    # ## 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!})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # sub.pull.each { |msg| msg.acknowledge! }
-    # ```
-    #
-    # Or, multiple messages can be acknowledged in a single API call:
-    # (See {Google::Cloud::Pubsub::Subscription#acknowledge})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # received_messages = sub.pull
-    # 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#delay!})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # received_message = sub.pull.first
-    # if received_message
-    #   puts received_message.message.data
-    #   # Delay for 2 minutes
-    #   received_message.delay! 120
-    # end
-    # ```
-    #
-    # The message can also be made available for immediate redelivery:
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # received_message = sub.pull.first
-    # if received_message
-    #   puts received_message.message.data
-    #   # Mark for redelivery by setting the deadline to now
-    #   received_message.delay! 0
-    # end
-    # ```
-    #
-    # Multiple messages can be delayed or made available for immediate
-    # redelivery: (See {Google::Cloud::Pubsub::Subscription#delay})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # received_messages = sub.pull
-    # sub.delay 120, received_messages
-    # ```
-    #
-    # ## Listening for Messages
-    #
-    # Long running workers are easy to create with `listen`, which runs an
-    # infinitely blocking loop to process messages as they are received. (See
-    # {Google::Cloud::Pubsub::Subscription#listen})
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # sub.listen do |msg|
-    #   # process msg
-    # end
-    # ```
-    #
-    # Messages are retrieved in batches for efficiency. The number of messages
-    # pulled per batch can be limited with the `max` option:
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # sub.listen max: 20 do |msg|
-    #   # process msg
-    # end
-    # ```
-    #
-    # When processing time and the acknowledgement deadline are a concern,
-    # messages can be automatically acknowledged as they are pulled with the
-    # `autoack` option:
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub
-    #
-    # sub = pubsub.subscription "my-topic-sub"
-    # sub.listen autoack: true do |msg|
-    #   # process msg
-    # end
-    # ```
-    #
-    # ## Configuring retries and timeout
-    #
-    # You can configure how many times API requests may be automatically
-    # retried. When an API request fails, the response will be inspected to see
-    # if the request meets criteria indicating that it may succeed on retry,
-    # such as `500` and `503` status codes or a specific internal error code
-    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
-    # retried after a delay. If another error occurs, the delay will be
-    # increased before a subsequent attempt, until the `retries` limit is
-    # reached.
-    #
-    # You can also set the request `timeout` value in seconds.
-    #
-    # ```ruby
-    # require "google/cloud"
-    #
-    # gcloud = Google::Cloud.new
-    # pubsub = gcloud.pubsub retries: 10, timeout: 120
-    # ```
-    #
-    # See the [Pub/Sub error codes](https://cloud.google.com/pubsub/error-codes)
-    # for a list of error conditions.
-    #
-    # ## Working Across Projects
-    #
-    # All calls to the Pub/Sub service use the same project and credentials
-    # provided to the {Google::Cloud#pubsub} 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"
-    #
-    # gcloud = Google::Cloud.new # my-project-id
-    # pubsub = gcloud.pubsub
-    #
-    # # Get a topic in the current project
-    # my_topic = pubsub.topic "my-topic"
-    # my_topic.name #=> "projects/my-project-id/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"
-    #
-    # gcloud = Google::Cloud.new # my-project-id
-    # pubsub = gcloud.pubsub
-    #
-    # # 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-id/subscriptions/my-sub"
-    # sub.topic.name #=> "projects/other-project-id/topics/other-topic"
-    # ```
-    #
-    # ## Using the 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"
-    #
-    # # Make Pub/Sub use the emulator
-    # ENV["PUBSUB_EMULATOR_HOST"] = "localhost:8918"
-    #
-    # gcloud = Google::Cloud.new "emulator-project-id"
-    # pubsub = gcloud.pubsub
-    #
-    # # Get a topic in the current project
-    # my_topic = pubsub.new_topic "my-topic"
-    # my_topic.name #=> "projects/emulator-project-id/topics/my-topic"
-    # ```
-    #
-    module Pubsub
+    module PubSub
+      # rubocop:disable Metrics/AbcSize
+
+      ##
+      # Creates a new object for connecting to the Pub/Sub service.
+      # Each call creates a new connection.
+      #
+      # For more information on connecting to Google Cloud see the
+      # {file:AUTHENTICATION.md Authentication Guide}.
+      #
+      # @param [String] project_id Project identifier for the Pub/Sub service
+      #   you are connecting to. If not present, the default project for the
+      #   credentials is used.
+      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {PubSub::Credentials})
+      # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
+      #   the set of resources and operations that the connection can access.
+      #   See [Using OAuth 2.0 to Access Google
+      #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+      #
+      #   The default scope is:
+      #
+      #   * `https://www.googleapis.com/auth/pubsub`
+      # @param [Integer] 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.
+      #   If the param is nil, uses the value of the `emulator_host` config.
+      # @param [String] project Alias for the `project_id` argument. Deprecated.
+      # @param [String] keyfile Alias for the `credentials` argument.
+      #   Deprecated.
+      #
+      # @return [Google::Cloud::PubSub::Project]
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #
+      #   topic = pubsub.topic "my-topic"
+      #   topic.publish "task completed"
+      #
+      def self.new project_id: nil,
+                   credentials: nil,
+                   scope: nil,
+                   timeout: nil,
+                   endpoint: nil,
+                   emulator_host: nil,
+                   project: nil,
+                   keyfile: nil
+        project_id    ||= (project || default_project_id)
+        scope         ||= configure.scope
+        timeout       ||= configure.timeout
+        endpoint      ||= configure.endpoint
+        emulator_host ||= configure.emulator_host
+
+        if emulator_host
+          project_id = project_id.to_s # Always cast to a string
+          raise ArgumentError, "project_id is missing" if project_id.empty?
+
+          service = PubSub::Service.new project_id, :this_channel_is_insecure, host: emulator_host, timeout: timeout
+          return PubSub::Project.new service
+        end
+
+        credentials ||= (keyfile || default_credentials(scope: scope))
+        unless credentials.is_a? Google::Auth::Credentials
+          credentials = PubSub::Credentials.new credentials, scope: scope
+        end
+
+        project_id ||= credentials.project_id if credentials.respond_to? :project_id
+        project_id = project_id.to_s # Always cast to a string
+        raise ArgumentError, "project_id is missing" if project_id.empty?
+
+        service = PubSub::Service.new project_id, credentials, host: endpoint, timeout: timeout
+        PubSub::Project.new service
+      end
+
+      # rubocop:enable Metrics/AbcSize
+
+      ##
+      # Configure the Google Cloud PubSub library.
+      #
+      # The following PubSub configuration parameters are supported:
+      #
+      # * `project_id` - (String) Identifier for a PubSub project. (The
+      #   parameter `project` is considered deprecated, but may also be used.)
+      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {PubSub::Credentials}) (The
+      #   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.
+      # * `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
+      #   `ENV["PUBSUB_EMULATOR_HOST"]`
+      # * `on_error` - (Proc) A Proc to be run when an error is encountered
+      #   on a background thread. The Proc must take the error object as the
+      #   single argument. (See {Subscriber.on_error}.)
+      #
+      # @return [Google::Cloud::Config] The configuration object the
+      #   Google::Cloud::PubSub library uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.pubsub if block_given?
+
+        Google::Cloud.configure.pubsub
+      end
+
+      ##
+      # @private Default project.
+      def self.default_project_id
+        Google::Cloud.configure.pubsub.project_id ||
+          Google::Cloud.configure.project_id ||
+          Google::Cloud.env.project_id
+      end
+
+      ##
+      # @private Default credentials.
+      def self.default_credentials scope: nil
+        Google::Cloud.configure.pubsub.credentials ||
+          Google::Cloud.configure.credentials ||
+          PubSub::Credentials.default(scope: scope)
+      end
     end
+
+    ## Legacy veneer namespace
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
+  ## Legacy generated client namespace
+  Pubsub = Cloud::PubSub unless const_defined? :Pubsub
 end