gotime_aws 2.5.6

data/lib/s3/s3.rb

@@ -0,0 +1,347 @@
+#
+# Copyright (c) 2007-2008 RightScale Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Aws
+
+  # = Aws::S3 -- RightScale's Amazon S3 interface
+  # The Aws::S3 class provides a complete interface to Amazon's Simple
+  # Storage Service.
+  # For explanations of the semantics
+  # of each call, please refer to Amazon's documentation at
+  # http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=48
+  #
+  # See examples below for the bucket and buckets methods.
+  #
+  # Error handling: all operations raise an Aws::AwsError in case
+  # of problems. Note that transient errors are automatically retried.
+  #
+  # It is a good way to use domain naming style getting a name for the buckets.
+  # See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingBucket.html
+  # about the naming convention for the buckets. This case they can be accessed using a virtual domains.
+  #
+  # Let assume you have 3 buckets: 'awesome-bucket', 'awesome_bucket' and 'AWEsomE-bucket'.
+  # The first ones objects can be accessed as: http:// awesome-bucket.s3.amazonaws.com/key/object
+  #
+  # But the rest have to be accessed as:
+  # http:// s3.amazonaws.com/awesome_bucket/key/object and  http:// s3.amazonaws.com/AWEsomE-bucket/key/object
+  #
+  # See: http://docs.amazonwebservices.com/AmazonS3/2006-03-01/VirtualHosting.html for better explanation.
+  #
+  class S3
+
+
+    class Owner
+      attr_reader :id, :name
+
+      def initialize(id, name)
+        @id   = id
+        @name = name
+      end
+
+      # Return Owner name as a +String+.
+      def to_s
+        @name
+      end
+    end
+
+    require_relative 'bucket'
+    require_relative 'key'
+    require_relative 'grantee'
+
+
+    attr_reader :interface
+
+
+    # Create a new handle to an S3 account. All handles share the same per process or per thread
+    # HTTP connection to Amazon S3. Each handle is for a specific account.
+    # The +params+ are passed through as-is to Aws::S3Interface.new
+    #
+    # Params is a hash:
+    #
+    #    {:server       => 's3.amazonaws.com'   # Amazon service host: 's3.amazonaws.com'(default)
+    #     :port         => 443                  # Amazon service port: 80 or 443(default)
+    #     :protocol     => 'https'              # Amazon service protocol: 'http' or 'https'(default)
+    #     :virtual_hosting  => false            # Force using bucket virtual hosting: https://s3.amazonaws.com/my-bucket vs. https://my-bucket.s3.amazonaws.com
+    #     :connection_mode  => :default         # options are
+    #                                                  :default (will use best known safe (as in won't need explicit close) option, may change in the future)
+    #                                                  :per_request (opens and closes a connection on every request)
+    #                                                  :single (one thread across entire app)
+    #                                                  :per_thread (one connection per thread)
+    #     :logger       => Logger Object}       # Logger instance: logs to STDOUT if omitted }
+    def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
+      @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params)
+    end
+
+    def close_connection
+      @interface.close_connection
+    end
+
+    # Retrieve a list of buckets.
+    # Returns an array of Aws::S3::Bucket instances.
+    #  # Create handle to S3 account
+    #  s3 = Aws::S3.new(aws_access_key_id, aws_secret_access_key)
+    #  my_buckets_names = s3.buckets.map{|b| b.name}
+    #  puts "Buckets on S3: #{my_bucket_names.join(', ')}"
+    def buckets
+      @interface.list_all_my_buckets.map! do |entry|
+        owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
+        Bucket.new(self, entry[:name], entry[:creation_date], owner)
+      end
+    end
+
+    # Retrieve an individual bucket.
+    # If the bucket does not exist and +create+ is set, a new bucket
+    # is created on S3. Launching this method with +create+=+true+ may
+    # affect on the bucket's ACL if the bucket already exists.
+    # Returns a Aws::S3::Bucket instance or +nil+ if the bucket does not exist
+    # and +create+ is not set.
+    #
+    #  s3 = Aws::S3.new(aws_access_key_id, aws_secret_access_key)
+    #  bucket1 = s3.bucket('my_awesome_bucket_1')
+    #  bucket1.keys  #=> exception here if the bucket does not exists
+    #   ...
+    #  bucket2 = s3.bucket('my_awesome_bucket_2', true)
+    #  bucket2.keys  #=> list of keys
+    #  # create a bucket at the European location with public read access
+    #  bucket3 = s3.bucket('my-awesome-bucket-3', true, 'public-read', :location => :eu)
+    #
+    #  see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html
+    #  (section: Canned Access Policies)
+    #
+    def bucket(name, create=false, perms=nil, headers={})
+      headers['x-amz-acl'] = perms if perms
+      @interface.create_bucket(name, headers) if create
+      return Bucket.new(self, name)
+      # The old way below was too slow and unnecessary because it retreived all the buckets every time.
+      #            owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
+#       buckets.each { |bucket| return bucket if bucket.name == name }
+#      nil
+    end
+
+
+  end
+
+  # Aws::S3Generator and Aws::S3Generator::Bucket methods:
+  #
+  #  s3g = Aws::S3Generator.new('1...2', 'nx...Y6') #=> #<Aws::S3Generator:0xb7b5cc94>
+  #
+  #    # List all buckets(method 'GET'):
+  #  buckets_list = s3g.buckets #=> 'https://s3.amazonaws.com:443/?Signature=Y...D&Expires=1180941864&AWSAccessKeyId=1...2'
+  #    # Create bucket link (method 'PUT'):
+  #  bucket = s3g.bucket('my_awesome_bucket')     #=> #<Aws::S3Generator::Bucket:0xb7bcbda8>
+  #  link_to_create = bucket.create_link(1.hour)  #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2
+  #    # ... or:
+  #  bucket = Aws::S3Generator::Bucket.create(s3g, 'my_awesome_bucket') #=> #<Aws::S3Generator::Bucket:0xb7bcbda8>
+  #  link_to_create = bucket.create_link(1.hour)                                 #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2
+  #    # ... or:
+  #  bucket = Aws::S3Generator::Bucket.new(s3g, 'my_awesome_bucket') #=> #<Aws::S3Generator::Bucket:0xb7bcbda8>
+  #  link_to_create = bucket.create_link(1.hour)                              #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2
+  #    # List bucket(method 'GET'):
+  #  bucket.keys(1.day) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=i...D&Expires=1180942620&AWSAccessKeyId=1...2
+  #    # Create/put key (method 'PUT'):
+  #  bucket.put('my_cool_key') #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=q...D&Expires=1180943094&AWSAccessKeyId=1...2
+  #    # Get key data (method 'GET'):
+  #  bucket.get('logs/today/1.log', 1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=h...M%3D&Expires=1180820032&AWSAccessKeyId=1...2
+  #    # Delete bucket (method 'DELETE'):
+  #  bucket.delete(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2
+  #
+  # Aws::S3Generator::Key methods:
+  #
+  #    # Create Key instance:
+  #  key = Aws::S3Generator::Key.new(bicket, 'my_cool_key') #=> #<Aws::S3Generator::Key:0xb7b7394c>
+  #    # Put key data (method 'PUT'):
+  #  key.put    #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=2...D&Expires=1180943302&AWSAccessKeyId=1...2
+  #    # Get key data (method 'GET'):
+  #  key.get    #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=a...D&Expires=1180820032&AWSAccessKeyId=1...2
+  #    # Head key (method 'HEAD'):
+  #  key.head   #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=b...D&Expires=1180820032&AWSAccessKeyId=1...2
+  #    # Delete key (method 'DELETE'):
+  #  key.delete #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=x...D&Expires=1180820032&AWSAccessKeyId=1...2
+  #
+  class S3Generator
+    attr_reader :interface
+
+    def initialize(aws_access_key_id, aws_secret_access_key, params={})
+      @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params)
+    end
+
+    # Generate link to list all buckets
+    #
+    #  s3.buckets(1.hour)
+    #
+    def buckets(expires=nil, headers={})
+      @interface.list_all_my_buckets_link(expires, headers)
+    end
+
+    # Create new S3LinkBucket instance and generate link to create it at S3.
+    #
+    #  bucket= s3.bucket('my_owesome_bucket')
+    #
+    def bucket(name, expires=nil, headers={})
+      Bucket.create(self, name.to_s)
+    end
+
+    class Bucket
+      attr_reader :s3, :name
+
+      def to_s
+        @name
+      end
+
+      alias_method :full_name, :to_s
+
+      # Return a public link to bucket.
+      #
+      #  bucket.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket'
+      #
+      def public_link
+        params = @s3.interface.params
+        "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name}"
+      end
+
+      #  Create new S3LinkBucket instance and generate creation link for it.
+      def self.create(s3, name, expires=nil, headers={})
+        new(s3, name.to_s)
+      end
+
+      #  Create new S3LinkBucket instance.
+      def initialize(s3, name)
+        @s3, @name = s3, name.to_s
+      end
+
+      # Return a link to create this bucket.
+      #
+      def create_link(expires=nil, headers={})
+        @s3.interface.create_bucket_link(@name, expires, headers)
+      end
+
+      # Generate link to list keys.
+      #
+      #  bucket.keys
+      #  bucket.keys('prefix'=>'logs')
+      #
+      def keys(options=nil, expires=nil, headers={})
+        @s3.interface.list_bucket_link(@name, options, expires, headers)
+      end
+
+      # Return a S3Generator::Key instance.
+      #
+      #  bucket.key('my_cool_key').get    #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=B...D&Expires=1180820032&AWSAccessKeyId=1...2
+      #  bucket.key('my_cool_key').delete #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=B...D&Expires=1180820098&AWSAccessKeyId=1...2
+      #
+      def key(name)
+        Key.new(self, name)
+      end
+
+      # Generates link to PUT key data.
+      #
+      #  puts bucket.put('logs/today/1.log', 2.hour)
+      #
+      def put(key, meta_headers={}, expires=nil, headers={})
+        meta = Aws::S3::Key.add_meta_prefix(meta_headers)
+        @s3.interface.put_link(@name, key.to_s, nil, expires, meta.merge(headers))
+      end
+
+      # Generate link to GET key data.
+      #
+      #  bucket.get('logs/today/1.log', 1.hour)
+      #
+      def get(key, expires=nil, headers={})
+        @s3.interface.get_link(@name, key.to_s, expires, headers)
+      end
+
+      # Generate link to delete bucket.
+      #
+      #  bucket.delete(2.hour)
+      #
+      def delete(expires=nil, headers={})
+        @s3.interface.delete_bucket_link(@name, expires, headers)
+      end
+    end
+
+
+    class Key
+      attr_reader :bucket, :name
+
+      def to_s
+        @name
+      end
+
+      # Return a full S# name (bucket/key).
+      #
+      #  key.full_name #=> 'my_awesome_bucket/cool_key'
+      #
+      def full_name(separator='/')
+        "#{@bucket.to_s}#{separator}#{@name}"
+      end
+
+      # Return a public link to key.
+      #
+      #  key.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket/cool_key'
+      #
+      def public_link
+        params = @bucket.s3.interface.params
+        "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name('/')}"
+      end
+
+      def initialize(bucket, name, meta_headers={})
+        @bucket       = bucket
+        @name         = name.to_s
+        @meta_headers = meta_headers
+        raise 'Key name can not be empty.' if Aws::Utils.blank?(@name)
+      end
+
+      # Generate link to PUT key data.
+      #
+      #  puts bucket.put('logs/today/1.log', '123', 2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=B...D&Expires=1180820032&AWSAccessKeyId=1...2
+      #
+      def put(expires=nil, headers={})
+        @bucket.put(@name.to_s, @meta_headers, expires, headers)
+      end
+
+      # Generate link to GET key data.
+      #
+      #  bucket.get('logs/today/1.log', 1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=h...M%3D&Expires=1180820032&AWSAccessKeyId=1...2
+      #
+      def get(expires=nil, headers={})
+        @bucket.s3.interface.get_link(@bucket.to_s, @name, expires, headers)
+      end
+
+      # Generate link to delete key.
+      #
+      #  bucket.delete(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2
+      #
+      def delete(expires=nil, headers={})
+        @bucket.s3.interface.delete_link(@bucket.to_s, @name, expires, headers)
+      end
+
+      # Generate link to head key.
+      #
+      #  bucket.head(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2
+      #
+      def head(expires=nil, headers={})
+        @bucket.s3.interface.head_link(@bucket.to_s, @name, expires, headers)
+      end
+    end
+  end
+
+end