HPCloud-JSACL Class
Construct a new ACL.
By default, an ACL is set to "private."
EXPERIMENTAL: This is bassed on a feature of Swift that is likely to change. Most of this is based on undocmented features of the API discovered both in the Python docs and in discussions by various members of the OpenStack community.
Swift access control rules are broken into two permissions: READ and WRITE. Read permissions grant the user the ability to access the file (using verbs like GET and HEAD), while WRITE permissions allow any modification operation. WRITE does not imply READ.
In the current implementation of Swift, access can be assigned based on two different factors:
- Accounts: Access can be granted to specific accounts, and within those accounts, can be further specified to specific users. See the addAccount() method for details on this.
- Referrers: Access can be granted based on host names or host name patterns. For example, only subdomains of *.example.com may be granted READ access to a particular object.
ACLs are transmitted within the HTTP headers for an object or container. Two headers are used: X-Container-Read for READ rules, and X-Container-Write for WRITE rules. Each header may have a chain of rules.
For a detailed description of the rules for ACL creation, see http://swift.openstack.org/misc.html#acls
Constructor
ACL
()
Item Index
Methods
- addAccount
- addReferrer
- addRule
- allowListings
- headers
- isPrivate
- isPublic
- makePrivate static
- makePublic static
- newFromHeaders static
- parseRule static
- rules
- ruleToString
- toString
Properties
Methods
addAccount
-
perm -
account -
user
Grant ACL access to an account.
Optionally, a user may be given to further limit access.
This is used to restrict access to a particular account and, if so specified, a specific user on that account.
If just an account is given, any user on that account will be automatically granted access.
If an account and a user is given, only that user of the account is granted access.
If $user is an array, every user in the array will be granted access under the provided account. That is, for each user in the array, an entry of the form \c account:user will be generated in the final ACL.
At this time there does not seem to be a way to grant global write access to an object.
Parameters:
-
permNumberACL.READ, ACL.WRITE or ACL.READ_WRITE
-
accountStringThe name of the account.
-
userString | ArrayThe name of the user, or optionally an indexed array of user names.
addReferrer
-
perm -
host
Allow (or deny) a hostname or host pattern.
In current Swift implementations, only READ rules can have host patterns. WRITE permissions cannot be granted to hostnames.
Formats: - Allow any host: '*' - Allow exact host: 'www.example.com' - Allow hosts in domain: '.example.com' - Disallow exact host: '-www.example.com' - Disallow hosts in domain: '-.example.com'
Note that a simple minus sign ('-') is illegal, though it seems it should be "disallow all hosts."
Parameters:
-
permObjectThe permission. One of ACL.READ, ACL.WRITE, ACL.READ_WRITE.
-
hostStringA host string, as described above.
Returns:
addRule
-
perm -
rule
Add a rule to the rule set.
This adds a rule with the given permission to the rule set.
Parameters:
-
permObjectA permission object.
-
ruleObjectA rule.
Returns:
allowListings
()
ACL
chainable
Allow hosts with READ permissions to list a container's content.
By default, granting READ permission on a container does not grant permission to list the contents of a container. Setting the ACL.allowListings() permission will allow matching hosts to also list the contents of a container.
In the current Swift implementation, there is no mechanism for allowing some hosts to get listings, while denying others.
Returns:
headers
()
Array
Transform the rule set into HTTP headers.
Returns:
isPrivate
()
Boolean
Check if the ACL marks this private.
This returns TRUE only if this ACL does not grant any permissions at all.
Returns:
isPublic
()
Boolean
Check whether this object allows public reading.
This will return TRUE the ACL allows (a) any host to access the item, and (b) it allows container listings.
This checks whether the object allows public reading, not whether it is ONLY allowing public reads.
See ACL.makePublic().
Returns:
makePrivate
()
ACL
static
A factory to create an ACL object with private permissions
Returns:
makePublic
()
ACL
static
A factory to create an ACL object with public permissions.
Returns:
newFromHeaders
-
headers
Build a new ACL object from a header array.
This will scan headers for expected rules, and parse out the results. If no headers are found, the returned ACL will be private.
Parameters:
-
headersArrayThe headers array.
Returns:
parseRule
-
perm -
rule
Parse an ACL rule into a rule object.
Parameters:
-
permNumberOne of ACL.READ or ACL.WRITE.
-
ruleStringA string representation of a rule.
Returns:
rules
()
Array
Get the rules set.
Returns:
ruleToString
-
perm -
rule
Convert a rule to a string.
Parameters:
-
permNumberThe permission type (ACL.WRITE, ACL.READ).
-
ruleObjectThe rule object.
Returns:
toString
()
String
Convert the ACL (headers) to a string. This is useful for debugging.
Returns:
Properties
HEADER_READ
String
Header for read permissions.
HEADER_WRITE
String
Header for write permissions.
READ
Number
Read flag.
READ_WRITE
Number
Read/write flag (shorthand for READ | WRITE).
WRITE
Number
Write flag.