gcloud 0.1.1 → 0.2.0

data/lib/gcloud/storage/credentials.rb

@@ -18,7 +18,7 @@ require "gcloud/credentials"
 module Gcloud
   module Storage
     ##
-    # Represents the Oauth2 signing logic for Storage.
+    # Represents the OAuth 2.0 signing logic for Storage.
     class Credentials < Gcloud::Credentials #:nodoc:
       SCOPE = ["https://www.googleapis.com/auth/devstorage.full_control"]
       PATH_ENV_VARS = %w(STORAGE_KEYFILE GOOGLE_CLOUD_KEYFILE)

data/lib/gcloud/storage/errors.rb

@@ -82,5 +82,13 @@ module Gcloud
         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 < Error
+    end
   end
 end

data/lib/gcloud/storage/file.rb

@@ -24,13 +24,14 @@ module Gcloud
     #
     # Represents the File/Object that belong to a Bucket.
     #
-    #   require "glcoud/storage"
+    #   require "gcloud"
     #
-    #   storage = Gcloud.storage
+    #   gcloud = Gcloud.new
+    #   storage = gcloud.storage
     #
-    #   bucket = storage.find_bucket "my-bucket"
+    #   bucket = storage.bucket "my-bucket"
     #
-    #   file = bucket.find_file "path/to/my-file.ext"
+    #   file = bucket.file "path/to/my-file.ext"
     #   file.download "/downloads/#{bucket.name}/#{file.name}"
     #
     class File
@@ -138,16 +139,16 @@ module Gcloud
       #   The path on the local file system to write the data to.
       #   The path provided must be writable. (+String+)
       # +options+::
-      #   An optional Hash for controlling additional behavor. (+Hash+)
-      # +options [:verify]+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:verify]</code>::
       #   The verification algoruthm used to ensure the downloaded file contents
       #   are correct. Default is +:md5+. (+Symbol+)
       #
       #   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.
+      #   * +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.
       #
       # === Returns
       #
@@ -155,47 +156,51 @@ module Gcloud
       #
       # === Examples
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext"
       #
       # The download is verified by calculating the MD5 digest.
       # The CRC32c digest can be used by passing :crc32c.
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :crc32c
       #
       # Both the MD5 and CRC32c digest can be used by passing :all.
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :all
       #
       # The download verification can be disabled by passing :none
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.download "path/to/downloaded/file.ext", verify: :none
       #
       def download path, options = {}
@@ -223,23 +228,23 @@ module Gcloud
       #   If a bucket was provided in the first parameter, this contains the
       #   path to copy the file to in the given bucket. (+String+)
       # +options+::
-      #   An optional Hash for controlling additional behavor. (+Hash+)
-      # +options [:acl]+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:acl]</code>::
       #   A predefined set of access controls to apply to new file.
       #   (+String+)
       #
       #   Acceptable values are:
       #   * +auth+, +auth_read+, +authenticated+, +authenticated_read+,
-      #     +authenticatedRead+:: File owner gets OWNER access, and
+      #     +authenticatedRead+ - File owner gets OWNER access, and
       #     allAuthenticatedUsers get READER access.
-      #   * +owner_full+, +bucketOwnerFullControl+:: File owner gets OWNER
+      #   * +owner_full+, +bucketOwnerFullControl+ - File owner gets OWNER
       #     access, and project team owners get OWNER access.
-      #   * +owner_read+, +bucketOwnerRead+:: File owner gets OWNER access, and
+      #   * +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,
+      #   * +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
+      #   * +public+, +public_read+, +publicRead+ - File owner gets OWNER
       #     access, and allUsers get READER access.
       #
       # === Returns
@@ -250,24 +255,26 @@ module Gcloud
       #
       # The file can also be copied to a new path in the current bucket:
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.copy "path/to/destination/file.ext"
       #
       # The file can also be copied to a different bucket:
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.copy "new-destination-bucket",
       #             "path/to/destination/file.ext"
       #
@@ -294,13 +301,14 @@ module Gcloud
       #
       # === Example
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.delete
       #
       def delete
@@ -321,46 +329,77 @@ module Gcloud
       # }[https://cloud.google.com/storage/docs/access-control#Signed-URLs]
       # for more.
       #
+      # Generating a URL requires service account credentials, either by
+      # connecting with a service account when calling Gcloud.storage, or by
+      # passing in the service account +issuer+ and +signing_key+ values. 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].
+      #
       # === Parameters
       #
       # +options+::
-      #   An optional Hash for controlling additional behavor. (+Hash+)
-      # +options [:method]+::
+      #   An optional Hash for controlling additional behavior. (+Hash+)
+      # <code>options[:method]</code>::
       #   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+.
       #   (+String+)
-      # +options [:expires]+::
+      # <code>options[:expires]</code>::
       #   The number of seconds until the URL expires. Default is 300/5 minutes.
       #   (+Integer+)
-      # +options [:content_type]+::
+      # <code>options[:content_type]</code>::
       #   When provided, the client (browser) must send this value in the
       #   HTTP header. e.g. +text/plain+ (+String+)
-      # +options [:content_md5]+::
+      # <code>options[:content_md5]</code>::
       #   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. (+String+)
+      # <code>options[:issuer]</code>::
+      #   Service Account's Client Email. (+String+)
+      # <code>options[:signing_key]</code>::
+      #   Service Account's Private Key. (+OpenSSL::PKey::RSA+ or +String+)
       #
       # === Examples
       #
-      #   require "gcloud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-todo-app"
-      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   bucket = storage.bucket "my-todo-app"
+      #   file = bucket.file "avatars/heidi/400x400.png"
       #   shared_url = file.signed_url
       #
       # Any of the option parameters may be specified:
       #
-      #   require "gcloud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-todo-app"
-      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   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
       #
+      # Signed URLs require service account credentials. If you are not
+      # authenticated with a service account, those credentials can be passed in
+      # using the +issuer+ and +signing_key+ options. 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+.
+      #
+      #   require "gcloud/storage"
+      #
+      #   storage = Gcloud.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 options = {}
         ensure_connection!
         signer = File::Signer.new self
@@ -382,12 +421,13 @@ module Gcloud
       # Access to a file can be granted to a user by appending +"user-"+ to the
       # email address:
       #
-      #   require "gcloud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-todo-app"
-      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   bucket = storage.bucket "my-todo-app"
+      #   file = bucket.file "avatars/heidi/400x400.png"
       #
       #   email = "heidi@example.net"
       #   file.acl.add_reader "user-#{email}"
@@ -395,12 +435,13 @@ module Gcloud
       # Access to a file can be granted to a group by appending +"group-"+ to
       # the email address:
       #
-      #   require "gcloud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-todo-app"
-      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   bucket = storage.bucket "my-todo-app"
+      #   file = bucket.file "avatars/heidi/400x400.png"
       #
       #   email = "authors@example.net"
       #   file.acl.add_reader "group-#{email}"
@@ -408,12 +449,13 @@ module Gcloud
       # Access to a file can also be granted to a predefined list of
       # permissions:
       #
-      #   require "gcloud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-todo-app"
-      #   file = bucket.find_file "avatars/heidi/400x400.png"
+      #   bucket = storage.bucket "my-todo-app"
+      #   file = bucket.file "avatars/heidi/400x400.png"
       #
       #   file.acl.public!
       #
@@ -489,21 +531,39 @@ module Gcloud
            ext_path].join "\n"
         end
 
-        def signing_key
-          @file.connection.credentials.signing_key
+        def determine_signing_key options = {}
+          options[:signing_key] || options[:private_key] ||
+            @file.connection.credentials.signing_key
         end
 
-        def issuer
-          @file.connection.credentials.issuer
+        def determine_issuer options = {}
+          options[:issuer] || options[:client_email] ||
+            @file.connection.credentials.issuer
         end
 
         def signed_url options
           options = apply_option_defaults options
-          signed_string = signing_key.sign OpenSSL::Digest::SHA256.new,
-                                           signature_str(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.encode64(signed_string).gsub("\n", "")
           "#{ext_url}?GoogleAccessId=#{CGI.escape issuer}" \
-                    "&Expires=#{options[:expires]}" \
+                    "&Expires=#{expires}" \
                     "&Signature=#{CGI.escape signature}"
         end
       end

data/lib/gcloud/storage/file/acl.rb

@@ -21,13 +21,14 @@ module Gcloud
       #
       # Represents a File's Access Control List.
       #
-      #   require "glcoud/storage"
+      #   require "gcloud"
       #
-      #   storage = Gcloud.storage
+      #   gcloud = Gcloud.new
+      #   storage = gcloud.storage
       #
-      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket = storage.bucket "my-bucket"
       #
-      #   file = bucket.find_file "path/to/my-file.ext"
+      #   file = bucket.file "path/to/my-file.ext"
       #   file.acl.readers.each { |reader| puts reader }
       #
       class Acl
@@ -64,13 +65,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.refresh!
         #
         def refresh!
@@ -90,13 +92,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.owners.each { |owner| puts owner }
         #
         def owners
@@ -113,13 +116,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.writers.each { |writer| puts writer }
         #
         def writers
@@ -136,13 +140,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.readers.each { |reader| puts reader }
         #
         def readers
@@ -169,8 +174,8 @@ module Gcloud
         #   * allAuthenticatedUsers
         #
         # +options+::
-        #   An optional Hash for controlling additional behavor. (+Hash+)
-        # +options [:generation]+::
+        #   An optional Hash for controlling additional behavior. (+Hash+)
+        # <code>options[:generation]</code>::
         #   When present, selects a specific revision of this object.
         #   Default is the latest version. (+Integer+)
         #
@@ -179,26 +184,28 @@ module Gcloud
         # Access to a file can be granted to a user by appending +"user-"+ to
         # the email address:
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "heidi@example.net"
         #   file.acl.add_owner "user-#{email}"
         #
         # Access to a file can be granted to a group by appending +"group-"+ to
         # the email address:
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "authors@example.net"
         #   file.acl.add_owner "group-#{email}"
         #
@@ -232,8 +239,8 @@ module Gcloud
         #   * allAuthenticatedUsers
         #
         # +options+::
-        #   An optional Hash for controlling additional behavor. (+Hash+)
-        # +options [:generation]+::
+        #   An optional Hash for controlling additional behavior. (+Hash+)
+        # <code>options[:generation]</code>::
         #   When present, selects a specific revision of this object.
         #   Default is the latest version. (+Integer+)
         #
@@ -242,26 +249,28 @@ module Gcloud
         # Access to a file can be granted to a user by appending +"user-"+ to
         # the email address:
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "heidi@example.net"
         #   file.acl.add_writer "user-#{email}"
         #
         # Access to a file can be granted to a group by appending +"group-"+ to
         # the email address:
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "authors@example.net"
         #   file.acl.add_writer "group-#{email}"
         #
@@ -295,8 +304,8 @@ module Gcloud
         #   * allAuthenticatedUsers
         #
         # +options+::
-        #   An optional Hash for controlling additional behavor. (+Hash+)
-        # +options [:generation]+::
+        #   An optional Hash for controlling additional behavior. (+Hash+)
+        # <code>options[:generation]</code>::
         #   When present, selects a specific revision of this object.
         #   Default is the latest version. (+Integer+)
         #
@@ -305,26 +314,28 @@ module Gcloud
         # Access to a file can be granted to a user by appending +"user-"+ to
         # the email address:
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "heidi@example.net"
         #   file.acl.add_reader "user-#{email}"
         #
         # Access to a file can be granted to a group by appending +"group-"+ to
         # the email address:
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "authors@example.net"
         #   file.acl.add_reader "group-#{email}"
         #
@@ -358,20 +369,21 @@ module Gcloud
         #   * allAuthenticatedUsers
         #
         # +options+::
-        #   An optional Hash for controlling additional behavor. (+Hash+)
-        # +options [:generation]+::
+        #   An optional Hash for controlling additional behavior. (+Hash+)
+        # <code>options[:generation]</code>::
         #   When present, selects a specific revision of this object.
         #   Default is the latest version. (+Integer+)
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   email = "heidi@example.net"
         #   file.acl.delete "user-#{email}"
         #
@@ -398,13 +410,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.auth!
         #
         def auth!
@@ -421,13 +434,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.owner_full!
         #
         def owner_full!
@@ -441,13 +455,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.owner_read!
         #
         def owner_read!
@@ -461,13 +476,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.private!
         #
         def private!
@@ -480,13 +496,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.project_private!
         #
         def project_private!
@@ -500,13 +517,14 @@ module Gcloud
         #
         # === Example
         #
-        #   require "glcoud/storage"
+        #   require "gcloud"
         #
-        #   storage = Gcloud.storage
+        #   gcloud = Gcloud.new
+        #   storage = gcloud.storage
         #
-        #   bucket = storage.find_bucket "my-bucket"
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   file = bucket.find_file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext"
         #   file.acl.public!
         #
         def public!