oss-ruby 1.0.0.beta

data/docs/object_api.md

@@ -0,0 +1,159 @@
+# Object API
+
+Objects are the basic unit you can operation on OSS service. An object contains three parts: key, meta and data. Objects created through `put_object` cannot exceed 5GB, and the size of the object uploaded through 'multipart' cannot exceed 48.8TB.
+
+* Object
+  * Object name conventions
+  * Upload an object through `put_object`
+  * Create a 'folder' in a bucket
+  * Set meta for an object
+  * Append object
+  * Multipart upload
+  * List all objects in a bucket
+  * Get object
+  * Get only meta of an object
+  * Delete object
+  * Copy object
+
+#### Object name conventions
+
+* Encode in 'UTF-8'.
+* Cannot start with "\" or "/".
+* Cannot contain "\r" or "\n".
+* Length between 1-1023 bytes.
+
+#### Upload an object through `put_object`
+You can upload a file in two ways.
+```ruby
+# method signature
+put_object(bucket, object, body, headers = {})
+```
+```ruby
+res = oss.put_object('bucket-name', 'object-name', 'string content')
+p res.status # => 200
+```
+```ruby
+# method signature
+put_object_from_file(bucket, object, file_name, headers = {})
+```
+```ruby
+res = oss.put_object_from_file('bucket-name', 'object-name', 'test.txt')
+p res.status # => 200
+```
+
+#### Create a 'folder' in a bucket
+OSS service does not support 'folder' by default, but you can achieve it by create a object with empty data and name like 'folder_name/'.
+
+```ruby
+res = oss.put_object('bucket-name', 'folder_name/', '')
+p res.status # => 200
+```
+
+#### Set meta for an object
+You can store meta information in an object through `put_object`
+Meta headers must start with 'x-oss-meta-'.
+
+```ruby
+res = oss.put_object('bucket-name', 'object-name', 'string content', 'x-oss-meta-uploader' => 'Lucy')
+p res.status # => 204
+```
+An object can have multiple meta headers, size limit of meta information is 2KB.
+
+#### Append object
+Only 'Appendable Object' can be appended through `append_object`. Object created by `append_object` is 'Appendable Object', object created by `put_object` is 'Normal Object'.
+
+You must set the right position to append. You can read the file length of object, and you can also get the right append position throught information in  'x-oss-next-append-position' of the response headers.
+
+```ruby
+# method signature
+append_object(bucket, object, body, position = 0, headers = {})
+```
+
+```ruby
+res = oss.append_object('bucket-name', 'object-name', 'string-content', 0)
+p res.status # => 200
+p res.headers['x-oss-next-append-position'] # => 14
+```
+
+#### Multipart upload
+See information in [Multipart Upload](docs/multipart_upload.md)
+
+#### List all objects in a bucket
+You can list all objects through `get_bucket`. Additional parameters like 'prefix', 'marker', 'delimiter', 'max-keys' and 'encoding-type' are supported.
+```ruby
+# method signature
+get_bucket(name, params = {})
+```
+```ruby
+res = oss.get_bucket('bucket-name')
+p res.status # => 200
+
+# use additional parameters
+res = oss.get_bucket('bucket-name', 'MaxKeys' => 100)
+p res.status # => 200
+```
+
+#### Get object
+```ruby
+# method signature
+get_object(bucket, object, headers = {})
+```
+```ruby
+res = oss.get_object('bucket-name', 'object-name')
+p res.status # => 200
+p res.body # => [344606 bytes of object data]
+```
+
+#### Get only meta of an object
+Sometimes you only need the meta information of an object. This API reponds with meta information in headers and no body attached.
+
+```ruby
+# method signature
+head_object(bucket, object, headers = {})
+```
+
+```ruby
+res = oss.get_object('bucket-name', 'object-name')
+p res.status # => 200
+```
+
+#### Delete object
+```ruby
+# method signature
+delete_object(bucket, object)
+```
+
+```ruby
+res = oss.delete_object('bucket-name', 'object-name')
+p res.status # => 200
+```
+
+You can also delete multiple objects at once using `delete_multiple_objects`.
+
+```ruby
+# method signature
+delete_multiple_objects(bucket, objects, quiet = false)
+```
+
+```ruby
+res = oss.delete_multiple_objects('bucket-name', ['object1-name', 'object2-name'])
+p res.status # => 200
+```
+
+#### Copy object
+Copying object is supported. But you can only copy objects inside the same region.
+```ruby
+# method signature
+copy_object(source_bucket, source_object, target_bucket, target_object, headers = {})
+```
+
+```ruby
+res = oss.copy_object('source-bucket-name', 'source-object-name', 'target-bucket-name', 'target-object-name')
+p res.status # => 200
+```
+
+And you can use this method simple modify the meta information of an object.
+```ruby
+res = oss.copy_object('target-bucket-name', 'target-object-name', 'target-bucket-name', 'target-object-name', "Content-Type" => "image/jpeg")
+p res.status # => 200
+```

data/docs/quick_start.md

@@ -0,0 +1,57 @@
+# Quick Start
+
+This doc will show you basic operations of OSS APIs.
+
+* Step 1: Initialize the `oss-ruby` SDK
+* Step 2: Create a new bucket
+* Step 3: Upload a file to a bucket
+* Step 4: List all the objects of a bucket
+* Step 5: Retrieve object from a bucket
+
+#### Step 1: Initialization
+`oss-ruby` requires you to initialize an instance before usage.
+
+```ruby
+require 'oss'
+
+oss = OSS.new({
+  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
+  access_key_id: 'your_access_key',
+  access_key_secret: 'your_access_secret'
+})
+```
+
+#### Step 2: Create a new bucket
+Bucket is the objects container of the OSS service. The bucket name must be unique.
+
+```ruby
+res = oss.put_bucket 'bucket-name'
+p res.status # => 200
+```
+
+#### Step 3: Upload a file to a bucket
+Object is the basic unit in OSS storage service. You can store a file in a bucket as one object.
+
+```ruby
+res = oss.put_object_from_file('bucket-name', 'object-name', 'local-file.txt')
+p res.status # => 200
+```
+
+#### Step 4: List all the objects of a bucket
+You can view all objects in a bucket through this API.
+
+```ruby
+res = oss.get_bucket('bucket-name')
+p res.status # => 200
+```
+
+#### Step 5: Retrieve object from a bucket
+Retrieve object from a bucket is pretty easy.
+
+```ruby
+res = oss.get_object('bucket-name', 'object-name')
+p res.status # => 200
+p res.body # => [344606 bytes of object data]
+```
+
+And you can get meta information of the object from the response headers.

data/lib/oss.rb

@@ -0,0 +1,21 @@
+require 'faraday'
+require 'nokogiri'
+
+require 'oss/version'
+require 'oss/error'
+require 'oss/utils'
+require 'oss/config'
+require 'oss/response'
+require 'oss/client'
+require 'oss/service'
+require 'oss/bucket'
+require 'oss/object'
+require 'oss/base'
+
+module OSS
+  class << self
+    def new(options)
+      OSS::Base.new(options)
+    end
+  end
+end

data/lib/oss/base.rb

@@ -0,0 +1,65 @@
+module OSS
+  class Base
+    extend Forwardable
+    attr_reader :config
+
+    def initialize(options = {})
+      @config = OSS::Config.new(
+        OSS::Utils.indifferent_hash(options)
+      )
+    end
+
+    def_delegators :bucket,
+                   :get_service,
+                   :put_bucket,
+                   :put_bucket_acl,
+                   :put_bucket_logging,
+                   :put_bucket_website,
+                   :put_bucket_referer,
+                   :put_bucket_lifecycle,
+                   :get_bucket,
+                   :get_bucket_acl,
+                   :get_bucket_location,
+                   :get_bucket_logging,
+                   :get_bucket_website,
+                   :get_bucket_referer,
+                   :get_bucket_lifecycle,
+                   :delete_bucket,
+                   :delete_bucket_logging,
+                   :delete_bucket_website,
+                   :delete_bucket_lifecycle,
+                   :put_bucket_cors,
+                   :get_bucket_cors,
+                   :delete_bucket_cors
+
+    def_delegators :object,
+                   :put_object,
+                   :put_object_from_file,
+                   :copy_object,
+                   :get_object,
+                   :append_object,
+                   :delete_object,
+                   :delete_multiple_objects,
+                   :head_object,
+                   :put_object_acl,
+                   :get_object_acl,
+                   :post_object,
+                   :init_multi_upload,
+                   :upload_object_part,
+                   :upload_object_part_copy,
+                   :complete_multi_upload,
+                   :abort_multi_upload,
+                   :list_multi_upload,
+                   :list_object_parts
+
+    private
+
+    def bucket
+      @bucket ||= OSS::Bucket.new(config)
+    end
+
+    def object
+      @object ||= OSS::Object.new(config)
+    end
+  end
+end

data/lib/oss/bucket.rb

@@ -0,0 +1,202 @@
+module OSS
+  class Bucket < Service
+    # params keys: prefix, marker, max-keys
+    def get_service(params = {})
+      client.run :get, '/', params
+    end
+
+    def put_bucket(name, permission = 'private', location = 'oss-cn-hangzhou')
+      body = '<?xml version="1.0" encoding="UTF-8"?>' \
+             '<CreateBucketConfiguration>' \
+             "<LocationConstraint>#{location}</LocationConstraint>" \
+             '</CreateBucketConfiguration>'
+      headers = {
+        'x-oss-acl' => permission,
+        'Content-Type' => 'application/xml'
+      }
+      options = setup_options(name)
+      client(options).run :put, '/', body, headers
+    end
+
+    # permission: public-read-write，public-read, private
+    def put_bucket_acl(name, permission)
+      headers = {
+        'x-oss-acl' => permission
+      }
+      options = setup_options(name, 'acl')
+      client(options).run :put, '?acl', nil, headers
+    end
+
+    def put_bucket_logging(source, target = nil, prefix = nil)
+      body = '<?xml version="1.0" encoding="UTF-8"?><BucketLoggingStatus>'
+      if target
+        body += "<LoggingEnabled><TargetBucket>#{target}</TargetBucket>"
+        body += "<TargetPrefix>#{prefix}</TargetPrefix>" if prefix
+        body += '</LoggingEnabled>'
+      end
+      body += '</BucketLoggingStatus>'
+
+      headers = {
+        'Content-Type' => 'application/xml'
+      }
+
+      options = setup_options(source, 'logging')
+      client(options).run :put, '?logging', body, headers
+    end
+
+    def put_bucket_website(name, index, error)
+      body = '<?xml version="1.0" encoding="UTF-8"?><WebsiteConfiguration>' \
+             "<IndexDocument><Suffix>#{index}</Suffix></IndexDocument>"
+      if error
+        body += "<ErrorDocument><Key>#{error}</Key></ErrorDocument>"
+      end
+      body += '</WebsiteConfiguration>'
+
+      headers = {
+        'Content-Type' => 'application/xml'
+      }
+
+      options = setup_options(name, 'website')
+      client(options).run :put, '?website', body, headers
+    end
+
+    def put_bucket_website(name, index, error)
+      body = '<?xml version="1.0" encoding="UTF-8"?><WebsiteConfiguration>' \
+             "<IndexDocument><Suffix>#{index}</Suffix></IndexDocument>"
+      if error
+        body += "<ErrorDocument><Key>#{error}</Key></ErrorDocument>"
+      end
+      body += '</WebsiteConfiguration>'
+
+      headers = {
+        'Content-Type' => 'application/xml'
+      }
+
+      options = setup_options(name, 'website')
+      client(options).run :put, '?website', body, headers
+    end
+
+    def put_bucket_referer(name, allow_empty_referer = true, referers=[])
+      body = '<?xml version="1.0" encoding="UTF-8"?><RefererConfiguration>' \
+             "<AllowEmptyReferer>#{allow_empty_referer}</AllowEmptyReferer >" \
+             "<RefererList>"
+      referers.each do |referer|
+        body += "<Referer>#{referer}</Referer>"
+      end
+      body += '</RefererList></RefererConfiguration>'
+
+      headers = {
+        'Content-Type' => 'application/xml'
+      }
+
+      options = setup_options(name, 'referer')
+      client(options).run :put, '?referer', body, headers
+    end
+
+    # status: Enabled, Disabled
+    def put_bucket_lifecycle(name, rules = [])
+      body = '<?xml version="1.0" encoding="UTF-8"?><LifecycleConfiguration>'
+      rules.each do |rule|
+        rule_content = '<Rule>'
+        rule_content += "<ID>#{rule[:id]}</ID>" if rule[:id]
+        rule_content += "<Prefix>#{rule[:prefix]}</Prefix>" if rule[:prefix]
+        rule_content += "<Status>#{rule[:status]}</Status>"
+        expiration =
+          if rule[:days]
+            "<Days>#{rule[:days]}</Days>"
+          else
+            "<Date>#{rule[:date]}</Date>"
+          end
+        rule_content += "<Expiration>#{expiration}</Expiration></Rule>"
+        body += rule_content
+      end
+
+      body += '</LifecycleConfiguration>'
+
+      headers = {
+        'Content-Type' => 'application/xml'
+      }
+
+      options = setup_options(name, 'lifecycle')
+      client(options).run :put, '?lifecycle', body, headers
+    end
+
+    # params keys: prefix, marker, delimiter, max-keys, encoding-type
+    def get_bucket(name, params = {})
+      options = setup_options(name)
+      client(options).run :get, '/', params
+    end
+
+    [:acl, :location, :logging, :website, :referer, :lifecycle, :cors].each do |sub_resource|
+      define_method("get_bucket_#{sub_resource}".to_sym) do |name|
+        get_bucket_sub_resource(name, sub_resource)
+      end
+    end
+
+    def delete_bucket(name)
+      options = setup_options(name)
+      client(options).run :delete, '/'
+    end
+
+    [:logging, :website, :lifecycle, :cors].each do |sub_resource|
+      define_method("delete_bucket_#{sub_resource}".to_sym) do |name|
+        delete_bucket_sub_resource(name, sub_resource)
+      end
+    end
+
+    def put_bucket_cors(name, rules)
+      body = '<?xml version="1.0" encoding="UTF-8"?><CORSConfiguration>'
+      rules.each do |rule|
+        rule_content = '<CORSRule>'
+        rule_content += cors_rule_content_generator(rule, 'AllowedOrigin')
+        rule_content += cors_rule_content_generator(rule, 'AllowedMethod')
+        rule_content += cors_rule_content_generator(rule, 'AllowedHeader')
+        rule_content += cors_rule_content_generator(rule, 'ExposeHeader')
+        rule_content += cors_rule_content_generator(rule, 'MaxAgeSeconds', false)
+        rule_content += '</CORSRule>'
+        body += rule_content
+      end
+      body += '</CORSConfiguration>'
+
+      headers = {
+        'Content-Type' => 'application/xml'
+      }
+
+      options = setup_options(name, 'cors')
+      client(options).run :put, '?cors', body, headers
+    end
+
+    private
+
+    def cors_rule_content_generator(rule, key, allow_multi = true)
+      options = rule[key]
+      return '' unless options
+      if allow_multi
+        options = options.is_a?(Array) ? options : [options]
+        options.reduce('') do |content, option|
+          content + "<#{key}>#{option}</#{key}>"
+        end
+      else
+        "<#{key}>#{options}</#{key}>"
+      end
+    end
+
+    def delete_bucket_sub_resource(name, sub_resource)
+      options = setup_options(name, sub_resource)
+      client(options).run :delete, "?#{sub_resource}"
+    end
+
+    def get_bucket_sub_resource(name, sub_resource)
+      options = setup_options(name, sub_resource)
+      client(options).run :get, '/', "#{sub_resource}" => nil
+    end
+
+    def setup_options(bucket, sub_resource = nil)
+      {
+        subdomain: bucket,
+        resource: "/#{bucket}/",
+        sub_resource: sub_resource
+      }
+    end
+  end
+end