bucketrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1714eff021fd232f90528369c18271c656b3a39ef914d13e27bf75bb2d33ef6
+  data.tar.gz: 13b57a0369936a711c5a7df997b1dc876e4ce2f1a1367a763fe58f76c1611a0b
+SHA512:
+  metadata.gz: 38e2991e62d516a57c3dc580bc58be208fb8fa741c767e425470fa96674ef9f72dcd05b8bcf11fe785d5917521475ec27de2a516de1b60753d0caba251ce9282
+  data.tar.gz: 7c72297714fb65261fd9a8abd8c83282c9fed3cd95bfc3e411b8baac07d702709e757f2dd39910e8a73d06fcf8941a55317375c4c5164b18d53147d0a83cf139

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bucketrb contributors
+
+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,128 @@
+# Bucketrb
+
+Bucketrb is a small local S3-compatible server for Ruby development and test
+environments. It is intentionally narrower than MinIO or LocalStack: it focuses
+on the S3 API surface commonly used by Rails apps, `aws-sdk-s3`, ActiveStorage
+adjacent integrations, and browser direct uploads.
+
+## Status
+
+This project is an early MVP. It currently implements:
+
+- path-style S3 requests
+- unsigned and presigned `GET`, `HEAD`, `PUT`, `POST`, and `DELETE`
+- `CreateBucket` and `HeadBucket`
+- `GetObject`, `HeadObject`, `PutObject`, `CopyObject`, and `DeleteObject`
+- `ListObjects` and `ListObjectsV2`
+- `DeleteObjects`
+- browser-style presigned POST multipart uploads
+- object metadata through `x-amz-meta-*`
+- filesystem persistence
+- permissive CORS for local browser uploads
+
+It does not currently implement S3 authorization, bucket policies, ACL
+semantics, multipart upload APIs, object versioning, lifecycle rules, virtual
+host-style bucket addressing, or service APIs outside S3.
+
+See [ROADMAP.md](ROADMAP.md) for planned work and explicit non-goals.
+
+## Install
+
+From a local checkout:
+
+```sh
+bundle install
+bundle exec exe/bucketrb serve --root ./data --bucket my-bucket
+```
+
+After release:
+
+```sh
+gem install bucketrb
+bucketrb serve --root ./data --bucket my-bucket
+```
+
+## CLI
+
+```sh
+bucketrb serve \
+  --host 127.0.0.1 \
+  --port 4566 \
+  --root ./data/bucketrb \
+  --bucket app-dev-bucket
+```
+
+Options:
+
+- `--host HOST`: bind host. Default: `127.0.0.1`
+- `--port PORT`: bind port. Default: `4566`
+- `--root PATH`: filesystem storage root. Default: `data/bucketrb`
+- `--bucket NAME`: create a bucket at startup. May be repeated.
+- `--buckets-from-env`: create buckets from environment variables ending in
+  `_BUCKET` or `_S3_BUCKET`
+
+## Ruby SDK Example
+
+```ruby
+require "aws-sdk-s3"
+
+client = Aws::S3::Client.new(
+  endpoint: "http://127.0.0.1:4566",
+  region: "ap-northeast-1",
+  access_key_id: "bucketrb",
+  secret_access_key: "bucketrb",
+  force_path_style: true
+)
+
+client.create_bucket(bucket: "example")
+client.put_object(bucket: "example", key: "hello.txt", body: "hello")
+puts client.get_object(bucket: "example", key: "hello.txt").body.read
+```
+
+## Docker
+
+Build locally:
+
+```sh
+docker build -t bucketrb .
+docker run --rm -p 4566:4566 -v "$PWD/data:/data" \
+  -e APP_S3_BUCKET=app-dev-bucket \
+  bucketrb
+```
+
+## Migration Sketch
+
+An application that currently uses a local S3 emulator can run Bucketrb on the
+same local port and point its S3 SDK configuration at that endpoint:
+
+```yaml
+services:
+  bucketrb:
+    image: bucketrb:latest
+    ports:
+      - 127.0.0.1:${S3_EMULATOR_PORT:-4566}:4566
+    environment:
+      - AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION:-ap-northeast-1}
+      - APP_S3_BUCKET=${APP_S3_BUCKET:-app-dev-bucket}
+      - PUBLIC_ASSETS_BUCKET=${PUBLIC_ASSETS_BUCKET:-public-assets-dev}
+      - PRIVATE_FILES_BUCKET=${PRIVATE_FILES_BUCKET:-private-files-dev}
+    volumes:
+      - ./data/bucketrb:/data:delegate
+```
+
+For `aws-sdk-s3`, use path-style addressing:
+
+```ruby
+endpoint: ENV.fetch("S3_ENDPOINT", "http://127.0.0.1:4566")
+force_path_style: true
+```
+
+## Test
+
+```sh
+ruby -Ilib:test test/bucketrb/object_store_test.rb
+ruby -Ilib:test test/bucketrb/s3_contract_test.rb
+```
+
+The contract test starts a localhost HTTP server and exercises it through
+`aws-sdk-s3`.

data/ROADMAP.md

@@ -0,0 +1,62 @@
+# Roadmap
+
+Bucketrb is intended to be a focused local S3-compatible server for development
+and test environments. It is not intended to become a production object store or
+a full cloud service emulator.
+
+## Near Term
+
+- Validate Bucketrb against a real application migration from an existing local
+  S3 emulator.
+- Expand contract tests for the S3 API subset already implemented.
+- Add request/response fixtures for AWS SDK behavior that is easy to regress.
+- Verify browser direct upload flows with presigned POST and presigned PUT.
+- Document supported and unsupported S3 behavior in a compatibility matrix.
+
+## S3 Compatibility
+
+- Support `Range` requests for `GetObject`.
+- Support `delimiter` and `CommonPrefixes` in object listing responses.
+- Improve pagination behavior for `ListObjects` and `ListObjectsV2`.
+- Add optional checksum response fields when clients send checksum headers.
+- Add multipart upload APIs: create, upload part, complete, abort, and list
+  parts.
+- Add optional virtual-host-style bucket addressing.
+- Add more complete error response parity for common AWS SDK code paths.
+
+## Configuration And Runtime
+
+- Make CORS behavior configurable instead of always permissive.
+- Add a health endpoint for container orchestration.
+- Add structured access logs with request IDs.
+- Add configurable startup bucket creation from files as well as environment
+  variables.
+- Add an option to auto-create buckets on first object write for development
+  convenience.
+- Add graceful shutdown coverage in tests.
+
+## Security Model
+
+- Keep permissive local-development mode as the default.
+- Add optional SigV4 validation for teams that want stricter local behavior.
+- Add optional presigned POST policy validation for content type, key prefix,
+  and content length constraints.
+- Document clearly that Bucketrb is not designed for production exposure.
+
+## Packaging And Release
+
+- Add CI for supported Ruby versions.
+- Add release automation for RubyGems.
+- Publish a container image.
+- Add a minimal changelog.
+- Add contribution guidelines.
+- Add a security policy for vulnerability reports.
+
+## Explicitly Out Of Scope
+
+- Production durability guarantees.
+- Bucket policies and IAM emulation beyond optional local checks.
+- Object versioning.
+- Lifecycle rules.
+- Replication.
+- Non-S3 cloud service APIs.

data/exe/bucketrb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "bucketrb/cli"
+
+exit Bucketrb::CLI.new(ARGV).run

data/lib/bucketrb/app.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rexml/document"
+require "uri"
+
+require_relative "errors"
+require_relative "object_store"
+require_relative "xml_response"
+
+module Bucketrb
+  class App
+    XML_CONTENT_TYPE = "application/xml"
+    DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+    def initialize(store:)
+      @store = store
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      return options_response if request.options?
+
+      bucket, key = path_parts(request.path_info)
+
+      if bucket.nil?
+        return root_request(request)
+      end
+
+      dispatch(request, bucket, key)
+    rescue Bucketrb::BucketNotFoundError => error
+      error_response("NoSuchBucket", error.message, 404, head: env["REQUEST_METHOD"] == "HEAD")
+    rescue Bucketrb::ObjectNotFoundError => error
+      error_response("NoSuchKey", error.message, 404, head: env["REQUEST_METHOD"] == "HEAD")
+    rescue Bucketrb::InvalidBucketNameError, Bucketrb::InvalidObjectKeyError, ArgumentError => error
+      error_response("InvalidArgument", error.message, 400, head: env["REQUEST_METHOD"] == "HEAD")
+    rescue StandardError => error
+      warn "#{error.class}: #{error.message}"
+      warn error.backtrace.join("\n") if ENV["BUCKETRB_DEBUG"]
+      error_response("InternalError", error.message, 500, head: env["REQUEST_METHOD"] == "HEAD")
+    end
+
+    private
+
+    def root_request(request)
+      if request.get?
+        xml_response(XMLResponse.list_all_my_buckets(@store.buckets))
+      else
+        error_response("NotImplemented", "Unsupported root request", 501)
+      end
+    end
+
+    def dispatch(request, bucket, key)
+      case request.request_method
+      when "GET"
+        key ? get_object(request, bucket, key) : list_objects(request, bucket)
+      when "HEAD"
+        key ? head_object(bucket, key) : head_bucket(bucket)
+      when "PUT"
+        key ? put_or_copy_object(request, bucket, key) : create_bucket(bucket)
+      when "POST"
+        post_request(request, bucket, key)
+      when "DELETE"
+        key ? delete_object(bucket, key) : error_response("NotImplemented", "DeleteBucket is not implemented", 501)
+      else
+        error_response("NotImplemented", "Unsupported method: #{request.request_method}", 501)
+      end
+    end
+
+    def create_bucket(bucket)
+      @store.create_bucket(bucket)
+      empty_response(200, "Location" => "/#{bucket}")
+    end
+
+    def head_bucket(bucket)
+      @store.ensure_bucket!(bucket)
+      empty_response(200)
+    end
+
+    def put_or_copy_object(request, bucket, key)
+      copy_source = request.get_header("HTTP_X_AMZ_COPY_SOURCE")
+      return copy_object(copy_source, bucket, key) if copy_source && !copy_source.empty?
+
+      entry = @store.put_object(
+        bucket: bucket,
+        key: key,
+        body: request.body,
+        content_type: request.content_type || DEFAULT_CONTENT_TYPE,
+        metadata: header_metadata(request.env)
+      )
+
+      empty_response(200, "ETag" => entry.quoted_etag)
+    end
+
+    def copy_object(copy_source, target_bucket, target_key)
+      source_bucket, source_key = parse_copy_source(copy_source)
+      entry = @store.copy_object(
+        source_bucket: source_bucket,
+        source_key: source_key,
+        target_bucket: target_bucket,
+        target_key: target_key
+      )
+
+      xml_response(XMLResponse.copy_result(entry), 200, "ETag" => entry.quoted_etag)
+    end
+
+    def post_request(request, bucket, key)
+      return error_response("InvalidRequest", "POST object keys are not supported", 400) if key
+      return delete_objects(request, bucket) if query_has?(request, "delete")
+
+      presigned_post(request, bucket)
+    end
+
+    def presigned_post(request, bucket)
+      params = request.POST
+      file = params["file"]
+      return error_response("InvalidRequest", "Missing multipart file field", 400) unless file
+      return error_response("InvalidRequest", "Missing multipart key field", 400) unless params["key"]
+
+      key = expand_post_key(params["key"], file)
+      body = file[:tempfile] || file["tempfile"]
+      return error_response("InvalidRequest", "Missing multipart tempfile", 400) unless body
+
+      content_type = params["Content-Type"] || file[:type] || file["type"] || DEFAULT_CONTENT_TYPE
+
+      @store.put_object(
+        bucket: bucket,
+        key: key,
+        body: body,
+        content_type: content_type,
+        metadata: form_metadata(params)
+      )
+
+      empty_response(success_action_status(params))
+    end
+
+    def get_object(_request, bucket, key)
+      entry = @store.get_object(bucket: bucket, key: key)
+      headers = object_headers(entry)
+      response(200, File.binread(entry.path), headers)
+    end
+
+    def head_object(bucket, key)
+      entry = @store.head_object(bucket: bucket, key: key)
+      empty_response(200, object_headers(entry))
+    end
+
+    def delete_object(bucket, key)
+      @store.delete_object(bucket: bucket, key: key)
+      empty_response(204)
+    end
+
+    def delete_objects(request, bucket)
+      keys = delete_keys(request.body.read)
+      deleted = @store.delete_objects(bucket: bucket, keys: keys)
+      xml_response(XMLResponse.delete_result(deleted))
+    end
+
+    def list_objects(request, bucket)
+      version = request.GET["list-type"].to_s == "2" ? 2 : 1
+      result = @store.list_objects(
+        bucket: bucket,
+        prefix: request.GET.fetch("prefix", ""),
+        marker: request.GET["marker"],
+        continuation_token: request.GET["continuation-token"],
+        max_keys: request.GET.fetch("max-keys", ObjectStore::DEFAULT_MAX_KEYS)
+      )
+
+      xml_response(XMLResponse.list_bucket(result, version: version))
+    end
+
+    def object_headers(entry)
+      headers = {
+        "Content-Type" => entry.content_type,
+        "Content-Length" => entry.size.to_s,
+        "ETag" => entry.quoted_etag,
+        "Last-Modified" => entry.last_modified.httpdate,
+        "Accept-Ranges" => "bytes"
+      }
+
+      entry.metadata.each do |key, value|
+        headers["x-amz-meta-#{key}"] = value
+      end
+
+      headers
+    end
+
+    def path_parts(path_info)
+      raw = path_info.to_s.sub(%r{\A/+}, "")
+      return [nil, nil] if raw.empty?
+
+      bucket, key = raw.split("/", 2)
+      [unescape_path(bucket), key ? unescape_path(key) : nil]
+    end
+
+    def unescape_path(value)
+      URI::RFC2396_PARSER.unescape(value.to_s)
+    end
+
+    def parse_copy_source(copy_source)
+      source = copy_source.split("?", 2).first.sub(%r{\A/+}, "")
+      bucket, key = unescape_path(source).split("/", 2)
+      raise ArgumentError, "Invalid x-amz-copy-source: #{copy_source.inspect}" if bucket.nil? || key.nil?
+
+      [bucket, key]
+    end
+
+    def header_metadata(env)
+      env.each_with_object({}) do |(key, value), metadata|
+        next unless key.start_with?("HTTP_X_AMZ_META_")
+
+        metadata[key.delete_prefix("HTTP_X_AMZ_META_").downcase.tr("_", "-")] = value
+      end
+    end
+
+    def form_metadata(params)
+      params.each_with_object({}) do |(key, value), metadata|
+        next unless key.to_s.downcase.start_with?("x-amz-meta-")
+
+        metadata[key.to_s.downcase.delete_prefix("x-amz-meta-")] = value
+      end
+    end
+
+    def expand_post_key(key, file)
+      filename = file[:filename] || file["filename"] || ""
+      key.to_s.gsub("${filename}", filename)
+    end
+
+    def success_action_status(params)
+      status = params["success_action_status"].to_i
+      [200, 201, 204].include?(status) ? status : 204
+    end
+
+    def delete_keys(xml)
+      document = REXML::Document.new(xml)
+      keys = []
+      collect_delete_keys(document.root, keys)
+      keys
+    end
+
+    def collect_delete_keys(element, keys)
+      return unless element
+
+      element.elements.each do |child|
+        keys << child.text.to_s if child.name == "Key"
+        collect_delete_keys(child, keys)
+      end
+    end
+
+    def query_has?(request, name)
+      request.query_string.split("&").any? do |part|
+        part == name || part.start_with?("#{name}=")
+      end
+    end
+
+    def xml_response(body, status = 200, headers = {})
+      response(status, body, {"Content-Type" => XML_CONTENT_TYPE}.merge(headers))
+    end
+
+    def empty_response(status, headers = {})
+      response(status, "", headers)
+    end
+
+    def error_response(code, message, status, head: false)
+      body = head ? "" : XMLResponse.error(code, message)
+      xml_response(body, status)
+    end
+
+    def options_response
+      empty_response(204)
+    end
+
+    def response(status, body, headers = {})
+      final_headers = cors_headers.merge(headers)
+      final_headers["Content-Length"] ||= body.bytesize.to_s if body.is_a?(String)
+
+      [status, final_headers, [body]]
+    end
+
+    def cors_headers
+      {
+        "Access-Control-Allow-Origin" => "*",
+        "Access-Control-Allow-Methods" => "GET, HEAD, PUT, POST, DELETE, OPTIONS",
+        "Access-Control-Allow-Headers" => "*",
+        "Access-Control-Expose-Headers" => "ETag, Last-Modified, x-amz-request-id, x-amz-id-2"
+      }
+    end
+  end
+end

data/lib/bucketrb/cli.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "app"
+require_relative "object_store"
+require_relative "server"
+require_relative "version"
+
+module Bucketrb
+  class CLI
+    DEFAULT_HOST = "127.0.0.1"
+    DEFAULT_PORT = 4566
+    DEFAULT_ROOT = "data/bucketrb"
+
+    BUCKET_ENV_PATTERN = /(?:^|_)(?:S3_)?BUCKET$/
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      command = @argv.shift
+
+      case command
+      when "serve"
+        serve
+      when "version", "--version", "-v"
+        puts Bucketrb::VERSION
+        0
+      when "help", "--help", "-h", nil
+        puts parser
+        0
+      else
+        warn "Unknown command: #{command}"
+        warn parser
+        1
+      end
+    end
+
+    private
+
+    def serve
+      options = {
+        host: DEFAULT_HOST,
+        port: DEFAULT_PORT,
+        root: DEFAULT_ROOT,
+        buckets: [],
+        buckets_from_env: false
+      }
+
+      parser(options).parse!(@argv)
+
+      buckets = options[:buckets]
+      buckets |= env_buckets if options[:buckets_from_env]
+
+      store = Bucketrb::ObjectStore.new(options[:root])
+      buckets.each { |bucket| store.create_bucket(bucket) }
+
+      app = Bucketrb::App.new(store: store)
+      server = Bucketrb::Server.new(app: app, host: options[:host], port: options[:port])
+
+      puts "Bucketrb #{Bucketrb::VERSION} listening on http://#{options[:host]}:#{options[:port]}"
+      puts "Storage root: #{File.expand_path(options[:root])}"
+      puts "Buckets: #{buckets.sort.join(", ")}" unless buckets.empty?
+
+      server.start
+      0
+    end
+
+    def parser(options = nil)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: bucketrb serve [options]"
+
+        opts.on("--host HOST", "Bind host. Default: #{DEFAULT_HOST}") do |host|
+          options[:host] = host
+        end
+
+        opts.on("--port PORT", Integer, "Bind port. Default: #{DEFAULT_PORT}") do |port|
+          options[:port] = port
+        end
+
+        opts.on("--root PATH", "Filesystem storage root. Default: #{DEFAULT_ROOT}") do |root|
+          options[:root] = root
+        end
+
+        opts.on("--bucket NAME", "Create a bucket at startup. May be repeated.") do |bucket|
+          options[:buckets] << bucket
+        end
+
+        opts.on("--buckets-from-env", "Create buckets from *_BUCKET and *_S3_BUCKET env vars.") do
+          options[:buckets_from_env] = true
+        end
+      end
+    end
+
+    def env_buckets
+      ENV.each_with_object([]) do |(key, value), buckets|
+        next unless key.match?(BUCKET_ENV_PATTERN)
+        next if value.nil? || value.empty?
+        next if value.start_with?("s3://", "gs://", "http://", "https://")
+
+        buckets << value
+      end
+    end
+  end
+end

data/lib/bucketrb/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Bucketrb
+  class Error < StandardError; end
+
+  class InvalidBucketNameError < Error; end
+  class InvalidObjectKeyError < Error; end
+  class BucketNotFoundError < Error; end
+  class ObjectNotFoundError < Error; end
+end

data/lib/bucketrb/object_store.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "pathname"
+require "securerandom"
+require "time"
+
+require_relative "errors"
+
+module Bucketrb
+  class ObjectStore
+    ObjectEntry = Struct.new(
+      :bucket,
+      :key,
+      :path,
+      :etag,
+      :size,
+      :last_modified,
+      :content_type,
+      :metadata,
+      keyword_init: true
+    ) do
+      def quoted_etag
+        %("#{etag}")
+      end
+    end
+
+    ListResult = Struct.new(
+      :bucket,
+      :prefix,
+      :marker,
+      :max_keys,
+      :objects,
+      :is_truncated,
+      :next_marker,
+      :next_continuation_token,
+      keyword_init: true
+    )
+
+    DEFAULT_MAX_KEYS = 1000
+
+    attr_reader :root
+
+    def initialize(root)
+      @root = Pathname.new(root).expand_path
+      FileUtils.mkdir_p(@root)
+    end
+
+    def create_bucket(bucket)
+      validate_bucket!(bucket)
+
+      FileUtils.mkdir_p(objects_dir(bucket))
+      FileUtils.mkdir_p(metadata_dir(bucket))
+      true
+    end
+
+    def buckets
+      return [] unless root.directory?
+
+      root.children.select { |path| path.directory? && path.join("objects").directory? }.map { |path| path.basename.to_s }.sort
+    end
+
+    def bucket?(bucket)
+      bucket_dir(bucket).join("objects").directory?
+    end
+
+    def ensure_bucket!(bucket)
+      validate_bucket!(bucket)
+      raise BucketNotFoundError, "No such bucket: #{bucket}" unless bucket?(bucket)
+    end
+
+    def put_object(bucket:, key:, body:, content_type: nil, metadata: {})
+      ensure_bucket!(bucket)
+      validate_key!(key)
+
+      path = object_path(bucket, key)
+      FileUtils.mkdir_p(path.dirname)
+
+      tmp_path = Pathname.new("#{path}.tmp-#{SecureRandom.hex(8)}")
+      File.open(tmp_path, "wb") do |file|
+        if body.respond_to?(:read)
+          IO.copy_stream(body, file)
+        else
+          file.write(body.to_s)
+        end
+      end
+      FileUtils.mv(tmp_path, path)
+
+      entry = build_entry(
+        bucket: bucket,
+        key: key,
+        path: path,
+        content_type: content_type || "application/octet-stream",
+        metadata: normalize_metadata(metadata),
+        etag: Digest::MD5.file(path).hexdigest,
+        last_modified: Time.now.utc
+      )
+      write_metadata(entry)
+      entry
+    ensure
+      FileUtils.rm_f(tmp_path) if tmp_path && tmp_path.exist?
+    end
+
+    def get_object(bucket:, key:)
+      ensure_bucket!(bucket)
+      entry_for(bucket, key)
+    end
+
+    def head_object(bucket:, key:)
+      get_object(bucket: bucket, key: key)
+    end
+
+    def delete_object(bucket:, key:)
+      ensure_bucket!(bucket)
+      validate_key!(key)
+
+      path = object_path(bucket, key)
+      FileUtils.rm_f(path)
+      FileUtils.rm_f(metadata_path(bucket, key))
+      true
+    end
+
+    def delete_objects(bucket:, keys:)
+      keys.each { |key| delete_object(bucket: bucket, key: key) }
+      keys
+    end
+
+    def copy_object(source_bucket:, source_key:, target_bucket:, target_key:)
+      source = get_object(bucket: source_bucket, key: source_key)
+
+      File.open(source.path, "rb") do |body|
+        put_object(
+          bucket: target_bucket,
+          key: target_key,
+          body: body,
+          content_type: source.content_type,
+          metadata: source.metadata
+        )
+      end
+    end
+
+    def list_objects(bucket:, prefix: "", marker: nil, continuation_token: nil, max_keys: DEFAULT_MAX_KEYS)
+      ensure_bucket!(bucket)
+
+      prefix = prefix.to_s
+      max_keys = max_keys.to_i
+      max_keys = DEFAULT_MAX_KEYS if max_keys <= 0
+      start_after = continuation_token || marker
+
+      keys = object_keys(bucket).select { |key| key.start_with?(prefix) }.sort
+      keys = keys.drop_while { |key| key <= start_after } if start_after && !start_after.empty?
+
+      limited_keys = keys.first(max_keys)
+      is_truncated = keys.length > limited_keys.length
+      objects = limited_keys.map { |key| entry_for(bucket, key) }
+      next_token = is_truncated && objects.any? ? objects.last.key : nil
+
+      ListResult.new(
+        bucket: bucket,
+        prefix: prefix,
+        marker: marker,
+        max_keys: max_keys,
+        objects: objects,
+        is_truncated: is_truncated,
+        next_marker: next_token,
+        next_continuation_token: next_token
+      )
+    end
+
+    private
+
+    def validate_bucket!(bucket)
+      unless bucket && !bucket.empty? && !bucket.include?("/") && bucket != "." && bucket != ".."
+        raise InvalidBucketNameError, "Invalid bucket name: #{bucket.inspect}"
+      end
+    end
+
+    def validate_key!(key)
+      unless key && !key.empty?
+        raise InvalidObjectKeyError, "Invalid object key: #{key.inspect}"
+      end
+    end
+
+    def bucket_dir(bucket)
+      root.join(bucket)
+    end
+
+    def objects_dir(bucket)
+      bucket_dir(bucket).join("objects")
+    end
+
+    def metadata_dir(bucket)
+      bucket_dir(bucket).join("metadata")
+    end
+
+    def object_path(bucket, key)
+      validate_key!(key)
+
+      base = objects_dir(bucket).expand_path
+      path = base.join(key).cleanpath.expand_path
+      unless path.to_s == base.to_s || path.to_s.start_with?("#{base}#{File::SEPARATOR}")
+        raise InvalidObjectKeyError, "Object key escapes bucket root: #{key.inspect}"
+      end
+
+      path
+    end
+
+    def metadata_path(bucket, key)
+      metadata_dir(bucket).join("#{Digest::SHA256.hexdigest(key)}.json")
+    end
+
+    def object_keys(bucket)
+      base = objects_dir(bucket)
+      return [] unless base.directory?
+
+      Dir.glob(base.join("**", "*"), File::FNM_DOTMATCH)
+        .map { |path| Pathname.new(path) }
+        .reject { |path| path.directory? || [".", ".."].include?(path.basename.to_s) }
+        .map { |path| path.relative_path_from(base).to_s }
+    end
+
+    def entry_for(bucket, key)
+      validate_key!(key)
+
+      path = object_path(bucket, key)
+      raise ObjectNotFoundError, "No such key: #{key}" unless path.file?
+
+      metadata = read_metadata(bucket, key)
+      build_entry(
+        bucket: bucket,
+        key: key,
+        path: path,
+        content_type: metadata.fetch("content_type", "application/octet-stream"),
+        metadata: metadata.fetch("metadata", {}),
+        etag: metadata.fetch("etag") { Digest::MD5.file(path).hexdigest },
+        last_modified: Time.parse(metadata.fetch("last_modified") { path.mtime.utc.iso8601 })
+      )
+    end
+
+    def build_entry(bucket:, key:, path:, content_type:, metadata:, etag:, last_modified:)
+      ObjectEntry.new(
+        bucket: bucket,
+        key: key,
+        path: path,
+        etag: etag,
+        size: path.size,
+        last_modified: last_modified.utc,
+        content_type: content_type,
+        metadata: metadata
+      )
+    end
+
+    def read_metadata(bucket, key)
+      path = metadata_path(bucket, key)
+      return {} unless path.file?
+
+      JSON.parse(path.read)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def write_metadata(entry)
+      path = metadata_path(entry.bucket, entry.key)
+      FileUtils.mkdir_p(path.dirname)
+      path.write(
+        JSON.pretty_generate(
+          "key" => entry.key,
+          "etag" => entry.etag,
+          "content_type" => entry.content_type,
+          "metadata" => entry.metadata,
+          "last_modified" => entry.last_modified.utc.iso8601(3)
+        )
+      )
+    end
+
+    def normalize_metadata(metadata)
+      metadata.each_with_object({}) do |(key, value), normalized|
+        normalized[key.to_s.downcase] = value.to_s
+      end
+    end
+  end
+end

data/lib/bucketrb/server.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rack/handler/webrick"
+require "webrick"
+
+module Bucketrb
+  class Server
+    attr_reader :host, :port
+
+    def initialize(app:, host:, port:, logger: nil)
+      @app = app
+      @host = host
+      @port = port
+      @logger = logger || WEBrick::Log.new($stderr, WEBrick::Log::INFO)
+      @server = build_server
+    end
+
+    def start
+      install_signal_traps if Thread.current == Thread.main
+      @server.start
+    end
+
+    def shutdown
+      @server.shutdown
+    end
+
+    private
+
+    def install_signal_traps
+      trap("INT") { shutdown }
+      trap("TERM") { shutdown }
+    end
+
+    def build_server
+      WEBrick::HTTPServer.new(
+        BindAddress: host,
+        Port: port,
+        AccessLog: [],
+        Logger: @logger
+      ).tap do |server|
+        server.mount("/", Rack::Handler::WEBrick, @app)
+      end
+    end
+  end
+end

data/lib/bucketrb/version.rb

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

data/lib/bucketrb/xml_response.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "time"
+
+module Bucketrb
+  module XMLResponse
+    module_function
+
+    def list_all_my_buckets(buckets)
+      bucket_xml = buckets.map do |bucket|
+        <<~XML
+          <Bucket>
+            <Name>#{escape(bucket)}</Name>
+            <CreationDate>#{timestamp(Time.now.utc)}</CreationDate>
+          </Bucket>
+        XML
+      end.join
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+          <Owner>
+            <ID>bucketrb</ID>
+            <DisplayName>bucketrb</DisplayName>
+          </Owner>
+          <Buckets>
+            #{bucket_xml}
+          </Buckets>
+        </ListAllMyBucketsResult>
+      XML
+    end
+
+    def list_bucket(result, version: 1)
+      contents = result.objects.map { |entry| content(entry) }.join
+
+      if version == 2
+        <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+            <Name>#{escape(result.bucket)}</Name>
+            <Prefix>#{escape(result.prefix)}</Prefix>
+            <KeyCount>#{result.objects.length}</KeyCount>
+            <MaxKeys>#{result.max_keys}</MaxKeys>
+            <IsTruncated>#{result.is_truncated}</IsTruncated>
+            #{continuation_token_xml(result)}
+            #{contents}
+          </ListBucketResult>
+        XML
+      else
+        <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+            <Name>#{escape(result.bucket)}</Name>
+            <Prefix>#{escape(result.prefix)}</Prefix>
+            <Marker>#{escape(result.marker)}</Marker>
+            <MaxKeys>#{result.max_keys}</MaxKeys>
+            <IsTruncated>#{result.is_truncated}</IsTruncated>
+            #{next_marker_xml(result)}
+            #{contents}
+          </ListBucketResult>
+        XML
+      end
+    end
+
+    def delete_result(keys)
+      deleted = keys.map do |key|
+        <<~XML
+          <Deleted>
+            <Key>#{escape(key)}</Key>
+          </Deleted>
+        XML
+      end.join
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+          #{deleted}
+        </DeleteResult>
+      XML
+    end
+
+    def copy_result(entry)
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+          <LastModified>#{timestamp(entry.last_modified)}</LastModified>
+          <ETag>#{entry.quoted_etag}</ETag>
+        </CopyObjectResult>
+      XML
+    end
+
+    def error(code, message)
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <Error>
+          <Code>#{escape(code)}</Code>
+          <Message>#{escape(message)}</Message>
+          <RequestId>bucketrb</RequestId>
+        </Error>
+      XML
+    end
+
+    def content(entry)
+      <<~XML
+        <Contents>
+          <Key>#{escape(entry.key)}</Key>
+          <LastModified>#{timestamp(entry.last_modified)}</LastModified>
+          <ETag>#{entry.quoted_etag}</ETag>
+          <Size>#{entry.size}</Size>
+          <StorageClass>STANDARD</StorageClass>
+        </Contents>
+      XML
+    end
+
+    def timestamp(time)
+      time.utc.iso8601(3)
+    end
+
+    def escape(value)
+      CGI.escapeHTML(value.to_s)
+    end
+
+    def next_marker_xml(result)
+      return "" unless result.next_marker
+
+      "<NextMarker>#{escape(result.next_marker)}</NextMarker>"
+    end
+
+    def continuation_token_xml(result)
+      return "" unless result.next_continuation_token
+
+      "<NextContinuationToken>#{escape(result.next_continuation_token)}</NextContinuationToken>"
+    end
+  end
+end

data/lib/bucketrb.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "bucketrb/version"
+require_relative "bucketrb/app"
+require_relative "bucketrb/object_store"
+require_relative "bucketrb/server"

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification
+name: bucketrb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bucketrb contributors
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.190'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.190'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+description: Bucketrb is a lightweight local S3-compatible HTTP server backed by the
+  filesystem.
+email: []
+executables:
+- bucketrb
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- ROADMAP.md
+- exe/bucketrb
+- lib/bucketrb.rb
+- lib/bucketrb/app.rb
+- lib/bucketrb/cli.rb
+- lib/bucketrb/errors.rb
+- lib/bucketrb/object_store.rb
+- lib/bucketrb/server.rb
+- lib/bucketrb/version.rb
+- lib/bucketrb/xml_response.rb
+homepage: https://rubygems.org/gems/bucketrb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://rubygems.org/gems/bucketrb
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A small local S3-compatible server for Ruby development.
+test_files: []