activestorage-ve-tos 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a368b295543fe0643511c4aac61a97da58d582bf582af34d6fec18d0ff2e9053
+  data.tar.gz: 42cc0110680ead98384f52dee47463ea1f8a9c056036527b6157578b80b4d756
+SHA512:
+  metadata.gz: 8b35a11c8d6484064e20afd8ef57b48afb569c6a2c0b68ada84341e0ac2fa4711633c5a9c4a14cbe7169db55397f8d76efa8498e914e47ad5e51f06e489e8481
+  data.tar.gz: b14474642993b493a73b62e4f2cbf4be01237ac806bc9067390d9e4dba5825ee588ffebddd2425d8bcba831869ab4b1b76c3f8b3a8797f61211c2f60feceaec9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renny Ren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# activestorage-ve-tos
+
+ActiveStorage adapter for [Volcengine TOS](https://www.volcengine.com/docs/6349). Wraps ve-tos-ruby-sdk.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "activestorage-ve-tos"
+```
+
+Then execute:
+
+```
+bundle install
+```
+
+## Configuration
+
+```yaml
+# config/storage.yml
+ve_tos:
+  service: VeTos
+  access_key_id: <%= ENV["TOS_ACCESS_KEY_ID"] %>
+  secret_access_key: <%= ENV["TOS_SECRET_ACCESS_KEY"] %>
+  region: cn-beijing
+  bucket: my-bucket
+  # endpoint: tos-cn-beijing.volces.com   # default: tos-{region}.volces.com
+  # public: false                          # if true and `host` is set, url returns an unsigned CDN url
+  # host: cdn.example.com                  # custom domain for delivery (replaces TOS host)
+  # upload_host: my-bucket.tos-cn-beijing.volces.com  # for direct uploads
+  # prefix: production                     # all keys are prefixed with this
+```
+
+Then point your environment at the new service in `config/environments/*.rb`:
+
+```ruby
+config.active_storage.service = :ve_tos
+```
+
+## Direct uploads
+
+`url_for_direct_upload` returns a presigned PUT URL. Configure CORS on your TOS bucket to allow `PUT` from your origin and the headers `Content-Type`, `Content-MD5`, `x-tos-meta-*`.
+
+## What it does
+
+| ActiveStorage method    | Backed by                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `upload`                | `PutObject`                                                                    |
+| `download` (full)       | `GetObject`                                                                    |
+| `download` (with block) | `GetObject` (streaming)                                                        |
+| `download_chunk`        | `GetObject` with `Range`                                                       |
+| `delete`                | `DeleteObject` (404 swallowed)                                                 |
+| `delete_prefixed`       | `ListObjectsV2` + `DeleteMultipleObjects` (paginated)                          |
+| `exist?`                | `HeadObject`                                                                   |
+| `url`                   | Presigned GET, or `https://{host}/{key}` when `public: true` and `host` is set |
+| `url_for_direct_upload` | Presigned PUT                                                                  |
+| `compose`               | Streamed concatenation + re-upload                                             |
+
+## Caveats
+
+- `compose` reads sources fully into memory and re-uploads. Fine for variants/thumbnails, not for very large composites.
+- Multipart upload is not supported by the underlying SDK yet, so `upload` sends the whole body in a single PutObject. Volcengine's per-request limit applies.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/activestorage-ve-tos.gemspec

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "lib/activestorage_ve_tos/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activestorage-ve-tos"
+  spec.version = ActiveStorageVeTos::VERSION
+  spec.authors = ["Renny"]
+  spec.summary = "ActiveStorage adapter for Volcengine TOS object storage"
+  spec.description = "Wraps Volcengine TOS as an ActiveStorage service."
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE", "activestorage-ve-tos.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ve-tos-ruby-sdk", ">= 0.1.0"
+  spec.add_dependency "activestorage", ">= 6.1"
+
+  spec.add_development_dependency "rspec", "~> 3.12"
+end

data/lib/active_storage/service/ve_tos_service.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "active_storage/service"
+require "tos"
+
+module ActiveStorage
+  class Service::VeTosService < Service
+    attr_reader :bucket_name, :prefix, :public, :host, :upload_host
+
+    def initialize(access_key_id:, secret_access_key:, region:, bucket:,
+                   endpoint: nil, security_token: nil, public: false,
+                   host: nil, upload_host: nil, prefix: nil, **)
+      @client = TOS::Client.new(
+        access_key_id: access_key_id,
+        secret_access_key: secret_access_key,
+        region: region,
+        endpoint: endpoint,
+        security_token: security_token,
+      )
+      @bucket_name = bucket
+      @prefix = prefix
+      @public = public
+      @host = host
+      @upload_host = upload_host
+    end
+
+    def upload(key, io, checksum: nil, content_type: nil, disposition: nil, filename: nil, custom_metadata: {}, **)
+      instrument :upload, key: key, checksum: checksum do
+        body = io.respond_to?(:read) ? io.read : io.to_s
+        bucket.put_object(
+          path_for(key),
+          body,
+          content_type: content_type,
+          content_md5: checksum,
+          metadata: custom_metadata,
+        )
+      end
+    end
+
+    def download(key, &block)
+      if block_given?
+        instrument :streaming_download, key: key do
+          bucket.get_object(path_for(key), &block)
+        end
+      else
+        instrument :download, key: key do
+          bucket.get_object(path_for(key)).body
+        end
+      end
+    end
+
+    def download_chunk(key, range)
+      instrument :download_chunk, key: key, range: range do
+        bucket.get_object(path_for(key), range: range).body
+      end
+    end
+
+    def delete(key)
+      instrument :delete, key: key do
+        bucket.delete_object(path_for(key))
+      end
+    rescue TOS::ServerError => e
+      raise unless e.status == 404
+    end
+
+    def delete_prefixed(prefix_value)
+      instrument :delete_prefixed, prefix: prefix_value do
+        loop do
+          page = bucket.list_objects(prefix: path_for(prefix_value), max_keys: 1000)
+          break if page[:keys].empty?
+
+          bucket.delete_multiple_objects(page[:keys])
+          break unless page[:is_truncated]
+        end
+      end
+    end
+
+    def exist?(key)
+      instrument :exist, key: key do |payload|
+        answer = head?(path_for(key))
+        payload[:exist] = answer
+        answer
+      end
+    end
+
+    def url(key, expires_in:, filename:, content_type:, disposition:, **)
+      instrument :url, key: key do |payload|
+        generated_url = if @public && @host
+            public_url(key)
+          else
+            private_url(key, expires_in: expires_in, filename: filename,
+                             content_type: content_type, disposition: disposition)
+          end
+        payload[:url] = generated_url
+        generated_url
+      end
+    end
+
+    def url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:, custom_metadata: {})
+      instrument :url, key: key do |payload|
+        url = @client.presign(
+          method: "PUT",
+          bucket: @bucket_name,
+          key: path_for(key),
+          expires_in: expires_in.to_i,
+        )
+        url = url.sub(/^https:\/\/[^\/]+/, "https://#{@upload_host}") if @upload_host
+        payload[:url] = url
+        url
+      end
+    end
+
+    def headers_for_direct_upload(_key, content_type:, checksum:, content_length:, custom_metadata: {}, **)
+      headers = {
+        "Content-Type" => content_type,
+        "Content-Length" => content_length.to_s,
+      }
+      headers["Content-MD5"] = checksum if checksum
+      custom_metadata.each { |k, v| headers["x-tos-meta-#{k}"] = v.to_s }
+      headers
+    end
+
+    # Server-side compose isn't supported by this minimal SDK; download all
+    # source keys and re-upload as a single object. Fine for small previews
+    # (variants, thumbnails) but not for very large composites.
+    def compose(source_keys, destination_key, filename: nil, content_type: nil, disposition: nil, custom_metadata: {})
+      buffer = +""
+      source_keys.each do |key|
+        buffer << bucket.get_object(path_for(key)).body
+      end
+
+      bucket.put_object(
+        path_for(destination_key),
+        buffer,
+        content_type: content_type,
+        metadata: custom_metadata,
+      )
+    end
+
+    private
+
+    def bucket
+      @bucket ||= @client.bucket(@bucket_name)
+    end
+
+    def head?(key)
+      bucket.head_object(key)
+      true
+    rescue TOS::ServerError => e
+      return false if e.status == 404
+
+      raise
+    end
+
+    def path_for(key)
+      [@prefix, key].compact.reject(&:empty?).join("/").gsub(%r{^/+}, "").squeeze("/")
+    end
+
+    def public_url(key)
+      "https://#{@host}/#{@client.escape_key(path_for(key))}"
+    end
+
+    def private_url(key, expires_in:, filename: nil, content_type: nil, disposition: nil)
+      query = {}
+      if filename
+        wrapped = ActiveStorage::Filename.wrap(filename)
+        query["response-content-disposition"] = content_disposition_with(type: disposition, filename: wrapped)
+      end
+      query["response-content-type"] = content_type if content_type
+
+      url = @client.presign(
+        method: "GET",
+        bucket: @bucket_name,
+        key: path_for(key),
+        query: query,
+        expires_in: expires_in.to_i,
+      )
+
+      if @host
+        url = url.sub(/^https:\/\/[^\/]+/, "https://#{@host}")
+      end
+      url
+    end
+  end
+end

data/lib/activestorage-ve-tos.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "tos"
+
+require "activestorage_ve_tos/version"
+require "active_storage/service/ve_tos_service"
+
+# When `service: VeTos` is configured in `config/storage.yml`, ActiveStorage
+# resolves it to `ActiveStorage::Service::VeTosService` via Ruby constant
+# lookup — no extra wiring is needed.
+module ActiveStorageVeTos
+end

data/lib/activestorage_ve_tos/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveStorageVeTos
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: activestorage-ve-tos
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Renny
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ve-tos-ruby-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: Wraps Volcengine TOS as an ActiveStorage service.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- activestorage-ve-tos.gemspec
+- lib/active_storage/service/ve_tos_service.rb
+- lib/activestorage-ve-tos.rb
+- lib/activestorage_ve_tos/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: ActiveStorage adapter for Volcengine TOS object storage
+test_files: []