mss-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1dc2b9530276e02bca4a51104fa404e15f3b05f9
+  data.tar.gz: 20e2e17ea7b1e2a43673e93bb99430503d5e36c8
+SHA512:
+  metadata.gz: 8aefe23900b039b77f0638c62c1479b5e1e1cfbcfd958f08dc1caab400402c6bf442fdb5b4fc46fe723eb62f7b0af85325d7c814255038e6d9b5c92a7e2f0ccb
+  data.tar.gz: 6e6ebbe26542eeb728f2b26dd58e89eb68207ae4f3aca17a1fe58bfaf1e3861d48933e20d72cac9e28431907685364bc9e51b1bb827004d6ac3811f11b6ab4d2

data/.yardopts

@@ -0,0 +1,9 @@
+--title 'MSS SDK for Ruby'
+--output-dir api-docs
+--template-path doc-src/templates
+--markup markdown
+--markup-provider rdiscount
+--hide-api private
+--plugin sitemap
+-e doc-src/api_docs_plugin.rb
+lib/**/*.rb

data/README.md

@@ -0,0 +1,192 @@
+# MSS(Meituan Storage Service) SDK for Ruby
+
+This is MSS SDK for Ruby.
+
+## Introduction
+
+### MSS服务介绍
+美团云存储服务（Meituan Storage Service, 简称MSS)，是美团云对外提供的云存储服务，其具备高可靠，安全，低成本等特性，并且其API兼容S3。MSS适合存放非结构化的数据，比如图片，视频，文档，备份等。
+
+### MSS基本概念介绍
+* MSS的API兼容S3, 其基本概念也和S3相同，主要包括Object, Bucket, Access Key, Secret Key等。
+
+* Object对应一个文件，包括数据和元数据两部分。元数据以key-value的形式构成，它包含一些默认的元数据信息，比如Content-Type, Etag等，用户也可以自定义元数据。
+
+* Bucket是object的容器，每个object都必须包含在一个bucket中。用户可以创建任意多个bucket。
+
+* Access Key和Secret Key: 用户注册MSS时，系统会给用户分配一对Access Key和Secret Key, 用于标识用户，用户在使用API使用MSS服务时，需要使用这两个Key。请在美团云管理控制台查询AccessKey和SecretKey。
+
+### MSS访问域名
+
+```
+  mtmss.com
+```
+
+## Installation
+
+  安装MSS SDK for Ruby，需要ruby与gem，并且ruby版本在1.9.3以上。
+
+```
+  # Build MSS SDK for Ruby Gem
+  gem build mss-sdk.gemspec
+
+  # Install MSS SDK for Ruby Gem
+  gem install -l mss-sdk-1.0.0.gem
+```
+
+## Quick Start
+
+##### 初始化
+
+```ruby
+  require 'mss-sdk'
+  s3 = MSS::S3.new({
+    :s3_endpoint => 'mtmss.com',
+    :use_ssl => false,
+    :s3_force_path_style => true,
+    :access_key_id => '****Access Key****',
+    :secret_access_key => '****Access Secret****'})
+```
+
+##### 新建bucket
+
+```ruby
+  bucket = s3.buckets.create('bucket_name')
+```
+
+##### 列出所有bucket
+
+```ruby
+  s3.buckets.each do |bucket|
+    puts bucket.name
+  end
+```
+
+##### 设置bucket属性为公共可读
+
+```ruby
+  bucket.set_acl_public_read
+```
+
+##### 设置bucket属性为私有
+
+```ruby
+  bucket.set_acl_private
+```
+
+##### 判断bucket是否存在
+
+```ruby
+  bucket.exists?
+```
+
+##### 从字符串或缓冲区上传对象
+
+```ruby
+  object_name_one = 'object1'
+  object_content = 'test'
+  obj = bucket.objects[object_name_one].write(object_content)
+```
+
+##### 删除对象
+
+```ruby
+  obj.delete
+```
+
+##### 从文件上传对象
+
+```ruby
+  object_name_for_test_upload = 'object2'
+  upload_file_path = 'filepath'
+  obj_upload = bucket.objects[object_name_for_test_upload]
+  obj_upload.write(:file => upload_file_path)
+```
+
+##### 下载对象到本地文件
+
+```ruby
+  File.open('output', 'wb') do |file|
+    obj_upload.read do |chunk|
+      file.write(chunk)
+    end
+  end
+```
+
+##### 生成预签名的对象地址
+  
+```ruby
+  temp_url_for_read = obj_upload.url_for(:read, {:expire => 600})
+  puts temp_url_for_read
+```
+
+##### 删除bucket内所有对象
+
+```ruby
+  bucket.clear!
+```
+
+##### 删除bucket
+
+```ruby
+  bucket.delete
+```
+
+##### 大文件分片上传
+
+```ruby
+  upload = bucket.objects["Hello美团云！"].multipart_upload
+  upload.add_part("a" * 5242880)
+  upload.add_part("b" * 2097152)
+  upload.complete()
+  puts "Multipart upload succ, upload id:" + upload.id
+```
+
+## 预签名Post上传对象
+
+```
+  请参考samples/s3/presinged_post.rb
+```
+
+##### 服务器端生成签名表单,用于发给客户端
+
+```ruby
+  post_info_str = s3.presigned_post_info(
+    "share", # bucket名字
+    {
+    :expires => 300,                                        # 签名有效期，单位秒
+    :metadata => {"x-amz-meta-server" => "Hello Server!"},  # 服务器端自定义的变量，必须以"x-amz-meta-"为前缀
+    :callback_url => "http://mtmsscb.mtmss.cn",             # 上传成功后的回调url
+    :callback_body => "name=${fname}&bucket=${bucket}&key=${key}&hash=${etag}&size=${fsize}&server=${x-amz-meta-server}&client=${x-amz-meta-client}",  # 上传成功后回调的内容，可以引用魔法变量和自定义变量
+    :callback_body_type => "application/x-www-form-urlencoded",  # 上传成功后回调的Content-Type
+    :callback_host => "mtmsscb.mtmss.com"                   # 上传成功后回调http header中的host
+    }).to_json
+```
+
+##### 目前支持的魔法变量
+| 名字   | 描述                 |
+|--------|----------------------|
+| bucket | bucket名字           |
+| key    | 对象名字             |
+| etag   | 对象内容的md5sum     |
+| fname  | 上传表单中的filename |
+| fsize  | 对象大小             | 
+
+##### 客户端使用Post上传对象
+
+```ruby
+  # 这里使用ruby的rest-client做为示例
+  client_info = {
+    "x-amz-meta-client" => "Hello Client!",  # 客户端自定义变量，mss遵守标准S3协议，post表单最后一项必须是对象内容，因此客户端自定义的变量要写在value之前
+    :key => "Key is lena.jpg",                      # 对象名字
+    :value => File.new("./lena.jpg", 'rb'),  # 待上传的对象内容
+  }
+  post_info_obj = JSON.parse(post_info_str)  # post_info_str为服务器端生成的签名表单对象，包括url和form，其中form为表单内容，url为上传要用到的url
+  RestClient.post post_info_obj["url"], post_info_obj["form"].merge(client_info)  # 与客户端自定义的表单内容合并后使用rest-client上传
+```
+
+##### 回调服务器收到的消息体
+
+```
+  name=lena.jpg&bucket=share&key=Key is lena.jpg&hash="76d710edc4cf48d84e3cfc7e24234a09"&size=68261&server=Hello Server!&client=Hello Client!
+```

data/bin/mss-rb

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+
+# Copyright 2011-2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#
+# or in the "license" file accompanying this file. This file 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.
+
+$:.unshift(File.join(File.dirname(File.dirname(__FILE__)), 'lib'))
+
+require 'rubygems'
+require 'optparse'
+require 'logger'
+
+def env_bool key, default
+  if ENV.key?(key)
+    !['0', 'false', 'no', 'off'].include?(ENV[key].downcase)
+  else
+    default
+  end
+end
+
+# setup default options, check ENV for most
+options = {
+  :repl => env_bool('MSSRB', nil),
+  :log => env_bool('MSSRB_LOG', true),
+  :color => env_bool('MSSRB_COLOR', true),
+  :debug => env_bool('MSSRB_DEBUG', false),
+  :load_paths => [],
+  :require => [],
+  :execute => [],
+}
+
+OptionParser.new do |opts|
+
+  opts.banner = "Usage: mss-rb [options]"
+
+  opts.on("--repl REPL", "specify the repl environment, pry or irb") do |value|
+    options[:repl] = value
+  end
+
+  opts.on("-e 'command'", "one line of script. Several -e's allowed.") do |value|
+    options[:execute] << value
+    options[:log] = false unless options[:log_set]
+    options[:debug] = false unless options[:debug_set]
+  end
+
+  opts.on("-l", "--[no-]log", "log client requets, on by default") do |value|
+    options[:log] = value
+    options[:log_set] = true
+  end
+
+  opts.on("-c", "--[no-]color", "colorize request logging, on by default") do |value|
+    options[:color] = value
+  end
+
+  opts.on("--profile PROFILE", "Use a specific profile from your credential file.") do |value|
+    options[:profile] = value
+  end
+
+  opts.on("-d", "--[no-]debug", "log HTTP wire traces, off by default") do |value|
+    options[:debug] = value
+    options[:debug_set] = true
+  end
+
+  opts.on("-Idirectory", Array, "specify $LOAD_PATH directory (may be used more than once)") do |values|
+    options[:load_paths] += values
+  end
+
+  opts.on("-rlibrary", Array, "require the library") do |values|
+    options[:require] += values
+  end
+
+  opts.on("-v", "--verbose", "enable client logging and HTTP wire tracing") do |value|
+    options[:log] = true
+    options[:log_set] = true
+    options[:debug] = true
+    options[:debug_set] = true
+  end
+
+  opts.on("-q", "--quiet", "disable client logging and HTTP wire tracing") do |value|
+    options[:log] = false
+    options[:log_set] = true
+    options[:debug] = false
+    options[:debug_set] = true
+  end
+
+  opts.on("-h", "--help") do
+    puts opts
+    exit
+  end
+
+end.parse!
+
+# amend the $LOAD_PATH
+options[:load_paths].each do |path|
+  $LOAD_PATH.unshift(path)
+end
+
+require 'mss-sdk'
+
+# configure the mss-sdk gem
+
+cfg = {}
+
+if options[:profile]
+  provider = MSS::Core::CredentialProviders::SharedCredentialFileProvider.new(
+    :profile_name => options[:profile]
+  )
+  cfg[:credential_provider] = provider
+end
+
+if options[:log]
+  logger = Logger.new($stdout)
+  logger.formatter = proc {|severity, datetime, progname, msg| msg }
+  cfg[:logger] = logger
+end
+
+if options[:color]
+  cfg[:log_formatter] = MSS::Core::LogFormatter.colored
+end
+
+if options[:debug]
+  cfg[:http_wire_trace] = true
+end
+
+MSS.config(cfg)
+
+options[:require].each do |library|
+  require(library)
+end
+
+unless options[:execute].empty?
+  eval(options[:execute].join("\n"))
+  exit
+end
+
+unless options[:repl] == 'irb'
+  # these dependencies are normally autoloaded by the mss-sdk, however
+  # we require them up front to squelch warnings from pry
+  require 'nokogiri'
+  require 'json'
+end
+
+class PryNotAvailable < StandardError; end
+
+def run_with_pry
+  begin
+    require 'pry'
+  rescue LoadError
+    raise PryNotAvailable
+  end
+  Pry.config.prompt = [proc { "MSS> " }, proc { "MSS| " }]
+  MSS.pry
+end
+
+def run_with_irb
+  require 'irb'
+  IRB.start
+end
+
+case options[:repl]
+when 'pry' then run_with_pry
+when 'irb' then run_with_irb
+else
+  begin
+    run_with_pry
+  rescue PryNotAvailable
+    warn("Pry not available, falling back to irb")
+    run_with_irb
+  end
+end