my-s3-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e31328cf2415286256d1337973342420274b36f67447251568f2ea07a063da53
+  data.tar.gz: 5d859629f72a9f0aa8cbdf96902805dbaa66d0bd2bb4ef358939b384a07c630e
+SHA512:
+  metadata.gz: 47de899d847f96edddf1f148a3e6160b6c0350164d044918f0bc3fc1a51e33d3b4a6d9b01c358fb63ee8e1715f075f04a6facd60fd16070becba81027b3f7674
+  data.tar.gz: b43571317be9a2c841517139de2805419bf953b7ec29f8ecab43d1906240c8fdfbaedccaa553c7b0c3a4d2d726148d9c33938be75c1aad39ed7bd2d935e6b763

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leandro Sardi
+
+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,67 @@
+# My.S3 Client
+
+Ruby client library for [My.S3](https://github.com/leandrosardi/my.s3) — the filesystem-backed object store. The gem adds ergonomic helpers around the official HTTP API and keeps dependencies minimal so it can run anywhere Ruby and Net::HTTP are available.
+
+## Installation
+
+```bash
+bundle add my-s3-client
+# or
+# gem install my-s3-client
+```
+
+## Quick Start
+
+```ruby
+require 'my_s3/client'
+
+client = MyS3::Client.new(
+  base_url: 'https://storage.example.com',
+  api_key: ENV.fetch('MY_S3_API_KEY')
+)
+
+client.ensure_folder_chain('channels/12345/assets')
+client.upload_file(
+  file_path: '/tmp/avatar.png',
+  path: 'channels/12345/assets',
+  filename: 'avatar.png'
+)
+
+listing = client.list(path: 'channels/12345')
+public_url = client.get_public_url(path: 'channels/12345/assets', filename: 'avatar.png')['public_url']
+client.download_file(path: 'channels/12345/assets', filename: 'avatar.png', target_path: 'avatar-copy.png')
+```
+
+## Covered Endpoints
+
+Each method returns the parsed JSON payload emitted by My.S3 (normally `{ 'success' => true, ... }`). Errors raise `MyS3::Client::Error`.
+
+| Method | Description |
+| --- | --- |
+| `list(path: '')` | `GET /list.json` to enumerate folders/files. |
+| `create_folder(path:, folder_name:)` | `POST /create_folder.json`. |
+| `delete_folder(path:)` | `DELETE /delete_folder.json`. |
+| `rename_folder(path:, new_name:)` | `POST /rename_folder.json`. |
+| `upload_file(file_path:, path: '', filename: nil, ensure_path: true)` | Multipart `POST /upload.json` with automatic folder creation. |
+| `delete_file(path:, filename:)` | `DELETE /delete.json`. |
+| `delete_older_than(path:, older_than:)` | `POST /delete_older_than.json`. |
+| `get_download_url(path:, filename:)` | `POST /get_download_url.json`. |
+| `get_public_url(path:, filename:)` | `POST /get_public_url.json`. |
+| `download_file(path:, filename:, target_path: nil)` | Streams the anonymous file endpoint (`GET /:path/:filename`). |
+| `ensure_folder_chain(path)` | Helper that recursively creates folders via repeated `create_folder` calls. |
+
+## Configuration Tips
+
+- `base_url` should point to the HTTP endpoint exposed by your My.S3 node; a trailing slash is optional.
+- `api_key` must match the `api_key` configured on the server.
+- Adjust `open_timeout` and `read_timeout` (constructor options) for slower networks or large uploads.
+- Combine this gem with background jobs or CLI scripts to automate ingestion, backups, or content rendering pipelines.
+
+## Development
+
+```bash
+bundle install
+# add specs under test/ or spec/ and run them via your preferred test runner
+```
+
+Bug reports and pull requests are welcome.

data/lib/my_s3/client/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MyS3
+  class Client
+    VERSION = '0.1.0'
+  end
+end

data/lib/my_s3/client.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'securerandom'
+require 'uri'
+
+require_relative 'client/version'
+
+module MyS3
+  class Client
+    class Error < StandardError; end
+
+    attr_reader :base_url, :api_key
+
+    def initialize(base_url:, api_key:, open_timeout: 10, read_timeout: 60)
+      @base_url = normalize_base_url(base_url)
+      @api_key = api_key.to_s.strip
+      raise Error, 'api_key is required' if @api_key.empty?
+
+      @open_timeout = Integer(open_timeout)
+      @read_timeout = Integer(read_timeout)
+    end
+
+    # ----------------------
+    # High-level API methods
+    # ----------------------
+
+    def list(path: '')
+      get_json('/list.json', path: path.to_s)
+    end
+
+    def create_folder(path:, folder_name:)
+      post_json('/create_folder.json', path: path.to_s, folder_name: folder_name.to_s)
+    end
+
+    def delete_folder(path:)
+      delete_json('/delete_folder.json', path: path.to_s)
+    end
+
+    def rename_folder(path:, new_name:)
+      post_json('/rename_folder.json', path: path.to_s, new_name: new_name.to_s)
+    end
+
+    def delete_file(path:, filename:)
+      delete_json('/delete.json', path: path.to_s, filename: filename.to_s)
+    end
+
+    def delete_older_than(path:, older_than:)
+      post_json('/delete_older_than.json', path: path.to_s, older_than: older_than)
+    end
+
+    def get_download_url(path:, filename:)
+      post_json('/get_download_url.json', path: path.to_s, filename: filename.to_s)
+    end
+
+    def get_public_url(path:, filename:)
+      post_json('/get_public_url.json', path: path.to_s, filename: filename.to_s)
+    end
+
+    def upload_file(file_path:, path: '', filename: nil, ensure_path: true)
+      raise Error, 'file_path is required' if file_path.to_s.strip.empty?
+      raise Error, "File not found: #{file_path}" unless File.file?(file_path)
+
+      relative_path = path.to_s
+      filename ||= File.basename(file_path)
+
+      ensure_folder_chain(relative_path) if ensure_path
+
+      boundary = "----MyS3Client#{SecureRandom.hex(12)}"
+      uri = uri_for('/upload.json')
+      request = Net::HTTP::Post.new(uri)
+      request['X-API-Key'] = api_key
+      request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+      request.body = build_my_s3_multipart(boundary, relative_path, filename, file_path)
+
+      response = http_request(uri, request)
+      json = parse_json(response.body)
+      return json if response.is_a?(Net::HTTPSuccess) && json['success']
+
+      message = json.dig('error', 'message') || response.body
+      raise Error, message
+    end
+
+    def download_file(path:, filename:, target_path: nil)
+      relative = join_relative_path(path, filename)
+      uri = URI.join(base_url, relative)
+      request = Net::HTTP::Get.new(uri)
+      response = http_request(uri, request, include_api_key: false)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Error, "Failed to download file: #{response.code} #{response.message}"
+      end
+
+      if target_path
+        File.binwrite(target_path, response.body)
+        target_path
+      else
+        response.body
+      end
+    end
+
+    def ensure_folder_chain(path)
+      sanitized = normalize_relative_path(path)
+      return true if sanitized.empty?
+
+      current = ''
+      sanitized.split('/').each do |segment|
+        begin
+          create_folder(path: current, folder_name: segment)
+        rescue Error => e
+          raise unless e.message =~ /already exists/i
+        end
+        current = current.empty? ? segment : [current, segment].join('/')
+      end
+
+      true
+    end
+
+    # ----------------------
+    # HTTP helper methods
+    # ----------------------
+
+    def get_json(endpoint, params = {})
+      uri = uri_for(endpoint, params: params)
+      request = Net::HTTP::Get.new(uri)
+      request['X-API-Key'] = api_key
+      request_json(uri, request)
+    end
+
+    def post_json(endpoint, payload = {})
+      uri = uri_for(endpoint)
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request['X-API-Key'] = api_key
+      request.body = JSON.generate(payload)
+      request_json(uri, request)
+    end
+
+    def delete_json(endpoint, payload = {})
+      uri = uri_for(endpoint)
+      request = Net::HTTP::Delete.new(uri)
+      request['Content-Type'] = 'application/json'
+      request['X-API-Key'] = api_key
+      request.body = JSON.generate(payload)
+      request_json(uri, request)
+    end
+
+    private
+
+    def request_json(uri, request)
+      response = http_request(uri, request)
+      json = parse_json(response.body)
+      return json if response.is_a?(Net::HTTPSuccess) && json['success']
+
+      message = json.dig('error', 'message') || response.body
+      raise Error, message
+    end
+
+    def http_request(uri, request, include_api_key: true)
+      request['X-API-Key'] = api_key if include_api_key && !request['X-API-Key']
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      http.request(request)
+    rescue Timeout::Error => e
+      raise Error, "MyS3 request timed out: #{e.message}"
+    rescue SocketError, Errno::ECONNREFUSED => e
+      raise Error, "MyS3 connection failed: #{e.message}"
+    end
+
+    def parse_json(body)
+      return {} if body.nil? || body.strip.empty?
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response: #{body}"
+    end
+
+    def build_my_s3_multipart(boundary, relative_path, filename, local_path)
+      body = []
+      body << "--#{boundary}\r\n"
+      body << "Content-Disposition: form-data; name=\"path\"\r\n\r\n"
+      body << "#{relative_path}\r\n"
+      body << "--#{boundary}\r\n"
+      body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n"
+      body << "Content-Type: application/octet-stream\r\n\r\n"
+      body << File.binread(local_path)
+      body << "\r\n--#{boundary}--\r\n"
+      body.join
+    end
+
+    def uri_for(endpoint, params: nil)
+      path = endpoint.to_s.sub(%r{^/+}, '')
+      uri = URI.join(base_url, path)
+      if params && !params.empty?
+        query = URI.encode_www_form(params.transform_values { |v| v.nil? ? '' : v })
+        uri.query = query
+      end
+      uri
+    end
+
+    def normalize_base_url(url)
+      value = url.to_s.strip
+      raise Error, 'base_url is required' if value.empty?
+      value.end_with?('/') ? value : "#{value}/"
+    end
+
+    def normalize_relative_path(path)
+      value = path.to_s.strip
+      return '' if value.empty?
+      value = value.gsub(%r{^/+}, '').gsub(%r{/+$}, '')
+      value
+    end
+
+    def join_relative_path(path, filename)
+      fragments = [normalize_relative_path(path), filename.to_s]
+      fragments.reject!(&:empty?)
+      fragments.join('/')
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: my-s3-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leandro D. Sardi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: Simple, dependency-light client for talking to a My.S3 server via its
+  JSON and multipart HTTP API.
+email:
+- leandro@massprospecting.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/my_s3/client.rb
+- lib/my_s3/client/version.rb
+homepage: https://github.com/leandrosardi/my.s3
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leandrosardi/my.s3
+  source_code_uri: https://github.com/leandrosardi/my.s3-client
+  changelog_uri: https://github.com/leandrosardi/my.s3-client
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: Ruby client for the My.S3 object storage service.
+test_files: []