gcloud 0.5.0 → 0.6.0

data/lib/gcloud/search/result/list.rb

@@ -0,0 +1,95 @@
+#--
+# 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.
+
+module Gcloud
+  module Search
+    class Result
+      ##
+      # Result::List is a special case Array with additional values.
+      class List < DelegateClass(::Array)
+        ##
+        # If not empty, indicates that there are more records that match
+        # the request and this value should be passed to continue.
+        attr_reader :token
+
+        ##
+        # The number of documents that match the query. It is greater than or
+        # equal to the number of documents actually returned. This is an
+        # approximation and not an exact count unless it is less than or equal
+        # to the Index#search +matched_count_accuracy+ option.
+        attr_reader :matched_count
+
+        ##
+        # Create a new Result::List with an array of Result instances.
+        def initialize arr = []
+          super arr
+        end
+
+        ##
+        # Whether there a next page of results.
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of results.
+        def next
+          return nil unless next?
+          ensure_index!
+          @index.search @query, @search_options.merge(token: token)
+        end
+
+        ##
+        # Retrieves all results by repeatedly loading pages until #next?
+        # returns false. Returns the list instance for method chaining.
+        def all
+          while next?
+            next_results = self.next
+            push(*next_results)
+            self.token = next_results.token
+          end
+          self
+        end
+
+        ##
+        # New Result::List from a response object.
+        def self.from_response resp, index, query, search_options #:nodoc:
+          data = JSON.parse resp.body
+          results = new(Array(data["results"]).map do |raw|
+            Result.from_hash raw
+          end)
+          results.instance_eval do
+            @token = data["results"].last["nextPageToken"]
+            @matched_count = data["matchedCount"]
+            @index = index
+            @query = query
+            @search_options = search_options
+          end
+          results
+        rescue JSON::ParserError
+          ApiError.from_response_status resp
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active connection is available.
+        def ensure_index!
+          fail "Must have active connection" unless @index
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/storage.rb

@@ -31,9 +31,7 @@ module Gcloud
   # +keyfile+::
   #   Keyfile downloaded from Google Cloud. If file path the file must be
   #   readable. (+String+ or +Hash+)
-  # +options+::
-  #   An optional Hash for controlling additional behavior. (+Hash+)
-  # <code>options[:scope]</code>::
+  # +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
   #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
@@ -57,12 +55,12 @@ module Gcloud
   #   bucket = storage.bucket "my-bucket"
   #   file = bucket.file "path/to/my-file.ext"
   #
-  def self.storage project = nil, keyfile = nil, options = {}
+  def self.storage project = nil, keyfile = nil, scope: nil
     project ||= Gcloud::Storage::Project.default_project
     if keyfile.nil?
-      credentials = Gcloud::Storage::Credentials.default options
+      credentials = Gcloud::Storage::Credentials.default scope: scope
     else
-      credentials = Gcloud::Storage::Credentials.new keyfile, options
+      credentials = Gcloud::Storage::Credentials.new keyfile, scope: scope
     end
     Gcloud::Storage::Project.new project, credentials
   end

data/lib/gcloud/storage/bucket.rb

@@ -304,9 +304,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:retries]</code>::
+      # +retries+::
       #   The number of times the API call should be retried.
       #   Default is Gcloud::Backoff.retries. (+Integer+)
       #
@@ -336,8 +334,9 @@ module Gcloud
       #   bucket = storage.bucket "my-bucket"
       #   bucket.delete retries: 5
       #
-      def delete options = {}
+      def delete retries: nil
         ensure_connection!
+        options = { retries: retries }
         resp = connection.delete_bucket name, options
         if resp.success?
           true
@@ -351,26 +350,22 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:prefix]</code>::
+      # +prefix+::
       #   Filter results to files whose names begin with this prefix.
       #   (+String+)
-      # <code>options[:token]</code>::
+      # +token+::
       #   A previously-returned page token representing part of the larger set
       #   of results to view. (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of items plus prefixes to return. As duplicate prefixes
       #   are omitted, fewer total results may be returned than requested.
       #   The default value of this parameter is 1,000 items. (+Integer+)
-      # <code>options[:versions]</code>::
+      # +versions+::
       #   If +true+, lists all versions of an object as distinct results.
       #   The default is +false+. For more information, see
       #   {Object Versioning
       #   }[https://cloud.google.com/storage/docs/object-versioning].
       #   (+Boolean+)
-      # <code>options[:max]</code>::
-      #   Maximum number of buckets to return. (+Integer+)
       #
       # === Returns
       #
@@ -411,8 +406,9 @@ module Gcloud
       #     tmp_files = bucket.files token: tmp_files.token
       #   end
       #
-      def files options = {}
+      def files prefix: nil, token: nil, max: nil, versions: nil
         ensure_connection!
+        options = { prefix: prefix, token: token, max: max, versions: versions }
         resp = connection.list_files name, options
         if resp.success?
           File::List.from_response resp, connection
@@ -429,6 +425,9 @@ module Gcloud
       #
       # +path+::
       #   Name (path) of the file. (+String+)
+      # +generation+::
+      #   When present, selects a specific revision of this object.
+      #   Default is the latest version. (+Integer+)
       #
       # === Returns
       #
@@ -446,8 +445,9 @@ module Gcloud
       #   file = bucket.file "path/to/my-file.ext"
       #   puts file.name
       #
-      def file path, options = {}
+      def file path, generation: nil
         ensure_connection!
+        options = { generation: generation }
         resp = connection.get_file name, path, options
         if resp.success?
           File.from_gapi resp.data, connection
@@ -467,9 +467,7 @@ module Gcloud
       #   Path of the file on the filesystem to upload. (+String+)
       # +path+::
       #   Path to store the file in Google Cloud Storage. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:acl]</code>::
+      # +acl+::
       #   A predefined set of access controls to apply to this file.
       #   (+String+)
       #
@@ -486,40 +484,40 @@ module Gcloud
       #     and project team members get access according to their roles.
       #   * +public+, +public_read+, +publicRead+ - File owner gets OWNER
       #     access, and allUsers get READER access.
-      # <code>options[:cache_control]</code>::
+      # +cache_control+::
       #   The {Cache-Control}[https://tools.ietf.org/html/rfc7234#section-5.2]
       #   response header to be returned when the file is downloaded. (+String+)
-      # <code>options[:content_disposition]</code>::
+      # +content_disposition+::
       #   The {Content-Disposition}[https://tools.ietf.org/html/rfc6266]
       #   response header to be returned when the file is downloaded. (+String+)
-      # <code>options[:content_encoding]</code>::
+      # +content_encoding+::
       #   The {Content-Encoding
       #   }[https://tools.ietf.org/html/rfc7231#section-3.1.2.2] response header
       #   to be returned when the file is downloaded. (+String+)
-      # <code>options[:content_language]</code>::
+      # +content_language+::
       #   The {Content-Language}[http://tools.ietf.org/html/bcp47] response
       #   header to be returned when the file is downloaded. (+String+)
-      # <code>options[:content_type]</code>::
+      # +content_type+::
       #   The {Content-Type}[https://tools.ietf.org/html/rfc2616#section-14.17]
       #   response header to be returned when the file is downloaded. (+String+)
-      # <code>options[:chunk_size]</code>::
+      # +chunk_size+::
       #   The number of bytes per chunk in a resumable upload. Must be divisible
       #   by 256KB. If it is not divisible by 265KB then it will be lowered to
       #   the nearest acceptable value. (+Integer+)
-      # <code>options[:crc32c]</code>::
+      # +crc32c+::
       #   The CRC32c checksum of the file data, as described in
       #   {RFC 4960, Appendix B}[http://tools.ietf.org/html/rfc4960#appendix-B].
       #   If provided, Cloud Storage will only create the file if the value
       #   matches the value calculated by the service. See
       #   {Validation}[https://cloud.google.com/storage/docs/hashes-etags]
       #   for more information. (+String+)
-      # <code>options[:md5]</code>::
+      # +md5+::
       #   The MD5 hash of the file data. If provided, Cloud Storage will only
       #   create the file if the value matches the value calculated by the
       #   service. See
       #   {Validation}[https://cloud.google.com/storage/docs/hashes-etags]
       #   for more information. (+String+)
-      # <code>options[:metadata]</code>::
+      # +metadata+::
       #   A hash of custom, user-provided web-safe keys and arbitrary string
       #   values that will returned with requests for the file as "x-goog-meta-"
       #   response headers. (+Hash+)
@@ -551,7 +549,7 @@ module Gcloud
       #   bucket.create_file "path/to/local.file.ext",
       #                      "destination/path/file.ext"
       #
-      # A chunk_size value can be provided in the options to be used
+      # A +chunk_size+ value can be provided in the options to be used
       # in resumable uploads. This value is the number of bytes per
       # chunk and must be divisible by 256KB. If it is not divisible
       # by 265KB then it will be lowered to the nearest acceptable
@@ -568,17 +566,27 @@ module Gcloud
       #                      "destination/path/file.ext",
       #                      chunk_size: 1024*1024 # 1 MB chunk
       #
-      # ==== A note about large uploads
+      # ==== Troubleshooting large uploads
       #
-      # You may encounter a Broken pipe (Errno::EPIPE) error when attempting to
-      # upload large files. To avoid this problem, add the
+      # You may encounter errors while attempting to upload large files. Below
+      # are a couple of common cases and their solutions.
+      #
+      # ===== Handling memory errors
+      #
+      # If you encounter a memory error such as +NoMemoryError+, try performing
+      # a resumable upload and setting the +chunk_size+ option to a value that
+      # works for your environment, as explained in the final example above.
+      #
+      # ===== Handling broken pipe errors
+      #
+      # To avoid broken pipe (+Errno::EPIPE+) errors when uploading, add the
       # {httpclient}[https://rubygems.org/gems/httpclient] gem to your project,
-      # and the line (or lines) of configuration shown below. These lines must
-      # execute after you require gcloud but before you make your first gcloud
-      # connection. The first statement configures
-      # {Faraday}[https://rubygems.org/gems/faraday] to use httpclient. The
-      # second statement, which should only be added if you are using a version
-      # of Faraday at or above 0.9.2, is a workaround for {this gzip
+      # and the configuration shown below. These lines must execute after you
+      # require gcloud but before you make your first gcloud connection. The
+      # first statement configures {Faraday}[https://rubygems.org/gems/faraday]
+      # to use httpclient. The second statement, which should only be added if
+      # you are using a version of Faraday at or above 0.9.2, is a workaround
+      # for {this gzip
       # issue}[https://github.com/GoogleCloudPlatform/gcloud-ruby/issues/367].
       #
       #   require "gcloud"
@@ -594,18 +602,22 @@ module Gcloud
       #   gcloud = Gcloud.new
       #   storage = gcloud.storage
       #
-      def create_file file, path = nil, options = {}
+      def create_file file, path = nil, acl: nil, cache_control: nil,
+                      content_disposition: nil, content_encoding: nil,
+                      content_language: nil, content_type: nil, chunk_size: nil,
+                      crc32c: nil, md5: nil, metadata: nil
         ensure_connection!
+        options = { acl: File::Acl.predefined_rule_for(acl), md5: md5,
+                    cache_control: cache_control, content_type: content_type,
+                    content_disposition: content_disposition, crc32c: crc32c,
+                    content_encoding: content_encoding, chunk_size: chunk_size,
+                    content_language: content_language, metadata: metadata }
         ensure_file_exists! file
-        options[:acl] = File::Acl.predefined_rule_for options[:acl]
         resumable = resumable_upload?(file)
         resp = @connection.upload_file resumable, name, file, path, options
 
-        if resp.success?
-          File.from_gapi resp.data, connection
-        else
-          fail ApiError.from_response(resp)
-        end
+        return File.from_gapi(resp.data, connection) if resp.success?
+        fail ApiError.from_response(resp)
       end
       alias_method :upload_file, :create_file
       alias_method :new_file, :create_file

data/lib/gcloud/storage/bucket/cors.rb

@@ -75,14 +75,12 @@ module Gcloud
         #   The list of HTTP methods permitted in cross origin resource sharing
         #   with the bucket. (GET, OPTIONS, POST, etc) Note: "*" is permitted in
         #   the list of methods, and means "any method". (+String+ or +Array+)
-        # +options+::
-        #   An optional Hash for controlling additional behavior. (+Hash+)
-        # <code>options[:headers]</code>::
+        # +headers+::
         #   The list of header field names to send in the
         #   Access-Control-Allow-Headers header in the preflight response.
         #   Indicates the custom request headers that may be used in the actual
         #   request. (+String+ or +Array+)
-        # <code>options[:max_age]</code>::
+        # +max_age+::
         #   The value to send in the Access-Control-Max-Age header in the
         #   preflight response. Indicates how many seconds the results of a
         #   preflight request can be cached in a preflight result cache. The
@@ -102,10 +100,10 @@ module Gcloud
         #                max_age: 300
         #   end
         #
-        def add_rule origin, methods, options = {}
+        def add_rule origin, methods, headers: nil, max_age: nil
           rule = { "origin" => Array(origin), "method" => Array(methods) }
-          rule["responseHeader"] = Array(options[:headers]) || []
-          rule["maxAgeSeconds"] = options[:max_age] || 1800
+          rule["responseHeader"] = Array(headers) || []
+          rule["maxAgeSeconds"]  = max_age || 1800
           push rule
         end
       end

data/lib/gcloud/storage/file.rb

@@ -284,9 +284,7 @@ module Gcloud
       # +path+::
       #   The path on the local file system to write the data to.
       #   The path provided must be writable. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:verify]</code>::
+      # +verify+::
       #   The verification algoruthm used to ensure the downloaded file contents
       #   are correct. Default is +:md5+. (+Symbol+)
       #
@@ -349,14 +347,14 @@ module Gcloud
       #   file = bucket.file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :none
       #
-      def download path, options = {}
+      def download path, verify: :md5
         ensure_connection!
         resp = connection.download_file bucket, name
         if resp.success?
           ::File.open path, "wb+" do |f|
             f.write resp.body
           end
-          verify_file! ::File.new(path), options
+          verify_file! ::File.new(path), verify
         else
           fail ApiError.from_response(resp)
         end
@@ -373,12 +371,7 @@ module Gcloud
       # +dest_path+::
       #   If a bucket was provided in the first parameter, this contains the
       #   path to copy the file to in the given bucket. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:generation]</code>::
-      #   Select a specific revision of the file to copy. The default is the
-      #   latest version. (+Integer+)
-      # <code>options[:acl]</code>::
+      # +acl+::
       #   A predefined set of access controls to apply to new file.
       #   (+String+)
       #
@@ -395,6 +388,9 @@ module Gcloud
       #     and project team members get access according to their roles.
       #   * +public+, +public_read+, +publicRead+ - File owner gets OWNER
       #     access, and allUsers get READER access.
+      # +generation+::
+      #   Select a specific revision of the file to copy. The default is the
+      #   latest version. (+Integer+)
       #
       # === Returns
       #
@@ -432,8 +428,9 @@ module Gcloud
       #   file.copy "copy/of/previous/generation/file.ext",
       #             generation: 123456
       #
-      def copy dest_bucket_or_path, dest_path = nil, options = {}
+      def copy dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil
         ensure_connection!
+        options = { acl: acl, generation: generation }
         dest_bucket, dest_path, options = fix_copy_args dest_bucket_or_path,
                                                         dest_path, options
 
@@ -485,9 +482,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:protocol]</code>::
+      # +protocol+::
       #   The protocol to use for the URL. Default is +HTTPS+. (+String+)
       #
       # === Examples
@@ -513,8 +508,7 @@ module Gcloud
       #   file = bucket.file "avatars/heidi/400x400.png"
       #   public_url = file.public_url protocol: "http"
       #
-      def public_url options = {}
-        protocol = options[:protocol] || :https
+      def public_url protocol: :https
         "#{protocol}://storage.googleapis.com/#{bucket}/#{name}"
       end
       alias_method :url, :public_url
@@ -537,25 +531,27 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:method]</code>::
+      # +method+::
       #   The HTTP verb to be used with the signed URL. Signed URLs can be used
       #   with +GET+, +HEAD+, +PUT+, and +DELETE+ requests. Default is +GET+.
       #   (+String+)
-      # <code>options[:expires]</code>::
+      # +expires+::
       #   The number of seconds until the URL expires. Default is 300/5 minutes.
       #   (+Integer+)
-      # <code>options[:content_type]</code>::
+      # +content_type+::
       #   When provided, the client (browser) must send this value in the
       #   HTTP header. e.g. +text/plain+ (+String+)
-      # <code>options[:content_md5]</code>::
+      # +content_md5+::
       #   The MD5 digest value in base64. If you provide this in the string, the
       #   client (usually a browser) must provide this HTTP header with this
       #   same value in its request. (+String+)
-      # <code>options[:issuer]</code>::
+      # +issuer+::
       #   Service Account's Client Email. (+String+)
-      # <code>options[:signing_key]</code>::
+      # +client_email+::
+      #   Service Account's Client Email. (+String+)
+      # +signing_key+::
+      #   Service Account's Private Key. (+OpenSSL::PKey::RSA+ or +String+)
+      # +private_key+::
       #   Service Account's Private Key. (+OpenSSL::PKey::RSA+ or +String+)
       #
       # === Examples
@@ -598,8 +594,14 @@ module Gcloud
       #   shared_url = file.signed_url issuer: "service-account@gcloud.com",
       #                                signing_key: key
       #
-      def signed_url options = {}
+      def signed_url method: nil, expires: nil, content_type: nil,
+                     content_md5: nil, issuer: nil, client_email: nil,
+                     signing_key: nil, private_key: nil
         ensure_connection!
+        options = { method: method, expires: expires,
+                    content_type: content_type, content_md5: content_md5,
+                    issuer: issuer, client_email: client_email,
+                    signing_key: signing_key, private_key: private_key }
         signer = File::Signer.new self
         signer.signed_url options
       end
@@ -710,16 +712,19 @@ module Gcloud
 
       def fix_copy_args dest_bucket, dest_path, options = {}
         if dest_path.respond_to?(:to_hash) && options.empty?
-          options, dest_path = dest_path, nil
+          options = dest_path
+          dest_path = nil
+        end
+        if dest_path.nil?
+          dest_path = dest_bucket
+          dest_bucket = bucket
         end
-        dest_path, dest_bucket = dest_bucket, bucket if dest_path.nil?
         dest_bucket = dest_bucket.name if dest_bucket.respond_to? :name
         options[:acl] = File::Acl.predefined_rule_for options[:acl]
         [dest_bucket, dest_path, options]
       end
 
-      def verify_file! file, options = {}
-        verify = options[:verify] || :md5
+      def verify_file! file, verify = :md5
         verify_md5    = verify == :md5    || verify == :all
         verify_crc32c = verify == :crc32c || verify == :all
         Verifier.verify_md5! self, file    if verify_md5