google-cloud-storage 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e64f8e7e313f4c8f5dc1bd0229e04436c7594281
-  data.tar.gz: 96638f6c5921a7be66cffac75e36d88abbee9337
+  metadata.gz: 4450abcfeebceca2abde8444b448c4361cd66bba
+  data.tar.gz: 9f9d2b7ec0dfcece945d361f3cc9828b8560d189
 SHA512:
-  metadata.gz: 984d4b6c132149b11cf697b341d5b6e88cb2e7d729597c2e2e93af21801771ac3486da2aa620b007e605bc1dca397a5b3ed2f9af999953d5bdd3d1679b08b1cd
-  data.tar.gz: 2cc2fbcaf2be7e8a5381f0791211a44cc6655428786c45dd4076833b10712313f7ee81e693073a9d0e0caf5e268e128557c130e79360f48fb3f8b1f2e6e8b62d
+  metadata.gz: 21241923c3f1b341eb21f495ae3e747ee2508df599c7ac1cf27ecccab85960eda2e7cdac878580d6def3343d551ff9de48cba5b2bda3fb73374be9eb77ada937
+  data.tar.gz: a685308ed10e4cece3b05d15c48c9a4f1c04bdba60587332db912646b9fd998e1e4c479f158472ac07a0b4079dc8bbe6c843880fef959f3000d17ee9d078fc85

data/README.md

@@ -2,7 +2,7 @@
 
 [Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/storage/docs/json_api/)) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.
 
-- [google-cloud-storage API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-storage/master/google/cloud/storage)
+- [google-cloud-storage API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-storage/latest)
 - [google-cloud-storage on RubyGems](https://rubygems.org/gems/google-cloud-storage)
 - [Google Cloud Storage documentation](https://cloud.google.com/storage/docs)
 

data/lib/google/cloud/storage.rb

@@ -55,11 +55,14 @@ module Google
     #
     # ## Retrieving Buckets
     #
-    # A Bucket is the container for your data. There is no limit on the number
-    # of buckets that you can create in a project. You can use buckets to
-    # organize and control access to your data. Each bucket has a unique name,
-    # which is how they are retrieved: (See
-    # {Google::Cloud::Storage::Project#bucket})
+    # A {Google::Cloud::Storage::Bucket} instance is a container for your data.
+    # There is no limit on the number of buckets that you can create in a
+    # project. You can use buckets to organize and control access to your data.
+    # For more information, see [Working with
+    # Buckets](https://cloud.google.com/storage/docs/creating-buckets).
+    #
+    # Each bucket has a globally unique name, which is how they are retrieved:
+    # (See {Google::Cloud::Storage::Project#bucket})
     #
     # ```ruby
     # require "google/cloud/storage"
@@ -80,27 +83,38 @@ module Google
     # all_buckets = storage.buckets
     # ```
     #
-    # If you have a significant number of buckets, you may need to paginate
-    # through them: (See {Google::Cloud::Storage::Bucket::List#token})
+    # If you have a significant number of buckets, you may need to fetch them
+    # in multiple service requests.
+    #
+    # Iterating over each bucket, potentially with multiple API calls, by
+    # invoking `all` with a block:
+    #
+    # ```ruby
+    # require "google/cloud/storage"
+    #
+    # storage = Google::Cloud::Storage.new
+    #
+    # buckets = storage.buckets
+    # buckets.all do |bucket|
+    #   puts bucket.name
+    # end
+    # ```
+    #
+    # Limiting the number of API calls made:
     #
     # ```ruby
     # require "google/cloud/storage"
     #
     # storage = Google::Cloud::Storage.new
     #
-    # all_buckets = []
-    # tmp_buckets = storage.buckets
-    # while tmp_buckets.any? do
-    #   tmp_buckets.each do |bucket|
-    #     all_buckets << bucket
-    #   end
-    #   # break loop if no more buckets available
-    #   break if tmp_buckets.token.nil?
-    #   # get the next group of buckets
-    #   tmp_buckets = storage.buckets token: tmp_buckets.token
+    # buckets = storage.buckets
+    # buckets.all(request_limit: 10) do |bucket|
+    #   puts bucket.name
     # end
     # ```
     #
+    # See {Google::Cloud::Storage::Bucket::List} for details.
+    #
     # ## Creating a Bucket
     #
     # A unique name is all that is needed to create a new bucket: (See
@@ -116,10 +130,12 @@ module Google
     #
     # ## Retrieving Files
     #
-    # A File is an individual pieces of data that you store in Google Cloud
-    # Storage. Files contain the data stored as well as metadata describing the
-    # data. Files belong to a bucket and cannot be shared among buckets. There
-    # is no limit on the number of objects that you can create in a bucket.
+    # A {Google::Cloud::Storage::File} instance is an individual data object
+    # that you store in Google Cloud Storage. Files contain the data stored as
+    # well as metadata describing the data. Files belong to a bucket and cannot
+    # be shared among buckets. There is no limit on the number of files that
+    # you can create in a bucket. For more information, see [Working with
+    # Objects](https://cloud.google.com/storage/docs/object-basics).
     #
     # Files are retrieved by their name, which is the path of the file in the
     # bucket: (See {Google::Cloud::Storage::Bucket#file})
@@ -155,32 +171,42 @@ module Google
     # avatar_files = bucket.files prefix: "avatars/"
     # ```
     #
-    # If you have a significant number of files, you may need to paginate
-    # through them: (See {Google::Cloud::Storage::File::List#token})
+    # If you have a significant number of files, you may need to fetch them
+    # in multiple service requests.
+    #
+    # Iterating over each file, potentially with multiple API calls, by
+    # invoking `all` with a block:
     #
     # ```ruby
     # require "google/cloud/storage"
     #
     # storage = Google::Cloud::Storage.new
-    #
     # bucket = storage.bucket "my-todo-app"
     #
-    # all_files = []
-    # tmp_files = bucket.files
-    # while tmp_files.any? do
-    #   tmp_files.each do |file|
-    #     all_files << file
-    #   end
-    #   # break loop if no more files available
-    #   break if tmp_files.token.nil?
-    #   # get the next group of files
-    #   tmp_files = bucket.files token: tmp_files.token
+    # files = storage.files
+    # files.all do |file|
+    #   puts file.name
     # end
     # ```
     #
+    # Limiting the number of API calls made:
+    #
+    # ```ruby
+    # require "google/cloud/storage"
+    #
+    # storage = Google::Cloud::Storage.new
+    #
+    # files = storage.files
+    # files.all(request_limit: 10) do |file|
+    #   puts bucket.name
+    # end
+    # ```
+    #
+    # See {Google::Cloud::Storage::File::List} for details.
+    #
     # ## Creating a File
     #
-    # A new File can be uploaded by specifying the location of a file on the
+    # A new file can be uploaded by specifying the location of a file on the
     # local file system, and the name/path that the file should be stored in the
     # bucket. (See {Google::Cloud::Storage::Bucket#create_file})
     #
@@ -194,6 +220,17 @@ module Google
     #                    "avatars/heidi/400x400.png"
     # ```
     #
+    # Files can also be created from an in-memory StringIO object:
+    #
+    # ```ruby
+    # require "google/cloud/storage"
+    #
+    # storage = Google::Cloud::Storage.new
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # bucket.create_file StringIO.new("Hello world!"), "hello-world.txt"
+    # ```
+    #
     # ### Customer-supplied encryption keys
     #
     # By default, Google Cloud Storage manages server-side encryption keys on
@@ -265,9 +302,24 @@ module Google
     # file.download "/var/todo-app/avatars/heidi/400x400.png"
     # ```
     #
+    # Files can also be downloaded to an in-memory StringIO object:
+    #
+    # ```ruby
+    # require "google/cloud/storage"
+    #
+    # storage = Google::Cloud::Storage.new
+    #
+    # bucket = storage.bucket "my-todo-app"
+    # file = bucket.file "hello-world.txt"
+    #
+    # downloaded = file.download
+    # downloaded.rewind
+    # downloaded.read #=> "Hello world!"
+    # ```
+    #
     # ## Using Signed URLs
     #
-    # Access without authentication can be granted to a File for a specified
+    # Access without authentication can be granted to a file for a specified
     # period of time. This URL uses a cryptographic signature of your
     # credentials to access the file. (See
     # {Google::Cloud::Storage::File#signed_url})

data/lib/google/cloud/storage/bucket.rb

@@ -449,8 +449,9 @@ module Google
         alias_method :find_file, :file
 
         ##
-        # Creates a new {File} object by providing a path to a local file to
-        # upload and the path to store it with in the bucket.
+        # Creates a new {File} object by providing a path to a local file (or
+        # any IO or IO-ish object) to upload, along with the path at which to
+        # store it in the bucket.
         #
         # #### Customer-supplied encryption keys
         #
@@ -465,7 +466,10 @@ module Google
         # and you can read or update the metadata of an encrypted file without
         # providing the encryption key.
         #
-        # @param [String] file Path of the file on the filesystem to upload.
+        # @param [String, IO] file Path of the file on the filesystem to
+        #   upload. Can be an IO object, or IO-ish object like StringIO. (If the
+        #   IO object does not have path, a `path` argument must be also be
+        #   provided.)
         # @param [String] path Path to store the file in Google Cloud Storage.
         # @param [String] acl A predefined set of access controls to apply to
         #   this file.
@@ -580,9 +584,11 @@ module Google
                       content_encoding: content_encoding, metadata: metadata,
                       content_language: content_language, key: encryption_key,
                       storage_class: storage_class_for(storage_class) }
-          ensure_file_exists! file
-          # TODO: Handle file as an IO and path is missing more gracefully
-          path ||= Pathname(file).to_path
+          ensure_io_or_file_exists! file
+          path ||= file.path if file.respond_to? :path
+          path ||= file if file.is_a? String
+          fail ArgumentError, "must provide path" if path.nil?
+
           gapi = service.insert_file name, file, path, options
           File.from_gapi gapi, service
         end
@@ -612,7 +618,7 @@ module Google
         # @see https://cloud.google.com/storage/docs/access-control#Signed-URLs
         #   Access Control Signed URLs guide
         #
-        # @param [String] path Path to of the file in Google Cloud Storage.
+        # @param [String] path Path to the file in Google Cloud Storage.
         # @param [String] 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`.
@@ -649,6 +655,7 @@ module Google
         #   bucket = storage.bucket "my-todo-app"
         #   shared_url = bucket.signed_url "avatars/heidi/400x400.png",
         #                                  method: "PUT",
+        #                                  content_type: "image/png",
         #                                  expires: 300 # 5 minutes from now
         #
         # @example Using the issuer and signing_key options:
@@ -705,7 +712,7 @@ module Google
         #
         # @see https://cloud.google.com/storage/docs/xml-api/post-object
         #
-        # @param [String] path Path to of the file in Google Cloud Storage.
+        # @param [String] path Path to the file in Google Cloud Storage.
         # @param [Hash] policy The security policy that describes what
         #   can and cannot be uploaded in the form. When provided,
         #   the PostObject fields will include a Signature based on the JSON
@@ -919,7 +926,8 @@ module Google
 
         ##
         # Raise an error if the file is not found.
-        def ensure_file_exists! file
+        def ensure_io_or_file_exists! file
+          return if file.respond_to?(:read) && file.respond_to?(:rewind)
           return if ::File.file? file
           fail ArgumentError, "cannot find file #{file}"
         end

data/lib/google/cloud/storage/bucket/list.rb

@@ -77,15 +77,15 @@ module Google
           end
 
           ##
-          # Retrieves all buckets by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each bucket, which
-          # is passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all buckets are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all buckets. Default is no limit.

data/lib/google/cloud/storage/file.rb

@@ -17,6 +17,7 @@ require "uri"
 require "google/cloud/storage/file/acl"
 require "google/cloud/storage/file/list"
 require "google/cloud/storage/file/verifier"
+require "google/cloud/storage/file/signer"
 
 module Google
   module Cloud
@@ -332,7 +333,7 @@ module Google
         end
 
         ##
-        # Download the file's contents to a local file.
+        # Download the file's contents to a local file or an IO instance.
         #
         # By default, the download is verified by calculating the MD5 digest.
         #
@@ -341,9 +342,12 @@ module Google
         # was used with {Bucket#create_file}, the `encryption_key` option must
         # be provided.
         #
-        # @param [String] path The path on the local file system to write the
-        #   data to. The path provided must be writable.
-        # @param [Symbol] verify The verification algoruthm used to ensure the
+        # @param [String, IO] path The path on the local file system to write
+        #   the data to. The path provided must be writable. Can also be an IO
+        #   object, or IO-ish object like StringIO. If an IO object, the object
+        #   will be written to, not the filesystem. If omitted, a new StringIO
+        #   instance will be written to and returned. Optional.
+        # @param [Symbol] verify The verification algorithm used to ensure the
         #   downloaded file contents are correct. Default is `:md5`.
         #
         #   Acceptable values are:
@@ -357,7 +361,11 @@ module Google
         #   AES-256 encryption key used to encrypt the file, if one was provided
         #   to {Bucket#create_file}.
         #
-        # @return [File] Returns a `::File` object on the local file system
+        # @return [IO] Returns an IO object representing the file data. This
+        #   will ordinarily be a `::File` object referencing the local file
+        #   system. However, if the argument to `path` is `nil`, a StringIO
+        #   instance will be returned. If the argument to `path` is an IO
+        #   object, then that object will be returned.
         #
         # @example
         #   require "google/cloud/storage"
@@ -399,12 +407,30 @@ module Google
         #   file = bucket.file "path/to/my-file.ext"
         #   file.download "path/to/downloaded/file.ext", verify: :none
         #
-        def download path, verify: :md5, encryption_key: nil
+        # @example Download to an in-memory StringIO object.
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   downloaded = file.download
+        #   downloaded.rewind
+        #   downloaded.read #=> "Hello world!"
+        #
+        def download path = nil, verify: :md5, encryption_key: nil
           ensure_service!
-          service.download_file \
+          if path.nil?
+            path = StringIO.new
+            path.set_encoding "ASCII-8BIT"
+          end
+          file = service.download_file \
             bucket, name, path,
             key: encryption_key
-          verify_file! ::File.new(path), verify
+          # FIX: downloading with encryption key will return nil
+          file ||= ::File.new(path)
+          verify_file! file, verify
         end
 
         ##
@@ -661,7 +687,8 @@ module Google
         #
         #   bucket = storage.bucket "my-todo-app"
         #   file = bucket.file "avatars/heidi/400x400.png"
-        #   shared_url = file.signed_url method: "GET",
+        #   shared_url = file.signed_url method: "PUT",
+        #                                content_type: "image/png",
         #                                expires: 300 # 5 minutes from now
         #
         # @example Using the `issuer` and `signing_key` options:
@@ -685,7 +712,7 @@ module Google
         #   shared_url = file.signed_url method: "GET",
         #                                headers: {
         #                                  "x-goog-acl" => "public-read",
-        #                                  "x-goog-meta-foo" => bar,baz"
+        #                                  "x-goog-meta-foo" => "bar,baz"
         #                                }
         #
         def signed_url method: nil, expires: nil, content_type: nil,
@@ -823,122 +850,6 @@ module Google
             "standard" => "STANDARD" }[str.to_s.downcase] || str.to_s
         end
 
-        ##
-        # @private Create a signed_url for a file.
-        class Signer
-          def initialize bucket, path, service
-            @bucket = bucket
-            @path = path
-            @service = service
-          end
-
-          def self.from_file file
-            new file.bucket, file.name, file.service
-          end
-
-          def self.from_bucket bucket, path
-            new bucket.name, path, bucket.service
-          end
-
-          ##
-          # The external path to the file.
-          def ext_path
-            URI.escape "/#{@bucket}/#{@path}"
-          end
-
-          ##
-          # The external url to the file.
-          def ext_url
-            "#{GOOGLEAPIS_URL}#{ext_path}"
-          end
-
-          def apply_option_defaults options
-            adjusted_expires = (Time.now.utc + (options[:expires] || 300)).to_i
-            options[:expires] = adjusted_expires
-            options[:method]  ||= "GET"
-            options
-          end
-
-          def signature_str options
-            [options[:method], options[:content_md5],
-             options[:content_type], options[:expires],
-             format_extension_headers(options[:headers]) + ext_path].join "\n"
-          end
-
-          def determine_signing_key options = {}
-            options[:signing_key] || options[:private_key] ||
-              @service.credentials.signing_key
-          end
-
-          def determine_issuer options = {}
-            options[:issuer] || options[:client_email] ||
-              @service.credentials.issuer
-          end
-
-          def post_object options
-            options = apply_option_defaults options
-
-            fields = {
-              key: ext_path.sub("/", "")
-            }
-
-            p = options[:policy] || {}
-            fail "Policy must be given in a Hash" unless p.is_a? Hash
-
-            i = determine_issuer options
-            s = determine_signing_key options
-
-            fail SignedUrlUnavailable unless i && s
-
-            policy_str = p.to_json
-            policy = Base64.strict_encode64(policy_str).delete("\n")
-
-            signature = generate_signature s, policy
-
-            fields[:GoogleAccessId] = i
-            fields[:signature] = signature
-            fields[:policy] = policy
-
-            Google::Cloud::Storage::PostObject.new GOOGLEAPIS_URL, fields
-          end
-
-          def signed_url options
-            options = apply_option_defaults options
-
-            i = determine_issuer options
-            s = determine_signing_key options
-
-            fail SignedUrlUnavailable unless i && s
-
-            sig = generate_signature s, signature_str(options)
-            generate_signed_url i, sig, options[:expires]
-          end
-
-          def generate_signature signing_key, secret
-            unless signing_key.respond_to? :sign
-              signing_key = OpenSSL::PKey::RSA.new signing_key
-            end
-            signature = signing_key.sign OpenSSL::Digest::SHA256.new, secret
-            Base64.strict_encode64(signature).delete("\n")
-          end
-
-          def generate_signed_url issuer, signed_string, expires
-            "#{ext_url}?GoogleAccessId=#{CGI.escape issuer}" \
-              "&Expires=#{expires}" \
-              "&Signature=#{CGI.escape signed_string}"
-          end
-
-          def format_extension_headers headers
-            return "" if headers.nil?
-            fail "Headers must be given in a Hash" unless headers.is_a? Hash
-            flatten = headers.map do |key, value|
-              "#{key.to_s.downcase}:#{value.gsub(/\s+/, ' ')}\n"
-            end
-            flatten.reject! { |h| h.start_with? "x-goog-encryption-key" }
-            flatten.sort.join
-          end
-        end
-
         ##
         # Yielded to a block to accumulate changes for a patch request.
         class Updater < File

data/lib/google/cloud/storage/file/acl.rb

@@ -76,11 +76,7 @@ module Google
           #
           def reload!
             gapi = @service.list_file_acls @bucket, @file
-            acls = Array(gapi.items).map do |acl|
-              next acl if acl.is_a? Google::Apis::StorageV1::ObjectAccessControl
-              fail "Unknown ACL format: #{acl.class}" unless acl.is_a? Hash
-              Google::Apis::StorageV1::ObjectAccessControl.from_json acl.to_json
-            end
+            acls = Array(gapi.items)
             @owners  = entities_from_acls acls, "OWNER"
             @readers = entities_from_acls acls, "READER"
           end

data/lib/google/cloud/storage/file/list.rb

@@ -87,15 +87,15 @@ module Google
           end
 
           ##
-          # Retrieves all files by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each file, which is
-          # passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all files are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all files. Default is no limit.

data/lib/google/cloud/storage/file/signer.rb

@@ -0,0 +1,142 @@
+# Copyright 2017 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 "base64"
+require "openssl"
+require "google/cloud/storage/errors"
+
+module Google
+  module Cloud
+    module Storage
+      class File
+        ##
+        # @private Create a signed_url for a file.
+        class Signer
+          def initialize bucket, path, service
+            @bucket = bucket
+            @path = path
+            @service = service
+          end
+
+          def self.from_file file
+            new file.bucket, file.name, file.service
+          end
+
+          def self.from_bucket bucket, path
+            new bucket.name, path, bucket.service
+          end
+
+          ##
+          # The external path to the file.
+          def ext_path
+            URI.escape "/#{@bucket}/#{@path}"
+          end
+
+          ##
+          # The external url to the file.
+          def ext_url
+            "#{GOOGLEAPIS_URL}#{ext_path}"
+          end
+
+          def apply_option_defaults options
+            adjusted_expires = (Time.now.utc + (options[:expires] || 300)).to_i
+            options[:expires] = adjusted_expires
+            options[:method]  ||= "GET"
+            options
+          end
+
+          def signature_str options
+            [options[:method], options[:content_md5],
+             options[:content_type], options[:expires],
+             format_extension_headers(options[:headers]) + ext_path].join "\n"
+          end
+
+          def determine_signing_key options = {}
+            options[:signing_key] || options[:private_key] ||
+              @service.credentials.signing_key
+          end
+
+          def determine_issuer options = {}
+            options[:issuer] || options[:client_email] ||
+              @service.credentials.issuer
+          end
+
+          def post_object options
+            options = apply_option_defaults options
+
+            fields = {
+              key: ext_path.sub("/", "")
+            }
+
+            p = options[:policy] || {}
+            fail "Policy must be given in a Hash" unless p.is_a? Hash
+
+            i = determine_issuer options
+            s = determine_signing_key options
+
+            fail SignedUrlUnavailable unless i && s
+
+            policy_str = p.to_json
+            policy = Base64.strict_encode64(policy_str).delete("\n")
+
+            signature = generate_signature s, policy
+
+            fields[:GoogleAccessId] = i
+            fields[:signature] = signature
+            fields[:policy] = policy
+
+            Google::Cloud::Storage::PostObject.new GOOGLEAPIS_URL, fields
+          end
+
+          def signed_url options
+            options = apply_option_defaults options
+
+            i = determine_issuer options
+            s = determine_signing_key options
+
+            fail SignedUrlUnavailable unless i && s
+
+            sig = generate_signature s, signature_str(options)
+            generate_signed_url i, sig, options[:expires]
+          end
+
+          def generate_signature signing_key, secret
+            unless signing_key.respond_to? :sign
+              signing_key = OpenSSL::PKey::RSA.new signing_key
+            end
+            signature = signing_key.sign OpenSSL::Digest::SHA256.new, secret
+            Base64.strict_encode64(signature).delete("\n")
+          end
+
+          def generate_signed_url issuer, signed_string, expires
+            "#{ext_url}?GoogleAccessId=#{CGI.escape issuer}" \
+              "&Expires=#{expires}" \
+              "&Signature=#{CGI.escape signed_string}"
+          end
+
+          def format_extension_headers headers
+            return "" if headers.nil?
+            fail "Headers must be given in a Hash" unless headers.is_a? Hash
+            flatten = headers.map do |key, value|
+              "#{key.to_s.downcase}:#{value.gsub(/\s+/, ' ')}\n"
+            end
+            flatten.reject! { |h| h.start_with? "x-goog-encryption-key" }
+            flatten.sort.join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/storage/file/verifier.rb

@@ -52,14 +52,24 @@ module Google
           end
 
           def self.md5_for local_file
-            ::File.open(Pathname(local_file).to_path, "rb") do |f|
-              ::Digest::MD5.file(f).base64digest
+            if local_file.respond_to? :path
+              ::File.open(Pathname(local_file).to_path, "rb") do |f|
+                ::Digest::MD5.file(f).base64digest
+              end
+            else # StringIO
+              local_file.rewind
+              ::Digest::MD5.base64digest local_file.read
             end
           end
 
           def self.crc32c_for local_file
-            ::File.open(Pathname(local_file).to_path, "rb") do |f|
-              ::Digest::CRC32c.file(f).base64digest
+            if local_file.respond_to? :path
+              ::File.open(Pathname(local_file).to_path, "rb") do |f|
+                ::Digest::CRC32c.file(f).base64digest
+              end
+            else # StringIO
+              local_file.rewind
+              ::Digest::CRC32c.base64digest local_file.read
             end
           end
         end

data/lib/google/cloud/storage/project.rb

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-require "google/cloud/core/environment"
+require "google/cloud/env"
 require "google/cloud/storage/errors"
 require "google/cloud/storage/service"
 require "google/cloud/storage/credentials"
@@ -82,7 +82,7 @@ module Google
           ENV["STORAGE_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             ENV["GCLOUD_PROJECT"] ||
-            Google::Cloud::Core::Environment.project_id
+            Google::Cloud.env.project_id
         end
 
         ##
@@ -299,6 +299,110 @@ module Google
           Bucket.from_gapi gapi, service
         end
 
+        ##
+        # Access without authentication can be granted to a File for a specified
+        # period of time. This URL uses a cryptographic signature of your
+        # credentials to access the file identified by `path`. A URL can be
+        # created for paths that do not yet exist. For instance, a URL can be
+        # created to `PUT` file contents to.
+        #
+        # Generating a URL requires service account credentials, either by
+        # connecting with a service account when calling
+        # {Google::Cloud.storage}, or by passing in the service account `issuer`
+        # and `signing_key` values. Although the private key can be passed as a
+        # string for convenience, creating and storing an instance of
+        # `OpenSSL::PKey::RSA` is more efficient when making multiple calls to
+        # `signed_url`.
+        #
+        # A {SignedUrlUnavailable} is raised if the service account credentials
+        # are missing. Service account credentials are acquired by following the
+        # steps in [Service Account Authentication](
+        # https://cloud.google.com/storage/docs/authentication#service_accounts).
+        #
+        # @see https://cloud.google.com/storage/docs/access-control#Signed-URLs
+        #   Access Control Signed URLs guide
+        #
+        # @param [String] bucket Name of the bucket.
+        # @param [String] path Path to the file in Google Cloud Storage.
+        # @param [String] 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`.
+        # @param [Integer] expires The number of seconds until the URL expires.
+        #   Default is 300/5 minutes.
+        # @param [String] content_type When provided, the client (browser) must
+        #   send this value in the HTTP header. e.g. `text/plain`
+        # @param [String] 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.
+        # @param [Hash] headers Google extension headers (custom HTTP headers
+        #   that begin with `x-goog-`) that must be included in requests that
+        #   use the signed URL.
+        # @param [String] issuer Service Account's Client Email.
+        # @param [String] client_email Service Account's Client Email.
+        # @param [OpenSSL::PKey::RSA, String] signing_key Service Account's
+        #   Private Key.
+        # @param [OpenSSL::PKey::RSA, String] private_key Service Account's
+        #   Private Key.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket_name = "my-todo-app"
+        #   file_path = "avatars/heidi/400x400.png"
+        #   shared_url = storage.signed_url bucket_name, file_path
+        #
+        # @example Any of the option parameters may be specified:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket_name = "my-todo-app"
+        #   file_path = "avatars/heidi/400x400.png"
+        #   shared_url = storage.signed_url bucket_name, file_path,
+        #                                   method: "PUT",
+        #                                   content_type: "image/png",
+        #                                   expires: 300 # 5 minutes from now
+        #
+        # @example Using the issuer and signing_key options:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud.storage
+        #
+        #   bucket_name = "my-todo-app"
+        #   file_path = "avatars/heidi/400x400.png"
+        #   issuer_email = "service-account@gcloud.com"
+        #   key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."
+        #   shared_url = storage.signed_url bucket_name, file_path,
+        #                                   issuer: issuer_email,
+        #                                   signing_key: key
+        #
+        # @example Using the headers option:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud.storage
+        #
+        #   bucket_name = "my-todo-app"
+        #   file_path = "avatars/heidi/400x400.png"
+        #   shared_url = storage.signed_url bucket_name, file_path,
+        #                                   headers: {
+        #                                     "x-goog-acl" => "private",
+        #                                     "x-goog-meta-foo" => "bar,baz"
+        #                                   }
+        #
+        def signed_url bucket, path, method: nil, expires: nil,
+                       content_type: nil, content_md5: nil, headers: nil,
+                       issuer: nil, client_email: nil, signing_key: nil,
+                       private_key: nil
+          options = { method: method, expires: expires, headers: headers,
+                      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 bucket, path, service
+          signer.signed_url options
+        end
+
         protected
 
         def acl_rule option_name

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

@@ -49,6 +49,9 @@ module Google
           @service.request_options.retries = retries || 3
           @service.request_options.timeout_sec      = timeout
           @service.request_options.open_timeout_sec = timeout
+          @service.request_options.header ||= {}
+          @service.request_options.header["x-goog-api-client"] = \
+            "gl-ruby/#{RUBY_VERSION} gccl/#{Google::Cloud::Storage::VERSION}"
           @service.authorization = @credentials.client
         end
 
@@ -178,7 +181,8 @@ module Google
             content_encoding: content_encoding, crc32c: crc32c,
             content_language: content_language, metadata: metadata,
             storage_class: storage_class }.delete_if { |_k, v| v.nil? })
-          content_type ||= mime_type_for(Pathname(source).to_path)
+          content_type ||= mime_type_for(path || Pathname(source).to_path)
+
           execute do
             service.insert_object \
               bucket_name, file_obj,

data/lib/google/cloud/storage/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "0.24.0"
+      VERSION = "0.25.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-04 00:00:00.000000000 Z
+date: 2017-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: google-api-client
   requirement: !ruby/object:Gem::Requirement
@@ -201,6 +201,7 @@ files:
 - lib/google/cloud/storage/file.rb
 - lib/google/cloud/storage/file/acl.rb
 - lib/google/cloud/storage/file/list.rb
+- lib/google/cloud/storage/file/signer.rb
 - lib/google/cloud/storage/file/verifier.rb
 - lib/google/cloud/storage/post_object.rb
 - lib/google/cloud/storage/project.rb
@@ -226,7 +227,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.10
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Storage