Parent

RightAws::S3::Grantee

There are 2 ways to set permissions for a bucket or key (called a thing below):

1 . Use perms param to set 'Canned Access Policies' when calling the bucket.create, bucket.put and key.put methods. The perms param can take these values: 'private', 'public-read', 'public-read-write' and 'authenticated-read'. (see docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html).

bucket = s3.bucket('bucket_for_kd_test_13', true, 'public-read')
key.put('Woohoo!','public-read-write' )

2 . Use Grantee instances (the permission is a String or an Array of: 'READ', 'WRITE', 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'):

bucket  = s3.bucket('my_awesome_bucket', true)
grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL, :apply)
grantee2 = RightAws::S3::Grantee.new(bucket, 'xy3v3...5fhp', [READ, WRITE], :apply)

There is only one way to get and to remove permission (via Grantee instances):

grantees = bucket.grantees # a list of Grantees that have any access for this bucket
grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c')
grantee1.perms #=> returns a list of perms for this grantee to that bucket
  ...
grantee1.drop             # remove all perms for this grantee
grantee2.revoke('WRITE')  # revoke write access only

Attributes

id[R]

Grantee Amazon id.

name[R]

Grantee display name.

perms[RW]

Array of permissions.

thing[R]

A bucket or a key the grantee has an access to.

Public Class Methods

grantees(thing) click to toggle source

Retrieves a list of Grantees instances that have an access to this thing(bucket or key).

bucket = s3.bucket('my_awesome_bucket', true, 'public-read')
 ...
RightAws::S3::Grantee.grantees(bucket) #=> grantees
# File lib/s3/right_s3.rb, line 723
def self.grantees(thing)
  owner_and_grantees(thing)[1]
end
new(thing, id, perms=[], action=:refresh, name=nil) click to toggle source

Create a new Grantee instance. Grantee id must exist on S3. If action == :refresh, then retrieve permissions from S3 and update @perms. If action == :apply, then apply perms to thing at S3. If action == :apply_and_refresh then it performs. both the actions. This is used for the new grantees that had no perms to this thing before. The default action is :refresh.

bucket = s3.bucket('my_awesome_bucket', true, 'public-read')
grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL)
  ...
grantee2 = RightAws::S3::Grantee.new(bucket, 'abcde...asdf', [FULL_CONTROL, READ], :apply)
grantee3 = RightAws::S3::Grantee.new(bucket, 'aaaaa...aaaa', 'READ', :apply_and_refresh)
# File lib/s3/right_s3.rb, line 758
def initialize(thing, id, perms=[], action=:refresh, name=nil)
  @thing = thing
  @id    = id
  @name  = name
  @perms = perms.to_a
  case action
    when :apply:             apply
    when :refresh:           refresh
    when :apply_and_refresh: apply; refresh
  end
end
owner_and_grantees(thing) click to toggle source

Retrieve Owner information and a list of Grantee instances that have a access to this thing (bucket or key).

bucket = s3.bucket('my_awesome_bucket', true, 'public-read')
 ...
RightAws::S3::Grantee.owner_and_grantees(bucket) #=> [owner, grantees]
# File lib/s3/right_s3.rb, line 701
def self.owner_and_grantees(thing)
  if thing.is_a?(Bucket)
    bucket, key = thing, ''
  else
    bucket, key = thing.bucket, thing
  end
  hash = bucket.s3.interface.get_acl_parse(bucket.to_s, key.to_s)
  owner = Owner.new(hash[:owner][:id], hash[:owner][:display_name])
  
  grantees = []
  hash[:grantees].each do |id, params|
    grantees << new(thing, id, params[:permissions], nil, params[:display_name])
  end
  [owner, grantees]
end

Public Instance Methods

apply() click to toggle source

Apply current grantee @perms to thing. This method is called internally by the grant and revoke methods. In normal use this method should not be called directly.

grantee.perms = ['FULL_CONTROL']
grantee.apply #=> true
# File lib/s3/right_s3.rb, line 863
def apply
  @perms.uniq!
  owner, grantees = self.class.owner_and_grantees(@thing)
  # walk through all the grantees and replace the data for the current one and ...
  grantees.map! { |grantee| grantee.id == @id ? self : grantee }
  # ... if this grantee is not known - add this bad boy to a list
  grantees << self unless grantees.include?(self)
  # set permissions
  self.class.put_acl(@thing, owner, grantees)
end
drop() click to toggle source

Revoke all permissions for this grantee. Returns true.

grantee.drop #=> true
# File lib/s3/right_s3.rb, line 830
def drop
  @perms = []
  apply
end
exists?() click to toggle source

Return true if the grantee has any permissions to the thing.

# File lib/s3/right_s3.rb, line 771
def exists?
  self.class.grantees(@thing).each do |grantee|
    return true if @id == grantee.id
  end
  false
end
grant(*permissions) click to toggle source

Add permissions for grantee. Permissions: 'READ', 'WRITE', 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'. See docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingPermissions.html . Returns true.

grantee.grant('FULL_CONTROL')                  #=> true
grantee.grant('FULL_CONTROL','WRITE','READ')   #=> true
grantee.grant(['WRITE_ACP','READ','READ_ACP']) #=> true
# File lib/s3/right_s3.rb, line 797
def grant(*permissions)
  permissions.flatten!
  old_perms = @perms.dup
  @perms   += permissions
  @perms.uniq!
  return true if @perms == old_perms
  apply
end
refresh() click to toggle source

Refresh grantee perms for its thing. Returns true if the grantee has perms for this thing or false otherwise, and updates @perms value as a side-effect.

grantee.grant('FULL_CONTROL') #=> true
grantee.refresh               #=> true
grantee.drop                  #=> true
grantee.refresh               #=> false
# File lib/s3/right_s3.rb, line 844
def refresh
  @perms = []
  self.class.grantees(@thing).each do |grantee|
    if @id == grantee.id
      @name  = grantee.name
      @perms = grantee.perms
      return true
    end
  end
  false
end
revoke(*permissions) click to toggle source

Revoke permissions for grantee. Permissions: 'READ', 'WRITE', 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL' See docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingPermissions.html . Default value is 'FULL_CONTROL'. Returns true.

grantee.revoke('READ')                   #=> true
grantee.revoke('FULL_CONTROL','WRITE')   #=> true
grantee.revoke(['READ_ACP','WRITE_ACP']) #=> true
# File lib/s3/right_s3.rb, line 816
def revoke(*permissions)
  permissions.flatten!
  old_perms = @perms.dup
  @perms   -= permissions
  @perms.uniq!
  return true if @perms == old_perms
  apply
end
to_s() click to toggle source

Return a name or an id.

# File lib/s3/right_s3.rb, line 784
def to_s
  @name || @id
end
type() click to toggle source

Return Grantee type (String): "Group" or "CanonicalUser".

# File lib/s3/right_s3.rb, line 779
def type
  @id[/^http:/] ? "Group" : "CanonicalUser"
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.