Class: RightAws::S3::Grantee

Inherits:
Object
  • 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 = 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

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. 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)



580
581
582
583
584
585
586
587
588
589
 
# File 'lib/s3/right_s3.rb', line 580

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
  end
end

Instance Attribute Details

#id ⇒ Object (readonly)

Grantee Amazon id.



512
513
514
 
# File 'lib/s3/right_s3.rb', line 512

def id
  @id
end

#name ⇒ Object (readonly)

Grantee display name.



514
515
516
 
# File 'lib/s3/right_s3.rb', line 514

def name
  @name
end

#perms ⇒ Object

Array of permissions.



516
517
518
 
# File 'lib/s3/right_s3.rb', line 516

def perms
  @perms
end

#thing ⇒ Object (readonly)

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



510
511
512
 
# File 'lib/s3/right_s3.rb', line 510

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



547
548
549
 
# File 'lib/s3/right_s3.rb', line 547

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



525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
 
# File 'lib/s3/right_s3.rb', line 525

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:



551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
 
# File 'lib/s3/right_s3.rb', line 551

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

grantee.perms = [‘FULL_CONTROL’]

grantee.apply #=> true



666
667
668
669
670
671
672
 
# File 'lib/s3/right_s3.rb', line 666

def apply
  owner, grantees = self.class.owner_and_grantees(@thing)
  grantees.map! do |grantee|
    grantee.id == @id ? self : grantee
  end
  self.class.put_acl(@thing, owner, grantees)
end

#drop ⇒ Object

Revoke all permissions for this grantee. Returns true.

grantee.drop #=> true



633
634
635
636
 
# File 'lib/s3/right_s3.rb', line 633

def drop
  @perms = []
  apply
end

#grant(permission) ⇒ 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



608
609
610
611
612
 
# File 'lib/s3/right_s3.rb', line 608

def grant(permission)
  return true if @perms.include?(permission)
  @perms += permission.to_a
  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



647
648
649
650
651
652
653
654
655
656
657
 
# File 'lib/s3/right_s3.rb', line 647

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(permission) ⇒ 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 #=> true



622
623
624
625
626
 
# File 'lib/s3/right_s3.rb', line 622

def revoke(permission)
  return true unless @perms.include?(permission)
  @perms -= permission.to_a
  apply
end

#to_s ⇒ Object

Return a name or an id.



597
598
599
 
# File 'lib/s3/right_s3.rb', line 597

def to_s
  @name || @id
end

#to_xml ⇒ Object

:nodoc:



674
675
676
677
678
679
680
681
682
683
684
685
 
# File 'lib/s3/right_s3.rb', line 674

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”.



592
593
594
 
# File 'lib/s3/right_s3.rb', line 592

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