google-cloud-pubsub 0.27.2 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f83c458e0a45afd77106e7e66922ad2b1e1d8515
-  data.tar.gz: 6aeda54db32d7f78e6c8b649cad9beac294408d4
+SHA256:
+  metadata.gz: 786c0d9e552987a0743be14c13240519f55fd1d65d18a7dc7462b9d5ce80d33d
+  data.tar.gz: 2238dfa68394d90617cced8cd2053761ccf53dc5533049c2b06cfb37a12b5c85
 SHA512:
-  metadata.gz: 609784712397870174e5fd07a41978f74616ee7bab81db6ad007efda11b8bb2d1d13f8dce68e0681f1ff4e64be8d2b5c5035e8ae8a10e0a669776eda474430d1
-  data.tar.gz: af8a25738680f2d7fb74e236ecb6ce7db9a7b5de56774fc34d33f917464c251c13caec9f4cc4d96750a1db786a8a424fd92064dd5b379278820f2d73222f432f
+  metadata.gz: 4516e62d4c349e53febc8a632b4aeff7f92633de0050ff2109bab6c64f9b4b8808cac44965c9654a32447dfd9d40ae58cddf82e1810f9cb9d89ff8c9bf5d1615
+  data.tar.gz: b553b1e011d2b8e8610e2404c1e9a4a6fec921f2435b60c41b3399582d2d6f67e89ccd14adf09f72615cef6735d0551f777f29ac659cd1dee29e7c5fc7c53aac

data/README.md

@@ -24,8 +24,8 @@ Instructions and configuration options are covered in the [Authentication Guide]
 require "google/cloud/pubsub"
 
 pubsub = Google::Cloud::Pubsub.new(
-  project: "my-project",
-  keyfile: "/path/to/keyfile.json"
+  project_id: "my-project",
+  credentials: "/path/to/keyfile.json"
 )
 
 # Retrieve a topic

data/lib/google-cloud-pubsub.rb

@@ -13,9 +13,9 @@
 # limitations under the License.
 
 ##
-# This file is here to be autorequired by bundler, so that the .bigquery and
-# #bigquery methods can be available, but the library and all dependencies won't
-# be loaded until required and used.
+# This file is here to be autorequired by bundler, so that the
+# Google::Cloud.pubsub and Google::Cloud#pubsub methods can be available, but
+# the library and all dependencies won't be loaded until required and used.
 
 
 gem "google-cloud-core"
@@ -72,10 +72,12 @@ module Google
     # For more information on connecting to Google Cloud see the [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
-    # @param [String] project Project identifier for the Pub/Sub service you are
-    #   connecting to.
-    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-    #   file path the file must be readable.
+    # @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
@@ -98,10 +100,11 @@ module Google
     #   topic = pubsub.topic "my-topic"
     #   topic.publish "task completed"
     #
-    def self.pubsub project = nil, keyfile = nil, scope: nil, timeout: nil,
-                    client_config: nil
+    def self.pubsub project_id = nil, credentials = nil, scope: nil,
+                    timeout: nil, client_config: nil
       require "google/cloud/pubsub"
-      Google::Cloud::Pubsub.new project: project, keyfile: keyfile,
+      Google::Cloud::Pubsub.new project_id: project_id,
+                                credentials: credentials,
                                 scope: scope, timeout: timeout,
                                 client_config: client_config
     end

data/lib/google/cloud/pubsub.rb

@@ -425,11 +425,11 @@ module Google
     # ```ruby
     # require "google/cloud/pubsub"
     #
-    # pubsub = Google::Cloud::Pubsub.new # my-project-id
+    # 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-id/topics/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"
@@ -441,14 +441,14 @@ module Google
     # ```ruby
     # require "google/cloud/pubsub"
     #
-    # pubsub = Google::Cloud::Pubsub.new # my-project-id
+    # 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-id/subscriptions/my-sub"
+    # sub.name #=> "projects/my-project/subscriptions/my-sub"
     # sub.topic.name #=> "projects/other-project-id/topics/other-topic"
     # ```
     #
@@ -489,10 +489,12 @@ module Google
       # [Authentication
       # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
       #
-      # @param [String] project Project identifier for the Pub/Sub service you
-      #   are connecting to.
-      # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-      #   file path the file must be readable.
+      # @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
@@ -506,6 +508,9 @@ module Google
       #   behavior of the API client. Optional.
       # @param [String] emulator_host Pub/Sub emulator host. Optional.
       #   If the param is nil, ENV["PUBSUB_EMULATOR_HOST"] will be used.
+      # @param [String] project Alias for the `project_id` argument. Deprecated.
+      # @param [String] keyfile Alias for the `credentials` argument.
+      #   Deprecated.
       #
       # @return [Google::Cloud::Pubsub::Project]
       #
@@ -517,37 +522,30 @@ module Google
       #   topic = pubsub.topic "my-topic"
       #   topic.publish "task completed"
       #
-      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
-                   client_config: nil, emulator_host: nil
-        project ||= Google::Cloud::Pubsub::Project.default_project
-        project = project.to_s # Always cast to a string
-        fail ArgumentError, "project is missing" if project.empty?
+      def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
+                   client_config: nil, emulator_host: nil, project: nil,
+                   keyfile: nil
+        project_id ||= (project || Pubsub::Project.default_project_id)
+        project_id = project_id.to_s # Always cast to a string
+        fail ArgumentError, "project_id is missing" if project_id.empty?
 
         emulator_host ||= ENV["PUBSUB_EMULATOR_HOST"]
         if emulator_host
-          ps = Google::Cloud::Pubsub::Project.new(
-            Google::Cloud::Pubsub::Service.new(
-              project, :this_channel_is_insecure))
-          ps.service.host = emulator_host
-          return ps
+          return Pubsub::Project.new(
+            Pubsub::Service.new(
+              project_id, :this_channel_is_insecure,
+              host: emulator_host))
         end
 
-        credentials = credentials_with_scope keyfile, scope
-
-        Google::Cloud::Pubsub::Project.new(
-          Google::Cloud::Pubsub::Service.new(
-            project, credentials, timeout: timeout,
-                                  client_config: client_config))
-      end
-
-      ##
-      # @private
-      def self.credentials_with_scope keyfile, scope
-        if keyfile.nil?
-          Google::Cloud::Pubsub::Credentials.default(scope: scope)
-        else
-          Google::Cloud::Pubsub::Credentials.new(keyfile, scope: scope)
+        credentials ||= (keyfile || Pubsub::Credentials.default(scope: scope))
+        unless credentials.is_a? Google::Auth::Credentials
+          credentials = Pubsub::Credentials.new credentials, scope: scope
         end
+
+        Pubsub::Project.new(
+          Pubsub::Service.new(
+            project_id, credentials, timeout: timeout,
+                                     client_config: client_config))
       end
     end
   end

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

@@ -13,18 +13,44 @@
 # limitations under the License.
 
 
-require "google/cloud/credentials"
+require "googleauth"
 
 module Google
   module Cloud
     module Pubsub
       ##
-      # @private Represents the OAuth 2.0 signing logic for Pub/Sub.
-      class Credentials < Google::Cloud::Credentials
+      # # Credentials
+      #
+      # Represents the authentication and authorization used to connect to the
+      # Pub/Sub API.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   keyfile = "/path/to/keyfile.json"
+      #   creds = Google::Cloud::Pubsub::Credentials.new keyfile
+      #
+      #   pubsub = Google::Cloud::Pubsub.new(
+      #     project_id: "my-project",
+      #     credentials: creds
+      #   )
+      #
+      #   pubsub.project_id #=> "my-project"
+      #
+      class Credentials < Google::Auth::Credentials
         SCOPE = ["https://www.googleapis.com/auth/pubsub"]
-        PATH_ENV_VARS = %w(PUBSUB_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-        JSON_ENV_VARS = %w(PUBSUB_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+        PATH_ENV_VARS = %w(PUBSUB_CREDENTIALS
+                           PUBSUB_KEYFILE
+                           GOOGLE_CLOUD_CREDENTIALS
+                           GOOGLE_CLOUD_KEYFILE
+                           GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(PUBSUB_CREDENTIALS_JSON
+                           PUBSUB_KEYFILE_JSON
+                           GOOGLE_CLOUD_CREDENTIALS_JSON
+                           GOOGLE_CLOUD_KEYFILE_JSON
                            GCLOUD_KEYFILE_JSON)
+        DEFAULT_PATHS = \
+          ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

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

@@ -62,19 +62,20 @@ module Google
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::Pubsub.new(
-        #     project: "my-project",
-        #     keyfile: "/path/to/keyfile.json"
+        #     project_id: "my-project",
+        #     credentials: "/path/to/keyfile.json"
         #   )
         #
-        #   pubsub.project #=> "my-project"
+        #   pubsub.project_id #=> "my-project"
         #
-        def project
+        def project_id
           service.project
         end
+        alias_method :project, :project_id
 
         ##
         # @private Default project.
-        def self.default_project
+        def self.default_project_id
           ENV["PUBSUB_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             ENV["GCLOUD_PROJECT"] ||

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

@@ -63,7 +63,7 @@ module Google
           @subscriber ||= begin
             V1::SubscriberClient.new(
               service_path: host,
-              channel: channel,
+              credentials: channel,
               timeout: timeout,
               client_config: client_config,
               lib_name: "gccl",
@@ -77,7 +77,7 @@ module Google
           @publisher ||= begin
             V1::PublisherClient.new(
               service_path: host,
-              channel: channel,
+              credentials: channel,
               timeout: timeout,
               lib_name: "gccl",
               lib_version: Google::Cloud::Pubsub::VERSION)

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

@@ -107,7 +107,7 @@ module Google
         #   snapshot.expiration_time
         #
         def expiration_time
-          self.class.timestamp_from_grpc @grpc.expiration_time
+          self.class.timestamp_from_grpc @grpc.expire_time
         end
 
         ##

data/lib/google/cloud/pubsub/v1/doc/google/protobuf/duration.rb

@@ -21,6 +21,8 @@ module Google
     # two Timestamp values is a Duration and it can be added or subtracted
     # from a Timestamp. Range is approximately +-10,000 years.
     #
+    # = Examples
+    #
     # Example 1: Compute Duration from two Timestamps in pseudo code.
     #
     #     Timestamp start = ...;
@@ -60,10 +62,21 @@ module Google
     #     td = datetime.timedelta(days=3, minutes=10)
     #     duration = Duration()
     #     duration.FromTimedelta(td)
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Duration type is encoded as a string rather than an
+    # object, where the string ends in the suffix "s" (indicating seconds) and
+    # is preceded by the number of seconds, with nanoseconds expressed as
+    # fractional seconds. For example, 3 seconds with 0 nanoseconds should be
+    # encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should
+    # be expressed in JSON format as "3.000000001s", and 3 seconds and 1
+    # microsecond should be expressed in JSON format as "3.000001s".
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Signed seconds of the span of time. Must be from -315,576,000,000
-    #     to +315,576,000,000 inclusive.
+    #     to +315,576,000,000 inclusive. Note: these bounds are computed from:
+    #     60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
     # @!attribute [rw] nanos
     #   @return [Integer]
     #     Signed fractions of a second at nanosecond resolution of the span

data/lib/google/cloud/pubsub/v1/doc/google/protobuf/timestamp.rb

@@ -24,7 +24,9 @@ module Google
     # 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
     # By restricting to that range, we ensure that we can convert to
     # and from  RFC 3339 date strings.
-    # See {https://www.ietf.org/rfc/rfc3339.txt}[https://www.ietf.org/rfc/rfc3339.txt].
+    # See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+    #
+    # = Examples
     #
     # Example 1: Compute Timestamp from POSIX +time()+.
     #
@@ -65,6 +67,29 @@ module Google
     #
     #     timestamp = Timestamp()
     #     timestamp.GetCurrentTime()
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Timestamp type is encoded as a string in the
+    # [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
+    # format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
+    # where {year} is always expressed using four digits while {month}, {day},
+    # {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
+    # seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
+    # are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
+    # is required, though only UTC (as indicated by "Z") is presently supported.
+    #
+    # For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
+    # 01:30 UTC on January 15, 2017.
+    #
+    # In JavaScript, one can convert a Date object to this format using the
+    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+    # method. In Python, a standard +datetime.datetime+ object can be converted
+    # to this format using [+strftime+](https://docs.python.org/2/library/time.html#time.strftime)
+    # with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
+    # can use the Joda Time's [+ISODateTimeFormat.dateTime()+](
+    # http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime())
+    # to obtain a formatter capable of generating timestamps in this format.
     # @!attribute [rw] seconds
     #   @return [Integer]
     #     Represents seconds of UTC time since Unix epoch

data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb

@@ -14,6 +14,19 @@
 
 module Google
   module Pubsub
+    ##
+    # # Google Cloud Pub/Sub API Contents
+    #
+    # | Class | Description |
+    # | ----- | ----------- |
+    # | [PublisherClient][] | Provides reliable, many-to-many, asynchronous messaging between applications. |
+    # | [SubscriberClient][] | Provides reliable, many-to-many, asynchronous messaging between applications. |
+    # | [Data Types][] | Data types for Google::Cloud::Pubsub::V1 |
+    #
+    # [PublisherClient]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-pubsub/latest/google/pubsub/v1/publisherclient
+    # [SubscriberClient]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-pubsub/latest/google/pubsub/v1/subscriberclient
+    # [Data Types]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-pubsub/latest/google/pubsub/v1/datatypes
+    #
     module V1
       # A topic resource.
       # @!attribute [rw] name
@@ -24,6 +37,9 @@ module Google
       #     underscores (+_+), periods (+.+), tildes (+~+), plus (+++) or percent
       #     signs (+%+). It must be between 3 and 255 characters in length, and it
       #     must not start with +"goog"+.
+      # @!attribute [rw] labels
+      #   @return [Hash{String => String}]
+      #     User labels.
       class Topic; end
 
       # A message data and its attributes. The message payload must not be empty;
@@ -54,6 +70,16 @@ module Google
       #     Format is +projects/{project}/topics/{topic}+.
       class GetTopicRequest; end
 
+      # Request for the UpdateTopic method.
+      # @!attribute [rw] topic
+      #   @return [Google::Pubsub::V1::Topic]
+      #     The topic to update.
+      # @!attribute [rw] update_mask
+      #   @return [Google::Protobuf::FieldMask]
+      #     Indicates which fields in the provided topic to update.
+      #     Must be specified and non-empty.
+      class UpdateTopicRequest; end
+
       # Request for the Publish method.
       # @!attribute [rw] topic
       #   @return [String]
@@ -185,6 +211,9 @@ module Google
       #     of acknowledged messages, and thus configures how far back in time a +Seek+
       #     can be done. Defaults to 7 days. Cannot be more than 7 days or less than 10
       #     minutes.
+      # @!attribute [rw] labels
+      #   @return [Hash{String => String}]
+      #     User labels.
       class Subscription; end
 
       # Configuration for a push delivery endpoint.
@@ -421,6 +450,16 @@ module Google
       #     Format is +projects/{project}/subscriptions/{sub}+.
       class CreateSnapshotRequest; end
 
+      # Request for the UpdateSnapshot method.
+      # @!attribute [rw] snapshot
+      #   @return [Google::Pubsub::V1::Snapshot]
+      #     The updated snpashot object.
+      # @!attribute [rw] update_mask
+      #   @return [Google::Protobuf::FieldMask]
+      #     Indicates which fields in the provided snapshot to update.
+      #     Must be specified and non-empty.
+      class UpdateSnapshotRequest; end
+
       # A snapshot resource.
       # @!attribute [rw] name
       #   @return [String]
@@ -428,7 +467,7 @@ module Google
       # @!attribute [rw] topic
       #   @return [String]
       #     The name of the topic from which this snapshot is retaining messages.
-      # @!attribute [rw] expiration_time
+      # @!attribute [rw] expire_time
       #   @return [Google::Protobuf::Timestamp]
       #     The snapshot is guaranteed to exist up until this time.
       #     A newly-created snapshot expires no later than 7 days from the time of its
@@ -439,6 +478,9 @@ module Google
       #     old. If a snapshot is created from this subscription, the snapshot -- which
       #     will always capture this 3-day-old backlog as long as the snapshot
       #     exists -- will expire in 4 days.
+      # @!attribute [rw] labels
+      #   @return [Hash{String => String}]
+      #     User labels.
       class Snapshot; end
 
       # Request for the +ListSnapshots+ method.