oss-ruby 1.0.0.beta

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9c5d58f8a8f8af73c7e5a505c7e04e8136023fae
+  data.tar.gz: cd3e9e42e90da89c6eacd6ed984df1e42a9769ca
+SHA512:
+  metadata.gz: 202bdfbf7dfe629accf744b48c4fef7b11328b6ddf55e848d9ef5eb49a3c99b85d1693af6b5105db86b556cc2809615016ac5e33d94e647c142d7d7bdc8b7984
+  data.tar.gz: 568dc2c1bd89f26bc9ce2801966b44a5d821540add10b1a2d0aee47c0e6219150dcb3cc22e56ea038c9264341185f22e2a7cf6b1693e0d5edf9ec81c8a0732b6

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in easy_ping.gemspec
+gemspec
+
+gem 'webmock', '~> 1.22.3'

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    oss-ruby (1.0.0.beta)
+      faraday (~> 0.9.0)
+      mime-types (~> 2.6)
+      nokogiri (~> 1.6.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.8)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    hashdiff (0.2.3)
+    mime-types (2.6.2)
+    mini_portile (0.6.2)
+    multipart-post (2.0.0)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    rake (10.4.2)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    safe_yaml (1.0.4)
+    webmock (1.22.3)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  oss-ruby!
+  rake (~> 10.0)
+  rspec
+  webmock (~> 1.22.3)
+
+BUNDLED WITH
+   1.10.6

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright [2015] [Xiaoguang Chen]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,92 @@
+# oss-ruby
+
+`oss-ruby` is the Ruby SDK of Aliyun OSS API service. All oss api methods are available through this SDK.
+
+What is [Aliyun OSS](http://www.aliyun.com/product/oss)  
+Aliyun OSS [API Official Doc](https://docs.aliyun.com/#/pub/oss)
+
+**Note**
+It's released on [RubyGems](https://rubygems.org/gems/oss-ruby).
+If something doesn't work, feel free to report a bug or start an issue.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'oss-ruby'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install oss-ruby
+
+If you prefer to use the latest code, you can build from source:
+
+```
+gem build oss-ruby.gemspec
+gem install oss-ruby-<VERSION>.gem
+```
+
+## Usage
+
+#### Initialization
+`oss-ruby` requires you to initialize an instance before usage.
+
+```ruby
+# Initialize oss-ruby
+require 'oss'
+
+oss = OSS.new({
+  endpoint: 'oss-cn-hangzhou.aliyuncs.com',
+  access_key_id: 'your_access_key',
+  access_key_secret: 'your_access_secret'
+})
+```
+
+#### Call API with SDK
+Using sdk to call oss service is quite straight forward.
+
+```ruby
+# Get Service
+res = oss.get_service
+p res.status # => 200
+```
+
+#### API Response
+
+Some of the APIs returns with a xml string as response body.
+`oss-ruby` uses `Nokogiri` to parse the xml document internally.
+
+```ruby
+res = oss.get_service
+p res.status # => 200
+p res.body # => "<?xml version=\"1.0\"..."
+p res.doc.xpath("//ID").text # => "1216909307023357"
+# and it can be shorter
+p res.xpath("//ID").text # => "1216909307023357"
+```
+
+When API responds with an error. `oss-ruby` provide a `error` method in response object to easily parse error messages.
+
+```ruby
+res = oss.get_bucket('non-exist-bucket')
+p res.status # => 404
+p res.body # => "<?xml version=\"1.0\"..."
+p res.error.code #=> "NoSuchBucket"
+p res.error.message #=> "The specified bucket does not exist."
+```
+
+And if network connection fails, `oss-ruby` will raise a `OSS::HTTPClientError` with backtrace and error message.
+
+## Other Documentation
+
+* [Quick Start](docs/quick_start.md)
+* [Bucket API](docs/bucket_api.md)
+* [Object API](docs/object_api.md)
+* [Multipart Upload](docs/multipart_upload.md)
+* [Cross-Origin Resource Sharing](docs/cors.md)

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/docs/bucket_api.md

@@ -0,0 +1,100 @@
+# Bucket API
+
+Buckets are the instances with full control of permissions and logs, and they are also the pricing unit in OSS service. Objects must belong to one particular bucket. User can create 10 buckets at most, and space limit of a bucket is 2PB.
+
+* Bucket
+  * Bucket name conventions
+  * Create a bucket
+  * List all buckets
+  * Delete a bucket
+  * Get location of a bucket
+  * Manage permissions of a bucket
+
+#### Bucket name conventions
+
+* Contains only alphanumeric characters, numbers and hyphen.
+* Only lower case is allowed.
+* Must start with alphanumeric character or number.
+* Length between 3-63 bytes.
+
+#### Create a bucket
+You can setup the permission of the bucket during creation, default permission is `private`. And you can also choose which [location](https://docs.aliyun.com/#/pub/oss/product-documentation/domain-region) to store the bucket.
+
+**Note: bucket once created cannot change its name later.**
+
+```ruby
+# method signature
+put_bucket(name, permission = 'private', location = 'oss-cn-hangzhou')
+```
+```ruby
+res = oss.put_bucket('bucket-name')
+p res.status # => 200
+```
+
+#### List all buckets
+You can get the buckets information by simple calling this method without arguments. And 'prefix', 'marker' and 'max-keys' are possible keys to filter results.
+```ruby
+# method signature
+get_service(params = {})
+```
+
+```ruby
+res = oss.get_service
+p res.status # => 200
+
+# filter
+res = oss.get_service(prefix: 'abc-')
+```
+
+#### Delete a bucket
+Note: only empty bucket can be deleted. If you want to delete a bucket that has objects inside, you have to delete all the objects first.
+
+```ruby
+# method signature
+delete_bucket(name)
+```
+
+```ruby
+res = oss.delete_bucket('bucket-name')
+p res.status # => 204
+```
+
+#### Get location of a bucket
+You can get the location of a bucket through `get_bucket_location`
+
+```ruby
+# method signature
+get_bucket_location(name)
+```
+
+```ruby
+res = oss.get_bucket_location('bucket-name')
+p res.status # => 204
+p res.xpath("//LocationConstraint") # => 'oss-cn-hangzhou'
+```
+
+#### Manage permissions of a bucket
+You can change the permission of a bucket after the creation.
+
+```ruby
+# method signature
+put_bucket_acl(name, permission)
+```
+Acceptable `permission`: 'public-read-write', 'public-read', 'private'.
+
+```ruby
+res = oss.put_bucket_acl('bucket-name', 'public-read-write')
+p res.status # => 200
+```
+
+Get the current permission of a bucket can be done throuth `get_bucket_acl`.
+```ruby
+# method signature
+get_bucket_acl(name)
+```
+
+```ruby
+res = oss.get_bucket_acl('bucket-name')
+p res.status # => 200
+p res.xpath("//Grant") # => 'public-read-write'
+```

data/docs/cors.md

@@ -0,0 +1,56 @@
+# Cross-Origin Resource Sharing API
+
+Cross-Origin Resource Sharing allows Javascript scripts from other origins be able to access resources in a specific bucket.
+
+* Cross-Origin Resource Sharing
+  * Setup CORS rules of a bucket
+  * Get CORS rules of a bucket
+  * Delete CORS rules of a bucket
+
+#### Setup CORS rules of a bucket
+Rules can be set through `put_bucket_cors`. A bucket can have at most 10 rules.
+See details spec of a rule in [API doc](https://docs.aliyun.com/#/pub/oss/api-reference/cors&PutBucketcors)
+
+```ruby
+# method signature
+put_bucket_cors(name, rules)
+```
+```ruby
+res = oss.put_bucket_cors(
+  'bucket-name',
+  [{
+    'AllowedOrigin' => '*',
+    'AllowedMethod' => ['PUT', 'GET'],
+    'AllowedHeader' => 'Authorization'
+  }, {
+    'AllowedOrigin' => ['http://www.a.com', 'http://www.b.com'],
+    'AllowedMethod' => 'GET',
+    'AllowedHeader' => 'Authorization',
+    'ExposeHeader'  => ['x-oss-test', 'x-oss-test1'],
+    'MaxAgeSeconds' => 100
+  }]
+)
+p res.status # => 200
+```
+
+#### Get CORS rules of a bucket
+
+```ruby
+# method signature
+get_bucket_cors(name)
+```
+```ruby
+res = oss.get_bucket_cors('bucket-name')
+p res.status # => 200
+```
+
+#### Delete CORS rules of a bucket
+
+```ruby
+# method signature
+delete_bucket_cors(name)
+```
+```ruby
+res = oss.delete_bucket_cors('bucket-name')
+p res.status # => 200
+```

data/docs/multipart_upload.md

@@ -0,0 +1,116 @@
+# Multipart Upload API
+
+OSS service support more than one ways to upload files. Besides `put_object`, user can upload files through 'Multipart Upload'. It supports 'broken-point continuingly-transferring', so it's very suitable in these scenarios:
+
+* Needs support of broken-point continuingly-transferring.
+* Large file with size exceeded 100MB.
+* Terrible Networking condition.
+* File size not determined.
+
+---
+
+* Multipart Upload
+  * Initialize a multipart upload event
+  * Upload an object part
+  * Copy an object part
+  * Complete a multipart upload event
+  * Abort a multipart upload event
+  * List all multipart upload events in a bucket
+  * List parts of an object
+
+#### Initialize a multipart upload event
+Before upload parts of the file you need to upload, you have to initialize a multipart upload event.
+```ruby
+# method signature
+init_multi_upload(bucket, object, headers = {})
+```
+```ruby
+res = oss.init_multi_upload('bucket-name', 'object-name')
+p res.status # => 200
+p res.xpath("//UploadId") # => '0004B9894A22E5B1888A1E29F8236E2D'
+```
+
+'UploadId' is the identifier of the multipart upload event, you'll need it later operations.
+
+#### Upload an object part
+```ruby
+# method signature
+upload_object_part(bucket, object, body, upload_id, part = 1)
+```
+```ruby
+res = upload_object_part('bucket-name', 'object-name', 'String Content of Part 1', '0004B9894A22E5B1888A1E29F8236E2D', 1)
+p res.status # => 200
+```
+
+#### Copy an object part
+`upload_object_part_copy` allows user to copy an existed object as a part of the multipart upload object. And objects large than 1GB must be copied through this method.
+
+Note:
+  * Each part must large than 100KB except the last part.
+  * Valid range of part number: 1~10000.
+
+```ruby
+# method signature
+upload_object_part_copy(source_bucket, source_object, target_bucket, target_object, upload_id, part = 1, headers = {})
+```
+```ruby
+res = upload_object_part_copy('target-bucket-name', 'target-object-name', 'target-bucket-name', 'target-object-name', '0004B9894A22E5B1888A1E29F8236E2D', 2)
+p res.status # => 200
+```
+
+#### Complete a multipart upload event
+After finishing uploading parts, you have to call `complete_multi_upload` to finish the multipart upload event.
+
+```ruby
+# method signature
+complete_multi_upload(bucket, object, upload_id, parts = [])
+```
+```ruby
+res = oss.complete_multi_upload(
+  'bucket-name', 'object-name', '0004B9894A22E5B1888A1E29F8236E2D',
+  [{
+    part_number: 1,
+    etag: "172F5D31191B965FE8CCB5A0F5BECD9A"
+  }, {
+    part_number: 2,
+    etag: "172F5D31191B965FE8CCB5A0F5BECD9A"
+  }]
+)
+p res.status # => 200
+```
+
+#### Abort a multipart upload event
+Sometimes you need to abort the upload event, this is where `abort_multi_upload` come into play.
+
+```ruby
+# method signature
+abort_multi_upload(bucket, object, upload_id)
+```
+```ruby
+res = oss.abort_multi_upload('bucket-name', 'object-name', '0004B9894A22E5B1888A1E29F8236E2D')
+p res.status # => 204
+```
+
+#### List all multipart upload events in a bucket
+You can get all unfinished multipart upload events through `list_multi_upload`.
+
+```ruby
+# method signature
+list_multi_upload(bucket, headers = {})
+```
+```ruby
+res = oss.list_multi_upload('bucket-name')
+p res.status # => 200
+```
+
+#### List parts of an object
+Sometimes you need to view the parts that have been uploaded successfully during a multipart upload event.
+
+```ruby
+# method signature
+list_object_parts(bucket, object, upload_id, headers = {})
+```
+```ruby
+res = oss.list_object_parts('bucket-name', 'object-name', '0004B9894A22E5B1888A1E29F8236E2D')
+p res.status # => 200
+```