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:

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:

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

name[R]

@return [String] The bucket name

Public Class Methods

new(name, options = {}) click to toggle source

@param [String] name @param [Hash] options @option options [String] :owner (nil) The owner id of this bucket.

Calls superclass method 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

==(other) click to toggle source

@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
acl() click to toggle source

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
as_tree(options = {}) click to toggle source

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
clear!() click to toggle source

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
delete() click to toggle source

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
delete!() click to toggle source

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
empty?() click to toggle source

@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
eql?(other_bucket) click to toggle source

@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
exists?() click to toggle source

@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
inspect() click to toggle source

@api private

# File lib/mss/s3/bucket.rb, line 493
def inspect
  "#<MSS::S3::Bucket:#{name}>"
end
multipart_uploads() click to toggle source

@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
objects() click to toggle source

@return [ObjectCollection] Represents all objects(keys) in

this bucket.
# File lib/mss/s3/bucket.rb, line 526
def objects
  ObjectCollection.new(self)
end
owner() click to toggle source

@return [String] bucket owner id

# File lib/mss/s3/bucket.rb, line 488
def owner
  @owner || client.list_buckets.owner
end
presigned_post(options = {}) click to toggle source

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
set_acl_private() click to toggle source
# 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
set_acl_public_read() click to toggle source

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
url(options = {}) click to toggle source

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
versioned?()
Alias for: versioning_enabled?
versioning_enabled?() click to toggle source

@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
Also aliased as: versioned?
versioning_state() click to toggle source

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