google-cloud-storage 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38b2256d0194e6d5fbedc19e638b2b57dab8038a9f93a3019538d2eb56b740c4
-  data.tar.gz: 10f4915478a797f777cb64a1cfafa6b841c0590a89f3c8d5784e153a13b8a885
+  metadata.gz: aa3b7db1df4e7dfaf4f531dc12faf2245d7d9d18107e9dbad1877520df131939
+  data.tar.gz: 5ff65a195b17e9a52eccd0787cba142153fb24347984b3453cd2ce2e295b6b92
 SHA512:
-  metadata.gz: 8d0a5be11ac43e57988db525cad4bf2d006d053a0d69b2ed1c017f71771771017f6e9acc190811b2d575c305971f3ecac736082eac399aff9bea62a9d730cdba
-  data.tar.gz: f412a33c819aace6190dfff910df58fe2708b15f2680c8d2749092b860d980d85156e02ebc97a9f7474de90b2f19e67b6c463acd0012c085465225ad7be3e9be
+  metadata.gz: c372dc40320fa3ac1561b804c3cafc591ce51e3c6fb299709b30282a7f13e2bceb34fa30cbe913a39d723cbdbce8ef77b4adeaea9f40971a4cff1993912144f9
+  data.tar.gz: 3122a76ab51e4604fcb44e53cf1e784bacbabbfd5086448493c1a1a48416cdf43f37bad23517ac369d67e465734e66f864510b6302d9b8f129c6259e40cb6583

data/LICENSE

@@ -1,6 +1,6 @@
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -192,7 +192,7 @@
    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
+       https://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,

data/lib/google-cloud-storage.rb

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2016 Google LLC
 #
 # 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
+#     https://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,
@@ -20,6 +20,8 @@
 
 gem "google-cloud-core"
 require "google/cloud"
+require "google/cloud/config"
+require "googleauth"
 
 module Google
   module Cloud
@@ -114,3 +116,26 @@ module Google
     end
   end
 end
+
+# Set the default storage configuration
+Google::Cloud.configure.add_config! :storage do |config|
+  default_project = Google::Cloud::Config.deferred do
+    ENV["STORAGE_PROJECT"]
+  end
+  default_creds = Google::Cloud::Config.deferred do
+    Google::Cloud::Config.credentials_from_env(
+      "STORAGE_CREDENTIALS", "STORAGE_CREDENTIALS_JSON",
+      "STORAGE_KEYFILE", "STORAGE_KEYFILE_JSON"
+    )
+  end
+
+  config.add_field! :project_id, default_project, match: String, allow_nil: true
+  config.add_alias! :project, :project_id
+  config.add_field! :credentials, default_creds,
+                    match: [String, Hash, Google::Auth::Credentials],
+                    allow_nil: true
+  config.add_alias! :keyfile, :credentials
+  config.add_field! :scope, nil, match: [String, Array]
+  config.add_field! :retries, nil, match: Integer
+  config.add_field! :timeout, nil, match: Integer
+end

data/lib/google/cloud/storage.rb

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,
@@ -15,6 +15,8 @@
 
 require "google-cloud-storage"
 require "google/cloud/storage/project"
+require "google/cloud/config"
+require "google/cloud/env"
 
 module Google
   module Cloud
@@ -27,11 +29,14 @@ module Google
     # networking infrastructure to perform data operations in a cost effective
     # manner.
     #
-    # The goal of google-cloud is to provide a API that is comfortable to
-    # Rubyists. Authentication is handled by {Google::Cloud#storage}. You can
-    # provide the project and credential information to connect to the Storage
-    # service, or if you are running on Google Compute Engine this configuration
-    # is taken care of for you.
+    # The goal of google-cloud is to provide an API that is comfortable to
+    # Rubyists. Your authentication credentials are detected automatically in
+    # Google Cloud Platform environments such as Google Compute Engine, Google
+    # App Engine and Google Kubernetes Engine. In other environments you can
+    # configure authentication easily, either directly in your code or via
+    # environment variables. Read more about the options for connecting in the
+    # [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
     # ```ruby
     # require "google/cloud/storage"
@@ -334,6 +339,44 @@ module Google
     # downloaded.read #=> "Hello world!"
     # ```
     #
+    # ## Creating and downloading gzip-encoded files
+    #
+    # When uploading a gzip-compressed file, you should pass
+    # `content_encoding: "gzip"` if you want the file to be eligible for
+    # [decompressive transcoding](https://cloud.google.com/storage/docs/transcoding)
+    # when it is later downloaded. In addition, giving the gzip-compressed file
+    # a name containing the original file extension (for example, `.txt`) will
+    # ensure that the file's `Content-Type` metadata is set correctly. (You can
+    # also set the file's `Content-Type` metadata explicitly with the
+    # `content_type` option.)
+    #
+    # ```ruby
+    # require "zlib"
+    # require "google/cloud/storage"
+    #
+    # storage = Google::Cloud::Storage.new
+    #
+    # gz = StringIO.new ""
+    # z = Zlib::GzipWriter.new gz
+    # z.write "Hello world!"
+    # z.close
+    # data = StringIO.new gz.string
+    #
+    # bucket = storage.bucket "my-bucket"
+    #
+    # bucket.create_file data, "path/to/gzipped.txt",
+    #                    content_encoding: "gzip"
+    #
+    # file = bucket.file "path/to/gzipped.txt"
+    #
+    # # The downloaded data is decompressed by default.
+    # file.download "path/to/downloaded/hello.txt"
+    #
+    # # The downloaded data remains compressed with skip_decompress.
+    # file.download "path/to/downloaded/gzipped.txt",
+    #               skip_decompress: true
+    # ```
+    #
     # ## Using Signed URLs
     #
     # Access without authentication can be granted to a file for a specified
@@ -604,18 +647,23 @@ module Google
       #
       def self.new project_id: nil, credentials: nil, scope: nil, retries: nil,
                    timeout: nil, project: nil, keyfile: nil
-        project_id ||= (project || Storage::Project.default_project_id)
+        project_id ||= (project || default_project_id)
         project_id = project_id.to_s # Always cast to a string
-        fail ArgumentError, "project_id is missing" if project_id.empty?
+        raise ArgumentError, "project_id is missing" if project_id.empty?
 
-        credentials ||= (keyfile || Storage::Credentials.default(scope: scope))
+        scope ||= configure.scope
+        retries ||= configure.retries
+        timeout ||= configure.timeout
+        credentials ||= (keyfile || default_credentials(scope: scope))
         unless credentials.is_a? Google::Auth::Credentials
           credentials = Storage::Credentials.new credentials, scope: scope
         end
 
         Storage::Project.new(
           Storage::Service.new(
-            project_id, credentials, retries: retries, timeout: timeout))
+            project_id, credentials, retries: retries, timeout: timeout
+          )
+        )
       end
 
       ##
@@ -645,6 +693,48 @@ module Google
           Storage::Service.new(nil, nil, retries: retries, timeout: timeout)
         )
       end
+
+      ##
+      # Configure the Google Cloud Storage library.
+      #
+      # The following Storage configuration parameters are supported:
+      #
+      # * `project_id` - (String) Identifier for a Storage project. (The
+      #   parameter `project` is considered deprecated, but may also be used.)
+      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {Storage::Credentials}) (The
+      #   parameter `keyfile` is considered deprecated, but may also be used.)
+      # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
+      #   the set of resources and operations that the connection can access.
+      # * `retries` - (Integer) Number of times to retry requests on server
+      #   error.
+      # * `timeout` - (Integer) Default timeout to use in requests.
+      #
+      # @return [Google::Cloud::Config] The configuration object the
+      #   Google::Cloud::Storage library uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.storage if block_given?
+
+        Google::Cloud.configure.storage
+      end
+
+      ##
+      # @private Default project.
+      def self.default_project_id
+        Google::Cloud.configure.storage.project_id ||
+          Google::Cloud.configure.project_id ||
+          Google::Cloud.env.project_id
+      end
+
+      ##
+      # @private Default credentials.
+      def self.default_credentials scope: nil
+        Google::Cloud.configure.storage.credentials ||
+          Google::Cloud.configure.credentials ||
+          Storage::Credentials.default(scope: scope)
+      end
     end
   end
 end

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

@@ -1,10 +1,10 @@
-# Copyright 2014 Google Inc. All rights reserved.
+# Copyright 2014 Google LLC
 #
 # 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
+#     https://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,
@@ -349,7 +349,7 @@ module Google
         def requester_pays
           @gapi.billing.requester_pays if @gapi.billing
         end
-        alias_method :requester_pays?, :requester_pays
+        alias requester_pays? requester_pays
 
         ##
         # Enables requester pays for the bucket. If enabled, a client accessing
@@ -508,7 +508,7 @@ module Google
           File::List.from_gapi gapi, service, name, prefix, delimiter, max,
                                versions, user_project: user_project
         end
-        alias_method :find_files, :files
+        alias find_files files
 
         ##
         # Retrieves a file matching the path.
@@ -557,7 +557,7 @@ module Google
         rescue Google::Cloud::NotFoundError
           nil
         end
-        alias_method :find_file, :file
+        alias find_file file
 
         ##
         # Creates a new {File} object by providing a path to a local file (or
@@ -608,7 +608,12 @@ module Google
         #   response header to be returned when the file is downloaded.
         # @param [String] 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.
+        #   header to be returned when the file is downloaded. For example,
+        #   `content_encoding: "gzip"` can indicate to clients that the uploaded
+        #   data is gzip-compressed. However, there is no check to guarantee the
+        #   specified `Content-Encoding` has actually been applied to the file
+        #   data, and incorrectly specifying the file's encoding could lead
+        #   to unintended behavior on subsequent download requests.
         # @param [String] content_language The
         #   [Content-Language](http://tools.ietf.org/html/bcp47) response
         #   header to be returned when the file is downloaded.
@@ -682,6 +687,32 @@ module Google
         #   file = bucket.file "destination/path/file.ext",
         #                      encryption_key: key
         #
+        # @example Create a file with gzip-encoded data.
+        #   require "zlib"
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   gz = StringIO.new ""
+        #   z = Zlib::GzipWriter.new gz
+        #   z.write "Hello world!"
+        #   z.close
+        #   data = StringIO.new gz.string
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.create_file data, "path/to/gzipped.txt",
+        #                      content_encoding: "gzip"
+        #
+        #   file = bucket.file "path/to/gzipped.txt"
+        #
+        #   # The downloaded data is decompressed by default.
+        #   file.download "path/to/downloaded/hello.txt"
+        #
+        #   # The downloaded data remains compressed with skip_decompress.
+        #   file.download "path/to/downloaded/gzipped.txt",
+        #                 skip_decompress: true
+        #
         def create_file file, path = nil, acl: nil, cache_control: nil,
                         content_disposition: nil, content_encoding: nil,
                         content_language: nil, content_type: nil,
@@ -698,13 +729,13 @@ module Google
           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?
+          raise ArgumentError, "must provide path" if path.nil?
 
           gapi = service.insert_file name, file, path, options
           File.from_gapi gapi, service, user_project: user_project
         end
-        alias_method :upload_file, :create_file
-        alias_method :new_file, :create_file
+        alias upload_file create_file
+        alias new_file create_file
 
         ##
         # Concatenates a list of existing files in the bucket into a new file in
@@ -796,7 +827,7 @@ module Google
           ensure_service!
           sources = Array sources
           if sources.size < 2
-            fail ArgumentError, "must provide at least two source files"
+            raise ArgumentError, "must provide at least two source files"
           end
 
           options = { acl: File::Acl.predefined_rule_for(acl),
@@ -813,8 +844,8 @@ module Google
                                       destination_gapi, options
           File.from_gapi gapi, service, user_project: user_project
         end
-        alias_method :compose_file, :compose
-        alias_method :combine, :compose
+        alias compose_file compose
+        alias combine compose
 
         ##
         # Access without authentication can be granted to a File for a specified
@@ -1166,7 +1197,7 @@ module Google
           policy = Policy.from_gapi gapi
           return policy unless block_given?
           yield policy
-          self.policy = policy
+          update_policy policy
         end
 
         ##
@@ -1199,14 +1230,15 @@ module Google
         #
         #   policy.add "roles/owner", "user:owner@example.com"
         #
-        #   bucket.policy = policy # API call
+        #   bucket.update_policy policy # API call
         #
-        def policy= new_policy
+        def update_policy new_policy
           ensure_service!
           gapi = service.set_bucket_policy name, new_policy.to_gapi,
                                            user_project: user_project
           Policy.from_gapi gapi
         end
+        alias policy= update_policy
 
         ##
         # Tests the specified permissions against the [Cloud
@@ -1270,7 +1302,7 @@ module Google
                                    user_project: user_project
           end
         end
-        alias_method :find_notifications, :notifications
+        alias find_notifications notifications
 
         ##
         # Retrieves a Pub/Sub notification subscription for the bucket.
@@ -1300,7 +1332,7 @@ module Google
         rescue Google::Cloud::NotFoundError
           nil
         end
-        alias_method :find_notification, :notification
+        alias find_notification notification
 
 
         ##
@@ -1381,7 +1413,7 @@ module Google
           gapi = service.insert_notification name, topic, options
           Notification.from_gapi name, gapi, service, user_project: user_project
         end
-        alias_method :new_notification, :create_notification
+        alias new_notification create_notification
 
         ##
         # Reloads the bucket with current data from the Storage service.
@@ -1392,7 +1424,7 @@ module Google
           @lazy = nil
           self
         end
-        alias_method :refresh!, :reload!
+        alias refresh! reload!
 
         ##
         # Determines whether the bucket exists in the Storage service.
@@ -1442,7 +1474,7 @@ module Google
         ##
         # Raise an error unless an active service is available.
         def ensure_service!
-          fail "Must have active connection" unless service
+          raise "Must have active connection" unless service
         end
 
         ##
@@ -1472,7 +1504,7 @@ module Google
         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}"
+          raise ArgumentError, "cannot find file #{file}"
         end
 
         def storage_class_for str

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

@@ -1,10 +1,10 @@
-# Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2015 Google LLC
 #
 # 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
+#     https://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,
@@ -46,7 +46,7 @@ module Google
                     "public" => "publicRead",
                     "public_read" => "publicRead",
                     "publicReadWrite" => "publicReadWrite",
-                    "public_write" => "publicReadWrite" }
+                    "public_write" => "publicReadWrite" }.freeze
 
           ##
           # A boolean value or a project ID string to indicate the project to
@@ -98,7 +98,7 @@ module Google
             @writers = entities_from_acls acls, "WRITER"
             @readers = entities_from_acls acls, "READER"
           end
-          alias_method :refresh!, :reload!
+          alias refresh! reload!
 
           ##
           # Lists the owners of the bucket.
@@ -344,10 +344,10 @@ module Google
           def auth!
             update_predefined_acl! "authenticatedRead"
           end
-          alias_method :authenticatedRead!, :auth!
-          alias_method :auth_read!, :auth!
-          alias_method :authenticated!, :auth!
-          alias_method :authenticated_read!, :auth!
+          alias authenticatedRead! auth!
+          alias auth_read! auth!
+          alias authenticated! auth!
+          alias authenticated_read! auth!
 
           ##
           # Convenience method to apply the `private` predefined ACL
@@ -382,7 +382,7 @@ module Google
           def project_private!
             update_predefined_acl! "projectPrivate"
           end
-          alias_method :projectPrivate!, :project_private!
+          alias projectPrivate! project_private!
 
           ##
           # Convenience method to apply the `publicRead` predefined ACL
@@ -400,8 +400,8 @@ module Google
           def public!
             update_predefined_acl! "publicRead"
           end
-          alias_method :publicRead!, :public!
-          alias_method :public_read!, :public!
+          alias publicRead! public!
+          alias public_read! public!
 
           # Convenience method to apply the `publicReadWrite` predefined ACL
           # rule to the bucket.
@@ -418,7 +418,7 @@ module Google
           def public_write!
             update_predefined_acl! "publicReadWrite"
           end
-          alias_method :publicReadWrite!, :public_write!
+          alias publicReadWrite! public_write!
 
           protected
 
@@ -472,7 +472,7 @@ module Google
                     "project_private" => "projectPrivate",
                     "publicRead" => "publicRead",
                     "public" => "publicRead",
-                    "public_read" => "publicRead" }
+                    "public_read" => "publicRead" }.freeze
 
           ##
           # A boolean value or a project ID string to indicate the project to
@@ -521,13 +521,13 @@ module Google
                                               user_project: user_project
             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
+              raise "Unknown ACL format: #{acl.class}" unless acl.is_a? Hash
               Google::Apis::StorageV1::ObjectAccessControl.from_json acl.to_json
             end
             @owners  = entities_from_acls acls, "OWNER"
             @readers = entities_from_acls acls, "READER"
           end
-          alias_method :refresh!, :reload!
+          alias refresh! reload!
 
           ##
           # Lists the default owners for files in the bucket.
@@ -710,10 +710,10 @@ module Google
           def auth!
             update_predefined_default_acl! "authenticatedRead"
           end
-          alias_method :authenticatedRead!, :auth!
-          alias_method :auth_read!, :auth!
-          alias_method :authenticated!, :auth!
-          alias_method :authenticated_read!, :auth!
+          alias authenticatedRead! auth!
+          alias auth_read! auth!
+          alias authenticated! auth!
+          alias authenticated_read! auth!
 
           ##
           # Convenience method to apply the default `bucketOwnerFullControl`
@@ -731,7 +731,7 @@ module Google
           def owner_full!
             update_predefined_default_acl! "bucketOwnerFullControl"
           end
-          alias_method :bucketOwnerFullControl!, :owner_full!
+          alias bucketOwnerFullControl! owner_full!
 
           ##
           # Convenience method to apply the default `bucketOwnerRead`
@@ -749,7 +749,7 @@ module Google
           def owner_read!
             update_predefined_default_acl! "bucketOwnerRead"
           end
-          alias_method :bucketOwnerRead!, :owner_read!
+          alias bucketOwnerRead! owner_read!
 
           ##
           # Convenience method to apply the default `private`
@@ -784,7 +784,7 @@ module Google
           def project_private!
             update_predefined_default_acl! "projectPrivate"
           end
-          alias_method :projectPrivate!, :project_private!
+          alias projectPrivate! project_private!
 
           ##
           # Convenience method to apply the default `publicRead`
@@ -802,8 +802,8 @@ module Google
           def public!
             update_predefined_default_acl! "publicRead"
           end
-          alias_method :publicRead!, :public!
-          alias_method :public_read!, :public!
+          alias publicRead! public!
+          alias public_read! public!
 
           protected