Class: Aws::S3::Grantee

Inherits:
Object show all
Defined in:
lib/s3/right_s3.rb

Overview

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 = Aws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL, :apply)
grantee2 = Aws::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 = Aws::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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(thing, id, perms = [], action = :refresh, name = nil) ⇒ Grantee

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 = Aws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL)
  ...
grantee2 = Aws::S3::Grantee.new(bucket, 'abcde...asdf', [FULL_CONTROL, READ], :apply)
grantee3 = Aws::S3::Grantee.new(bucket, 'aaaaa...aaaa', 'READ', :apply_and_refresh)



770
771
772
773
774
775
776
777
778
779
780
781
782
783
 
# File 'lib/s3/right_s3.rb', line 770

def initialize(thing, id, perms=[], action=:refresh, name=nil)
    @thing = thing
    @id    = id
    @name  = name
    @perms = perms.to_a
    case action
        when :apply then
            apply
        when :refresh then
            refresh
        when :apply_and_refresh then
            apply; refresh
    end
end

Instance Attribute Details

#id ⇒ Object (readonly)

Grantee Amazon id.



700
701
702
 
# File 'lib/s3/right_s3.rb', line 700

def id
  @id
end

#name ⇒ Object (readonly)

Grantee display name.



702
703
704
 
# File 'lib/s3/right_s3.rb', line 702

def name
  @name
end

#perms ⇒ Object

Array of permissions.



704
705
706
 
# File 'lib/s3/right_s3.rb', line 704

def perms
  @perms
end

#thing ⇒ Object (readonly)

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



698
699
700
 
# File 'lib/s3/right_s3.rb', line 698

def thing
  @thing
end

Class Method Details

.grantees(thing) ⇒ Object

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')
 ...
Aws::S3::Grantee.grantees(bucket) #=> grantees



735
736
737
 
# File 'lib/s3/right_s3.rb', line 735

def self.grantees(thing)
    owner_and_grantees(thing)[1]
end

.owner_and_grantees(thing) ⇒ Object

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')
 ...
Aws::S3::Grantee.owner_and_grantees(bucket) #=> [owner, grantees]



713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
 
# File 'lib/s3/right_s3.rb', line 713

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

.put_acl(thing, owner, grantees) ⇒ Object

:nodoc:



739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
 
# File 'lib/s3/right_s3.rb', line 739

def self.put_acl(thing, owner, grantees) #:nodoc:
    if thing.is_a?(Bucket)
        bucket, key = thing, ''
    else
        bucket, key = thing.bucket, thing
    end
    body = "<AccessControlPolicy>" +
            "<Owner>" +
            "<ID>#{owner.id}</ID>" +
            "<DisplayName>#{owner.name}</DisplayName>" +
            "</Owner>" +
            "<AccessControlList>" +
            grantees.map { |grantee| grantee.to_xml }.join +
            "</AccessControlList>" +
            "</AccessControlPolicy>"
    bucket.s3.interface.put_acl(bucket.to_s, key.to_s, body)
end

Instance Method Details

#apply ⇒ Object

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



878
879
880
881
882
883
884
885
886
887
 
# File 'lib/s3/right_s3.rb', line 878

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 ⇒ Object

Revoke all permissions for this grantee. Returns true.

grantee.drop #=> true



845
846
847
848
 
# File 'lib/s3/right_s3.rb', line 845

def drop
    @perms = []
    apply
end

#exists? ⇒ Boolean

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

Returns:

  • (Boolean) 


786
787
788
789
790
791
 
# File 'lib/s3/right_s3.rb', line 786

def exists?
    self.class.grantees(@thing).each do |grantee|
        return true if @id == grantee.id
    end
    false
end

#grant(*permissions) ⇒ Object

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



812
813
814
815
816
817
818
819
 
# File 'lib/s3/right_s3.rb', line 812

def grant(*permissions)
    permissions.flatten!
    old_perms = @perms.dup
    @perms    += permissions
    @perms.uniq!
    return true if @perms == old_perms
    apply
end

#refresh ⇒ Object

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



859
860
861
862
863
864
865
866
867
868
869
 
# File 'lib/s3/right_s3.rb', line 859

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) ⇒ Object

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



831
832
833
834
835
836
837
838
 
# File 'lib/s3/right_s3.rb', line 831

def revoke(*permissions)
    permissions.flatten!
    old_perms = @perms.dup
    @perms    -= permissions
    @perms.uniq!
    return true if @perms == old_perms
    apply
end

#to_s ⇒ Object

Return a name or an id.



799
800
801
 
# File 'lib/s3/right_s3.rb', line 799

def to_s
    @name || @id
end

#to_xml ⇒ Object

:nodoc:



889
890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/s3/right_s3.rb', line 889

def to_xml # :nodoc:
    id_str = @id[/^http/] ? "<URI>#{@id}</URI>" : "<ID>#{@id}</ID>"
    grants = ''
    @perms.each do |perm|
        grants << "<Grant>" +
                "<Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" " +
                "xsi:type=\"#{type}\">#{id_str}</Grantee>" +
                "<Permission>#{perm}</Permission>" +
                "</Grant>"
    end
    grants
end

#type ⇒ Object

Return Grantee type (String): “Group” or “CanonicalUser”.



794
795
796
 
# File 'lib/s3/right_s3.rb', line 794

def type
    @id[/^http:/] ? "Group" : "CanonicalUser"
end