google-cloud-storage 0.20.0

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

@@ -0,0 +1,429 @@
+# 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.
+
+
+module Google
+  module Cloud
+    module Storage
+      class File
+        ##
+        # # File Access Control List
+        #
+        # Represents a File's Access Control List.
+        #
+        # @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.acl.readers.each { |reader| puts reader }
+        #
+        class Acl
+          # @private
+          RULES = { "authenticatedRead" => "authenticatedRead",
+                    "auth" => "authenticatedRead",
+                    "auth_read" => "authenticatedRead",
+                    "authenticated" => "authenticatedRead",
+                    "authenticated_read" => "authenticatedRead",
+                    "bucketOwnerFullControl" => "bucketOwnerFullControl",
+                    "owner_full" => "bucketOwnerFullControl",
+                    "bucketOwnerRead" => "bucketOwnerRead",
+                    "owner_read" => "bucketOwnerRead",
+                    "private" => "private",
+                    "projectPrivate" => "projectPrivate",
+                    "project_private" => "projectPrivate",
+                    "publicRead" => "publicRead",
+                    "public" => "publicRead",
+                    "public_read" => "publicRead" }
+
+          ##
+          # @private Initialized a new Acl object.
+          # Must provide a valid Bucket object.
+          def initialize file
+            @bucket = file.bucket
+            @file = file.name
+            @service = file.service
+            @owners  = nil
+            @readers = nil
+          end
+
+          ##
+          # Reloads all Access Control List data for 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.acl.reload!
+          #
+          def reload!
+            gapi = @service.list_file_acls @bucket, @file
+            acls = Array(gapi.items).map do |acl|
+              if acl.is_a? Google::Apis::StorageV1::ObjectAccessControl
+                return acl
+              end
+              fail "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!
+
+          ##
+          # Lists the owners of the file.
+          #
+          # @return [Array<String>]
+          #
+          # @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.acl.owners.each { |owner| puts owner }
+          #
+          def owners
+            reload! if @owners.nil?
+            @owners
+          end
+
+          ##
+          # Lists the readers of the file.
+          #
+          # @return [Array<String>]
+          #
+          # @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.acl.readers.each { |reader| puts reader }
+          #
+          def readers
+            reload! if @readers.nil?
+            @readers
+          end
+
+          ##
+          # Grants owner permission to the file.
+          #
+          # @param [String] entity The entity holding the permission, in one of
+          #   the following forms:
+          #
+          #   * user-userId
+          #   * user-email
+          #   * group-groupId
+          #   * group-email
+          #   * domain-domain
+          #   * project-team-projectId
+          #   * allUsers
+          #   * allAuthenticatedUsers
+          #
+          # @param [Integer] generation When present, selects a specific
+          #   revision of this object. Default is the latest version.
+          #
+          # @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-bucket"
+          #
+          #   file = bucket.file "path/to/my-file.ext"
+          #   email = "heidi@example.net"
+          #   file.acl.add_owner "user-#{email}"
+          #
+          # @example Grant access to a group by prepending `"group-"` to email:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   file = bucket.file "path/to/my-file.ext"
+          #   email = "authors@example.net"
+          #   file.acl.add_owner "group-#{email}"
+          #
+          def add_owner entity, generation: nil
+            options = { generation: generation }
+            gapi = @service.insert_file_acl @bucket, @file, entity, "OWNER",
+                                            options
+            entity = gapi.entity
+            @owners.push entity unless @owners.nil?
+            entity
+          end
+
+          ##
+          # Grants reader permission to the file.
+          #
+          # @param [String] entity The entity holding the permission, in one of
+          #   the following forms:
+          #
+          #   * user-userId
+          #   * user-email
+          #   * group-groupId
+          #   * group-email
+          #   * domain-domain
+          #   * project-team-projectId
+          #   * allUsers
+          #   * allAuthenticatedUsers
+          #
+          # @param [Integer] generation When present, selects a specific
+          #   revision of this object. Default is the latest version.
+          #
+          # @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-bucket"
+          #
+          #   file = bucket.file "path/to/my-file.ext"
+          #   email = "heidi@example.net"
+          #   file.acl.add_reader "user-#{email}"
+          #
+          # @example Grant access to a group by prepending `"group-"` to email:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   file = bucket.file "path/to/my-file.ext"
+          #   email = "authors@example.net"
+          #   file.acl.add_reader "group-#{email}"
+          #
+          def add_reader entity, generation: nil
+            options = { generation: generation }
+            gapi = @service.insert_file_acl @bucket, @file, entity, "READER",
+                                            options
+            entity = gapi.entity
+            @readers.push entity unless @readers.nil?
+            entity
+          end
+
+          ##
+          # Permanently deletes the entity from the file's access control list.
+          #
+          # @param [String] entity The entity holding the permission, in one of
+          #   the following forms:
+          #
+          #   * user-userId
+          #   * user-email
+          #   * group-groupId
+          #   * group-email
+          #   * domain-domain
+          #   * project-team-projectId
+          #   * allUsers
+          #   * allAuthenticatedUsers
+          #
+          # @param [Integer] generation When present, selects a specific
+          #   revision of this object. Default is the latest version.
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   file = bucket.file "path/to/my-file.ext"
+          #   email = "heidi@example.net"
+          #   file.acl.delete "user-#{email}"
+          #
+          def delete entity, generation: nil
+            options = { generation: generation }
+            @service.delete_file_acl @bucket, @file, entity, options
+            @owners.delete entity  unless @owners.nil?
+            @readers.delete entity unless @readers.nil?
+            true
+          end
+
+          # @private
+          def self.predefined_rule_for rule_name
+            RULES[rule_name.to_s]
+          end
+
+          # Predefined ACL helpers
+
+          ##
+          # Convenience method to apply the `authenticatedRead` predefined ACL
+          # rule to 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.acl.auth!
+          #
+          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!
+
+          ##
+          # Convenience method to apply the `bucketOwnerFullControl` predefined
+          # ACL rule to 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.acl.owner_full!
+          #
+          def owner_full!
+            update_predefined_acl! "bucketOwnerFullControl"
+          end
+          alias_method :bucketOwnerFullControl!, :owner_full!
+
+          ##
+          # Convenience method to apply the `bucketOwnerRead` predefined ACL
+          # rule to 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.acl.owner_read!
+          #
+          def owner_read!
+            update_predefined_acl! "bucketOwnerRead"
+          end
+          alias_method :bucketOwnerRead!, :owner_read!
+
+          ##
+          # Convenience method to apply the `private` predefined ACL
+          # rule to 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.acl.private!
+          #
+          def private!
+            update_predefined_acl! "private"
+          end
+
+          ##
+          # Convenience method to apply the `projectPrivate` predefined ACL
+          # rule to 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.acl.project_private!
+          #
+          def project_private!
+            update_predefined_acl! "projectPrivate"
+          end
+          alias_method :projectPrivate!, :project_private!
+
+          ##
+          # Convenience method to apply the `publicRead` predefined ACL
+          # rule to 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.acl.public!
+          #
+          def public!
+            update_predefined_acl! "publicRead"
+          end
+          alias_method :publicRead!, :public!
+          alias_method :public_read!, :public!
+
+          protected
+
+          def clear!
+            @owners  = nil
+            @readers = nil
+            self
+          end
+
+          def update_predefined_acl! acl_role
+            patched_file = Google::Apis::StorageV1::Object.new acl: nil
+            @service.patch_file \
+              @bucket, @file, patched_file, predefined_acl: acl_role
+            clear!
+          end
+
+          def entities_from_acls acls, role
+            selected = acls.select { |acl| acl.role == role }
+            entities = selected.map(&:entity)
+            entities
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,193 @@
+# 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 File
+        ##
+        # File::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more files that match the
+          # request and this value should be passed to the next
+          # {Google::Cloud::Storage::Bucket#files} to continue.
+          attr_accessor :token
+
+          # The list of prefixes of objects matching-but-not-listed up to and
+          # including the requested delimiter.
+          attr_accessor :prefixes
+
+          ##
+          # @private Create a new File::List with an array of values.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of files.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #   files = bucket.files
+          #   if files.next?
+          #     next_files = files.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of files.
+          #
+          # @return [File::List]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #   files = bucket.files
+          #   if files.next?
+          #     next_files = files.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            options = {
+              prefix: @prefix, delimiter: @delimiter, token: @token, max: @max,
+              versions: @versions
+            }
+            gapi = @service.list_files @bucket, options
+            File::List.from_gapi gapi, @service, @bucket, @prefix,
+                                 @delimiter, @max, @versions
+          end
+
+          ##
+          # Retrieves all files by repeatedly loading {#next} until {#next?}
+          # returns `false`. Calls the given block once for each file, which is
+          # passed as the parameter.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method may make several API calls until all files 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 files. Default is no limit.
+          # @yield [file] The block for accessing each file.
+          # @yieldparam [File] file The file object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each file by passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #   files = bucket.files
+          #   files.all do |file|
+          #     puts file.name
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #   files = bucket.files
+          #
+          #   all_names = files.all.map do |file|
+          #     file.name
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   storage = gcloud.storage
+          #
+          #   bucket = storage.bucket "my-bucket"
+          #   files = bucket.files
+          #   files.all(request_limit: 10) do |file|
+          #     puts file.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 File::List from a Google API Client
+          # Google::Apis::StorageV1::Objects object.
+          def self.from_gapi gapi_list, service, bucket = nil, prefix = nil,
+                             delimiter = nil, max = nil, versions = nil
+            files = new(Array(gapi_list.items).map do |gapi_object|
+              File.from_gapi gapi_object, service
+            end)
+            files.instance_variable_set :@token, gapi_list.next_page_token
+            files.instance_variable_set :@prefixes, Array(gapi_list.prefixes)
+            files.instance_variable_set :@service, service
+            files.instance_variable_set :@bucket, bucket
+            files.instance_variable_set :@prefix, prefix
+            files.instance_variable_set :@delimiter, delimiter
+            files.instance_variable_set :@max, max
+            files.instance_variable_set :@versions, versions
+            files
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            fail "Must have active connection" unless @service
+          end
+        end
+      end
+    end
+  end
+end