qcloud_cos 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 725d8ee2d23b4c1680e6af13c12936afedffd50a
-  data.tar.gz: 77446b32de74008c5d1a31ab665e249df72fbc4d
+  metadata.gz: c46f40136350e35780ce86e5a216af26a75ec799
+  data.tar.gz: a90fe51412a6a35a83188e8509d7f51d48b469ec
 SHA512:
-  metadata.gz: 6f48665e19689e1565beba79216581a69ff4e55bcd426c24a16fbce545c4c3c32c59653fa7ce8f6acdecc00a85e1a4343c3ba5f0b55b05cf80b1f01af3cc1851
-  data.tar.gz: 08c879544700e8b0ac76d9b1d9aa7a8d9a9fe4058ded37fbe65f2cdc2f30c727dcb5348e8018484785589c2949131e3d94935c3f32179b5db06936a3babcc2cc
+  metadata.gz: 9d889e680582184954f7bb93260762f9406acf285b7c7bb70ff439992bda8157e8e8c19cecc7e16ee367f2786982861d4decc8fe110bf9e73dbf4d38c4af0f30
+  data.tar.gz: ffd68ec5201c615ba2d12598a4595148214260a0a90f30d03c837b318768e0a5651be14e97197bcc2154854c8b298f05d4fb278c1ad416e6fa4e3068f7a91595

data/.rubocop.yml

@@ -0,0 +1,37 @@
+# This is the configuration used to check the rubocop source code.
+
+AllCops:
+  Exclude:
+    - 'demo/**/*'
+    - 'test/**/*'
+
+Metrics/LineLength:
+  Max: 100
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Style/AccessorMethodName:
+  Enabled: false
+
+Style/PredicateName:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false

data/.travis.yml

@@ -1,4 +1,7 @@
 language: ruby
 rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
   - 2.2.0
-before_install: gem install bundler -v 1.10.6
+before_install: gem install bundler

data/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in qcloud_cos.gemspec
 gemspec
+gem 'simplecov'

data/README.md

@@ -1,46 +1,79 @@
-# Qcloud Cos
-
-It's the full featured library for qcloud cos, Enjoy it!
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'qcloud_cos'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install qcloud_cos
-
-## Usage
-
-    QCloud::Cos.configure do |config|
-      config.app_id = ""
-      config.access_key = ""
-      config.secret_key = ""
-      config.default_bucket = "bucket-name"
-    end
-
-    QCloud::Cos.list_buckets
-
-    QCloud::Cos.buckets.list
-
-    QCloud::Cos.bucket.files/folders
-
-    QCloud::Cos.bucket.upload
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/zlx/qcloud_cos.
+# Qcloud COS
+
+It's the full featured Ruby SDK for Qcloud COS(Cloud Object Service).
+
+We keep API simple but powerful, to give you more freedom.
+
+Enjoy it!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+
+    gem 'qcloud_cos'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install qcloud_cos
+
+## Usage
+
+```ruby
+QcloudCos.configure do |config|
+  config.app_id = 'app-id'
+  config.secret_id = 'secret_id'
+  config.secret_key = 'secret_key'
+  config.endpoint = "http://web.file.myqcloud.com/files/v1/"
+  config.bucket = "default-bucket-name"
+end
+
+QcloudCos.list # 列出 / 目录下的文件和文件夹
+
+QcloudCos.upload('/test.log', 'Hello World')
+QcloudCos.upload('/test.log', File.new('path/to/log'))
+
+QcloudCos.upload_slice('/video.mp4', 'path/to/video.mp4')
+
+QcloudCos.create_folder('/test/') # 创建目录
+```
+
+More Example and Scenario, visit our [Document](#document)
+
+
+## Document
+
+Here is original Restful API, It has the most detailed and authoritative explanation for every API.
+
++ [COS RESTful API文档](http://www.qcloud.com/wiki/RESTful_API%E6%96%87%E6%A1%A3)
++ [COS 详细文档](http://www.qcloud.com/doc/product/227/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D)
+
+Here is our RDoc Document, It's well format to help you find more detail about methods.
+
++ [RDoc Document](http://www.rubydoc.info/gems/qcloud_cos/0.1.0)
+
+
+Here are some more guides for help you. Welcome to advice.
+
++ [Getting Started](http://git.oschina.net/newell_zlx/cos_ruby_sdk/blob/master/wiki/get_started.md)
+
+
+## Test
+
+We use minitest for test and rubocop for Syntax checker, If you want to make contribute to this library. Confirm below Command is success:
+
+    bundle exec rake test
+
+
+## Authors && Contributors
+
+- [Newell](https://github.com/zlx_star)
+
+
+## License
+
+licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html)

data/Rakefile

@@ -1,10 +1,20 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test
+
+task :test do
+  Rake::Task['test'].invoke
+  # Rake::Task['rubocop'].invoke
+end
+
+RuboCop::RakeTask.new do |task|
+  task.fail_on_error = false
+end

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "qcloud_cos"
+require 'bundler/setup'
+require 'qcloud_cos'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,14 @@ require "qcloud_cos"
 # require "pry"
 # Pry.start
 
-require "irb"
+QcloudCos.configure do |config|
+  config.app_id = ENV['QCLOUD_APP_ID'] || 'app-id'
+  config.secret_id = ENV['QCLOUD_SECRET_ID'] || 'secret_id'
+  config.secret_key = ENV['QCLOUD_SECRET_KEY'] || 'secret_key'
+  config.endpoint = ENV['QCLOUD_ENDPOINT'] || 'https://web.file.myqcloud.com/files/v1/'
+  config.bucket = ENV['QCLOUD_BUCKET'] || 'privatesdkdemo'
+  config.ssl_ca_file = ENV['SSL_CA_FILE'] || 'path/to/ssl/ca/file'
+end
+
+require 'irb'
 IRB.start

data/lib/qcloud_cos.rb

@@ -1,5 +1,66 @@
-require "qcloud_cos/version"
+require 'qcloud_cos/version'
+require 'qcloud_cos/configuration'
+require 'qcloud_cos/authorization'
+require 'qcloud_cos/http'
+require 'qcloud_cos/api'
+require 'qcloud_cos/convenient_api'
 
 module QcloudCos
-  # Your code goes here...
+  EXPIRED_SECONDS = 60 # 60 seconds
+  PUBLIC_EXPIRED_SECONDS = 600 # 10 minutes
+  DEFAULT_SLICE_SIZE = 3_145_728 # 3M
+  MIN_SLICE_FILE_SIZE = 10 # 10M
+  MAX_RETRY_TIMES = 3
+
+  class << self
+    include Api
+    include ConvenientApi
+
+    def configure
+      @configuration ||= Configuration.new
+      yield @configuration
+      @configuration
+    end
+
+    def config
+      @configuration
+    end
+
+    private
+
+    def http
+      @http ||= Http.new(config)
+    end
+
+    def authorization
+      @authorization ||= Authorization.new(QcloudCos.config)
+    end
+
+    def validates(path, options, path_validate = :file_only)
+      Utils.stringify_keys!(options)
+      file_validates(path, path_validate)
+
+      bucket = options['bucket'] || config.bucket
+      fail MissingBucketError unless bucket
+
+      bucket
+    end
+
+    def fixed_path(path)
+      path.start_with?('/') ? path : "/#{path}"
+    end
+
+    def generate_rest_url(bucket, path)
+      "#{config.endpoint}#{config.app_id}/#{bucket}#{path}"
+    end
+
+    def file_validates(path, path_validate)
+      case path_validate.to_s
+      when 'file_only'
+        fail InvalidFilePathError if path.end_with?('/')
+      when 'folder_only'
+        FolderObject.validate(path)
+      end
+    end
+  end
 end

data/lib/qcloud_cos/api.rb

@@ -0,0 +1,365 @@
+# encoding: utf-8
+require 'qcloud_cos/utils'
+require 'qcloud_cos/model/list'
+
+module QcloudCos
+  module Api
+    # 列出所有文件或者目录
+    #
+    # @param path [String] 指定目标路径, 以 / 结尾, 则列出该目录下文件或者文件夹，不以 / 结尾，就搜索该前缀的文件或者文件夹
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :num (100) 指定需要拉取的条目
+    # @option options [String] :pattern (eListBoth) 指定拉取的内容，可选值: eListBoth, eListDirOnly, eListFileOnly
+    # @option options [Integer] :order (0) 指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1
+    # @option options [String] :context ("") 透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。
+    #
+    # @return [Hash]
+    def list(path = '/', options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options, 'both')
+
+      query = {
+        'op' => 'list',
+        'num' => 100
+      }.merge(Utils.hash_slice(options, 'num', 'pattern', 'order', 'context'))
+
+      url = generate_rest_url(bucket, path)
+      sign = authorization.sign(bucket)
+
+      result = http.get(url, query: query, headers: { 'Authorization' => sign }).parsed_response
+      QcloudCos::List.new(result['data'])
+    end
+
+    # 列出所有文件
+    #
+    # @param path [String] 指定目标路径, 以 / 结尾, 则列出该目录下文件，不以 / 结尾，就搜索该前缀的文件
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :num (100) 指定需要拉取的条目
+    # @option options [Integer] :order (0) 指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1
+    # @option options [String] :context ("") 透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。
+    #
+    # @return [Hash]
+    def list_files(path = '/', options = {})
+      Utils.stringify_keys!(options)
+      list(path, options.merge('pattern' => 'eListFileOnly'))
+    end
+
+    # 列出所有目录
+    #
+    # @param path [String] 指定目标路径, 以 / 结尾, 则列出该目录下文件夹，不以 / 结尾，就搜索该前缀的文件夹
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :num (100) 指定需要拉取的条目
+    # @option options [Integer] :order (0) 指定拉取文件的顺序, 默认为正序(=0), 可选值: 0, 1
+    # @option options [String] :context ("") 透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的context透传到参数中。order用于指定翻页顺序。若order填0，则从当前页正序/往下翻页；若order填1，则从当前页倒序/往上翻页。
+    #
+    # @return [Hash]
+    def list_folders(path = '/', options = {})
+      Utils.stringify_keys!(options)
+      list(path, options.merge('pattern' => 'eListDirOnly'))
+    end
+
+    # 创建目录
+    #
+    # @param path [String] 指定要创建的文件夹名字，支持级联创建
+    # @param options [Hash] options
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :biz_attr 指定目录的 biz_attr 由业务端维护, 会在文件信息中返回
+    #
+    # @return [Hash]
+    def create_folder(path, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options, :folder_only)
+
+      url = generate_rest_url(bucket, path)
+
+      query = { 'op' => 'create' }.merge(Utils.hash_slice(options, 'biz_attr'))
+
+      headers = {
+        'Authorization' => authorization.sign(bucket),
+        'Content-Type' => 'application/json'
+      }
+
+      http.post(url, body: query.to_json, headers: headers).parsed_response
+    end
+
+    # 上传文件
+    #
+    # @param path [String] 指定上传文件的路径
+    # @param file_or_bin [File||String] 指定文件或者文件内容
+    # @param options [Hash] options
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :biz_attr 指定文件的 biz_attr 由业务端维护, 会在文件信息中返回
+    #
+    # @return [Hash]
+    def upload(path, file_or_bin, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options)
+
+      url = generate_rest_url(bucket, path)
+
+      query = {
+        'op' => 'upload'
+      }.merge(Utils.hash_slice(options, 'biz_attr')).merge(generate_file_query(file_or_bin))
+
+      http.post(url, query: query, headers: { 'Authorization' => authorization.sign(bucket) }).parsed_response
+    end
+    alias_method :create, :upload
+
+    # 分片上传
+    #
+    # @param dst_path [String] 指定文件的目标路径
+    # @param src_path [String] 指定文件的本地路径
+    # @param options [Hash] options
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :biz_attr 指定文件的 biz_attr 由业务端维护, 会在文件信息中返回
+    # @option options [Integer] :session 指定本次分片上传的 session
+    # @option options [Integer] :slice_size 指定分片大小
+    #
+    # @raise [MissingSessionIdError] 如果缺少 session
+    # @raise [FileNotExistError] 如果本地文件不存在
+    # @raise [InvalidFilePathError] 如果目标路径是非法文件路径
+    #
+    # @return [Hash]
+    def upload_slice(dst_path, src_path, options = {})
+      dst_path = fixed_path(dst_path)
+      fail FileNotExistError unless File.exist?(src_path)
+      bucket = validates(dst_path, options)
+
+      filesize = File.size(src_path)
+      sha = Utils.generate_file_sha(src_path)
+      sign = authorization.sign(bucket)
+
+      resp = init_slice_upload(dst_path, filesize, sha, options.merge('sign' => sign))
+      puts "init slice upload: #{resp}"
+
+      data = resp['data']
+      return data if data.key?('url') # 妙传命中
+
+      slice_size = data['slice_size'] || DEFAULT_SLICE_SIZE
+      session = data['session'] || options['session']
+      offset = data['offset'] || 0
+
+      fail MissingSessionIdError unless session
+
+      while offset < filesize
+        filecontent = IO.read(src_path, slice_size, offset)
+
+        retry_times = 0
+        begin
+          result = upload_part(dst_path, session, offset, filecontent, options)
+          puts "upload part data: #{result}"
+
+          if result.key?('data') && result['data'].key?('session')
+            session = result['data']['session']
+          elsif result.key?('data') && result['data'].key?('url')
+            return result['data']
+          end
+        rescue => e
+          retry_times += 1
+          puts "retry part upload request with offset:#{offset}, slice_size:#{slice_size} ..."
+          retry if retry_times <= config.max_retry_times
+          raise e
+        end
+        offset += slice_size
+      end
+    end
+
+    # 初始化分片上传
+    # @private
+    #
+    # @param path [String] 指定上传文件的路径
+    # @param filesize [Integer] 指定文件总大小
+    # @param sha [String] 指定该文件的 sha 值
+    # @param options [Hash] options
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Integer] :biz_attr 指定文件的 biz_attr 由业务端维护, 会在文件信息中返回
+    # @option options [Integer] :session 如果想要断点续传,则带上上一次的session
+    # @option options [Integer] :slice_size 指定分片大小
+    #
+    # @return [Hash]
+    def init_slice_upload(path, filesize, sha, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options)
+
+      url = generate_rest_url(bucket, path)
+      query = generate_slice_upload_query(filesize, sha, options)
+      sign = options['sign'] || authorization.sign(bucket)
+
+      http.post(url, query: query, headers: { 'Authorization' => sign }).parsed_response
+    end
+    private :init_slice_upload
+
+    # 上传分片数据
+    # @private
+    #
+    # @param path [String] 指定上传文件的路径
+    # @param session [String] 指定分片上传的 session id
+    # @param offset [Integer] 本次分片位移
+    # @param content [Binary] 指定文件内容
+    # @param options [Hash] options
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    #
+    # @return [Hash]
+    def upload_part(path, session, offset, content, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options)
+
+      url = generate_rest_url(bucket, path)
+      query = generate_upload_part_query(session, offset, content)
+      sign = options['sign'] || authorization.sign(bucket)
+
+      http.post(url, query: query, headers: { 'Authorization' => sign }).parsed_response
+    end
+    private :upload_part
+
+    # 更新文件或者目录信息
+    #
+    # @param path [String] 指定文件或者目录路径
+    # @param biz_attr [String] 指定文件或者目录的 biz_attr
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    #
+    # @return [Hash]
+    def update(path, biz_attr, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options, 'both')
+      url = generate_rest_url(bucket, path)
+
+      query = { 'op' => 'update', 'biz_attr' => biz_attr }
+
+      resource = "/#{bucket}#{Utils.url_encode(path)}"
+      headers = {
+        'Authorization' => authorization.sign_once(bucket, resource),
+        'Content-Type' => 'application/json'
+      }
+
+      http.post(url, body: query.to_json, headers: headers).parsed_response
+    end
+
+    # 删除文件或者目录
+    #
+    # @param path [String] 指定文件或者目录路径
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    #
+    # @return [Hash]
+    def delete(path, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options, 'both')
+      url = generate_rest_url(bucket, path)
+
+      query = { 'op' => 'delete' }
+
+      resource = "/#{bucket}#{Utils.url_encode(path)}"
+      headers = {
+        'Authorization' => authorization.sign_once(bucket, resource),
+        'Content-Type' => 'application/json'
+      }
+
+      http.post(url, body: query.to_json, headers: headers).parsed_response
+    end
+
+    # 删除目录
+    #
+    # @param path [String] 指定目录路径
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    # @option options [Boolean] :recursive (false) 指定是否需要级连删除
+    #
+    # @raise [InvalidFolderPathError] 如果路径是非法文件夹路径
+    #
+    # @return [Hash]
+    def delete_folder(path, options = {})
+      validates(path, options, 'folder_only')
+
+      return delete(path, options) if options['recursive'] != true
+
+      loop do
+        objects = list(path, options)
+        objects.each do |object|
+          if object.is_a?(QcloudCos::FolderObject)
+            delete_folder("#{path}#{object.name}/", options)
+          elsif object.is_a?(QcloudCos::FileObject)
+            delete_file("#{path}#{object.name}", options)
+          end
+        end
+        break unless objects.has_more
+        options['context'] = objects.context
+      end
+      delete(path)
+    end
+
+    # 删除文件
+    #
+    # @param path [String] 指定文件路径
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    #
+    # @raise [InvalidFilePathError] 如果文件路径不合法
+    #
+    # @return [Hash]
+    def delete_file(path, options = {})
+      fail InvalidFilePathError if path.end_with?('/')
+      delete(path, options)
+    end
+
+    # 查看文件或者文件夹信息
+    #
+    # @param path [String] 指定文件或者文件夹目录
+    # @param options [Hash] 额外参数
+    # @option options [String] :bucket (config.bucket_name) 指定当前 bucket, 默认是配置里面的 bucket
+    #
+    # @return [Hash]
+    def stat(path, options = {})
+      path = fixed_path(path)
+      bucket = validates(path, options, 'both')
+      url = generate_rest_url(bucket, path)
+
+      query = { 'op' => 'stat' }
+      sign = authorization.sign(bucket)
+
+      http.get(url, query: query, headers: { 'Authorization' => sign }).parsed_response
+    end
+
+    private
+
+    def generate_slice_upload_query(filesize, sha, options)
+      {
+        'op' => 'upload_slice',
+        'filesize' => filesize,
+        'sha' => sha,
+        'filecontent' => Tempfile.new("temp-#{Time.now.to_i}")
+      }.merge(Utils.hash_slice(options, 'biz_attr', 'session', 'slice_size'))
+    end
+
+    def generate_upload_part_query(session, offset, content)
+      {
+        'op' => 'upload_slice',
+        'session' => session,
+        'offset' => offset
+      }.merge(generate_file_query(content))
+    end
+
+    def generate_file_query(file_or_bin)
+      query = {}
+      if file_or_bin.respond_to?(:read)
+        query['filecontent'] = file_or_bin
+        query['sha'] = Utils.generate_sha(IO.binread(file_or_bin))
+      else
+        query['filecontent'] = generate_tempfile(file_or_bin)
+        query['sha'] = Utils.generate_sha(file_or_bin)
+      end
+      query
+    end
+
+    def generate_tempfile(file_or_bin)
+      tempfile = Tempfile.new("temp-#{Time.now.to_i}")
+      tempfile.write(file_or_bin)
+      tempfile.rewind
+      tempfile
+    end
+  end
+end