upyun 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e728cd2f23654592cfaea37730c0ad780a31eea
-  data.tar.gz: 41572412bf3d5ea83525082d71851687605fc7bc
+  metadata.gz: bfbd5be64ea11f088fedd5b5923496458ca543a9
+  data.tar.gz: b269595a497748ecc3c744aa43595aa84d03ac69
 SHA512:
-  metadata.gz: ec030a7fcc5ff6009b077d2408bfa945666bcbeebf49f0fc9fd33dfb2c8635c74e84baea60943bc23c6ba4fcef794d4b6e0aeae92b407be203fda37a32153b62
-  data.tar.gz: 8ad799d0272e685c803308c313bea67d75432331d9964416fba150b8802df9b6e3f8cc7b9b08d3bc97bbe45db111814f12509eabab79a8bd6599bbad7ab5ed83
+  metadata.gz: 53fa5fce2ac4c9886659f080026136c8d2213724ac9904f2a77864d2c8045b57e9cc1bc9e7349ad51bd175dfa93c0bc2baa9f0985d04f29ce0d39db42c1822cf
+  data.tar.gz: ec874df8d90f96dde3b8ace8d47bb9498120192221c032b9618bd457e516785d9d3ae6a9d9075733b6336a328efe495ec62a309496f6057e3dc342a63f12116b

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## CHANGE LOG
+
+### v1.0.2
+- 初始化实例的时候增加选项，特别地将连接超时时间设为 60s；
+- URL `encode`, `decode` 使用 `open-uri` 代替 `uri`；
+- 定义 `User-Agent` 为 `Upyun-Ruby-SDK-<VERSION>`；
+- `Upyun::Rest#usage` 方法如下去掉多余的参数；
+

data/README.md

@@ -3,27 +3,35 @@
 [![Build status](https://img.shields.io/travis/upyun/ruby-sdk.svg?style=flat)](https://travis-ci.org/upyun/ruby-sdk)
 [![Coverage Status](https://img.shields.io/coveralls/upyun/ruby-sdk.svg)](https://coveralls.io/r/upyun/ruby-sdk)
 
-[UPYUN](https://www.upyun.com) [Rest API](http://docs.upyun.com/api/rest_api/) 和 [Form API](http://docs.upyun.com/api/form_api/) 的 Ruby SDK !
+[UPYUN](https://www.upyun.com) 官方 [Rest API](http://docs.upyun.com/api/rest_api/) 以及 [Form API](http://docs.upyun.com/api/form_api/) SDK !
 
+> **注：**
+> `0.x.x` 版本为之前第三方开发者 [veggie89](https://rubygems.org/profiles/veggie89) 开发，后续将不会维护，如果您有使用 `0.x.x` 版本，请尽快切换至 `1.x.x` 版本，以获得最新的官方 SDK 支持
 
-## 安装说明
+## 安装
 
-*Gemfile* 中加入以下代码
+在 `Gemfile` 中加入以下代码
 
 ```ruby
-gem 'upyun'
+gem 'upyun', '~> 1.0.1'
 ```
 
-然后执行:
+然后执行如下命令安装:
 
-    $ bundle
+```
+$ bundle
+```
 
-或者可以手动安装:
+或者可以使用 `gem` 手动安装:
 
-    $ gem install upyun
+```
+$ gem install upyun
+```
 
 ## 基本使用
 
+在使用本 SDK 之前，您需要拥有一个有效的 UPYUN 空间，并做好操作员的授权。详情可见 [开发者指南](http://docs.upyun.com/guide/#_2)
+
 ### Rest API 使用
 
 #### 初始化一个实例
@@ -31,13 +39,17 @@ gem 'upyun'
 ```ruby
 require 'upyun'
 
-upyun = Upyun::Rest.new('bucket', 'operator', 'password', 'endpoint')
+upyun = Upyun::Rest.new('bucket', 'operator', 'password', 'options', 'endpoint')
 ```
+**参数**
 
-其中，参数 `bucket` 为空间名称，`operator` 为授权操作员帐号, `password` 为授权操作员密码，必选。
+* `bucket`: UPYUN 空间名称
+* `operator`: 授权操作员帐号
+* `password`: 授权操作员密码
+* `options`: 连接选项，可用的选项见[RestClient::Resource](https://github.com/rest-client/rest-client/blob/master/lib/restclient/resource.rb), 默认设置超时时间 60s
+* `endpoint`（可选）（默认：`Upyun::ED_AUTO`）: API接入点，可根据具体网络情况设置最优的接入点，详情见 [API 域名](http://docs.upyun.com/api/)
 
-参数 `endpoint` 为又拍云存储 API 接入点，根据国内的网络情况，又拍云存储 API 提供了电信、联通（网通）、移动（铁通）数个接入点，
-在初始化时可由参数 `endpoint` 进行设置，详情查阅 [API 域名](http://docs.upyun.com/api/)。其可选的值有：
+其中 `endpoint` 可选值如下：
 
 ```ruby
 Upyun::ED_AUTO     # 自动判断最优线路
@@ -46,51 +58,73 @@ Upyun::ED_UNION    # 联通（网通）接入点
 Upyun::ED_CMCC     # 移动（铁通）接入点
 ```
 
-默认设置为 `Upyun::ED_AUTO` ，但是我们推荐根据服务器网络状况，手动设置合理的接入点以获取最佳的访问速度。
-同时，也可以在初始化一个实例之后通过：
+
+> 在初始化实例后，也可以重新切换 API 接入点，方法如下：
 
 ```ruby
 upyun.endpoint = Upyun::ED_CMCC
 ```
-更改接入点。
 
 #### 上传文件
 
+##### 默认方式
 默认使用 Upyun 基本 Header 头上传文件:
 
+> **注：**
+> 这种方式只指定了又拍云必选的 `Date`, `Content-Length` 两个 Header，其它 Header 信息均未指定
+
 ```ruby
 upyun.put('/save/to/path', 'file or binary')
 ```
-其中 `/save/to/path` 为文件保存路径，  `file or binary` 为本机上文件路径或者文件内容。
-**注：**
-> 这里只指定了又拍云必选的 `Date`, `Content-Length` 两个 Header，其它 Header 信息均未指定
+**参数**
+
+* `/save/to/path`： 文件在 UPYUN 空间的保存路径
+* `file or binary`：本地文件路径或文件内容
 
-也可以使用 Upyun 定义的额外 Header 头上传文件，详情查阅 [Rest API](http://docs.upyun.com/api/rest_api/), 如:
+##### 自定义方式
+您也可以选择使用 API 允许的额外可选 HTTP Header 参数，以使用 API 提供的预处理等功能：
 
 ```ruby
 headers = {'Content-Type' => 'image/jpeg', 'x-gmkerl-type' => 'fix_width', 'x-gmkerl-value' => 1080}
 upyun.put('/save/to/path', 'file or binary', headers)
 ```
 
+其中， `/save/to/path` 和 `file or binary` 和默认上传方式中一致，`headers` 参数即为额外的可选 HTTP Header 参数，详情查阅 [Rest API](http://docs.upyun.com/api/rest_api/#_4)
+
+**返回**
+
 上传成功返回 `true`，失败返回一个 `Hash` 结构: `{error: {code: code, message: message}}`,
 其中 `code` 为又拍云返回的错误码, `message` 为错误信息。
 
 
 #### 下载文件
 
+##### 获取文件内容
+
 ```ruby
 file = upyun.get('/path/to/file')
 ```
 
+**参数**
+
+* `'/path/to/file'`: 文件在 UPYUN 空间中的路径
+
+**返回**
 下载成功返回文件信息，失败返回一个 `Hash`: `{error: {code: code, message: message}}`,
 其中 `code` 为又拍云返回的错误码, `message` 为错误信息。
 
-也可以指定保存路径，下载到的文件将写入到保存路径中:
+##### 保存文件至本地
 
 ```ruby
 upyun.get('/path/to/file', 'saved/foo.png')
 ```
 
+**参数**
+
+* `'/path/to/file'`: 文件在 UPYUN 空间中的路径
+* `saved/foo.png`: 文件本地保存路径
+
+**返回**
 下载成功返回获取的文件长度。
 
 
@@ -99,6 +133,11 @@ upyun.get('/path/to/file', 'saved/foo.png')
 ```ruby
 upyun.getinfo('/path/to/file')
 ```
+**参数**
+
+* `'/path/to/file'`: 文件在 UPYUN 空间中的路径
+
+**返回**
 
 成功返回 `Hash` 结构:
 
@@ -120,6 +159,11 @@ upyun.getinfo('/path/to/file')
 ```ruby
 upyun.delete('/path/to/file')
 ```
+**参数**
+
+* `'/path/to/file'`: 文件在 UPYUN 空间中的路径
+
+**返回**
 
 成功返回: `true`,
 
@@ -131,6 +175,12 @@ upyun.delete('/path/to/file')
 upyun.mkdir('/path/to/dir')
 ```
 
+**参数**
+
+* `'/path/to/dir'`: 文件在 UPYUN 空间中的路径
+
+**返回**
+
 成功返回: `true`,
 
 失败返回一个 `Hash`: `{error: {code: code, message: message}}`。
@@ -140,7 +190,11 @@ upyun.mkdir('/path/to/dir')
 ```ruby
 upyun.getlist('/path/to/dir')
 ```
+**参数**
 
+* `'/path/to/dir'`: 文件在 UPYUN 空间中的路径
+
+**返回**
 成功返回一个数组，每个数组成员为一个文件/目录:
 
 ```ruby
@@ -156,6 +210,8 @@ upyun.getlist('/path/to/dir')
 upyun.usage
 ```
 
+**返回**
+
 成功返回空间使用量（单位为 `Byte`）: `12400`,
 
 失败返回一个 `Hash`: `{error: {code: code, message: message}}`。
@@ -167,32 +223,38 @@ upyun.usage
 ```ruby
 require 'upyun'
 
-upyun = Upyun::Form.new('form-password', 'bucket')
+upyun = Upyun::Form.new('form-api-secret', 'bucket', 'options')
 ```
 
-其中，参数 `form-password` 为空间表单 API 密钥，可通过又拍云后台获取，`bucket` 为空间名称（必选）。
+**参数**
 
-与 Rest API 相似， 表单 API 也有个实例变量 `endpoint` 代表又拍云基本域名，默认设置为 `Upyun::ED_AUTO` ，也可以在初始化一个实例之后通过：
+* `form-api-secret`: 表单 API 密钥，可通过 UPYUN 用户控制面板获取
+* `bucket`: UPYUN 空间名称
+* `options`: 连接选项，可用的选项见[RestClient::Resource](https://github.com/rest-client/rest-client/blob/master/lib/restclient/resource.rb), 默认设置超时时间 60s
+
+与 Rest API 相似， 表单 API 也有个实例变量 `endpoint` 代表又拍云基本域名，默认设置为 `Upyun::ED_AUTO` ，也可以在初始化一个实例之后通过如下方式切换：
 
 ```ruby
 upyun.endpoint = Upyun::ED_CMCC
 ```
-更改接入点。
-
 
 #### 上传文件
 
+##### 简化版
 为了简化使用，又拍云文档必选的参数中:
->
-  `save-key` 默认设置为: `'/{year}/{mon}/{day}/{filename}{.suffix}'`
-  `expiration` 默认设置为10分钟: `Time.now.to_i + 600`
 
+> `save-key` 默认设置为: `'/{year}/{mon}/{day}/{filename}{.suffix}'` <br />
+> `expiration` 默认设置为10分钟: `Time.now.to_i + 600`
 
-使用简化版本，不使用额外的策略参数:
+<br />
+
+> 使用简化版本，将不使用额外的策略参数:
 
 ```ruby
 upyun.upload('file')
 ```
+
+**返回**
 上传结果返回一个 `Hash` 结构:
 
 ```ruby
@@ -205,13 +267,15 @@ upyun.upload('file')
 }
 ```
 其中
-  1. `code`: 返回的状态码，`200` 为成功，其它为失败
-  2. `message`: 错误信息，具体查阅 [表单 API 状态代码表](http://docs.upyun.com/api/form_api/#api_2)
-  3. `url`: 上传文件保存路径
-  4. `time`: 请求的时间戳
-  5. `sign`: 签名参数，详情见 [sign与non-sign参数说明](http://docs.upyun.com/api/form_api/#note6)
-  6. 如果在请求中指定了 `ext-param`, 那么返回的结构中也会有 `ext-param` 字段，详情见 [ext-param](http://docs.upyun.com/api/form_api/#note5)
 
+* `code`: 返回的状态码，`200` 为成功，其它为失败
+* `message`: 错误信息，具体查阅 [表单 API 状态代码表](http://docs.upyun.com/api/form_api/#api_2)
+* `url`: 上传文件保存路径
+* `time`: 请求的时间戳
+* `sign`: 签名参数，详情见 [sign与non-sign参数说明](http://docs.upyun.com/api/form_api/#note6)
+* 如果在请求中指定了 `ext-param`, 那么返回的结构中也会有 `ext-param` 字段，详情见 [ext-param](http://docs.upyun.com/api/form_api/#note5)
+
+##### 自定义参数
 可以在上传的时候指定一些策略参数:
 
 ```ruby
@@ -227,10 +291,10 @@ upyun.upload('file', opts)
 详情查阅 [通知规则](http://docs.upyun.com/api/form_api/#notify_return)
 
 
-## Contributing
+## 贡献
 
-1. Fork it ( https://github.com/[my-github-username]/upyun/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+1. Fork 本仓库 ( https://github.com/upyun/ruby-sdk/fork )
+2. 创建您的新特性分支 (`git checkout -b my-new-feature`)
+3. 提交你的更新 (`git commit -am 'Add some feature'`)
+4. 同步你的代码到 GitHub 远程仓库 (`git push origin my-new-feature`)
+5. 发起 Pull Request 给我们

data/lib/upyun/form.rb

@@ -33,10 +33,12 @@ module Upyun
     )
 
     attr_accessor :bucket, :password
+    attr_reader :options
 
-    def initialize(password, bucket)
+    def initialize(password, bucket, options={timeout: 60})
       @password = password
       @bucket = bucket
+      @options = options
       @endpoint = ED_AUTO
     end
 
@@ -53,7 +55,7 @@ module Upyun
         file: File.new(file, 'rb')
       }
 
-      RestClient.post("http://#{@endpoint}/#{@bucket}", payload) do |res|
+      rest_client.post(payload, {'User-Agent' => "Upyun-Ruby-SDK-#{VERSION}"}) do |res|
         case res.code
         when 302
           res
@@ -83,5 +85,9 @@ module Upyun
         end
         policies.to_json
       end
+
+      def rest_client
+        @rest_clint ||= RestClient::Resource.new("http://#{@endpoint}/#{@bucket}", options)
+      end
   end
 end

data/lib/upyun/rest.rb

@@ -1,21 +1,24 @@
 # encoding: utf-8
 require 'restclient'
-require 'uri'
+require 'open-uri'
 
 module Upyun
   class Rest
     include Utils
 
-    def initialize(bucket, operator, password, endpoint=Upyun::ED_AUTO)
+    attr_reader :options
+
+    def initialize(bucket, operator, password, options={timeout: 60}, endpoint=Upyun::ED_AUTO)
       @bucket = bucket
       @operator = operator
       @password = md5(password)
+      @options = options
       @endpoint = endpoint
     end
 
     def put(path, file, headers={})
       raise ArgumentError, "'file' is not an instance of String" unless file.is_a?(String)
-      headers = headers.merge({"mkdir" => true}) unless headers.key?("mkdir")
+      headers = headers.merge({'mkdir' => true}) unless headers.key?('mkdir')
       options = if File.file?(file)
                   {body: File.read(file), length: File.size(file), headers: headers}
                 else
@@ -47,22 +50,23 @@ module Upyun
       request(:post, path, {headers: {folder: true, mkdir: true}})
     end
 
-    def getlist(path="/")
+    def getlist(path='/')
       res = request(:get, path)
       return res if res.is_a?(Hash)
-      res.split("\n").map do |f|
-        attrs = f.split("\t")
+
+      res.split('\n').map do |f|
+        attrs = f.split('\t')
         {
           name: attrs[0],
-          type: attrs[1] == "N" ? :file : :folder,
+          type: attrs[1] == 'N' ? :file : :folder,
           length: attrs[2].to_i,
           last_modified: attrs[3].to_i
         }
       end
     end
 
-    def usage(path="/")
-      res = request(:get, path, {params: "usage"})
+    def usage
+      res = request(:get, '/', {query: 'usage'})
       return res if res.is_a?(Hash)
 
       # RestClient has a bug, body.to_i returns the code instead of body,
@@ -80,30 +84,30 @@ module Upyun
       end
 
       def fullpath(path)
-        "/#{@bucket}#{URI.encode(URI.decode(path[0] == '/' ? path : '/' + path))}"
-      end
-
-      def encode(fullpath, params)
-        URI.join("http://#{@endpoint}", fullpath, params.nil? ? '' : '?' + params).to_s
+        decoded = URI::encode(URI::decode(path.force_encoding('utf-8')))
+        "/#{@bucket}#{decoded.start_with?('/') ? decoded : '/' + decoded}"
       end
 
       def request(method, path, options={})
         fullpath = fullpath(path)
-        url = encode(fullpath, options[:params])
+        query = options[:query]
+        fullpath_query = "#{fullpath}#{query.nil? ? '' : '?' + query}"
         headers = options[:headers] || {}
         date = gmdate
         length = options[:length] || 0
         headers.merge!({
+          'User-Agent' => "Upyun-Ruby-SDK-#{VERSION}",
           'Date' => date,
           'Authorization' => sign(method, date, fullpath, length)
         })
 
         if [:post, :patch, :put].include? method
-          RestClient.send(method, url, options[:body].nil? ? "" : options[:body], headers) do |res|
+          body = options[:body].nil? ? '' : options[:body]
+          rest_client[fullpath_query].send(method, body, headers) do |res|
             res.code == 200 ? true : {error: {code: res.code, message: res.body}}
           end
         else
-          RestClient.send(method, url, headers) do |res|
+          rest_client[fullpath_query].send(method, headers) do |res|
             if res.code == 200
               case method
               when :get
@@ -120,6 +124,10 @@ module Upyun
         end
       end
 
+      def rest_client
+        @rest_clint ||= RestClient::Resource.new("http://#{@endpoint}", options)
+      end
+
       def gmdate
         Time.now.utc.strftime('%a, %d %b %Y %H:%M:%S GMT')
       end

data/lib/upyun/version.rb

@@ -1,3 +1,3 @@
 module Upyun
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/spec/upyun_spec.rb

@@ -1,4 +1,5 @@
 require File.dirname(__FILE__) + '/spec_helper'
+require 'uri'
 
 describe "Upyun Restful API Basic testing" do
   before :all do
@@ -42,6 +43,24 @@ describe "Upyun Restful API Basic testing" do
       expect(@upyun.put(@path, @file, headers)).to be true
     end
 
+    describe "PUT a file while the path is not encoded" do
+      before(:all) { @path_cn = '/ruby-sdk/这是中文路径/foo.txt' }
+
+      it "should success" do
+        expect(@upyun.put(@path_cn, @str)).to be true
+      end
+
+      it "then get the non encoded path also success" do
+        expect(@upyun.get(@path_cn)).to eq(@str)
+      end
+
+      it "then get the encoded path should also success" do
+        expect(@upyun.get(URI.encode(@path_cn))).to eq(@str)
+      end
+
+      after(:all) { @upyun.delete(@path_cn) }
+    end
+
     after { @upyun.delete(@path) }
   end
 
@@ -124,7 +143,7 @@ describe "Upyun Restful API Basic testing" do
   end
 end
 
-describe "Form Upload" do
+describe "Form Upload", current: true do
   before :all do
     @form = Upyun::Form.new('ESxWIoMmF39nSDY7CSFUsC7s50U=', 'sdkfile')
     @file = File.expand_path('../upyun.jpg', __FILE__)

metadata

@@ -1,83 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: upyun
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - jsvisa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-17 00:00:00.000000000 Z
+date: 2014-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 1.6.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 1.6.7
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 4.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 4.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 3.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 3.1.0
 description: UPYUN Rest API and Form API SDK
@@ -87,10 +87,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".coveralls.yml"
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
+- .coveralls.yml
+- .gitignore
+- .rspec
+- .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -114,17 +115,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.4
+rubygems_version: 2.1.11
 signing_key: 
 specification_version: 4
 summary: UPYUN API SDK