google-cloud-storage 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa3b7db1df4e7dfaf4f531dc12faf2245d7d9d18107e9dbad1877520df131939
-  data.tar.gz: 5ff65a195b17e9a52eccd0787cba142153fb24347984b3453cd2ce2e295b6b92
+  metadata.gz: 6df77120a6b6b06e34910f4150a4b4734e9f1ee6055f24dd1dcdcce6852c200a
+  data.tar.gz: d3d9ae16b4cafc4e8d033efa4686ebbeeffbcf70005a34e1804fdf67ea16fb58
 SHA512:
-  metadata.gz: c372dc40320fa3ac1561b804c3cafc591ce51e3c6fb299709b30282a7f13e2bceb34fa30cbe913a39d723cbdbce8ef77b4adeaea9f40971a4cff1993912144f9
-  data.tar.gz: 3122a76ab51e4604fcb44e53cf1e784bacbabbfd5086448493c1a1a48416cdf43f37bad23517ac369d67e465734e66f864510b6302d9b8f129c6259e40cb6583
+  metadata.gz: db977a4ee0406302562c8d0d71f6a8a55bea904305a774dc2244898c7c08e3253b98ec77181d425f30a0953f9be693d36e27052b1e22a678bd6e3470b9aacfde
+  data.tar.gz: 827d0709cc5f86a215813a93ce308c354e61f2a9b5bbbd9d087b89776ff9a1818b5f4e34418f976689ea1bd415231b8d73ec870628e8dccd67c82bc71242e363

data/README.md

@@ -44,6 +44,13 @@ file.copy backup, file.name
 
 This library is supported on Ruby 2.0+.
 
+However, Ruby 2.3 or later is strongly recommended, as earlier releases have
+reached or are nearing end-of-life. After June 1, 2018, Google will provide
+official support only for Ruby versions that are considered current and
+supported by Ruby Core (that is, Ruby versions that are either in normal
+maintenance or in security maintenance).
+See https://www.ruby-lang.org/en/downloads/branches/ for further details.
+
 ## Versioning
 
 This library follows [Semantic Versioning](http://semver.org/).

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

@@ -561,8 +561,8 @@ module Google
 
         ##
         # 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.
+        # any File-like object such as StringIO) to upload, along with the path
+        # at which to store it in the bucket.
         #
         # #### Customer-supplied encryption keys
         #
@@ -577,9 +577,9 @@ module Google
         # and you can read or update the metadata of an encrypted file without
         # providing the encryption key.
         #
-        # @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
+        # @param [String, ::File] file Path of the file on the filesystem to
+        #   upload. Can be an File object, or File-like object such as StringIO.
+        #   (If the 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

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

@@ -411,7 +411,7 @@ module Google
         end
 
         ##
-        # Download the file's contents to a local file or an IO instance.
+        # Download the file's contents to a local file or an File-like object.
         #
         # By default, the download is verified by calculating the MD5 digest.
         #
@@ -420,11 +420,12 @@ module Google
         # was used with {Bucket#create_file}, the `encryption_key` option must
         # be provided.
         #
-        # @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 [String, ::File] path The path on the local file system to
+        #   write the data to. The path provided must be writable. Can also be
+        #   an File object, or File-like object such as StringIO. If an file
+        #   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`.
         #
@@ -438,6 +439,13 @@ module Google
         # @param [String] encryption_key Optional. The customer-supplied,
         #   AES-256 encryption key used to encrypt the file, if one was provided
         #   to {Bucket#create_file}.
+        #
+        # @param [Range, String] range Optional. The byte range of the file's
+        #   contents to download or a string header value. Provide this to
+        #   perform a partial download. When a range is provided, no
+        #   verification is performed regardless of the `verify` parameter's
+        #   value.
+        #
         # @param [Boolean] skip_decompress Optional. If `true`, the data for a
         #   Storage object returning a `Content-Encoding: gzip` response header
         #   will *not* be automatically decompressed by this client library. The
@@ -446,11 +454,11 @@ module Google
         #   not performed in the Storage service. (See [Transcoding of
         #   gzip-compressed files](https://cloud.google.com/storage/docs/transcoding))
         #
-        # @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.
+        # @return [::File, StringIO] Returns a file 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
+        #   File-like object, then that object will be returned.
         #
         # @example
         #   require "google/cloud/storage"
@@ -542,17 +550,32 @@ module Google
         #   file.download "path/to/downloaded/gzipped.txt",
         #                 skip_decompress: true
         #
-        def download path = nil, verify: :md5, encryption_key: nil,
+        # @example Partially download.
+        #
+        #   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 range: 6..10
+        #   downloaded.rewind
+        #   downloaded.read #=> "world"
+        #
+        def download path = nil, verify: :md5, encryption_key: nil, range: nil,
                      skip_decompress: nil
           ensure_service!
           if path.nil?
             path = StringIO.new
             path.set_encoding "ASCII-8BIT"
           end
-          file, resp = service.download_file \
-            bucket, name, path, key: encryption_key, user_project: user_project
+          file, resp =
+            service.download_file bucket, name, path,
+                                  key: encryption_key, range: range,
+                                  user_project: user_project
           # FIX: downloading with encryption key will return nil
           file ||= ::File.new(path)
+          verify = :none if range
           verify_file! file, verify
           if !skip_decompress &&
              Array(resp.header["Content-Encoding"]).include?("gzip")
@@ -646,31 +669,155 @@ module Google
         #     f.metadata["copied_from"] = "#{file.bucket}/#{file.name}"
         #   end
         #
-        def copy dest_bucket_or_path, dest_path = nil, acl: nil,
-                 generation: nil, encryption_key: nil
+        def copy dest_bucket_or_path, dest_path = nil,
+                 acl: nil, generation: nil, encryption_key: nil
+          rewrite dest_bucket_or_path, dest_path,
+                  acl: acl, generation: generation,
+                  encryption_key: encryption_key,
+                  new_encryption_key: encryption_key do |updater|
+            yield updater if block_given?
+          end
+        end
+
+        ##
+        # [Rewrites](https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite)
+        # the file to a new location. Or the same location can be provided to
+        # rewrite the file in place.
+        #
+        # If a [customer-supplied encryption
+        # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
+        # was used with {Bucket#create_file}, the `encryption_key` option must
+        # be provided. Unlike {#copy}, separate encryption keys are used to read
+        # (encryption_key) and to write (new_encryption_key) file contents.
+        #
+        # @param [String] dest_bucket_or_path Either the bucket to rewrite the
+        #   file to, or the path to rewrite the file to in the current bucket.
+        # @param [String] dest_path If a bucket was provided in the first
+        #   parameter, this contains the path to rewrite the file to in the
+        #   given bucket.
+        # @param [String] acl A predefined set of access controls to apply to
+        #   new file.
+        #
+        #   Acceptable values are:
+        #
+        #   * `auth`, `auth_read`, `authenticated`, `authenticated_read`,
+        #     `authenticatedRead` - File owner gets OWNER access, and
+        #     allAuthenticatedUsers get READER access.
+        #   * `owner_full`, `bucketOwnerFullControl` - File owner gets OWNER
+        #     access, and project team owners get OWNER access.
+        #   * `owner_read`, `bucketOwnerRead` - File owner gets OWNER access,
+        #     and project team owners get READER access.
+        #   * `private` - File owner gets OWNER access.
+        #   * `project_private`, `projectPrivate` - File owner gets OWNER
+        #     access, and project team members get access according to their
+        #     roles.
+        #   * `public`, `public_read`, `publicRead` - File owner gets OWNER
+        #     access, and allUsers get READER access.
+        # @param [Integer] generation Select a specific revision of the file to
+        #   rewrite. The default is the latest version.
+        # @param [String] encryption_key Optional. The customer-supplied,
+        #   AES-256 encryption key used to decrypt the file, if the existing
+        #   file is encrypted.
+        # @param [String] new_encryption_key Optional. The customer-supplied,
+        #   AES-256 encryption key used to encrypt the file, if the rewritten
+        #   file is intended to be encrypted.
+        # @yield [file] a block yielding a delegate object for updating
+        #
+        # @return [Google::Cloud::Storage::File]
+        #
+        # @example The file can be rewritten to a new path in the bucket:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.rewrite "path/to/destination/file.ext"
+        #
+        # @example The file can also be rewritten to a different bucket:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.rewrite "new-destination-bucket",
+        #                "path/to/destination/file.ext"
+        #
+        # @example The file can also be rewritten by specifying a generation:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.rewrite "copy/of/previous/generation/file.ext",
+        #                generation: 123456
+        #
+        # @example The file can be modified during rewriting:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.rewrite "new-destination-bucket",
+        #                "path/to/destination/file.ext" do |f|
+        #     f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
+        #   end
+        #
+        # @example The file can be rewritten with a new encryption key:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   # Old key was stored securely for later use.
+        #   old_key = "y\x03\"\x0E\xB6\xD3\x9B\x0E\xAB*\x19\xFAv\xDEY\xBEI..."
+        #
+        #   # Key generation shown for example purposes only. Write your own.
+        #   cipher = OpenSSL::Cipher.new "aes-256-cfb"
+        #   cipher.encrypt
+        #   new_key = cipher.random_key
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.rewrite "new-destination-bucket",
+        #                "path/to/destination/file.ext",
+        #                encryption_key: old_key,
+        #                new_encryption_key: new_key do |f|
+        #     f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
+        #   end
+        #
+        def rewrite dest_bucket_or_path, dest_path = nil,
+                    acl: nil, generation: nil,
+                    encryption_key: nil, new_encryption_key: nil
           ensure_service!
-          options = { acl: acl, generation: generation, key: encryption_key,
-                      user_project: user_project }
-          dest_bucket, dest_path, options = fix_copy_args dest_bucket_or_path,
-                                                          dest_path, options
+          dest_bucket, dest_path = fix_rewrite_args dest_bucket_or_path,
+                                                    dest_path
 
-          copy_gapi = nil
+          update_gapi = nil
           if block_given?
             updater = Updater.new gapi
             yield updater
             updater.check_for_changed_metadata!
-            copy_gapi = gapi_from_attrs(updater.updates) if updater.updates.any?
+            if updater.updates.any?
+              update_gapi = gapi_from_attrs updater.updates
+            end
           end
 
-          resp = service.copy_file bucket, name, dest_bucket, dest_path,
-                                   copy_gapi, options
-          until resp.done
-            sleep 1
-            resp = service.copy_file bucket, name, dest_bucket, dest_path,
-                                     copy_gapi,
-                                     options.merge(token: resp.rewrite_token)
-          end
-          File.from_gapi resp.resource, service, user_project: user_project
+          new_gapi = rewrite_gapi bucket, name, update_gapi,
+                                  new_bucket: dest_bucket, new_name: dest_path,
+                                  acl: acl, generation: generation,
+                                  encryption_key: encryption_key,
+                                  new_encryption_key: new_encryption_key,
+                                  user_project: user_project
+
+          File.from_gapi new_gapi, service, user_project: user_project
         end
 
         ##
@@ -719,17 +866,8 @@ module Google
         #   file.rotate encryption_key: old_key, new_encryption_key: new_key
         #
         def rotate encryption_key: nil, new_encryption_key: nil
-          ensure_service!
-          options = { source_key: encryption_key,
-                      destination_key: new_encryption_key,
-                      user_project: user_project }
-          gapi = service.rewrite_file bucket, name, bucket, name, nil, options
-          until gapi.done
-            sleep 1
-            options[:token] = gapi.rewrite_token
-            gapi = service.rewrite_file bucket, name, bucket, name, nil, options
-          end
-          File.from_gapi gapi.resource, service, user_project: user_project
+          rewrite bucket, name, encryption_key: encryption_key,
+                                new_encryption_key: new_encryption_key
         end
 
         ##
@@ -1096,7 +1234,8 @@ module Google
           ensure_service!
 
           @gapi = if attributes.include? :storage_class
-                    rewrite_gapi bucket, name, update_gapi
+                    rewrite_gapi \
+                      bucket, name, update_gapi, user_project: user_project
                   else
                     service.patch_file \
                       bucket, name, update_gapi, user_project: user_project
@@ -1112,30 +1251,36 @@ module Google
           Google::Apis::StorageV1::Object.new attr_params
         end
 
-        def rewrite_gapi bucket, name, update_gapi
+        def rewrite_gapi bucket, name, updated_gapi,
+                         new_bucket: nil, new_name: nil, acl: nil,
+                         generation: nil, encryption_key: nil,
+                         new_encryption_key: nil, user_project: nil
+          new_bucket ||= bucket
+          new_name ||= name
+          options = { acl: File::Acl.predefined_rule_for(acl),
+                      generation: generation, source_key: encryption_key,
+                      destination_key: new_encryption_key,
+                      user_project: user_project }.delete_if { |_k, v| v.nil? }
+
           resp = service.rewrite_file \
-            bucket, name, bucket, name, update_gapi, user_project: user_project
+            bucket, name, new_bucket, new_name, updated_gapi, options
           until resp.done
             sleep 1
+            retry_options = options.merge token: resp.rewrite_token
             resp = service.rewrite_file \
-              bucket, name, bucket, name, update_gapi,
-              token: resp.rewrite_token, user_project: user_project
+              bucket, name, new_bucket, new_name, updated_gapi, retry_options
           end
           resp.resource
         end
 
-        def fix_copy_args dest_bucket, dest_path, options = {}
-          if dest_path.respond_to?(:to_hash) && options.empty?
-            options = dest_path
-            dest_path = nil
-          end
+        def fix_rewrite_args dest_bucket, dest_path
           if dest_path.nil?
             dest_path = dest_bucket
             dest_bucket = bucket
           end
           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]
+          dest_path = dest_path.name if dest_path.respond_to? :name
+          [dest_bucket, dest_path]
         end
 
         def verify_file! file, verify = :md5

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

@@ -311,26 +311,6 @@ module Google
           end
         end
 
-        ## Copy a file from source bucket/object to a
-        # destination bucket/object.
-        def copy_file source_bucket_name, source_file_path,
-                      destination_bucket_name, destination_file_path,
-                      file_gapi = nil, key: nil, acl: nil, generation: nil,
-                      token: nil, user_project: nil
-          key_options = rewrite_key_options key, key
-          execute do
-            service.rewrite_object \
-              source_bucket_name, source_file_path,
-              destination_bucket_name, destination_file_path,
-              file_gapi,
-              destination_predefined_acl: acl,
-              source_generation: generation,
-              rewrite_token: token,
-              user_project: user_project(user_project),
-              options: key_options
-          end
-        end
-
         ## Rewrite a file from source bucket/object to a
         # destination bucket/object.
         def rewrite_file source_bucket_name, source_file_path,
@@ -381,8 +361,10 @@ module Google
         #     Apis::StorageV1::StorageService and Apis::Core::DownloadCommand at
         #     the end of this file.
         def download_file bucket_name, file_path, target_path, generation: nil,
-                          key: nil, user_project: nil
+                          key: nil, range: nil, user_project: nil
           options = key_options key
+          options = range_header options, range
+
           execute do
             service.get_object_with_response \
               bucket_name, file_path,
@@ -501,6 +483,19 @@ module Google
           options
         end
 
+        def range_header options, range
+          case range
+          when Range
+            options[:header] ||= {}
+            options[:header]["Range"] = "bytes=#{range.min}-#{range.max}"
+          when String
+            options[:header] ||= {}
+            options[:header]["Range"] = range
+          end
+
+          options
+        end
+
         def topic_path topic_name
           return topic_name if topic_name.to_s.include? "/"
           "//pubsub.googleapis.com/projects/#{project}/topics/#{topic_name}"

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.10.0".freeze
+      VERSION = "1.11.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-28 00:00:00.000000000 Z
+date: 2018-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core