google-cloud-firestore 0.20.0

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

@@ -0,0 +1,449 @@
+# Copyright 2017 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/service"
+require "google/cloud/firestore/field_path"
+require "google/cloud/firestore/field_value"
+require "google/cloud/firestore/collection_reference"
+require "google/cloud/firestore/document_reference"
+require "google/cloud/firestore/document_snapshot"
+require "google/cloud/firestore/batch"
+require "google/cloud/firestore/transaction"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # Client
+      #
+      # The Cloud Firestore Client used is to access and manipulate the
+      # collections and documents in the Firestore database.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Get a document reference
+      #   nyc_ref = firestore.doc "cities/NYC"
+      #
+      #   firestore.batch do |b|
+      #     b.update(nyc_ref, { name: "New York City" })
+      #   end
+      #
+      class Client
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new Firestore Database instance.
+        def initialize service
+          @service = service
+        end
+
+        ##
+        # The project identifier for the Cloud Firestore database.
+        #
+        # @return [String] project identifier.
+        def project_id
+          service.project
+        end
+
+        ##
+        # The database identifier for the Cloud Firestore database.
+        #
+        # @return [String] database identifier.
+        def database_id
+          "(default)"
+        end
+
+        ##
+        # @private The full Database path for the Cloud Firestore database.
+        #
+        # @return [String] database resource path.
+        def path
+          service.database_path
+        end
+
+        # @!group Access
+
+        ##
+        # Retrieves a list of collections.
+        #
+        # @yield [collections] The block for accessing the collections.
+        # @yieldparam [CollectionReference] collection A collection.
+        #
+        # @return [Enumerator<CollectionReference>] collection list.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get the root collections
+        #   firestore.cols.each do |col|
+        #     puts col.collection_id
+        #   end
+        #
+        def cols
+          ensure_service!
+
+          return enum_for(:cols) unless block_given?
+
+          collection_ids = service.list_collections "#{path}/documents"
+          collection_ids.each { |collection_id| yield col(collection_id) }
+        end
+        alias_method :collections, :cols
+
+        ##
+        # Retrieves a collection.
+        #
+        # @param [String] collection_path A string representing the path of the
+        #   collection, relative to the document root of the database.
+        #
+        # @return [CollectionReference] A collection.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get the cities collection
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get the document for NYC
+        #   nyc_ref = cities_col.doc "NYC"
+        #
+        def col collection_path
+          if collection_path.to_s.split("/").count.even?
+            fail ArgumentError, "collection_path must refer to a collection."
+          end
+
+          CollectionReference.from_path \
+            "#{path}/documents/#{collection_path}", self
+        end
+        alias_method :collection, :col
+
+        ##
+        # Retrieves a document reference.
+        #
+        # @param [String] document_path A string representing the path of the
+        #   document, relative to the document root of the database.
+        #
+        # @return [DocumentReference] A document.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   puts nyc_ref.document_id
+        #
+        def doc document_path
+          if document_path.to_s.split("/").count.odd?
+            fail ArgumentError, "document_path must refer to a document."
+          end
+
+          doc_path = "#{path}/documents/#{document_path}"
+
+          DocumentReference.from_path doc_path, self
+        end
+        alias_method :document, :doc
+
+        ##
+        # Retrieves a list of document snapshots.
+        #
+        # @param [String, DocumentReference] docs One or more strings
+        #   representing the path of the document, or document reference
+        #   objects.
+        #
+        # @yield [documents] The block for accessing the document snapshots.
+        # @yieldparam [DocumentSnapshot] document A document snapshot.
+        #
+        # @return [Enumerator<DocumentSnapshot>] document snapshots list.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get and print city documents
+        #   cities = ["cities/NYC", "cities/SF", "cities/LA"]
+        #   firestore.get_all(cities).each do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def get_all *docs
+          ensure_service!
+
+          return enum_for(:get_all, docs) unless block_given?
+
+          doc_paths = Array(docs).flatten.map do |doc_path|
+            coalesce_doc_path_argument doc_path
+          end
+
+          results = service.get_documents doc_paths
+          results.each do |result|
+            next if result.result.nil?
+            yield DocumentSnapshot.from_batch_result(result, self)
+          end
+        end
+        alias_method :get_docs, :get_all
+        alias_method :get_documents, :get_all
+        alias_method :find, :get_all
+
+        ##
+        # Creates a field path object representing the sentinel ID of a
+        # document. It can be used in queries to sort or filter by the document
+        # ID. See {Client#document_id}.
+        #
+        # @return [FieldPath] The field path object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Create a query
+        #   query = cities_col.start_at("NYC").order(
+        #     Google::Cloud::Firestore::FieldPath.document_id
+        #   )
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def document_id
+          FieldPath.document_id
+        end
+
+        ##
+        # Creates a field path object representing the nested fields for
+        # document data.
+        #
+        # @return [Array<String>] The fields.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   user_snap = firestore.doc("users/frank").get
+        #
+        #   nested_field_path = firestore.field_path :favorites, :food
+        #   user_snap.get(nested_field_path) #=> "Pizza"
+        #
+        def field_path *fields
+          FieldPath.new(*fields)
+        end
+
+        ##
+        # Creates a field value object representing the deletion of a field in
+        # document data.
+        #
+        # @return [FieldValue] The delete field value object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    trash: firestore.field_delete })
+        #
+        def field_delete
+          FieldValue.delete
+        end
+
+        ##
+        # Creates a field value object representing set a field's value to
+        # the server timestamp when accessing the document data.
+        #
+        # @return [FieldValue] The server time field value object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    updated_at: firestore.field_server_time })
+        #
+        def field_server_time
+          FieldValue.server_time
+        end
+
+        # @!endgroup
+
+        # @!group Operations
+
+        ##
+        # Perform multiple changes at the same time.
+        #
+        # All changes are accumulated in memory until the block completes.
+        # Unlike transactions, batches don't lock on document reads, should only
+        # fail if users provide preconditions, and are not automatically
+        # retried. See {Batch}.
+        #
+        # @see https://firebase.google.com/docs/firestore/manage-data/transactions
+        #   Transactions and Batched Writes
+        #
+        # @yield [batch] The block for reading data and making changes.
+        # @yieldparam [Batch] batch The write batch object for making changes.
+        #
+        # @return [CommitResponse] The response from committing the changes.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   firestore.batch do |b|
+        #     # Set the data for NYC
+        #     b.set("cities/NYC", { name: "New York City" })
+        #
+        #     # Update the population for SF
+        #     b.update("cities/SF", { population: 1000000 })
+        #
+        #     # Delete LA
+        #     b.delete("cities/LA")
+        #   end
+        #
+        def batch
+          batch = Batch.from_client self
+          yield batch
+          batch.commit
+        end
+
+        ##
+        # Create a transaction to perform multiple reads and writes that are
+        # executed atomically at a single logical point in time in a database.
+        #
+        # All changes are accumulated in memory until the block completes.
+        # Transactions will be automatically retried when documents change
+        # before the transaction is committed. See {Transaction}.
+        #
+        # @see https://firebase.google.com/docs/firestore/manage-data/transactions
+        #   Transactions and Batched Writes
+        #
+        # @param [Integer] max_retries The maximum number of retries for
+        #   transactions failed due to errors. Default is 5. Optional.
+        #
+        # @yield [transaction] The block for reading data and making changes.
+        # @yieldparam [Transaction] transaction The transaction object for
+        #   making changes.
+        #
+        # @return [CommitResponse] The response from committing the changes.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   firestore.transaction do |tx|
+        #     # Set the data for NYC
+        #     tx.set("cities/NYC", { name: "New York City" })
+        #
+        #     # Update the population for SF
+        #     tx.update("cities/SF", { population: 1000000 })
+        #
+        #     # Delete LA
+        #     tx.delete("cities/LA")
+        #   end
+        #
+        def transaction max_retries: nil
+          max_retries = 5 unless max_retries.is_a? Integer
+          retries = 0
+          backoff = 1.0
+
+          transaction = Transaction.from_client self
+          begin
+            yield transaction
+            transaction.commit
+          rescue Google::Cloud::UnavailableError => err
+            # Re-raise if deadline has passed
+            raise err if retries >= max_retries
+            # Sleep with incremental backoff
+            sleep(backoff *= 1.3)
+            # Create new transaction and retry
+            transaction = Transaction.from_client \
+              self, previous_transaction: transaction.transaction_id
+            retries += 1
+            retry
+          rescue Google::Cloud::InvalidArgumentError => err
+            # Return if a previous call has succeeded
+            return nil if retries > 0
+            # Re-raise error.
+            raise err
+          rescue => err
+            # Rollback transaction when handling unexpected error
+            transaction.rollback rescue nil
+            # Re-raise error.
+            raise err
+          end
+        end
+
+        # @!endgroup
+
+        protected
+
+        ##
+        # @private
+        def coalesce_get_argument obj
+          if obj.is_a?(String) || obj.is_a?(Symbol)
+            if obj.to_s.split("/").count.even?
+              return doc obj # Convert a DocumentReference
+            else
+              return col obj # Convert to Query
+            end
+          end
+
+          return obj.ref if obj.is_a? DocumentSnapshot
+
+          obj
+        end
+
+        ##
+        # @private
+        def coalesce_doc_path_argument doc_path
+          return doc_path.path if doc_path.respond_to? :path
+
+          doc(doc_path).path
+        end
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          fail "Must have active connection to service" unless service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,249 @@
+# Copyright 2017 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/document_snapshot"
+require "google/cloud/firestore/query"
+require "google/cloud/firestore/generate"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # CollectionReference
+      #
+      # A collection reference object ise used for adding documents, getting
+      # document references, and querying for documents (See {Query}).
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Get a collection reference
+      #   cities_col = firestore.col "cities"
+      #
+      #   # Get and print all city documents
+      #   cities_col.get do |city|
+      #     puts "#{city.document_id} has #{city[:population]} residents."
+      #   end
+      #
+      class CollectionReference < Query
+        ##
+        # @private The firestore client object.
+        attr_accessor :client
+
+        ##
+        # The collection identifier for the collection resource.
+        #
+        # @return [String] collection identifier.
+        def collection_id
+          path.split("/").last
+        end
+
+        ##
+        # A string representing the path of the collection, relative to the
+        # document root of the database.
+        #
+        # @return [String] collection path.
+        def collection_path
+          path.split("/", 6).last
+        end
+
+        ##
+        # @private A string representing the full path of the collection
+        # resource.
+        #
+        # @return [String] collection resource path.
+        def path
+          @path
+        end
+
+        ##
+        # @private The parent path for the collection.
+        def parent_path
+          path.split("/")[0...-1].join("/")
+        end
+
+        # @!group Access
+
+        ##
+        # Retrieves a document reference.
+        #
+        # @param [String, nil] document_path A string representing the path of
+        #   the document, relative to the document root of the database. If a
+        #   string is not provided, and random document identifier will be
+        #   generated. Optional.
+        #
+        # @return [DocumentReference] A document.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document reference
+        #   nyc_ref = cities_col.doc "NYC"
+        #
+        #   # The document ID is what was provided
+        #   nyc_ref.document_id #=> "NYC"
+        #
+        # @example Create a document reference with a random ID:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document reference without specifying path
+        #   random_ref = cities_col.doc
+        #
+        #   # The document ID is randomly generated
+        #   random_ref.document_id #=> "RANDOMID123XYZ"
+        #
+        def doc document_path = nil
+          document_path ||= random_document_id
+
+          ensure_client!
+          client.doc "#{collection_path}/#{document_path}"
+        end
+        alias_method :document, :doc
+
+        ##
+        # The document reference or database the collection reference belongs
+        # to. If the collection is a root collection, it will return the
+        # database object. If the collection is nested under a document, it
+        # will return the document reference object.
+        #
+        # @return [Database, DocumentReference] parent object.
+        #
+        # @example Returns database object for root collections:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get the document's parent collection
+        #   database = cities_col.parent
+        #
+        # @example Returns document object for nested collections:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   precincts_ref = firestore.col "cities/NYC/precincts"
+        #
+        #   # Get the document's parent collection
+        #   nyc_ref = precincts_ref.parent
+        #
+        def parent
+          if collection_path.include? "/"
+            return DocumentReference.from_path parent_path, client
+          end
+          client
+        end
+
+        # @!endgroup
+
+        # @!group Modifications
+
+        ##
+        # Create a document with random document identifier.
+        #
+        # The operation will fail if the document already exists.
+        #
+        # @param [Hash] data The document's fields and values. Optional.
+        #
+        # @return [DocumentReference] A created document.
+        #
+        # @example Create a document with a random ID:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document reference without data
+        #   random_ref = cities_col.add
+        #
+        #   # The document ID is randomly generated
+        #   random_ref.document_id #=> "RANDOMID123XYZ"
+        #
+        # @example Create a document snapshot:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document snapshot
+        #   random_ref = cities_col.add({ name: "New York City" })
+        #
+        #   # The document ID is randomly generated
+        #   random_ref.document_id #=> "RANDOMID123XYZ"
+        #
+        def add data = nil
+          data ||= {}
+          doc.tap { |d| d.create data }
+        end
+
+        # @!endgroup
+
+        ##
+        # @private New Collection reference object from a path.
+        def self.from_path path, client
+          # Very important to correctly set @query on a collection object
+          query = StructuredQuery.new(
+            from: [
+              StructuredQuery::CollectionSelector.new(
+                collection_id: path.split("/").last
+              )
+            ]
+          )
+
+          new.tap do |c|
+            c.client = client
+            c.instance_variable_set :@path, path
+            c.instance_variable_set :@query, query
+          end
+        end
+
+        protected
+
+        ##
+        # @private
+        def random_document_id
+          Generate.unique_id
+        end
+
+        ##
+        # @private Raise an error unless an database available.
+        def ensure_client!
+          fail "Must have active connection to service" unless client
+        end
+      end
+    end
+  end
+end