gcloud 0.12.2 → 0.20.0

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

@@ -1,425 +0,0 @@
-# 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 Gcloud
-  module Storage
-    class File
-      ##
-      # # File Access Control List
-      #
-      # Represents a File's Access Control List.
-      #
-      # @example
-      #   require "gcloud"
-      #
-      #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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|
-            return acl if acl.is_a? Google::Apis::StorageV1::ObjectAccessControl
-            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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 pre-pending `"user-"` to an email:
-        #   require "gcloud"
-        #
-        #   gcloud = Gcloud.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 pre-pending `"group-"` to an email
-        #   require "gcloud"
-        #
-        #   gcloud = Gcloud.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 pre-pending `"user-"` to an email:
-        #   require "gcloud"
-        #
-        #   gcloud = Gcloud.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 pre-pending `"group-"` to an email
-        #   require "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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

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

@@ -1,191 +0,0 @@
-# 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 Gcloud
-  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
-        # {Gcloud::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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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 "gcloud"
-        #
-        #   gcloud = Gcloud.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