google-cloud-firestore 0.22.0 → 0.23.0

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

@@ -0,0 +1,118 @@
+# Copyright 2018 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
+#
+#     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,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/firestore/watch/listener"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # QueryListener
+      #
+      # An ongoing listen operation on a query. This is returned by calling
+      # {Query#listen}.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Create a query
+      #   query = firestore.col(:cities).order(:population, :desc)
+      #
+      #   listener = query.listen do |snapshot|
+      #     puts "The query snapshot has #{snapshot.docs.count} documents "
+      #     puts "and has #{snapshot.changes.count} changes."
+      #   end
+      #
+      #   # When ready, stop the listen operation and close the stream.
+      #   listener.stop
+      #
+      class QueryListener
+        ##
+        # @private
+        # Creates the watch stream and listener object.
+        def initialize query, &callback
+          @query = query
+          raise ArgumentError if @query.nil?
+
+          @callback = callback
+          raise ArgumentError if @callback.nil?
+
+          @listener = Watch::Listener.for_query query, &callback
+        end
+
+        ##
+        # @private
+        def start
+          @listener.start
+          self
+        end
+
+        ##
+        # Stops the client listening for changes.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a query
+        #   query = firestore.col(:cities).order(:population, :desc)
+        #
+        #   listener = query.listen do |snapshot|
+        #     puts "The query snapshot has #{snapshot.docs.count} documents "
+        #     puts "and has #{snapshot.changes.count} changes."
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def stop
+          @listener.stop
+        end
+
+        ##
+        # Whether the client has stopped listening for changes.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a query
+        #   query = firestore.col(:cities).order(:population, :desc)
+        #
+        #   listener = query.listen do |snapshot|
+        #     puts "The query snapshot has #{snapshot.docs.count} documents "
+        #     puts "and has #{snapshot.changes.count} changes."
+        #   end
+        #
+        #   # Checks if the listener is stopped.
+        #   listener.stopped? #=> false
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        #   # Checks if the listener is stopped.
+        #   listener.stopped? #=> true
+        #
+        def stopped?
+          @listener.stopped?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# Copyright 2018 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
+#
+#     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,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/firestore/v1beta1"
+require "google/cloud/firestore/document_reference"
+require "google/cloud/firestore/collection_reference"
+require "google/cloud/firestore/convert"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # QuerySnapshot
+      #
+      # A query snapshot object is an immutable representation of query results,
+      # including chnages from the previous snapshot.
+      #
+      # See {Query#listen}.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Create a query
+      #   query = firestore.col(:cities).order(:population, :desc)
+      #
+      #   listener = query.listen do |snapshot|
+      #     puts "The query snapshot has #{snapshot.docs.count} documents "
+      #     puts "and has #{snapshot.changes.count} changes."
+      #   end
+      #
+      #   # When ready, stop the listen operation and close the stream.
+      #   listener.stop
+      #
+      class QuerySnapshot
+        ##
+        # The query producing this snapshot.
+        #
+        # @return [Query] query.
+        #
+        def query
+          @query
+        end
+
+        ##
+        # The documents in the snapshot.
+        #
+        # @return [Array<DocumentSnapshot>] document snapshots.
+        #
+        def docs
+          @docs
+        end
+        alias documents docs
+
+        ##
+        # The document change objects for the query snapshot.
+        #
+        # @return [Array<DocumentChange>] document changes.
+        #
+        def changes
+          @changes
+        end
+        alias doc_changes changes
+        alias document_changes changes
+
+        ##
+        # Returns the number of documents in this query snapshot.
+        #
+        # @return [Integer] The number of documents.
+        #
+        def size
+          docs.size
+        end
+        alias count size
+
+        ##
+        # Determines whether query results exists.
+        #
+        # @return [Boolean] Whether query results exists.
+        #
+        def empty?
+          docs.empty?
+        end
+
+        ##
+        # The time at which the snapshot was read.
+        #
+        # @return [Time] The time at which the documents were read.
+        #
+        def read_at
+          @read_at
+        end
+        alias read_time read_at
+
+        ##
+        # @private New QuerySnapshot
+        def self.from_docs query, docs, changes, read_at
+          new.tap do |s|
+            s.instance_variable_set :@query,   query
+            s.instance_variable_set :@docs,    docs
+            s.instance_variable_set :@changes, changes
+            s.instance_variable_set :@read_at, read_at
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -91,6 +91,14 @@ module Google
           end
         end
 
+        def listen enum
+          options = call_options parent: database_path
+
+          execute do
+            firestore.listen enum, options: options
+          end
+        end
+
         def begin_transaction transaction_opt
           options = call_options parent: database_path
 

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

@@ -29,9 +29,9 @@ module Google
       # execute atomically at a single logical point in time.
       #
       # All changes are accumulated in memory until the block passed to
-      # {Database#transaction} completes. Transactions will be automatically
+      # {Client#transaction} completes. Transactions will be automatically
       # retried when documents change before the transaction is committed. See
-      # {Database#transaction}.
+      # {Client#transaction}.
       #
       # @example
       #   require "google/cloud/firestore"

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

@@ -1,4 +1,4 @@
-# Copyright 2017 Google LLC
+# Copyright 2018 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,33 +16,59 @@ require "google/cloud/firestore/v1beta1/firestore_client"
 
 module Google
   module Cloud
-    # rubocop:disable LineLength
-
-    ##
-    # # Ruby Client for Google Cloud Firestore API ([Beta](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
-    #
-    # [Google Cloud Firestore API][Product Documentation]:
-    #
-    # - [Product Documentation][]
-    #
-    # ## Quick Start
-    # In order to use this library, you first need to go through the following
-    # steps:
-    #
-    # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
-    # 2. [Enable the Google Cloud Firestore API.](https://console.cloud.google.com/apis/api/firestore)
-    # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
-    #
-    # ### Next Steps
-    # - Read the [Google Cloud Firestore API Product documentation][Product Documentation]
-    #   to learn more about the product and see How-to Guides.
-    # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
-    #   to see the full list of Cloud APIs that we cover.
-    #
-    # [Product Documentation]: https://cloud.google.com/firestore
-    #
-    #
     module Firestore
+      # rubocop:disable LineLength
+
+      ##
+      # # Ruby Client for Google Cloud Firestore API ([Beta](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+      #
+      # [Google Cloud Firestore API][Product Documentation]:
+      #
+      # - [Product Documentation][]
+      #
+      # ## Quick Start
+      # In order to use this library, you first need to go through the following
+      # steps:
+      #
+      # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+      # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+      # 3. [Enable the Google Cloud Firestore API.](https://console.cloud.google.com/apis/library/firestore.googleapis.com)
+      # 4. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+      #
+      # ### Next Steps
+      # - Read the [Google Cloud Firestore API Product documentation][Product Documentation]
+      #   to learn more about the product and see How-to Guides.
+      # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+      #   to see the full list of Cloud APIs that we cover.
+      #
+      # [Product Documentation]: https://cloud.google.com/firestore
+      #
+      # ## Enabling 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-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below,
+      # or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
+      # 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
+      # ```
+      #
       module V1beta1
         # rubocop:enable LineLength
 
@@ -88,28 +114,27 @@ module Google
         #   or the specified config is missing data points.
         # @param timeout [Numeric]
         #   The default timeout, in seconds, for calls made through this client.
+        # @param metadata [Hash]
+        #   Default metadata to be sent with each request. This can be overridden on a per call basis.
+        # @param exception_transformer [Proc]
+        #   An optional proc that intercepts any exceptions raised during an API call to inject
+        #   custom error handling.
         def self.new \
-            service_path: nil,
-            port: nil,
-            channel: nil,
-            chan_creds: nil,
-            updater_proc: nil,
             credentials: nil,
             scopes: nil,
             client_config: nil,
             timeout: nil,
+            metadata: nil,
+            exception_transformer: nil,
             lib_name: nil,
             lib_version: nil
           kwargs = {
-            service_path: service_path,
-            port: port,
-            channel: channel,
-            chan_creds: chan_creds,
-            updater_proc: updater_proc,
             credentials: credentials,
             scopes: scopes,
             client_config: client_config,
             timeout: timeout,
+            metadata: metadata,
+            exception_transformer: exception_transformer,
             lib_name: lib_name,
             lib_version: lib_version
           }.select { |_, v| v != nil }

data/lib/google/cloud/firestore/v1beta1/credentials.rb

@@ -0,0 +1,41 @@
+# Copyright 2018 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
+#
+#     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,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "googleauth"
+
+module Google
+  module Cloud
+    module Firestore
+      module V1beta1
+        class Credentials < Google::Auth::Credentials
+          SCOPE = [
+            "https://www.googleapis.com/auth/cloud-platform",
+            "https://www.googleapis.com/auth/datastore"
+          ].freeze
+          PATH_ENV_VARS = %w(FIRESTORE_CREDENTIALS
+                             FIRESTORE_KEYFILE
+                             GOOGLE_CLOUD_CREDENTIALS
+                             GOOGLE_CLOUD_KEYFILE
+                             GCLOUD_KEYFILE)
+          JSON_ENV_VARS = %w(FIRESTORE_CREDENTIALS_JSON
+                             FIRESTORE_KEYFILE_JSON
+                             GOOGLE_CLOUD_CREDENTIALS_JSON
+                             GOOGLE_CLOUD_KEYFILE_JSON
+                             GCLOUD_KEYFILE_JSON)
+          DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/common.rb

@@ -1,4 +1,4 @@
-# Copyright 2017 Google LLC
+# Copyright 2018 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/document.rb

@@ -1,4 +1,4 @@
-# Copyright 2017 Google LLC
+# Copyright 2018 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@ module Google
       #     The map keys represent field names.
       #
       #     A simple field name contains only characters +a+ to +z+, +A+ to +Z+,
-      #     +0+ to +9+, or +_+, and must not start with +0+ to +9+ or +_+. For example,
+      #     +0+ to +9+, or +_+, and must not start with +0+ to +9+. For example,
       #     +foo_bar_17+.
       #
       #     Field names matching the regular expression +__.*__+ are reserved. Reserved
@@ -59,7 +59,7 @@ module Google
       #   @return [Google::Protobuf::Timestamp]
       #     Output only. The time at which the document was last changed.
       #
-      #     This value is initally set to the +create_time+ then increases
+      #     This value is initially set to the +create_time+ then increases
       #     monotonically with each change to the document. It can also be
       #     compared to values from other documents and the +read_time+ of a query.
       class Document; end
@@ -107,7 +107,8 @@ module Google
       #   @return [Google::Firestore::V1beta1::ArrayValue]
       #     An array value.
       #
-      #     Cannot contain another array value.
+      #     Cannot directly contain another array value, though can contain an
+      #     map which contains another array.
       # @!attribute [rw] map_value
       #   @return [Google::Firestore::V1beta1::MapValue]
       #     A map value.