google-cloud-storage 0.20.0

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

@@ -0,0 +1,157 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Storage
+      class Bucket
+        ##
+        # # Bucket Cors
+        #
+        # A special-case Array for managing the website CORS rules for a bucket.
+        # Accessed via {Bucket#cors}.
+        #
+        # @see https://cloud.google.com/storage/docs/cross-origin Cross-Origin
+        #   Resource Sharing (CORS)
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.cors do |c|
+        #     # Remove the last CORS rule from the array
+        #     c.pop
+        #     # Remove all existing rules with the https protocol
+        #     c.delete_if { |r| r.origin.include? "http://example.com" }
+        #     c.add_rule ["http://example.org", "https://example.org"],
+        #                ["GET", "POST", "DELETE"],
+        #                response_headers: ["X-My-Custom-Header"],
+        #                max_age: 3600
+        #   end
+        #
+        class Cors < DelegateClass(::Array)
+          ##
+          # @private Initialize a new CORS rules builder with existing CORS
+          # rules, if any.
+          def initialize rules = []
+            super rules
+            @original = to_gapi.map(&:to_json)
+          end
+
+          # @private
+          def changed?
+            @original != to_gapi.map(&:to_json)
+          end
+
+          ##
+          # Add a CORS rule to the CORS rules for a bucket. Accepts options for
+          # setting preflight response headers. Preflight requests and responses
+          # are required if the request method and headers are not both [simple
+          # methods](http://www.w3.org/TR/cors/#simple-method) and [simple
+          # headers](http://www.w3.org/TR/cors/#simple-header).
+          #
+          # @param [String, Array<String>] origin The
+          #   [origin](http://tools.ietf.org/html/rfc6454) or origins permitted
+          #   for cross origin resource sharing with the bucket. Note: "*" is
+          #   permitted in the list of origins, and means "any Origin".
+          # @param [String, Array<String>] methods The list of HTTP methods
+          #   permitted in cross origin resource sharing with the bucket. (GET,
+          #   OPTIONS, POST, etc) Note: "*" is permitted in the list of methods,
+          #   and means "any method".
+          # @param [String, Array<String>] headers The list of header field
+          #   names to send in the Access-Control-Allow-Headers header in the
+          #   preflight response. Indicates the custom request headers that may
+          #   be used in the actual request.
+          # @param [Integer] max_age The value to send in the
+          #   Access-Control-Max-Age header in the preflight response. Indicates
+          #   how many seconds the results of a preflight request can be cached
+          #   in a preflight result cache. The default value is `1800` (30
+          #   minutes.)
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.create_bucket "my-bucket" do |c|
+          #     c.add_rule ["http://example.org", "https://example.org"],
+          #                "*",
+          #                response_headers: ["X-My-Custom-Header"],
+          #                max_age: 300
+          #   end
+          #
+          def add_rule origin, methods, headers: nil, max_age: nil
+            push Rule.new(origin, methods, headers: headers, max_age: max_age)
+          end
+
+          # @private
+          def to_gapi
+            map(&:to_gapi)
+          end
+
+          # @private
+          def self.from_gapi gapi_list
+            rules = Array(gapi_list).map { |gapi| Rule.from_gapi gapi }
+            new rules
+          end
+
+          # @private
+          def freeze
+            each(&:freeze)
+            super
+          end
+
+          class Rule
+            attr_accessor :origin, :methods, :headers, :max_age
+
+            def initialize origin, methods, headers: nil, max_age: nil
+              @origin = Array(origin)
+              @methods = Array(methods)
+              @headers = Array(headers)
+              @max_age = (max_age||1800)
+            end
+
+            def to_gapi
+              Google::Apis::StorageV1::Bucket::CorsConfiguration.new(
+                origin: Array(origin).dup, http_method: Array(methods).dup,
+                response_header: Array(headers).dup, max_age_seconds: max_age
+              )
+            end
+
+            def self.from_gapi gapi
+              new gapi.origin.dup, gapi.http_method.dup, \
+                  headers: gapi.response_header.dup,
+                  max_age: gapi.max_age_seconds
+            end
+
+            def freeze
+              @origin.freeze
+              @methods.freeze
+              @headers.freeze
+              super
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Storage
+      class Bucket
+        ##
+        # Bucket::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more buckets
+          # that match the request and this value should be passed to
+          # the next {Google::Cloud::Storage::Project#buckets} to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Bucket::List with an array of values.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of buckets.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   buckets = storage.buckets
+          #   if buckets.next?
+          #     next_buckets = buckets.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of buckets.
+          #
+          # @return [Bucket::List]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   buckets = storage.buckets
+          #   if buckets.next?
+          #     next_buckets = buckets.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            options = { prefix: @prefix, token: @token, max: @max }
+            gapi = @service.list_buckets options
+            Bucket::List.from_gapi gapi, @service, @prefix, @max
+          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.
+          #
+          # 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.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all buckets. Default is no limit.
+          # @yield [bucket] The block for accessing each bucket.
+          # @yieldparam [Bucket] bucket The bucket object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each bucket by passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   buckets = storage.buckets
+          #   buckets.all do |bucket|
+          #     puts bucket.name
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   buckets = storage.buckets
+          #   all_names = buckets.all.map do |bucket|
+          #     bucket.name
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   buckets = storage.buckets
+          #   buckets.all(request_limit: 10) do |bucket|
+          #     puts bucket.name
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for(:all, request_limit: request_limit)
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Bucket::List from a Google API Client
+          # Google::Apis::StorageV1::Buckets object.
+          def self.from_gapi gapi_list, service, prefix = nil, max = nil
+            buckets = new(Array(gapi_list.items).map do |gapi_object|
+              Bucket.from_gapi gapi_object, service
+            end)
+            buckets.instance_variable_set :@token, gapi_list.next_page_token
+            buckets.instance_variable_set :@service, service
+            buckets.instance_variable_set :@prefix, prefix
+            buckets.instance_variable_set :@max, max
+            buckets
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active connection is available.
+          def ensure_service!
+            fail "Must have active connection" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# Copyright 2014 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 "google/cloud/credentials"
+
+module Google
+  module Cloud
+    module Storage
+      ##
+      # @private Represents the OAuth 2.0 signing logic for Storage.
+      class Credentials < Google::Cloud::Credentials
+        SCOPE = ["https://www.googleapis.com/auth/devstorage.full_control"]
+        PATH_ENV_VARS = %w(STORAGE_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(STORAGE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+                           GCLOUD_KEYFILE_JSON)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# Copyright 2014 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 "google/cloud/errors"
+
+module Google
+  module Cloud
+    module Storage
+      ##
+      # # FileVerificationError
+      #
+      # Raised when a File download fails the verification.
+      class FileVerificationError < Google::Cloud::Error
+        ##
+        # The type of digest that failed verification,
+        # :md5 or :crc32c.
+        attr_accessor :type
+
+        ##
+        # The value of the digest on the google-cloud file.
+        attr_accessor :gcloud_digest
+
+        ##
+        # The value of the digest on the downloaded file.
+        attr_accessor :local_digest
+
+        # @private
+        def self.for_md5 gcloud_digest, local_digest
+          new("The downloaded file failed MD5 verification.").tap do |e|
+            e.type = :md5
+            e.gcloud_digest = gcloud_digest
+            e.local_digest = local_digest
+          end
+        end
+
+        # @private
+        def self.for_crc32c gcloud_digest, local_digest
+          new("The downloaded file failed CRC32c verification.").tap do |e|
+            e.type = :crc32c
+            e.gcloud_digest = gcloud_digest
+            e.local_digest = local_digest
+          end
+        end
+      end
+
+      ##
+      # # SignedUrlUnavailable Error
+      #
+      # This is raised when File#signed_url is unable to generate a URL due to
+      # missing credentials needed to create the URL.
+      class SignedUrlUnavailable < Google::Cloud::Error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,849 @@
+# Copyright 2014 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 "google/cloud/storage/file/acl"
+require "google/cloud/storage/file/list"
+require "google/cloud/storage/file/verifier"
+
+module Google
+  module Cloud
+    module Storage
+      ##
+      # # File
+      #
+      # Represents a File
+      # ([Object](https://cloud.google.com/storage/docs/json_api/v1/objects))
+      # that belongs to a {Bucket}. Files (Objects) are the individual pieces of
+      # data that you store in Google Cloud Storage. A file can be up to 5 TB in
+      # size. Files have two components: data and metadata. The data component
+      # is the data from an external file or other data source that you want to
+      # store in Google Cloud Storage. The metadata component is a collection of
+      # name-value pairs that describe various qualities of the data.
+      #
+      # @see https://cloud.google.com/storage/docs/concepts-techniques Concepts
+      #   and Techniques
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   storage = gcloud.storage
+      #
+      #   bucket = storage.bucket "my-bucket"
+      #
+      #   file = bucket.file "path/to/my-file.ext"
+      #   file.download "path/to/downloaded/file.ext"
+      #
+      class File
+        ##
+        # @private The Connection object.
+        attr_accessor :service
+
+        ##
+        # @private The Google API Client object.
+        attr_accessor :gapi
+
+        ##
+        # @private Create an empty File object.
+        def initialize
+          @service = nil
+          @gapi = Google::Apis::StorageV1::Object.new
+        end
+
+        ##
+        # The kind of item this is.
+        # For files, this is always storage#object.
+        def kind
+          @gapi.kind
+        end
+
+        ##
+        # The ID of the file.
+        def id
+          @gapi.id
+        end
+
+        ##
+        # The name of this file.
+        def name
+          @gapi.name
+        end
+
+        ##
+        # The name of the {Bucket} containing this file.
+        def bucket
+          @gapi.bucket
+        end
+
+        ##
+        # The content generation of this file.
+        # Used for object versioning.
+        def generation
+          @gapi.generation
+        end
+
+        ##
+        # The version of the metadata for this file at this generation.
+        # Used for preconditions and for detecting changes in metadata.
+        # A metageneration number is only meaningful in the context of a
+        # particular generation of a particular file.
+        def metageneration
+          @gapi.metageneration
+        end
+
+        ##
+        # A URL that can be used to access the file using the REST API.
+        def api_url
+          @gapi.self_link
+        end
+
+        ##
+        # A URL that can be used to download the file using the REST API.
+        def media_url
+          @gapi.media_link
+        end
+
+        ##
+        # Content-Length of the data in bytes.
+        def size
+          @gapi.size.to_i if @gapi.size
+        end
+
+        ##
+        # Creation time of the file.
+        def created_at
+          @gapi.time_created
+        end
+
+        ##
+        # The creation or modification time of the file.
+        # For buckets with versioning enabled, changing an object's
+        # metadata does not change this property.
+        def updated_at
+          @gapi.updated
+        end
+
+        ##
+        # MD5 hash of the data; encoded using base64.
+        def md5
+          @gapi.md5_hash
+        end
+
+        ##
+        # The CRC32c checksum of the data, as described in
+        # [RFC 4960, Appendix B](http://tools.ietf.org/html/rfc4960#appendix-B).
+        # Encoded using base64 in big-endian byte order.
+        def crc32c
+          @gapi.crc32c
+        end
+
+        ##
+        # HTTP 1.1 Entity tag for the file.
+        def etag
+          @gapi.etag
+        end
+
+        ##
+        # The [Cache-Control](https://tools.ietf.org/html/rfc7234#section-5.2)
+        # directive for the file data.
+        def cache_control
+          @gapi.cache_control
+        end
+
+        ##
+        # Updates the
+        # [Cache-Control](https://tools.ietf.org/html/rfc7234#section-5.2)
+        # directive for the file data.
+        def cache_control= cache_control
+          @gapi.cache_control = cache_control
+          patch_gapi! :cache_control
+        end
+
+        ##
+        # The [Content-Disposition](https://tools.ietf.org/html/rfc6266) of the
+        # file data.
+        def content_disposition
+          @gapi.content_disposition
+        end
+
+        ##
+        # Updates the [Content-Disposition](https://tools.ietf.org/html/rfc6266)
+        # of the file data.
+        def content_disposition= content_disposition
+          @gapi.content_disposition = content_disposition
+          patch_gapi! :content_disposition
+        end
+
+        ##
+        # The [Content-Encoding
+        # ](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file
+        # data.
+        def content_encoding
+          @gapi.content_encoding
+        end
+
+        ##
+        # Updates the [Content-Encoding
+        # ](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file
+        # data.
+        def content_encoding= content_encoding
+          @gapi.content_encoding = content_encoding
+          patch_gapi! :content_encoding
+        end
+
+        ##
+        # The [Content-Language](http://tools.ietf.org/html/bcp47) of the file
+        # data.
+        def content_language
+          @gapi.content_language
+        end
+
+        ##
+        # Updates the [Content-Language](http://tools.ietf.org/html/bcp47) of
+        # the file data.
+        def content_language= content_language
+          @gapi.content_language = content_language
+          patch_gapi! :content_language
+        end
+
+        ##
+        # The [Content-Type](https://tools.ietf.org/html/rfc2616#section-14.17)
+        # of the file data.
+        def content_type
+          @gapi.content_type
+        end
+
+        ##
+        # Updates the
+        # [Content-Type](https://tools.ietf.org/html/rfc2616#section-14.17) of
+        # the file data.
+        def content_type= content_type
+          @gapi.content_type = content_type
+          patch_gapi! :content_type
+        end
+
+        ##
+        # A hash of custom, user-provided web-safe keys and arbitrary string
+        # values that will returned with requests for the file as "x-goog-meta-"
+        # response headers.
+        def metadata
+          m = @gapi.metadata
+          m = m.to_h if m.respond_to? :to_h
+          m.dup.freeze
+        end
+
+        ##
+        # Updates the hash of custom, user-provided web-safe keys and arbitrary
+        # string values that will returned with requests for the file as
+        # "x-goog-meta-" response headers.
+        def metadata= metadata
+          @gapi.metadata = metadata
+          patch_gapi! :metadata
+        end
+
+        ##
+        # An [RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)
+        # Base64-encoded string of the SHA256 hash of the [customer-supplied
+        # encryption
+        # key](https://cloud.google.com/storage/docs/encryption#customer-supplied).
+        # You can use this SHA256 hash to uniquely identify the AES-256
+        # encryption key required to decrypt this file.
+        def encryption_key_sha256
+          return nil unless @gapi.customer_encryption
+          Base64.decode64 @gapi.customer_encryption.key_sha256
+        end
+
+        ##
+        # Updates the file with changes made in the given block in a single
+        # PATCH request. The following attributes may be set: {#cache_control=},
+        # {#content_disposition=}, {#content_encoding=}, {#content_language=},
+        # {#content_type=}, and {#metadata=}. The {#metadata} hash accessible in
+        # the block is completely mutable and will be included in the request.
+        #
+        # @yield [file] a block yielding a delegate object for updating the file
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.update do |f|
+        #     f.cache_control = "private, max-age=0, no-cache"
+        #     f.content_disposition = "inline; filename=filename.ext"
+        #     f.content_encoding = "deflate"
+        #     f.content_language = "de"
+        #     f.content_type = "application/json"
+        #     f.metadata["player"] = "Bob"
+        #     f.metadata["score"] = "10"
+        #   end
+        #
+        def update
+          updater = Updater.new gapi
+          yield updater
+          updater.check_for_changed_metadata!
+          patch_gapi! updater.updates unless updater.updates.empty?
+        end
+
+        ##
+        # Download the file's contents to a local file.
+        #
+        # By default, the download is verified by calculating the MD5 digest.
+        #
+        # If a [customer-supplied encryption
+        # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
+        # was used with {Bucket#create_file}, the `encryption_key` and
+        # `encryption_key_sha256` options 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
+        #   downloaded file contents are correct. Default is `:md5`.
+        #
+        #   Acceptable values are:
+        #
+        #   * `md5` - Verify file content match using the MD5 hash.
+        #   * `crc32c` - Verify file content match using the CRC32c hash.
+        #   * `all` - Perform all available file content verification.
+        #   * `none` - Don't perform file content verification.
+        #
+        # @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}. Must be provided if `encryption_key_sha256`
+        #   is provided.
+        # @param [String] encryption_key_sha256 Optional. The SHA256 hash of the
+        #   customer-supplied, AES-256 encryption key used to encrypt the file,
+        #   if one was provided to {Bucket#create_file}. Must be provided if
+        #   `encryption_key` is provided.
+        #
+        # @return [File] Returns a `::File` object on the local file system
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.download "path/to/downloaded/file.ext"
+        #
+        # @example Use the CRC32c digest by passing :crc32c.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.download "path/to/downloaded/file.ext", verify: :crc32c
+        #
+        # @example Use the MD5 and CRC32c digests by passing :all.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.download "path/to/downloaded/file.ext", verify: :all
+        #
+        # @example Disable the download verification by passing :none.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   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,
+                     encryption_key_sha256: nil
+          ensure_service!
+          service.download_file \
+            bucket, name, path,
+            key: encryption_key, key_sha256: encryption_key_sha256
+          verify_file! ::File.new(path), verify
+        end
+
+        ##
+        # Copy the file to a new location.
+        #
+        # If a [customer-supplied encryption
+        # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
+        # was used with {Bucket#create_file}, the `encryption_key` and
+        # `encryption_key_sha256` options must be provided.
+        #
+        # @param [String] dest_bucket_or_path Either the bucket to copy the file
+        #   to, or the path to copy 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 copy 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
+        #   copy. The default is the latest version.
+        # @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}. Must be provided if `encryption_key_sha256`
+        #   is provided.
+        # @param [String] encryption_key_sha256 Optional. The SHA256 hash of the
+        #   customer-supplied, AES-256 encryption key used to encrypt the file,
+        #   if one was provided to {Bucket#create_file}. Must be provided if
+        #   `encryption_key` is provided.
+        #
+        # @return [Google::Cloud::Storage::File]
+        #
+        # @example The file can be copied to a new path in the current bucket:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.copy "path/to/destination/file.ext"
+        #
+        # @example The file can also be copied to a different bucket:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.copy "new-destination-bucket",
+        #             "path/to/destination/file.ext"
+        #
+        # @example The file can also be copied by specifying a generation:
+        #   file.copy "copy/of/previous/generation/file.ext",
+        #             generation: 123456
+        #
+        def copy dest_bucket_or_path, dest_path = nil, acl: nil,
+                 generation: nil, encryption_key: nil,
+                 encryption_key_sha256: nil
+          ensure_service!
+          options = { acl: acl, generation: generation,
+                      key: encryption_key, key_sha256: encryption_key_sha256 }
+          dest_bucket, dest_path, options = fix_copy_args dest_bucket_or_path,
+                                                          dest_path, options
+
+          gapi = service.copy_file bucket, name,
+                                   dest_bucket, dest_path, options
+          File.from_gapi gapi, service
+        end
+
+        ##
+        # Permanently deletes the file.
+        #
+        # @return [Boolean] Returns `true` if the file was deleted.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #   file.delete
+        #
+        def delete
+          ensure_service!
+          service.delete_file bucket, name
+          true
+        end
+
+        ##
+        # Public URL to access the file. If the file is not public, requests to
+        # the URL will return an error. (See {File::Acl#public!} and
+        # {Bucket::DefaultAcl#public!}) To share a file that is not public see
+        # {#signed_url}.
+        #
+        # @see https://cloud.google.com/storage/docs/access-public-data
+        #   Accessing Public Data
+        #
+        # @param [String] protocol The protocol to use for the URL. Default is
+        #   `HTTPS`.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   public_url = file.public_url
+        #
+        # @example Generate the URL with a protocol other than HTTPS:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   public_url = file.public_url protocol: "http"
+        #
+        def public_url protocol: :https
+          "#{protocol}://storage.googleapis.com/#{bucket}/#{name}"
+        end
+        alias_method :url, :public_url
+
+        ##
+        # 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.
+        #
+        # 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] 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 [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"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   shared_url = file.signed_url
+        #
+        # @example Any of the option parameters may be specified:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   shared_url = file.signed_url method: "GET",
+        #                                expires: 300 # 5 minutes from now
+        #
+        # @example Using the `issuer` and `signing_key` options:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."
+        #   shared_url = file.signed_url issuer: "service-account@gcloud.com",
+        #                                signing_key: key
+        #
+        def signed_url method: nil, expires: nil, content_type: nil,
+                       content_md5: nil, issuer: nil, client_email: nil,
+                       signing_key: nil, private_key: nil
+          ensure_service!
+          options = { method: method, expires: expires,
+                      content_type: content_type, content_md5: content_md5,
+                      issuer: issuer, client_email: client_email,
+                      signing_key: signing_key, private_key: private_key }
+          signer = File::Signer.new self
+          signer.signed_url options
+        end
+
+        ##
+        # The {File::Acl} instance used to control access to the file.
+        #
+        # A file has owners, writers, and readers. Permissions can be granted to
+        # an individual user's email address, a group's email address,  as well
+        # as many predefined lists.
+        #
+        # @see https://cloud.google.com/storage/docs/access-control Access
+        #   Control guide
+        #
+        # @example Grant access to a user by prepending `"user-"` to an email:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #
+        #   email = "heidi@example.net"
+        #   file.acl.add_reader "user-#{email}"
+        #
+        # @example Grant access to a group by prepending `"group-"` to an email:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #
+        #   email = "authors@example.net"
+        #   file.acl.add_reader "group-#{email}"
+        #
+        # @example Or, grant access via a predefined permissions list:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   storage = gcloud.storage
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #
+        #   file.acl.public!
+        #
+        def acl
+          @acl ||= File::Acl.new self
+        end
+
+        ##
+        # Reloads the file with current data from the Storage service.
+        def reload!
+          ensure_service!
+          @gapi = service.get_file bucket, name
+        end
+        alias_method :refresh!, :reload!
+
+        ##
+        # @private URI of the location and file name in the format of
+        # <code>gs://my-bucket/file-name.json</code>.
+        def to_gs_url
+          "gs://#{bucket}/#{name}"
+        end
+
+        ##
+        # @private New File from a Google API Client object.
+        def self.from_gapi gapi, service
+          new.tap do |f|
+            f.gapi = gapi
+            f.service = service
+          end
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active service is available.
+        def ensure_service!
+          fail "Must have active connection" unless service
+        end
+
+        def patch_gapi! *attributes
+          attributes.flatten!
+          return if attributes.empty?
+          ensure_service!
+          patch_args = Hash[attributes.map do |attr|
+            [attr, @gapi.send(attr)]
+          end]
+          patch_gapi = Google::Apis::StorageV1::Object.new patch_args
+          @gapi = service.patch_file bucket, name, patch_gapi
+        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
+          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]
+        end
+
+        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
+          file
+        end
+
+        ##
+        # @private Create a signed_url for a file.
+        class Signer
+          def initialize file
+            @file = file
+          end
+
+          ##
+          # The external path to the file.
+          def ext_path
+            "/#{@file.bucket}/#{@file.name}"
+          end
+
+          ##
+          # The external url to the file.
+          def ext_url
+            "https://storage.googleapis.com#{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],
+             ext_path].join "\n"
+          end
+
+          def determine_signing_key options = {}
+            options[:signing_key] || options[:private_key] ||
+              @file.service.credentials.signing_key
+          end
+
+          def determine_issuer options = {}
+            options[:issuer] || options[:client_email] ||
+              @file.service.credentials.issuer
+          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, options
+            generate_signed_url i, sig, options[:expires]
+          end
+
+          def generate_signature signing_key, options = {}
+            unless signing_key.respond_to? :sign
+              signing_key = OpenSSL::PKey::RSA.new signing_key
+            end
+            signing_key.sign OpenSSL::Digest::SHA256.new, signature_str(options)
+          end
+
+          def generate_signed_url issuer, signed_string, expires
+            signature = Base64.strict_encode64(signed_string).delete("\n")
+            "#{ext_url}?GoogleAccessId=#{CGI.escape issuer}" \
+                      "&Expires=#{expires}" \
+                      "&Signature=#{CGI.escape signature}"
+          end
+        end
+
+        ##
+        # Yielded to a block to accumulate changes for a patch request.
+        class Updater < File
+          attr_reader :updates
+          ##
+          # Create an Updater object.
+          def initialize gapi
+            @updates = []
+            @gapi = gapi
+          end
+
+          ##
+          # A hash of custom, user-provided web-safe keys and arbitrary string
+          # values that will returned with requests for the file as
+          # "x-goog-meta-" response headers.
+          def metadata
+            # do not freeze metadata
+            @metadata ||= @gapi.metadata.to_h.dup
+          end
+
+          ##
+          # Updates the hash of custom, user-provided web-safe keys and
+          # arbitrary string values that will returned with requests for the
+          # file as "x-goog-meta-" response headers.
+          def metadata= metadata
+            @metadata = metadata
+            @gapi.metadata = @metadata
+            patch_gapi! :metadata
+          end
+
+          ##
+          # @private Make sure any metadata changes are saved
+          def check_for_changed_metadata!
+            return if @metadata == @gapi.metadata
+            @gapi.metadata = @metadata
+            patch_gapi! :metadata
+          end
+
+          protected
+
+          ##
+          # Queue up all the updates instead of making them.
+          def patch_gapi! attribute
+            @updates << attribute
+            @updates.uniq!
+          end
+        end
+      end
+    end
+  end
+end