class AWS::S3::ACL::Grant

A Policy is made up of one or more Grant objects. A grant sets a specific permission and grants it to the associated grantee.

When creating a new grant to add to a policy, you need only set its permission and then associate with a Grantee.

grant = ACL::Grant.new
=> #<AWS::S3::ACL::Grant (permission) to (grantee)>

Here we see that neither the permission nor the grantee have been set. Let's make this grant provide the READ permission.

grant.permission = 'READ'
grant
=> #<AWS::S3::ACL::Grant READ to (grantee)>

Now let's assume we have a grantee to the AllUsers group already set up. Just associate that grantee with our grant.

grant.grantee = all_users_group_grantee
grant
=> #<AWS::S3::ACL::Grant READ to AllUsers Group>

And now are grant is complete. It provides READ permission to the AllUsers group, effectively making this object publicly readable without any authorization.

Assuming we have some object's policy available in a local variable called policy, we can now add this grant onto its collection of grants.

policy.grants << grant

And then we send the updated policy to the S3 servers.

some_s3object.acl(policy)

Attributes

grantee[RW]

Public Class Methods

grant(type) click to toggle source

Returns stock grants with name type.

public_read_grant = ACL::Grant.grant :public_read
=> #<AWS::S3::ACL::Grant READ to AllUsers Group>

Valid stock grant types are:

  • :authenticated_read

  • :authenticated_read_acp

  • :authenticated_write

  • :authenticated_write_acp

  • :logging_read

  • :logging_read_acp

  • :logging_write

  • :logging_write_acp

  • :public_read

  • :public_read_acp

  • :public_write

  • :public_write_acp

    # File lib/aws/s3/acl.rb
258 def grant(type)
259   case type
260   when *stock_grant_map.keys
261     build_stock_grant_for type
262   else
263     raise ArgumentError, "Unknown grant type `#{type}'"
264   end
265 end
new(attributes = {}) { |self| ... } click to toggle source
    # File lib/aws/s3/acl.rb
294 def initialize(attributes = {})
295   attributes = {'permission' => nil}.merge(attributes)
296   @attributes = attributes
297   extract_grantee!
298   yield self if block_given?
299 end

Private Class Methods

build_stock_grant_for(type) click to toggle source
    # File lib/aws/s3/acl.rb
282 def build_stock_grant_for(type)
283   stock_grant = stock_grant_map[type]
284   grant = new do |g|
285     g.permission = stock_grant[:permission]
286   end
287   grant.grantee = Grantee.new do |gr|
288     gr.group = stock_grant[:group]
289   end
290   grant
291 end
stock_grant_map() click to toggle source
    # File lib/aws/s3/acl.rb
268 def stock_grant_map
269   grant        = lambda {|permission, group| {:permission => permission, :group => group}}
270   groups       = {:public => 'AllUsers', :authenticated => 'Authenticated', :logging => 'LogDelivery'}
271   permissions  = %w(READ WRITE READ_ACP WRITE_ACP)
272   stock_grants = {}
273   groups.each do |grant_group_name, group_name|
274     permissions.each do |permission|
275       stock_grants["#{grant_group_name}_#{permission.downcase}".to_sym] = grant[permission, group_name]
276     end
277   end
278   stock_grants
279 end

Public Instance Methods

permission=(permission_level) click to toggle source

Set the permission for this grant.

grant.permission = 'READ'
grant
=> #<AWS::S3::ACL::Grant READ to (grantee)>

If the specified permisison level is not valid, an InvalidAccessControlLevel exception will be raised.

    # File lib/aws/s3/acl.rb
308 def permission=(permission_level)
309   unless self.class.valid_permissions.include?(permission_level)
310     raise InvalidAccessControlLevel.new(self.class.valid_permissions, permission_level)
311   end
312   attributes['permission'] = permission_level
313 end
to_xml() click to toggle source

The xml representation of this grant.

    # File lib/aws/s3/acl.rb
316 def to_xml
317   Builder.new(permission, grantee).to_s
318 end

Private Instance Methods

extract_grantee!() click to toggle source
    # File lib/aws/s3/acl.rb
341 def extract_grantee!
342   @grantee = Grantee.new(attributes['grantee']) if attributes['grantee']
343 end