| Class | S33r::S3ACL::ACLDoc |
| In: |
lib/s33r/s3_acl.rb
|
| Parent: | Object |
An S3 ACL document, incorporating one or more Grants (see docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingACL.html).
Represents both retrieved ACL XML or can be built up using objects and converted to XML. NB the ACLDoc is oblivious to the resource it is going to be applied to.
| grants | [RW] | List of grants to be applied. |
| owner | [RW] | List of grants to be applied. |
Create an ACLDoc instance from a raw Access Control Policy XML document.
acl_xml is a raw Access Control Policy XML string (NOT libxml Document or Node).
Returns nil if the ACL XML is nil.
# File lib/s33r/s3_acl.rb, line 34
34: def self.from_xml(acl_xml)
35: return nil if acl_xml.nil?
36:
37: acl_xml = S33r.remove_namespace(acl_xml)
38: doc = XML.get_xml_doc(acl_xml)
39:
40: owner_xml = doc.find('//Owner').to_a.first
41: owner = CanonicalUser.from_xml(owner_xml)
42:
43: grants = []
44: doc.find('//AccessControlList/Grant').to_a.each do |g|
45: grantee_xml = g.find('Grantee').to_a.first
46: grantee = Grantee.from_xml(grantee_xml)
47: permission = g.xget('Permission')
48:
49: grants << Grant.new(grantee, permission)
50: end
51:
52: ACLDoc.new(owner, grants)
53: end
owner: S33r::S3ACL::CanonicalUser instance
# File lib/s33r/s3_acl.rb, line 24
24: def initialize(owner, grants=[])
25: @grants = grants
26: @owner = owner
27: end
Add a grant to the ACL document.
Returns true if grant was added; false otherwise (grant already exists).
# File lib/s33r/s3_acl.rb, line 82
82: def add_grant(grant)
83: if @grants.include?(grant)
84: return false
85: else
86: @grants << grant
87: return true
88: end
89: end
Add permissions to an instances which give READ_ACL and WRITE permissions to the LogDelivery group. Used to enable a bucket as a logging destination.
Returns true if grants added, false otherwise (if already a log target).
# File lib/s33r/s3_acl.rb, line 132
132: def add_log_target_grants
133: if log_targetable?
134: return false
135: else
136: Grant.log_target_grants.each { |g| add_grant(g) }
137: return true
138: end
139: end
Add a public READ permission to this instance.
# File lib/s33r/s3_acl.rb, line 115
115: def add_public_read_grants
116: add_grant(Grant.public_read_grant)
117: end
Does the ACL make the associated resource available as a log target?
# File lib/s33r/s3_acl.rb, line 120
120: def log_targetable?
121: log_target_grants = Grant.log_target_grants
122: log_target_grants.each { |g| return false if !grants.include?(g) }
123: return true
124: end
Does the ACL contain a grant for public reads? (i.e. grants holds a Grant object for :all_users with :read permission)
# File lib/s33r/s3_acl.rb, line 106
106: def public_readable?
107: pr_grant = Grant.public_read_grant
108: grants.each do |g|
109: return true if pr_grant == g
110: end
111: return false
112: end
Remove a grant from the ACL document. Note that if you set a grant for an AmazonCustomer, you want be able to remove it by specifying the same grant. This is because grants set by AmazonCustomer are converted at the S3 end into CanonicalUser grants - so you will need to remove a CanonicalUser grant instead. See Grant.for_amazon_customer for a few more details.
Returns true if grant was removed; false if it wasn’t in the document.
# File lib/s33r/s3_acl.rb, line 100
100: def remove_grant(grant)
101: @grants.delete_if { |g| grant == g }
102: end
Remove log target ACLs from the document.
Returns true if all log target grants were removed; false otherwise.
NB even if this method returns false, that doesn’t mean the bucket is still a log target. Use log_targetable? to check whether a bucket can be used as a log target.
# File lib/s33r/s3_acl.rb, line 149
149: def remove_log_target_grants
150: ok = true
151: Grant.log_target_grants.each { |g| ok = ok and remove_grant(g) }
152: ok
153: end
Generate AccessControlPolicy XML document.
# File lib/s33r/s3_acl.rb, line 56
56: def to_xml
57: xml_str = ""
58: xml = Builder::XmlMarkup.new(:target => xml_str, :indent => 0)
59:
60: xml.instruct!
61:
62: # Access control policy XML.
63: xml.AccessControlPolicy({"xmlns" => RESPONSE_NAMESPACE_URI}) {
64: xml.Owner {
65: xml.ID owner.user_id
66: xml.DisplayName owner.display_name
67: }
68: xml.AccessControlList {
69: grants.each do |grant|
70: xml << grant.to_xml
71: end
72: }
73: }
74:
75: xml_str
76: end