ve-tos-ruby-sdk

Ruby SDK for Volcengine TOS.

• PutObject, GetObject (with Range), HeadObject, DeleteObject
• DeleteMultipleObjects (batch)
• ListObjectsV2 (with prefix + pagination)
• Presigned URLs (GET / PUT)

Authentication uses TOS4-HMAC-SHA256 (the TOS variant of AWS SigV4).

Installation

# Gemfile
gem "ve-tos-ruby-sdk"

Usage

client = TOS::Client.new(
  access_key_id: ENV.fetch("TOS_ACCESS_KEY_ID"),
  secret_access_key: ENV.fetch("TOS_SECRET_ACCESS_KEY"),
  region: "cn-beijing"
  # endpoint: "tos-cn-beijing.volces.com"  # optional override
)

bucket = client.bucket("my-bucket")

# Upload
bucket.put_object("hello.txt", "world", content_type: "text/plain")

# Download (full body)
res = bucket.get_object("hello.txt")
res.body # => "world"

# Download (streaming)
File.open("/tmp/out.bin", "wb") do |f|
  bucket.get_object("big.bin") { |chunk| f.write(chunk) }
end

# Range request
bucket.get_object("big.bin", range: 0..1023) # first 1 KiB

# Metadata
bucket.head_object("hello.txt").header("content-length")

# Delete
bucket.delete_object("hello.txt")
bucket.delete_multiple_objects(%w[a.txt b.txt c.txt])

# List
page = bucket.list_objects(prefix: "uploads/", max_keys: 100)
page[:keys] # => ["uploads/foo.png", ...]

# Presigned URL (read)
url = client.presign(method: "GET", bucket: "my-bucket", key: "hello.txt", expires_in: 600)

Errors

All HTTP errors raise TOS::ServerError, which carries status, code, request_id, and body. Network failures raise TOS::NetworkError. Configuration mistakes raise TOS::ConfigError.

begin
  bucket.get_object("missing")
rescue TOS::ServerError => e
  e.status     # => 404
  e.code       # => "NoSuchKey"
  e.request_id # => "..."
end

Out of scope

This SDK is intentionally narrow. The following are not implemented; if you need them, the Client#request method gives you a signed-request escape hatch:

• Multipart upload (initiate / upload-part / complete / abort)
• Bucket-level operations (create, lifecycle, CORS, ACL, tagging)
• Object copy / append / restore
• Server-side encryption headers, object tagging

Development

bundle install
bundle exec rspec

License

Apache License 2.0