gcloud 0.5.0 → 0.6.0

data/lib/gcloud/search/api_client.rb

@@ -0,0 +1,144 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+# 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 "gcloud/version"
+require "google/api_client"
+
+module Gcloud
+  module Search
+    ##
+    # Temporary substitute for Google::APIClient. Once the Search API is
+    # discoverable, initialization of this class in Connection should be
+    # replaced with the Google API Client.
+    class APIClient #:nodoc:
+      attr_accessor :authorization, :connection
+
+      ##
+      # Creates a new APIClient instance.
+      def initialize _options
+        @connection = Faraday.new request: {
+          params_encoder: Faraday::FlatParamsEncoder }
+      end
+
+      def discovered_api name, version
+        DiscoveredApi.new name, version
+      end
+
+      def execute options
+        api_method = options[:api_method]
+        uri = generate_search_uri api_method[:uri], options
+        run api_method[:method], uri, options
+      end
+
+      def inspect
+        "#{self.class}(#{@project})"
+      end
+
+      protected
+
+      ##
+      # Return type for APIClient#discovered_api
+      class DiscoveredApi #:nodoc:
+        def initialize name, version
+          @name = name
+          @version = version
+        end
+
+        def indexes
+          IndexResourcePath.new @name, @version, "indexes", "indexId"
+        end
+
+        def documents
+          ResourcePath.new @name,
+                           @version,
+                           "indexes/{indexId}/documents",
+                           "docId"
+        end
+      end
+
+      ##
+      # Return type for DiscoveredApi http verb methods
+      class ResourcePath #:nodoc:
+        def initialize api_name, api_version, resource_root, resource_id_param
+          @root = "https://#{api_name}.googleapis.com/#{api_version}" \
+                  "/projects/{projectId}/#{resource_root}"
+          @resource_id_param = resource_id_param
+        end
+
+        def create
+          api_method :post
+        end
+
+        def delete
+          api_method :delete, "/{docId}"
+        end
+
+        def get
+          api_method :get, "/{docId}"
+        end
+
+        def list
+          api_method :get
+        end
+
+        def api_method method, path = nil
+          { method: method, uri: "#{@root}#{path}" }
+        end
+      end
+
+      ##
+      # Special-case return type for DiscoveredApi http search verb method
+      class IndexResourcePath < ResourcePath #:nodoc:
+        def search
+          api_method :get, "/{indexId}/search"
+        end
+      end
+
+      def run method, uri, options = {}
+        fix_serialization! options
+        if authorization.nil?
+          @connection.send method do |req|
+            req.url uri
+            req.params = options[:parameters] if options[:parameters]
+            req.body = options[:body] if options[:body]
+          end
+        else
+          options[:method] = method
+          options[:uri] = uri
+          options[:connection] = @connection
+          authorization.fetch_protected_resource options
+        end
+      end
+
+      def generate_search_uri uri, options = {}
+        params = options.delete :parameters
+        [:projectId, :indexId, :docId].each do |param|
+          uri.gsub! "{#{param}}", params.delete(param) if params[param]
+        end
+        uri = URI uri
+        unless params.empty?
+          uri.query = Faraday::FlatParamsEncoder.encode params
+        end
+        uri.to_s
+      end
+
+      def fix_serialization! options
+        return unless options[:body_object]
+        options[:headers] = { "Content-Type" => "application/json" }
+        options[:body] = options.delete(:body_object).to_json
+      end
+    end
+  end
+end

data/lib/gcloud/search/connection.rb

@@ -0,0 +1,146 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+# 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 "gcloud/version"
+require "gcloud/search/api_client"
+
+module Gcloud
+  module Search
+    ##
+    # Represents the connection to Search,
+    # as well as expose the API calls.
+    class Connection #:nodoc:
+      API_VERSION = "v1"
+
+      attr_accessor :project
+      attr_accessor :credentials #:nodoc:
+      attr_accessor :client #:nodoc:
+      attr_accessor :connection #:nodoc:
+
+      ##
+      # Creates a new Connection instance.
+      def initialize project, credentials #:nodoc:
+        @project = project
+        @credentials = credentials
+        client_config = {
+          application_name: "gcloud-ruby",
+          application_version: Gcloud::VERSION
+        }
+        @client = Gcloud::Search::APIClient.new client_config
+        @client.authorization = @credentials.client
+        @search = @client.discovered_api "cloudsearch", API_VERSION
+      end
+
+      def list_indexes options = {}
+        params = { projectId: @project,
+                   indexNamePrefix: options[:prefix],
+                   view: (options[:view] || "FULL"),
+                   pageSize: options[:max],
+                   pageToken: options[:token]
+        }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @search.indexes.list,
+          parameters: params
+        )
+      end
+
+      def delete_index index_id
+        @client.execute(
+          api_method: @search.indexes.delete,
+          parameters: { projectId: @project,
+                        indexId: index_id }
+        )
+      end
+
+      def get_doc index_id, doc_id
+        @client.execute(
+          api_method: @search.documents.get,
+          parameters: { projectId: @project,
+                        indexId: index_id,
+                        docId: doc_id }
+        )
+      end
+
+      def list_docs index_id, options = {}
+        params = { projectId: @project,
+                   indexId: index_id,
+                   view: (options[:view] || "FULL"),
+                   pageSize: options[:max],
+                   pageToken: options[:token]
+                 }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @search.documents.list,
+          parameters: params
+        )
+      end
+
+      def create_doc index_id, document_hash
+        @client.execute(
+          api_method: @search.documents.create,
+          parameters: { projectId: @project,
+                        indexId: index_id },
+          body_object: document_hash
+        )
+      end
+
+      def delete_doc index_id, doc_id
+        @client.execute(
+          api_method: @search.documents.delete,
+          parameters: { projectId: @project,
+                        indexId: index_id,
+                        docId: doc_id }
+        )
+      end
+
+      def search index_id, query, options = {}
+        # Always encode expression hashes as JSON strings
+        if options[:expressions]
+          # Force to an array of hashes, this works with an array or a hash
+          tmp = [options[:expressions]].flatten.map { |ex| JSON.dump ex }
+          options[:expressions] = tmp
+        end
+
+        @client.execute(
+          api_method: @search.indexes.search,
+          parameters: search_request(index_id, query, options)
+        )
+      end
+
+      def inspect #:nodoc:
+        "#{self.class}(#{@project})"
+      end
+
+      protected
+
+      def search_request index_id, query, options = {}
+        { projectId: @project,
+          indexId: index_id,
+          query: query,
+          fieldExpressions: options[:expressions],
+          matchedCountAccuracy: options[:matched_count_accuracy],
+          offset: options[:offset],
+          orderBy: options[:order],
+          pageSize: options[:max],
+          pageToken: options[:token],
+          returnFields: options[:fields],
+          scorerSize: options[:scorer_size],
+          scorer: options[:scorer]
+        }.delete_if { |_, v| v.nil? }
+      end
+    end
+  end
+end

data/lib/gcloud/search/credentials.rb

@@ -0,0 +1,30 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+# 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 "gcloud/credentials"
+
+module Gcloud
+  module Search
+    ##
+    # Represents the Oauth2 signing logic for Search.
+    class Credentials < Gcloud::Credentials #:nodoc:
+      SCOPE = ["https://www.googleapis.com/auth/cloudsearch",
+               "https://www.googleapis.com/auth/userinfo.email"]
+      PATH_ENV_VARS = %w(SEARCH_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
+      JSON_ENV_VARS = %w(SEARCH_KEYFILE_JSON GCLOUD_KEYFILE_JSON
+                         GOOGLE_CLOUD_KEYFILE_JSON)
+    end
+  end
+end

data/lib/gcloud/search/document.rb

@@ -0,0 +1,301 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+# 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 "gcloud/search/document/list"
+require "gcloud/search/connection"
+require "gcloud/search/fields"
+
+module Gcloud
+  module Search
+    ##
+    # = Document
+    #
+    # A document is an object that stores data that can be searched. Each
+    # document has a #doc_id that is
+    # unique within its index, a #rank, and a list of #fields that contain typed
+    # data. Its field values can be accessed through hash-like methods such as
+    # #[] and #each.
+    #
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   search = gcloud.search
+    #   index = search.index "products"
+    #
+    #   document = index.document "product-sku-000001"
+    #   document.add "price", 24.95
+    #   index.save document
+    #   document.rank #=> 1443648166
+    #   document["price"] #=> 24.95
+    #
+    # For more information, see {Documents and
+    # Indexes}[https://cloud.google.com/search/documents_indexes].
+    #
+    class Document
+      ##
+      # Creates a new Document instance.
+      #
+      def initialize #:nodoc:
+        @fields = Fields.new
+        @raw = {}
+      end
+
+      ##
+      # The unique identifier for the document. Can be set explicitly when the
+      # document is saved. (See Index#document and #doc_id= .) If missing, it is
+      # automatically assigned to the document when saved.
+      def doc_id
+        @raw["docId"]
+      end
+
+      ##
+      # Sets the unique identifier for the document.
+      #
+      # Must contain only visible, printable ASCII characters (ASCII codes 33
+      # through 126 inclusive) and be no longer than 500 characters. It cannot
+      # begin with an exclamation point (<code>!</code>), and it cannot begin
+      # and end with double underscores (<code>__</code>).
+      def doc_id= new_doc_id
+        @raw["docId"] = new_doc_id
+      end
+
+      ##
+      # A positive integer which determines the default ordering of documents
+      # returned from a search. The rank can be set explicitly when the document
+      # is saved. (See Index#document and #rank= .)  If missing, it is
+      # automatically assigned to the document when saved.
+      def rank
+        @raw["rank"]
+      end
+
+      ##
+      # Sets the rank of the document.
+      #
+      # The same rank should not be assigned to many documents, and should
+      # never be assigned to more than 10,000 documents. By default (when it is
+      # not specified or set to 0), it is set at the time the document is
+      # created to the number of seconds since January 1, 2011. The rank can be
+      # used in Index#search options +expressions+, +order+, and
+      # +fields+, where it is referenced as +rank+.
+      def rank= new_rank
+        @raw["rank"] = new_rank
+      end
+
+      ##
+      # Retrieve the field values associated to a field name.
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. New values will be configured with this name.
+      #   (+String+)
+      #
+      # === Returns
+      #
+      # FieldValues
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   puts "The document description is:"
+      #   document["description"].each do |value|
+      #     puts "* #{value} (#{value.type}) [#{value.lang}]"
+      #   end
+      #
+      def [] name
+        @fields[name]
+      end
+
+      # rubocop:disable Style/TrivialAccessors
+      # Disable rubocop because we want .fields to be listed with the other
+      # methods on the class.
+
+      ##
+      # The fields in the document. Each field has a name (String) and a list of
+      # values (FieldValues). (See Fields)
+      def fields
+        @fields
+      end
+
+      # rubocop:enable Style/TrivialAccessors
+
+      # rubocop:disable Metrics/LineLength
+      # Disabled because there are links in the docs that are long.
+
+      ##
+      # Add a new value. If the field name does not exist it will be added. If
+      # the field value is a DateTime or Numeric, or the type is set to
+      # +:datetime+ or +:number+, then the added value will replace any existing
+      # values of the same type (since there can be only one). (See Fields#add)
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. (+String+)
+      # +value+::
+      #   The value to add to the field. (+String+ or +Datetime+ or +Float+)
+      # +type+::
+      #   The type of the field value. An attempt is made to set the correct
+      #   type when this option is missing, although it must be provided for
+      #   +:geo+ values. A field can have multiple values with same or different
+      #   types; however, it cannot have multiple +:datetime+ or +:number+
+      #   values. (+Symbol+)
+      #
+      #   The following values are supported:
+      #   * +:default+ - The value is a string. The format will be automatically
+      #     detected. This is the default value for strings.
+      #   * +:text+ - The value is a string with maximum length 1024**2
+      #     characters.
+      #   * +:html+ - The value is an HTML-formatted string with maximum length
+      #     1024**2 characters.
+      #   * +:atom+ - The value is a string with maximum length 500 characters.
+      #   * +:geo+ - The value is a point on earth described by latitude and
+      #     longitude coordinates, represented in string with any of the listed
+      #     {ways of writing
+      #     coordinates}[http://en.wikipedia.org/wiki/Geographic_coordinate_conversion].
+      #   * +:datetime+ - The value is a +DateTime+.
+      #   * +:number+ - The value is a +Numeric+ between -2,147,483,647 and
+      #     2,147,483,647. The value will be stored as a double precision
+      #     floating point value in Cloud Search.
+      # +lang+::
+      #   The language of a string value. Must be a valid {ISO 639-1
+      #   code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
+      #   (+String+)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document.add "sku", "product-sku-000001", type: :atom
+      #   document.add "description", "The best T-shirt ever.",
+      #                type: :text, lang: "en"
+      #   document.add "description", "<p>The best T-shirt ever.</p>",
+      #                type: :html, lang: "en"
+      #   document.add "price", 24.95
+      #
+      def add name, value, type: nil, lang: nil
+        @fields[name].add value, type: type, lang: lang
+      end
+
+      # rubocop:enable Metrics/LineLength
+
+      ##
+      # Deletes a field and all values. (See Fields#delete)
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. (+String+)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document.delete "description"
+      #
+      def delete name, &block
+        @fields.delete name, &block
+      end
+
+      ##
+      # Calls block once for each field, passing the field name and values pair
+      # as parameters. If no block is given an enumerator is returned instead.
+      # (See Fields#each)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   puts "The document #{document.doc_id} has the following fields:"
+      #   document.each do |name, values|
+      #     puts "* #{name}:"
+      #     values.each do |value|
+      #       puts "  * #{value} (#{value.type})"
+      #     end
+      #   end
+      #
+      def each &block
+        @fields.each(&block)
+      end
+
+      ##
+      # Returns a new array populated with all the field names.
+      # (See Fields#names)
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   puts "The document #{document.doc_id} has the following fields:"
+      #   document.names.each do |name|
+      #     puts "* #{name}:"
+      #   end
+      #
+      def names
+        @fields.names
+      end
+
+      ##
+      # Override to keep working in interactive shells manageable.
+      def inspect #:nodoc:
+        insp_rank = ""
+        insp_rank = ", rank: #{rank}" if rank
+        insp_fields = ", fields: (#{fields.names.map(&:inspect).join ', '})"
+        "#{self.class}(doc_id: #{doc_id.inspect}#{insp_rank}#{insp_fields})"
+      end
+
+      ##
+      # New Document from a raw data object.
+      def self.from_hash hash #:nodoc:
+        doc = new
+        doc.instance_variable_set "@raw", hash
+        doc.instance_variable_set "@fields", Fields.from_raw(hash["fields"])
+        doc
+      end
+
+      ##
+      # Returns the Document data as a hash
+      def to_hash #:nodoc:
+        hash = @raw.dup
+        hash["fields"] = @fields.to_raw
+        hash
+      end
+    end
+  end
+end