class MSS::S3::Bucket
Represents a bucket in S3
.
# Creating Buckets
You create a bucket by name. Bucket
names must be globally unique and must be DNS compatible.
s3 = MSS::S3.new bucket = s3.buckets.create('dns-compat-bucket-name')
# Getting a Bucket
You can create a reference to a bucket, given its name.
bucket = s3.buckets['bucket-name'] # makes no request bucket.exists? #=> returns true/false
# Enumerating Buckets
The {BucketCollection} class is enumerable.
s3.buckets.each do |bucket| puts bucket.name end
# Deleting a Bucket
You can delete an empty bucket you own.
bucket = s3.buckets.create('my-temp-bucket') bucket.objects['abc'].write('xyz') bucket.clear! # deletes all object versions in batches bucket.delete
You can alternatively call {#delete!} which will clear the bucket for your first.
bucket.delete!
# Objects
Given a bucket you can access its objects, either by key or by enumeration.
bucket.objects['key'] #=> makes no request, returns an S3Object bucket.objects.each do |obj| puts obj.key end
See {ObjectCollection} and {S3Object} for more information on working with objects.
# Website Configuration
It is easy to enable website hosting for a bucket.
bucket.configure_website
You can specify the index and error documents by passing a block. If your bucket is already configured as a website, the current configuration will be yielded. If you bucket it not currently configured as a website, a new configuration will be yielded with default values.
bucket.configure_website do |cfg| cfg.index_document_suffix = 'index.html' cfg.error_document_key = 'error.html' end
You can disable website hosting two ways:
bucket.remove_website_configuration bucket.website_configuration = nil
You can use {#website_configuration=} to copy a website configuration from one bucket to another.
bucket.website_configuration = other_bucket.website_configuration
# Bucket
Policies and ACLs
You can control access to your bucket and its contents a number of ways. You can specify a bucket ACL (access control list) or a bucket policy.
## ACLs
ACLs control access to your bucket and its contents via a list of grants and grantees.
### Canned ACLs
The simplest way to specify an ACL is to use one of Amazon's “canned” ACLs. Amazon accepts the following canned ACLs:
-
`:private`
-
`:public_read`
-
`:public_read_write`
-
`:authenticated_read`
-
`:bucket_owner_read`
-
`:bucket_owner_full_control`
You can specify a the ACL at bucket creation or later update a bucket.
# at create time, defaults to :private when not specified bucket = s3.buckets.create('name', :acl => :public_read) # replacing an existing bucket ACL bucket.acl = :private
### Grants
Alternatively you can specify a hash of grants. Each entry in the `:grant` hash has a grant (key) and a list of grantees (values). Valid grant keys are:
-
`:grant_read`
-
`:grant_write`
-
`:grant_read_acp`
-
`:grant_write_acp`
-
`:grant_full_control`
Each grantee can be a String, Hash or array of strings or hashes. The following example uses grants to provide public read to everyone while providing full control to a user by email address and to another by their account id (cannonical user id).
bucket = s3.buckets.create('name', :grants => { :grant_read => [ { :uri => "http://acs.amazonmss.com/groups/global/AllUsers" }, ], :grant_full_control => [ { :id => 'abc...mno' } # cannonical user id { :email_address => 'foo@bar.com' }, # email address ] })
### ACL Object
Lastly, you can build an ACL object and use a Ruby DSL to specify grants and grantees. See {ACLObject} for more information.
# updating an existing bucket acl using ACLObject bucket.acl.change do |acl| acl.grants.reject! do |g| g.grantee.canonical_user_id != bucket.owner.id end end
## Policies
You can also work with bucket policies.
policy = MSS::S3::Policy.new policy.allow( :actions => [:put_object, :get_object] :resources => [bucket] :principals => :any) bucket.policy = policy
See {Core::Policy} and {S3::Policy} for more information on build policy objects.
# Versioned Buckets
You can enable versioning on a bucket you control. When versioning is enabled, S3
will keep track of each version of each object you write to the bucket (even deletions).
bucket.versioning_enabled? #=> false bucket.enable_versioning # there is also a #suspend_versioning method obj = bucket.objects['my-obj'] obj.write('a') obj.write('b') obj.delete obj.write('c') obj.versions.each do |obj_version| if obj_version.delete_marker? puts obj_version.read else puts "- DELETE MARKER" end end
Alternatively you can enumerate all versions of all objects in your bucket.
bucket.versions.each do |obj_version| puts obj_version.key ` " : " ` obj_version.version_id end
See {BucketVersionCollection}, {ObjectVersionCollection} and {ObjectVersion} for more information on working with objects in a versioned bucket. Also see the S3
documentation for information on object versioning.
Attributes
@return [String] The bucket name
Public Class Methods
@param [String] name @param [Hash] options @option options [String] :owner (nil) The owner id of this bucket.
MSS::Core::Model::new
# File lib/mss/s3/bucket.rb, line 226 def initialize(name, options = {}) # the S3 docs disagree with what the service allows, # so it's not safe to toss out invalid bucket names # S3::Client.validate_bucket_name!(name) @name = name @owner = options[:owner] super end
Public Instance Methods
@return [Boolean] Returns true if the two buckets have the same name.
# File lib/mss/s3/bucket.rb, line 498 def ==(other) other.kind_of?(Bucket) && other.name == name end
Returns the bucket's access control list. This will be an instance of AccessControlList
, plus an additional `change` method:
bucket.acl.change do |acl| acl.grants.reject! do |g| g.grantee.canonical_user_id != bucket.owner.id end end
@return [AccessControlList]
# File lib/mss/s3/bucket.rb, line 565 def acl resp = client.get_bucket_acl(:bucket_name => name) acl = AccessControlList.new(resp.data) acl.extend ACLProxy acl.bucket = self acl end
Returns a tree that allows you to expose the bucket contents like a directory structure.
@see Tree
@param [Hash] options @option options [String] :prefix (nil) Set prefix to choose where
the top of the tree will be. A value of `nil` means that the tree will include all objects in the collection.
@option options [String] :delimiter ('/') The string that separates
each level of the tree. This is usually a directory separator.
@option options [Boolean] :append (true) If true, the delimiter is
appended to the prefix when the prefix does not already end with the delimiter.
@return [Tree]
# File lib/mss/s3/bucket.rb, line 742 def as_tree options = {} objects.as_tree(options) end
Deletes all objects from this bucket. @return [nil]
# File lib/mss/s3/bucket.rb, line 463 def clear! # versions.each_batch do |versions| # objects.delete(versions) # end objects.each do |object| object.delete end end
Deletes the current bucket. An error will be raised if the bucket is not empty. @return [nil]
# File lib/mss/s3/bucket.rb, line 475 def delete client.delete_bucket(:bucket_name => @name) nil end
Deletes all objects in a bucket and then deletes the bucket. @return [nil]
# File lib/mss/s3/bucket.rb, line 482 def delete! clear! delete end
@return [Boolean] Returns true if the bucket has no objects
(this includes versioned objects that are delete markers).
# File lib/mss/s3/bucket.rb, line 253 def empty? # versions.first ? false : true objects.first ? false : true end
@return [Boolean] Returns true if the two buckets have the same name
# File lib/mss/s3/bucket.rb, line 503 def eql?(other_bucket) self == other_bucket end
@note This method only indicates if there is a bucket in S3
, not
if you have permissions to work with the bucket or not.
@return [Boolean] Returns true if the bucket exists in S3
.
# File lib/mss/s3/bucket.rb, line 510 def exists? begin versioned? # makes a get bucket request without listing contents # raises a client error if the bucket doesn't exist or # if you don't have permission to get the bucket # versioning status. true rescue Errors::NoSuchBucket => e false # bucket does not exist rescue Errors::AccessDenied => e true # bucket exists end end
@api private
# File lib/mss/s3/bucket.rb, line 493 def inspect "#<MSS::S3::Bucket:#{name}>" end
@return [MultipartUploadCollection] Represents all of the
multipart uploads that are in progress for this bucket.
# File lib/mss/s3/bucket.rb, line 538 def multipart_uploads MultipartUploadCollection.new(self) end
@return [ObjectCollection] Represents all objects(keys) in
this bucket.
# File lib/mss/s3/bucket.rb, line 526 def objects ObjectCollection.new(self) end
@return [String] bucket owner id
# File lib/mss/s3/bucket.rb, line 488 def owner @owner || client.list_buckets.owner end
Generates fields for a presigned POST to this object. All options are sent to the PresignedPost
constructor.
@see PresignedPost
# File lib/mss/s3/bucket.rb, line 750 def presigned_post(options = {}) PresignedPost.new(self, options) end
# File lib/mss/s3/bucket.rb, line 589 def set_acl_private client.set_bucket_acl(acl_options(:private).merge(:bucket_name => name)) nil end
Sets the bucket's ACL (access control list). You can provide an ACL in a number of different formats. @param (see ACLOptions#acl_options
) @return [nil]
def acl= acl client.set_bucket_acl(acl_options(acl).merge(:bucket_name => name)) nil end
# File lib/mss/s3/bucket.rb, line 584 def set_acl_public_read client.set_bucket_acl(acl_options(:public_read).merge(:bucket_name => name)) nil end
Returns the url for this bucket. @return [String] url to the bucket
# File lib/mss/s3/bucket.rb, line 240 def url(options = {}) protocol = options.fetch(:secure, false) ? "https://" : "http://" if client.dns_compatible_bucket_name?(name) # "#{protocol}#{name}.s3.amazonmss.com/" "#{protocol}#{name}.mtmos.com/" else # "#{protocol}s3.amazonmss.com/#{name}/" "#{protocol}mtmos.com/#{name}/" end end
@return [Boolean] returns `true` if version is enabled on this bucket.
# File lib/mss/s3/bucket.rb, line 445 def versioning_enabled? versioning_state == :enabled end
Returns the versioning status for this bucket. States include:
-
`:enabled` - currently enabled
-
`:suspended` - currently suspended
-
`:unversioned` - versioning has never been enabled
@return [Symbol] the versioning state
# File lib/mss/s3/bucket.rb, line 457 def versioning_state client.get_bucket_versioning(:bucket_name => @name).status end