Class: 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

Methods

apply drop exists? grant grantees new owner_and_grantees refresh revoke to_s type

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)

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

[Source]

     # File lib/s3/right_s3.rb, line 723
723:       def self.grantees(thing)
724:         owner_and_grantees(thing)[1]
725:       end

new(thing, id, perms=[], action=:refresh, name=nil)

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)

[Source]

     # File lib/s3/right_s3.rb, line 758
758:       def initialize(thing, id, perms=[], action=:refresh, name=nil)
759:         @thing = thing
760:         @id    = id
761:         @name  = name
762:         @perms = perms.to_a
763:         case action
764:           when :apply:             apply
765:           when :refresh:           refresh
766:           when :apply_and_refresh: apply; refresh
767:         end
768:       end

owner_and_grantees(thing)

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]

[Source]

     # File lib/s3/right_s3.rb, line 701
701:       def self.owner_and_grantees(thing)
702:         if thing.is_a?(Bucket)
703:           bucket, key = thing, ''
704:         else
705:           bucket, key = thing.bucket, thing
706:         end
707:         hash = bucket.s3.interface.get_acl_parse(bucket.to_s, key.to_s)
708:         owner = Owner.new(hash[:owner][:id], hash[:owner][:display_name])
709:         
710:         grantees = []
711:         hash[:grantees].each do |id, params|
712:           grantees << new(thing, id, params[:permissions], nil, params[:display_name])
713:         end
714:         [owner, grantees]
715:       end

Public Instance methods

apply()

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

[Source]

     # File lib/s3/right_s3.rb, line 863
863:       def apply
864:         @perms.uniq!
865:         owner, grantees = self.class.owner_and_grantees(@thing)
866:         # walk through all the grantees and replace the data for the current one and ...
867:         grantees.map! { |grantee| grantee.id == @id ? self : grantee }
868:         # ... if this grantee is not known - add this bad boy to a list
869:         grantees << self unless grantees.include?(self)
870:         # set permissions
871:         self.class.put_acl(@thing, owner, grantees)
872:       end

drop()

Revoke all permissions for this grantee. Returns true.

 grantee.drop #=> true

[Source]

     # File lib/s3/right_s3.rb, line 830
830:       def drop
831:         @perms = []
832:         apply
833:       end

exists?()

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

[Source]

     # File lib/s3/right_s3.rb, line 771
771:       def exists?
772:         self.class.grantees(@thing).each do |grantee|
773:           return true if @id == grantee.id
774:         end
775:         false
776:       end

grant(*permissions)

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

[Source]

     # File lib/s3/right_s3.rb, line 797
797:       def grant(*permissions)
798:         permissions.flatten!
799:         old_perms = @perms.dup
800:         @perms   += permissions
801:         @perms.uniq!
802:         return true if @perms == old_perms
803:         apply
804:       end

refresh()

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

[Source]

     # File lib/s3/right_s3.rb, line 844
844:       def refresh
845:         @perms = []
846:         self.class.grantees(@thing).each do |grantee|
847:           if @id == grantee.id
848:             @name  = grantee.name
849:             @perms = grantee.perms
850:             return true
851:           end
852:         end
853:         false
854:       end

revoke(*permissions)

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

[Source]

     # File lib/s3/right_s3.rb, line 816
816:       def revoke(*permissions)
817:         permissions.flatten!
818:         old_perms = @perms.dup
819:         @perms   -= permissions
820:         @perms.uniq!
821:         return true if @perms == old_perms
822:         apply
823:       end

to_s()

Return a name or an id.

[Source]

     # File lib/s3/right_s3.rb, line 784
784:       def to_s
785:         @name || @id
786:       end

type()

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

[Source]

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