google-cloud-firestore 0.25.0 → 0.25.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20e48c6792126fe8c5a79b40397c538b31ebc323b14047ffea02469105548a05
-  data.tar.gz: fdc7adba72dfb45c176538777c3c7fcd75d0fe17938b2732589e2f7cae52ff73
+  metadata.gz: 827e034858a868b3f10ad1aa997efd49ae602d56a57d16cbc12fa57cd6d69f1c
+  data.tar.gz: 3a7e878306128346310111ec5c99ca008b48cb030c44096f7a86c1d9b99da6fc
 SHA512:
-  metadata.gz: 4b878632115005af9f47874d6ac9655e12a20017786f234c8cf77949a54c3b3a8f67e86d73819e42fc7c0dc62102d5fdee54d3406932e724b4cee6efc99726e1
-  data.tar.gz: feb031af0e58139b0e039e8230c1921f72a91e0cdfe5b31d8d3c39823fa1a30e12f1569f26d29a0623ebf0c6790eb5b49bf164c5405c36b447a0d561d0cbdf34
+  metadata.gz: 2bee3a7931f0dedec0666925e3e8e1485cd9c2865cc6a2d5909dba2121a15590f4282baa61190829d888610e289c33ef3d60421a19378cdd1019773a9d9bce86
+  data.tar.gz: afad9e59107345669f0918e6f28faf2fd5baefc01e445111e9e01abb6d19278e10789a7cff21930125f6229a5e03886c32bf63b8a8e17d70e1ac70b58917400c

data/AUTHENTICATION.md

@@ -2,20 +2,39 @@
 
 In general, the google-cloud-firestore library uses [Service
 Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
-credentials to connect to Google Cloud services. When running on Compute Engine
+credentials to connect to Google Cloud services. When running within [Google
+Cloud Platform environments](#google-cloud-platform-environments)
 the credentials will be discovered automatically. When running on other
 environments, the Service Account credentials can be specified by providing the
 path to the [JSON
 keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
-the account (or the JSON itself) in environment variables. Additionally, Cloud
-SDK credentials can also be discovered automatically, but this is only
-recommended during development.
+the account (or the JSON itself) in [environment
+variables](#environment-variables). Additionally, Cloud SDK credentials can also
+be discovered automatically, but this is only recommended during development.
+
+## Quickstart
+
+1. [Create a service account and credentials](#creating-a-service-account).
+2. Set the [environment variable](#environment-variables).
+
+```sh
+export FIRESTORE_CREDENTIALS=/path/to/json`
+```
+
+3. Initialize the client.
+
+```ruby
+require "google/cloud/firestore"
+
+client = Google::Cloud::Firestore.new
+```
 
 ## Project and Credential Lookup
 
-The google-cloud-firestore library aims to make authentication as simple as
-possible, and provides several mechanisms to configure your system without
-providing **Project ID** and **Service Account Credentials** directly in code.
+The google-cloud-firestore library aims to make authentication
+as simple as possible, and provides several mechanisms to configure your system
+without providing **Project ID** and **Service Account Credentials** directly in
+code.
 
 **Project ID** is discovered in the following order:
 
@@ -23,6 +42,7 @@ providing **Project ID** and **Service Account Credentials** directly in code.
 2. Specify project ID in configuration
 3. Discover project ID in environment variables
 4. Discover GCE project ID
+5. Discover project ID in credentials JSON
 
 **Credentials** are discovered in the following order:
 
@@ -73,12 +93,12 @@ environment variable, or the **Credentials JSON** itself can be stored for
 environments such as Docker containers where writing files is difficult or not
 encouraged.
 
-The environment variables that Firestore checks for project ID are:
+The environment variables that google-cloud-firestore checks for project ID are:
 
 1. `FIRESTORE_PROJECT`
 2. `GOOGLE_CLOUD_PROJECT`
 
-The environment variables that Firestore checks for credentials are configured on {Google::Cloud::Firestore::V1beta1::Credentials}:
+The environment variables that google-cloud-firestore checks for credentials are configured on {Google::Cloud::Firestore::V1::Credentials}:
 
 1. `FIRESTORE_CREDENTIALS` - Path to JSON file, or JSON contents
 2. `FIRESTORE_KEYFILE` - Path to JSON file, or JSON contents
@@ -92,7 +112,7 @@ require "google/cloud/firestore"
 ENV["FIRESTORE_PROJECT"]     = "my-project-id"
 ENV["FIRESTORE_CREDENTIALS"] = "path/to/keyfile.json"
 
-firestore = Google::Cloud::Firestore.new
+client = Google::Cloud::Firestore.new
 ```
 
 ### Configuration
@@ -107,7 +127,7 @@ Google::Cloud::Firestore.configure do |config|
   config.credentials = "path/to/keyfile.json"
 end
 
-firestore = Google::Cloud::Firestore.new
+client = Google::Cloud::Firestore.new
 ```
 
 ### Cloud SDK
@@ -140,7 +160,8 @@ Google Cloud requires a **Project ID** and **Service Account Credentials** to
 connect to the APIs. You will use the **Project ID** and **JSON key file** to
 connect to most services with google-cloud-firestore.
 
-If you are not running this client on Google Compute Engine, you need a Google
+If you are not running this client within [Google Cloud Platform
+environments](#google-cloud-platform-environments), you need a Google
 Developers service account.
 
 1. Visit the [Google Developers Console][dev-console].

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 0.25.1 / 2019-04-29
+
+* Add AUTHENTICATION.md guide.
+* Update documentation for V1 Server API to GA.
+* Update generated documentation.
+* Extract gRPC header values from request.
+
 ### 0.25.0 / 2019-02-01
 
 * Switch Firestore to use the V1 API:
@@ -22,7 +29,7 @@
     This value was added in googleauth 0.7.0.
   * Loosen googleauth dependency
     Allow for new releases up to 0.10.
-    The googleauth devs have committed to maintanining the current API
+    The googleauth devs have committed to maintaining the current API
     and will not make backwards compatible changes before 0.10.
 * Add Firestore emulator support.
 

data/lib/google/cloud/firestore/client.rb

@@ -102,10 +102,10 @@ module Google
         def cols
           ensure_service!
 
-          return enum_for(:cols) unless block_given?
+          return enum_for :cols unless block_given?
 
           collection_ids = service.list_collections "#{path}/documents"
-          collection_ids.each { |collection_id| yield col(collection_id) }
+          collection_ids.each { |collection_id| yield col collection_id }
         end
         alias collections cols
         alias list_collections cols
@@ -217,7 +217,7 @@ module Google
           ensure_service!
 
           unless block_given?
-            return enum_for(:get_all, docs, field_mask: field_mask)
+            return enum_for :get_all, docs, field_mask: field_mask
           end
 
           doc_paths = Array(docs).flatten.map do |doc_path|
@@ -235,7 +235,7 @@ module Google
           results = service.get_documents doc_paths, mask: mask
           results.each do |result|
             next if result.result.nil?
-            yield DocumentSnapshot.from_batch_result(result, self)
+            yield DocumentSnapshot.from_batch_result result, self
           end
         end
         alias get_docs get_all

data/lib/google/cloud/firestore/collection_reference.rb

@@ -75,7 +75,7 @@ module Google
         ##
         # @private The parent path for the collection.
         def parent_path
-          path.split("/")[0...-1].join("/")
+          path.split("/")[0...-1].join "/"
         end
 
         # @!group Access

data/lib/google/cloud/firestore/document_reference.rb

@@ -91,10 +91,10 @@ module Google
         def cols
           ensure_service!
 
-          return enum_for(:cols) unless block_given?
+          return enum_for :cols unless block_given?
 
           collection_ids = service.list_collections path
-          collection_ids.each { |collection_id| yield col(collection_id) }
+          collection_ids.each { |collection_id| yield col collection_id }
         end
         alias collections cols
         alias list_collections cols
@@ -473,7 +473,7 @@ module Google
         ##
         # @private
         def parent_path
-          path.split("/")[0...-1].join("/")
+          path.split("/")[0...-1].join "/"
         end
 
         ##

data/lib/google/cloud/firestore/field_path.rb

@@ -110,7 +110,7 @@ module Google
         #
         def formatted_string
           escaped_fields = @fields.map { |field| escape_field_for_path field }
-          escaped_fields.join(".")
+          escaped_fields.join "."
         end
 
         ##
@@ -175,16 +175,17 @@ module Google
           end
 
           if dotted_string.is_a? Array
-            return @memoized_field_paths[dotted_string] = new(dotted_string)
+            @memoized_field_paths[dotted_string] = new dotted_string
+            return @memoized_field_paths[dotted_string]
           end
 
-          fields = String(dotted_string).split(".")
+          fields = String(dotted_string).split "."
 
           if fields.grep(INVALID_FIELD_PATH_CHARS).any?
             raise ArgumentError, "invalid character, use FieldPath instead"
           end
 
-          @memoized_field_paths[dotted_string] = new(fields)
+          @memoized_field_paths[dotted_string] = new fields
         end
 
         ##

data/lib/google/cloud/firestore/generate.rb

@@ -25,7 +25,7 @@ module Google
 
         def self.unique_id length: 20, chars: CHARS
           size = chars.size
-          Array.new(length) do
+          Array.new length do
             chars[SecureRandom.random_number(size)]
           end.join
         end

data/lib/google/cloud/firestore/query.rb

@@ -378,7 +378,7 @@ module Google
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
-          new_query.limit = Google::Protobuf::Int32Value.new(value: num)
+          new_query.limit = Google::Protobuf::Int32Value.new value: num
 
           Query.start new_query, parent_path, client
         end
@@ -825,12 +825,12 @@ module Google
         def get
           ensure_service!
 
-          return enum_for(:get) unless block_given?
+          return enum_for :get unless block_given?
 
           results = service.run_query parent_path, @query
           results.each do |result|
             next if result.document.nil?
-            yield DocumentSnapshot.from_query_result(result, client)
+            yield DocumentSnapshot.from_query_result result, client
           end
         end
         alias run get
@@ -923,13 +923,13 @@ module Google
         ].freeze
 
         def value_nil? value
-          [nil, :null, :nil].include?(value)
+          [nil, :null, :nil].include? value
         end
 
         def value_nan? value
           # Comparing NaN values raises, so check for #nan? first.
           return true if value.respond_to?(:nan?) && value.nan?
-          [:nan].include?(value)
+          [:nan].include? value
         end
 
         def value_unary? value
@@ -994,7 +994,7 @@ module Google
 
         def values_to_cursor values, query
           if values.count == 1 && values.first.is_a?(DocumentSnapshot)
-            return snapshot_to_cursor(values.first, query)
+            return snapshot_to_cursor values.first, query
           end
 
           # pair values with their field_paths to ensure correct formatting

data/lib/google/cloud/firestore/transaction.rb

@@ -131,7 +131,7 @@ module Google
           ensure_service!
 
           unless block_given?
-            return enum_for(:get_all, docs, field_mask: field_mask)
+            return enum_for :get_all, docs, field_mask: field_mask
           end
 
           doc_paths = Array(docs).flatten.map do |doc_path|
@@ -151,7 +151,7 @@ module Google
           results.each do |result|
             extract_transaction_from_result! result
             next if result.result.nil?
-            yield DocumentSnapshot.from_batch_result(result, client)
+            yield DocumentSnapshot.from_batch_result result, client
           end
         end
         alias get_docs get_all
@@ -251,20 +251,20 @@ module Google
 
           obj = coalesce_get_argument obj
 
-          if obj.is_a?(DocumentReference)
+          if obj.is_a? DocumentReference
             doc = get_all([obj]).first
             yield doc if block_given?
             return doc
           end
 
-          return enum_for(:get, obj) unless block_given?
+          return enum_for :get, obj unless block_given?
 
           results = service.run_query obj.parent_path, obj.query,
                                       transaction: transaction_or_create
           results.each do |result|
             extract_transaction_from_result! result
             next if result.document.nil?
-            yield DocumentSnapshot.from_query_result(result, client)
+            yield DocumentSnapshot.from_query_result result, client
           end
         end
         alias run get

data/lib/google/cloud/firestore/v1.rb

@@ -21,7 +21,7 @@ module Google
       # rubocop:disable LineLength
 
       ##
-      # # Ruby Client for Google Cloud Firestore API ([Beta](https://github.com/googleapis/google-cloud-ruby#versioning))
+      # # Ruby Client for Google Cloud Firestore API ([GA](https://github.com/googleapis/google-cloud-ruby#versioning))
       #
       # [Google Cloud Firestore API][Product Documentation]:
       #

data/lib/google/cloud/firestore/v1/doc/google/firestore/v1/query.rb

@@ -166,6 +166,11 @@ module Google
           end
         end
 
+        # A reference to a field, such as `max(messages.time) as max_time`.
+        # @!attribute [rw] field_path
+        #   @return [String]
+        class FieldReference; end
+
         # An order on a field.
         # @!attribute [rw] field
         #   @return [Google::Firestore::V1::StructuredQuery::FieldReference]
@@ -175,11 +180,6 @@ module Google
         #     The direction to order by. Defaults to `ASCENDING`.
         class Order; end
 
-        # A reference to a field, such as `max(messages.time) as max_time`.
-        # @!attribute [rw] field_path
-        #   @return [String]
-        class FieldReference; end
-
         # The projection of document's fields to return.
         # @!attribute [rw] fields
         #   @return [Array<Google::Firestore::V1::StructuredQuery::FieldReference>]

data/lib/google/cloud/firestore/v1/doc/google/firestore/v1/write.rb

@@ -26,7 +26,7 @@ module Google
       #     `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
       # @!attribute [rw] transform
       #   @return [Google::Firestore::V1::DocumentTransform]
-      #     Applies a tranformation to a document.
+      #     Applies a transformation to a document.
       #     At most one `transform` per document is allowed in a given request.
       #     An `update` cannot follow a `transform` on the same document in a given
       #     request.

data/lib/google/cloud/firestore/v1/doc/google/protobuf/any.rb

@@ -97,7 +97,8 @@ module Google
     # @!attribute [rw] type_url
     #   @return [String]
     #     A URL/resource name that uniquely identifies the type of the serialized
-    #     protocol buffer message. The last segment of the URL's path must represent
+    #     protocol buffer message. This string must contain at least
+    #     one "/" character. The last segment of the URL's path must represent
     #     the fully qualified name of the type (as in
     #     `path/google.protobuf.Duration`). The name should be in a canonical form
     #     (e.g., leading "." is not accepted).

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

@@ -15,17 +15,19 @@
 
 module Google
   module Protobuf
-    # A Timestamp represents a point in time independent of any time zone
-    # or calendar, represented as seconds and fractions of seconds at
-    # nanosecond resolution in UTC Epoch time. It is encoded using the
-    # Proleptic Gregorian Calendar which extends the Gregorian calendar
-    # backwards to year one. It is encoded assuming all minutes are 60
-    # seconds long, i.e. leap seconds are "smeared" so that no leap second
-    # table is needed for interpretation. Range is from
-    # 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).
+    # A Timestamp represents a point in time independent of any time zone or local
+    # calendar, encoded as a count of seconds and fractions of seconds at
+    # nanosecond resolution. The count is relative to an epoch at UTC midnight on
+    # January 1, 1970, in the proleptic Gregorian calendar which extends the
+    # Gregorian calendar backwards to year one.
+    #
+    # All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
+    # second table is needed for interpretation, using a [24-hour linear
+    # smear](https://developers.google.com/time/smear).
+    #
+    # The range is from 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](https://www.ietf.org/rfc/rfc3339.txt) date strings.
     #
     # = Examples
     #
@@ -86,12 +88,12 @@ module Google
     # 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]
+    # 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://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
+    # http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D
     # ) to obtain a formatter capable of generating timestamps in this format.
     # @!attribute [rw] seconds
     #   @return [Integer]

data/lib/google/cloud/firestore/v1/doc/google/rpc/status.rb

@@ -15,24 +15,25 @@
 
 module Google
   module Rpc
-    # The `Status` type defines a logical error model that is suitable for different
-    # programming environments, including REST APIs and RPC APIs. It is used by
-    # [gRPC](https://github.com/grpc). The error model is designed to be:
+    # The `Status` type defines a logical error model that is suitable for
+    # different programming environments, including REST APIs and RPC APIs. It is
+    # used by [gRPC](https://github.com/grpc). The error model is designed to be:
     #
     # * Simple to use and understand for most users
     # * Flexible enough to meet unexpected needs
     #
     # = Overview
     #
-    # The `Status` message contains three pieces of data: error code, error message,
-    # and error details. The error code should be an enum value of
-    # {Google::Rpc::Code}, but it may accept additional error codes if needed.  The
-    # error message should be a developer-facing English message that helps
-    # developers *understand* and *resolve* the error. If a localized user-facing
-    # error message is needed, put the localized message in the error details or
-    # localize it in the client. The optional error details may contain arbitrary
-    # information about the error. There is a predefined set of error detail types
-    # in the package `google.rpc` that can be used for common error conditions.
+    # The `Status` message contains three pieces of data: error code, error
+    # message, and error details. The error code should be an enum value of
+    # {Google::Rpc::Code}, but it may accept additional error codes
+    # if needed.  The error message should be a developer-facing English message
+    # that helps developers *understand* and *resolve* the error. If a localized
+    # user-facing error message is needed, put the localized message in the error
+    # details or localize it in the client. The optional error details may contain
+    # arbitrary information about the error. There is a predefined set of error
+    # detail types in the package `google.rpc` that can be used for common error
+    # conditions.
     #
     # = Language mapping
     #
@@ -69,12 +70,14 @@ module Google
     #   be used directly after any stripping needed for security/privacy reasons.
     # @!attribute [rw] code
     #   @return [Integer]
-    #     The status code, which should be an enum value of {Google::Rpc::Code}.
+    #     The status code, which should be an enum value of
+    #     {Google::Rpc::Code}.
     # @!attribute [rw] message
     #   @return [String]
     #     A developer-facing error message, which should be in English. Any
     #     user-facing error message should be localized and sent in the
-    #     {Google::Rpc::Status#details} field, or localized by the client.
+    #     {Google::Rpc::Status#details} field, or localized
+    #     by the client.
     # @!attribute [rw] details
     #   @return [Array<Google::Protobuf::Any>]
     #     A list of messages that carry the error details.  There is a common set of