google-cloud-storage 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 474743d603eb149e305fbbbaf7db863b04806cc0
-  data.tar.gz: f8eb5c36d9816604516c4c0d91c5350ba5152c76
+  metadata.gz: 68663d7f63e76435070cbcd4748022693d2561a5
+  data.tar.gz: cb6ecfdfaadeb41ed569d08ca9c069edf67c0ea4
 SHA512:
-  metadata.gz: e75929f212d3cea1b8b7064136ff2a6228571358225e1980ba5f46d982a31dc212d50cda1d59d117356c8429388b89d40502352f7020c7578a40e5361dc4ba82
-  data.tar.gz: ebd0b51233c64e48728850b2eb0a0e5ad4699486e0bc8a12d7be442b34092e7c73419051c857dabd4a23b6693da1a0d3bf9e2e3287e61df2a5bc9d0a523d16d4
+  metadata.gz: 1382c121c18b2cc7fa8a916895bec8c0a2b7c40a99b4fea1a54edc3562ba53b8e9f9538ea3e613f20c39572bdcc21cb2190d7a26da82240fe966901b24bf8ebb
+  data.tar.gz: 78b666563914f310968e53d4701c78781ebedae1977e1f51f6f3874ee69d23e9dfcf0b235178d0e13a0437c22fd41a12e9210577e1aa23d0ca2937b4babb0500

data/README.md

@@ -48,8 +48,6 @@ This library is supported on Ruby 2.0+.
 
 This library follows [Semantic Versioning](http://semver.org/).
 
-It is currently in major version zero (0.y.z), which means that anything may change at any time and the public API should not be considered stable.
-
 ## Contributing
 
 Contributions to this library are always welcome and highly encouraged.

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

@@ -234,12 +234,25 @@ module Google
         ##
         # The bucket's storage class. This defines how objects in the bucket are
         # stored and determines the SLA and the cost of storage. Values include
-        # `MULTI_REGIONAL`, `REGIONAL`, `NEARLINE`, `COLDLINE`, `STANDARD`,
-        # and `DURABLE_REDUCED_AVAILABILITY`.
+        # `MULTI_REGIONAL`, `REGIONAL`, `NEARLINE`, `COLDLINE`, and
+        # `DURABLE_REDUCED_AVAILABILITY`.
         def storage_class
           @gapi.storage_class
         end
 
+        ##
+        # Updates the bucket's storage class. This defines how objects in the
+        # bucket are stored and determines the SLA and the cost of storage.
+        # Accepted values include `:multi_regional`, `:regional`, `:nearline`,
+        # and `:coldline`, as well as the equivalent strings returned by
+        # {Bucket#storage_class}. For more information, see [Storage
+        # Classes](https://cloud.google.com/storage/docs/storage-classes).
+        # @param [Symbol, String] new_storage_class Storage class of the bucket.
+        def storage_class= new_storage_class
+          @gapi.storage_class = storage_class_for(new_storage_class)
+          patch_gapi! :storage_class
+        end
+
         ##
         # Whether [Object
         # Versioning](https://cloud.google.com/storage/docs/object-versioning)
@@ -514,9 +527,13 @@ module Google
         # @param [String] path Name (path) of the file.
         # @param [Integer] generation When present, selects a specific revision
         #   of this object. Default is the latest version.
+        # @param [Boolean] skip_lookup Optionally create a Bucket object
+        #   without verifying the bucket resource exists on the Storage service.
+        #   Calls made on this object will raise errors if the bucket resource
+        #   does not exist. Default is `false`.
         # @param [String] encryption_key Optional. The customer-supplied,
         #   AES-256 encryption key used to encrypt the file, if one was provided
-        #   to {#create_file}.
+        #   to {#create_file}. (Not used if `skip_lookup` is also set.)
         #
         # @return [Google::Cloud::Storage::File, nil] Returns nil if file does
         #   not exist
@@ -531,8 +548,13 @@ module Google
         #   file = bucket.file "path/to/my-file.ext"
         #   puts file.name
         #
-        def file path, generation: nil, encryption_key: nil
+        def file path, generation: nil, skip_lookup: nil, encryption_key: nil
           ensure_service!
+          if skip_lookup
+            return File.new_lazy name, path, service,
+                                 generation: generation,
+                                 user_project: user_project
+          end
           gapi = service.get_file name, path, generation: generation,
                                               key: encryption_key,
                                               user_project: user_project
@@ -615,12 +637,11 @@ module Google
         #   file as "x-goog-meta-" response headers.
         # @param [Symbol, String] storage_class Storage class of the file.
         #   Determines how the file is stored and determines the SLA and the
-        #   cost of storage. Values include `:multi_regional`, `:regional`,
-        #   `:nearline`, `:coldline`, `:standard`, and `:dra` (Durable Reduced
-        #   Availability), as well as the strings returned by
-        #   {#storage_class}. For more information, see [Storage
-        #   Classes](https://cloud.google.com/storage/docs/storage-classes) and
-        #   [Per-Object Storage
+        #   cost of storage. Accepted values include `:multi_regional`,
+        #   `:regional`, `:nearline`, and `:coldline`, as well as the equivalent
+        #   strings returned by {#storage_class}. For more information, see
+        #   [Storage Classes](https://cloud.google.com/storage/docs/storage-classes)
+        #   and [Per-Object Storage
         #   Class](https://cloud.google.com/storage/docs/per-object-storage-class).
         #   The default value is the default storage class for the bucket.
         # @param [String] encryption_key Optional. A customer-supplied, AES-256
@@ -1120,17 +1141,53 @@ module Google
         # Reloads the bucket with current data from the Storage service.
         def reload!
           ensure_service!
-          @gapi = service.get_bucket name
+          @gapi = service.get_bucket name, user_project: user_project
+          # If NotFound then lazy will never be unset
+          @lazy = nil
+          self
         end
         alias_method :refresh!, :reload!
 
+        ##
+        # Determines whether the bucket exists in the Storage service.
+        def exists?
+          # Always true if we have a grpc object
+          return true unless lazy?
+          # If we have a value, return it
+          return @exists unless @exists.nil?
+          ensure_gapi!
+          @exists = true
+        rescue Google::Cloud::NotFoundError
+          @exists = false
+        end
+
+        ##
+        # @private
+        # Determines whether the bucket was created without retrieving the
+        # resource record from the API.
+        def lazy?
+          @lazy
+        end
+
         ##
         # @private New Bucket from a Google API Client object.
         def self.from_gapi gapi, service, user_project: nil
-          new.tap do |f|
-            f.gapi = gapi
-            f.service = service
-            f.user_project = user_project
+          new.tap do |b|
+            b.gapi = gapi
+            b.service = service
+            b.user_project = user_project
+          end
+        end
+
+        ##
+        # @private New lazy Bucket object without making an HTTP request.
+        def self.new_lazy name, service, user_project: nil
+          # TODO: raise if name is nil?
+          new.tap do |b|
+            b.gapi.name = name
+            b.service = service
+            b.user_project = user_project
+            b.instance_variable_set :@lazy, true
           end
         end
 
@@ -1142,6 +1199,14 @@ module Google
           fail "Must have active connection" unless service
         end
 
+        ##
+        # Ensures the Google::Apis::StorageV1::Bucket object exists.
+        def ensure_gapi!
+          ensure_service!
+          return unless lazy?
+          reload!
+        end
+
         def patch_gapi! *attributes
           attributes.flatten!
           return if attributes.empty?
@@ -1152,6 +1217,8 @@ module Google
           patch_gapi = Google::Apis::StorageV1::Bucket.new patch_args
           @gapi = service.patch_bucket name, patch_gapi,
                                        user_project: user_project
+          @lazy = nil
+          self
         end
 
         ##

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

@@ -314,10 +314,10 @@ module Google
 
         ##
         # Updates how the file is stored and determines the SLA and the cost of
-        # storage. Values include `:multi_regional`, `:regional`, `:nearline`,
-        # `:coldline`, `:standard`, and `:dra` (Durable Reduced Availability),
-        # as well as the strings returned by {File#storage_class} or
-        # {Bucket#storage_class}. For more information, see [Storage
+        # storage. Accepted values include `:multi_regional`, `:regional`,
+        # `:nearline`, and `:coldline`, as well as the equivalent strings
+        # returned by {File#storage_class} or {Bucket#storage_class}. For more
+        # information, see [Storage
         # Classes](https://cloud.google.com/storage/docs/storage-classes) and
         # [Per-Object Storage
         # Class](https://cloud.google.com/storage/docs/per-object-storage-class).
@@ -329,6 +329,45 @@ module Google
           update_gapi! :storage_class
         end
 
+        ##
+        # Retrieves a list of versioned files for the current object.
+        #
+        # Useful for listing archived versions of the file, restoring the live
+        # version of the file to an older version, or deleting an archived
+        # version. You can turn versioning on or off for a bucket at any time
+        # with {Bucket#versioning=}. Turning versioning off leaves existing file
+        # versions in place and causes the bucket to stop accumulating new
+        # archived object versions. (See {Bucket#versioning} and
+        # {File#generation})
+        #
+        # @see https://cloud.google.com/storage/docs/object-versioning Object
+        #   Versioning
+        #
+        # @return [Array<Google::Cloud::Storage::File>] (See
+        #   {Google::Cloud::Storage::File::List})
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.generation #=> 1234567890
+        #   file.generations.each do |versioned_file|
+        #     versioned_file.generation
+        #   end
+        #
+        def generations
+          ensure_service!
+          gapi = service.list_files bucket, prefix: name,
+                                            versions: true,
+                                            user_project: user_project
+          File::List.from_gapi gapi, service, bucket, name, nil, nil, true,
+                               user_project: user_project
+        end
+
         ##
         # Updates the file with changes made in the given block in a single
         # PATCH request. The following attributes may be set: {#cache_control=},
@@ -639,6 +678,11 @@ module Google
         # Permanently deletes the file.
         #
         # @return [Boolean] Returns `true` if the file was deleted.
+        # @param [Boolean, Integer] generation Specify a version of the file to
+        #   delete. When `true`, it will delete the version returned by
+        #   {#generation}. The default behavior is to delete the latest version
+        #   of the file (regardless of the version to which the file is set,
+        #   which is the version returned by {#generation}.)
         #
         # @example
         #   require "google/cloud/storage"
@@ -650,9 +694,31 @@ module Google
         #   file = bucket.file "path/to/my-file.ext"
         #   file.delete
         #
-        def delete
+        # @example The file's generation can used by passing `true`:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.delete generation: true
+        #
+        # @example A generation can also be specified:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.delete generation: 123456
+        #
+        def delete generation: nil
+          generation = self.generation if generation == true
           ensure_service!
-          service.delete_file bucket, name, user_project: user_project
+          service.delete_file bucket, name, generation: generation,
+                                            user_project: user_project
           true
         end
 
@@ -846,12 +912,75 @@ module Google
 
         ##
         # Reloads the file with current data from the Storage service.
-        def reload!
+        #
+        # @param [Boolean, Integer] generation Specify a version of the file to
+        #   reload with. When `true`, it will reload the version returned by
+        #   {#generation}. The default behavior is to reload with the latest
+        #   version of the file (regardless of the version to which the file is
+        #   set, which is the version returned by {#generation}.)
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.reload!
+        #
+        # @example The file's generation can used by passing `true`:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext", generation: 123456
+        #   file.reload! generation: true
+        #
+        # @example A generation can also be specified:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext", generation: 123456
+        #   file.reload! generation: 123457
+        #
+        def reload! generation: nil
+          generation = self.generation if generation == true
           ensure_service!
-          @gapi = service.get_file bucket, name, user_project: user_project
+          @gapi = service.get_file bucket, name, generation: generation,
+                                                 user_project: user_project
+          # If NotFound then lazy will never be unset
+          @lazy = nil
+          self
         end
         alias_method :refresh!, :reload!
 
+        ##
+        # Determines whether the file exists in the Storage service.
+        def exists?
+          # Always true if we have a grpc object
+          return true unless lazy?
+          # If we have a value, return it
+          return @exists unless @exists.nil?
+          ensure_gapi!
+          @exists = true
+        rescue Google::Cloud::NotFoundError
+          @exists = false
+        end
+
+        ##
+        # @private
+        # Determines whether the file was created without retrieving the
+        # resource record from the API.
+        def lazy?
+          @lazy
+        end
+
         ##
         # @private URI of the location and file name in the format of
         # <code>gs://my-bucket/file-name.json</code>.
@@ -869,6 +998,21 @@ module Google
           end
         end
 
+        ##
+        # @private New lazy Bucket object without making an HTTP request.
+        def self.new_lazy bucket, name, service, generation: nil,
+                          user_project: nil
+          # TODO: raise if name is nil?
+          new.tap do |f|
+            f.gapi.bucket = bucket
+            f.gapi.name = name
+            f.gapi.generation = generation
+            f.service = service
+            f.user_project = user_project
+            f.instance_variable_set :@lazy, true
+          end
+        end
+
         protected
 
         ##
@@ -877,6 +1021,14 @@ module Google
           fail "Must have active connection" unless service
         end
 
+        ##
+        # Ensures the Google::Apis::StorageV1::Bucket object exists.
+        def ensure_gapi!
+          ensure_service!
+          return unless lazy?
+          reload! generation: true
+        end
+
         def update_gapi! *attributes
           attributes.flatten!
           return if attributes.empty?
@@ -931,8 +1083,8 @@ module Google
         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
-          Verifier.verify_crc32c! self, file if verify_crc32c
+          Verifier.verify_md5! self, file    if verify_md5    && md5
+          Verifier.verify_crc32c! self, file if verify_crc32c && crc32c
           file
         end
 

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

@@ -163,7 +163,7 @@ module Google
                              delimiter = nil, max = nil, versions = nil,
                              user_project: nil
             files = new(Array(gapi_list.items).map do |gapi_object|
-              File.from_gapi gapi_object, service
+              File.from_gapi gapi_object, service, user_project: user_project
             end)
             files.instance_variable_set :@token, gapi_list.next_page_token
             files.instance_variable_set :@prefixes, Array(gapi_list.prefixes)

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

@@ -137,6 +137,10 @@ module Google
         # Retrieves bucket by name.
         #
         # @param [String] bucket_name Name of a bucket.
+        # @param [Boolean] skip_lookup Optionally create a Bucket object
+        #   without verifying the bucket resource exists on the Storage service.
+        #   Calls made on this object will raise errors if the bucket resource
+        #   does not exist. Default is `false`.
         # @param [Boolean, String] user_project If the `requester_pays` flag is
         #   enabled for the requested bucket, and if this parameter is set to
         #   `true`, transit costs for operations on the requested bucket or a
@@ -180,7 +184,11 @@ module Google
         #                           user_project: "my-other-project"
         #   files = bucket.files # Billed to "my-other-project"
         #
-        def bucket bucket_name, user_project: nil
+        def bucket bucket_name, skip_lookup: false, user_project: nil
+          if skip_lookup
+            return Bucket.new_lazy bucket_name, service,
+                                   user_project: user_project
+          end
           gapi = service.get_bucket bucket_name, user_project: user_project
           Bucket.from_gapi gapi, service, user_project: user_project
         rescue Google::Cloud::NotFoundError
@@ -258,12 +266,11 @@ module Google
         #   Logs](https://cloud.google.com/storage/docs/access-logs).
         # @param [Symbol, String] storage_class Defines how objects in the
         #   bucket are stored and determines the SLA and the cost of storage.
-        #   Values include `:multi_regional`, `:regional`, `:nearline`,
-        #   `:coldline`, `:standard`, and `:dra` (Durable Reduced
-        #   Availability), as well as the strings returned by
+        #   Accepted values include `:multi_regional`, `:regional`, `:nearline`,
+        #   and `:coldline`, as well as the equivalent strings returned by
         #   {Bucket#storage_class}. For more information, see [Storage
         #   Classes](https://cloud.google.com/storage/docs/storage-classes). The
-        #   default value is `:standard`, which is equivalent to
+        #   default value is the Standard storage class, which is equivalent to
         #   `:multi_regional` or `:regional` depending on the bucket's location
         #   settings.
         # @param [Boolean] versioning Whether [Object
@@ -313,12 +320,13 @@ module Google
                           website_main: nil, website_404: nil, versioning: nil
           new_bucket = Google::Apis::StorageV1::Bucket.new({
             name: bucket_name,
-            location: location,
-            storage_class: storage_class_for(storage_class)
+            location: location
           }.delete_if { |_, v| v.nil? })
+          storage_class = storage_class_for(storage_class)
           updater = Bucket::Updater.new(new_bucket).tap do |b|
             b.logging_bucket = logging_bucket unless logging_bucket.nil?
             b.logging_prefix = logging_prefix unless logging_prefix.nil?
+            b.storage_class = storage_class unless storage_class.nil?
             b.website_main = website_main unless website_main.nil?
             b.website_404 = website_404 unless website_404.nil?
             b.versioning = versioning unless versioning.nil?

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

@@ -326,9 +326,11 @@ module Google
 
         ##
         # Permanently deletes a file.
-        def delete_file bucket_name, file_path, user_project: nil
+        def delete_file bucket_name, file_path, generation: nil,
+                        user_project: nil
           execute do
             service.delete_object bucket_name, file_path,
+                                  generation: generation,
                                   user_project: user_project(user_project)
           end
         end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.3.0"
+      VERSION = "1.4.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-11 00:00:00.000000000 Z
+date: 2017-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core