gemstack-storage 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 596b95da7b39fb9d21a5e099b2aed7fb1c9606cb08e94023f10e164ca4b4e87a
+  data.tar.gz: 202413346a690ec6ad8cc5a3b404fa579eac9ffaddbea26133bd565e50e30d6a
+SHA512:
+  metadata.gz: a0ca9969b8f7cd2a06889d098d1b9cb5607c67e593eb90f69c315b45299a8751a4ff528cff98ff9ce28c4c1d49bad47c8cdfae9c13346c62ec1ca55cd66e7ce3
+  data.tar.gz: 43f73ed8482c2f7e680009840a35faa6caaf453a28b843f631025493054e193320ad5811b737410f0dfa979ed683c3594623fcc0aaad358f4471d19891b81ed4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+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,28 @@
+# gemstack-storage
+
+GemStack storage: disk and S3 services, signed URLs, direct uploads.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Optional module — `gemstack add storage`:
+
+```ruby
+gem "gemstack-storage", "~> 0.1"
+```
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/storage.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-storage`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/storage/endpoint.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Storage
+    # Serves the :disk service's signed URLs:
+    #   PUT <path>/<token>   stores the request body (type and size as signed)
+    #   GET <path>/<token>   streams the file
+    # Unsigned, expired or tampered tokens get 404/403; nothing else is exposed.
+    class Endpoint
+      def initialize(app) = @app = app
+
+      def call(env)
+        prefix = "#{Storage.config.path}/"
+        path = env[Rack::PATH_INFO].to_s
+        return @app.call(env) unless path.start_with?(prefix)
+
+        token = path.delete_prefix(prefix)
+        case env[Rack::REQUEST_METHOD]
+        when "PUT" then put(env, token)
+        when "GET", "HEAD" then get(env, token)
+        else raise MethodNotAllowed.new(headers: { "allow" => "GET, HEAD, PUT" })
+        end
+      end
+
+      private
+
+      def service
+        service = Storage.service
+        raise NotFound unless service.is_a?(Services::Disk)
+
+        service
+      end
+
+      def put(env, token)
+        claims = Storage.verify(token, purpose: "disk-put") or raise Forbidden.new("Invalid or expired upload URL",
+                                                                                   code: "invalid_signature")
+        check_headers!(env, claims)
+        service.upload(claims["k"], LimitedReader.new(env["rack.input"], claims["n"]))
+        unless service.size(claims["k"]) == claims["n"]
+          service.delete(claims["k"])
+          raise BadRequest.new("The file is smaller than declared", code: "size_mismatch")
+        end
+        [201, { "content-length" => "0" }, []]
+      rescue LimitedReader::TooLarge
+        FileUtils.rm_f("#{service.path_for(claims["k"])}.part")
+        raise PayloadTooLarge.new("The file is larger than declared", code: "size_mismatch")
+      end
+
+      def check_headers!(env, claims)
+        type = env["CONTENT_TYPE"].to_s.split(";").first.to_s.strip.downcase
+        if type != claims["t"]
+          raise BadRequest.new("Content-Type must be #{claims["t"]}",
+                               code: "content_type_mismatch")
+        end
+
+        length = Integer(env["CONTENT_LENGTH"].to_s, exception: false)
+        return unless length && length != claims["n"]
+
+        raise BadRequest.new("Content-Length must be #{claims["n"]}", code: "size_mismatch")
+      end
+
+      def get(env, token)
+        claims = Storage.verify(token, purpose: "disk-get") or raise NotFound
+        file = service.path_for(claims["k"])
+        raise NotFound unless File.file?(file)
+
+        disposition = claims["d"] == "inline" ? "inline" : "attachment"
+        disposition += "; filename=\"#{claims["f"].gsub(/["\\\r\n]/, "")}\"" if claims["f"]
+        headers = {
+          "content-type" => Storage.content_type_for(claims["k"]), "content-length" => File.size(file).to_s,
+          "content-disposition" => disposition, "cache-control" => "private, max-age=300",
+          # Uploaded files are untrusted: never sniffed, never scripted.
+          "x-content-type-options" => "nosniff", "content-security-policy" => "default-src 'none'; sandbox"
+        }
+        body = env[Rack::REQUEST_METHOD] == "HEAD" ? [] : FileBody.new(file)
+        [200, headers, body]
+      end
+
+      # Reads at most `limit` bytes; more means the client lied about the size.
+      class LimitedReader
+        class TooLarge < StandardError; end
+
+        def initialize(io, limit)
+          @io = io
+          @left = limit
+        end
+
+        def read(length = nil, buffer = nil)
+          chunk = @io.read(length || 65_536, buffer)
+          return chunk if chunk.nil?
+
+          @left -= chunk.bytesize
+          raise TooLarge if @left.negative?
+
+          chunk
+        end
+      end
+
+      class FileBody
+        def initialize(path) = @path = path
+
+        def each
+          File.open(@path, "rb") do |file|
+            while (chunk = file.read(65_536))
+              yield chunk
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/storage/services/disk.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module GemStack
+  module Storage
+    module Services
+      # Files on the local disk. Signed URLs point at Storage::Endpoint, so
+      # the browser code is identical to S3's: PUT to upload, GET to download.
+      class Disk
+        attr_reader :root, :path
+
+        def initialize(root:, path:)
+          @root = File.expand_path(root)
+          @path = path
+        end
+
+        def upload(key, io, content_type: nil) # rubocop:disable Lint/UnusedMethodArgument
+          target = path_for(key)
+          FileUtils.mkdir_p(File.dirname(target))
+          File.open("#{target}.part", "wb") { |file| IO.copy_stream(io, file) }
+          File.rename("#{target}.part", target)
+          key
+        end
+
+        def download(key) = File.binread(path_for(key))
+        def exist?(key) = File.file?(path_for(key))
+
+        def delete(key)
+          FileUtils.rm_f(path_for(key))
+          true
+        end
+
+        def size(key) = File.size(path_for(key))
+
+        def presigned_upload(key, content_type:, byte_size:, expires_in:)
+          token = Storage.sign({ "k" => key, "t" => content_type, "n" => byte_size }, purpose: "disk-put",
+                                                                                      expires_in: expires_in)
+          { url: "#{path}/#{token}", method: "PUT", headers: { "content-type" => content_type } }
+        end
+
+        def url(key, expires_in:, disposition:, filename: nil)
+          token = Storage.sign({ "k" => key, "d" => disposition, "f" => filename }, purpose: "disk-get",
+                                                                                    expires_in: expires_in)
+          "#{path}/#{token}"
+        end
+
+        # Keys never escape the root (no "..", no absolute paths).
+        def path_for(key)
+          key = key.to_s
+          if key.empty? || key.start_with?("/") || key.split("/").any? { |part| part.empty? || part.start_with?(".") }
+            raise ArgumentError, "invalid storage key #{key.inspect}"
+          end
+
+          File.join(root, key)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/storage/services/s3.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+begin
+  require "aws-sdk-s3"
+rescue LoadError
+  raise GemStack::ConfigurationError, "config.storage.service = :s3 needs gem \"aws-sdk-s3\" in the Gemfile"
+end
+
+module GemStack
+  module Storage
+    module Services
+      # Amazon S3 and S3-compatible services (Cloudflare R2, MinIO, …).
+      # Browsers PUT directly to a presigned URL; its signature covers the
+      # content type and exact size, so neither can be changed.
+      #
+      # The bucket needs a CORS rule allowing PUT from your site (docs/storage.md).
+      class S3
+        attr_reader :bucket, :client
+
+        def initialize(bucket:, region:, endpoint: nil, client: nil, **options)
+          raise ConfigurationError, "set S3_BUCKET (config.storage.bucket) to use the :s3 storage service" if
+            bucket.to_s.empty? && client.nil?
+
+          @bucket = bucket
+          options = { region: region, endpoint: endpoint,
+                      force_path_style: !endpoint.nil? || nil }.compact.merge(options)
+          @client = client || Aws::S3::Client.new(**options)
+          @presigner = Aws::S3::Presigner.new(client: @client)
+        end
+
+        def upload(key, io, content_type:)
+          client.put_object(bucket: bucket, key: key, body: io, content_type: content_type)
+          key
+        end
+
+        def download(key) = client.get_object(bucket: bucket, key: key).body.read
+
+        def exist?(key)
+          client.head_object(bucket: bucket, key: key)
+          true
+        rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+          false
+        end
+
+        def delete(key)
+          client.delete_object(bucket: bucket, key: key)
+          true
+        end
+
+        def presigned_upload(key, content_type:, byte_size:, expires_in:)
+          url = @presigner.presigned_url(:put_object, bucket: bucket, key: key, content_type: content_type,
+                                                      content_length: byte_size, expires_in: expires_in,
+                                                      whitelist_headers: ["content-length"]) # sign the size too
+          { url: url, method: "PUT", headers: { "content-type" => content_type } }
+        end
+
+        def url(key, expires_in:, disposition:, filename: nil)
+          header = filename ? "#{disposition}; filename=\"#{filename.to_s.gsub(/["\\\r\n]/, "")}\"" : disposition
+          @presigner.presigned_url(:get_object, bucket: bucket, key: key, expires_in: expires_in,
+                                                response_content_disposition: header)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/storage/testing.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "gemstack/storage"
+require "tmpdir"
+
+module GemStack
+  module Storage
+    # Tests store files on disk in a temporary directory, cleared after each test.
+    module Testing
+      def before_setup
+        super
+        @gemstack_storage_root = Dir.mktmpdir("gemstack-storage")
+        Storage.service = Services::Disk.new(root: @gemstack_storage_root, path: Storage.config.path)
+      end
+
+      def after_teardown
+        FileUtils.rm_rf(@gemstack_storage_root) if @gemstack_storage_root
+        Storage.reset!
+        super
+      end
+
+      # Stores a file as if the browser had uploaded it; returns its signed_id.
+      def upload_fixture(content, filename: "file.png", content_type: "image/png")
+        key = Storage.generate_key("uploads", filename, content_type)
+        Storage.upload(key, StringIO.new(content), content_type: content_type)
+        Storage.sign(key, purpose: "upload")
+      end
+    end
+  end
+end

data/lib/gemstack/storage.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+require "json"
+require "time"
+require "gemstack/core"
+require "gemstack/http"
+
+module GemStack
+  # File storage (DECISIONS D-053): files go from the browser straight to
+  # the storage service, never through a Ruby process.
+  #
+  #   # POST /api/uploads → presigned upload for the browser
+  #   upload = GemStack::Storage.direct_upload(filename: "cat.png", content_type: "image/png", byte_size: 52_000)
+  #   # browser: PUT the file to upload[:url] with upload[:headers]
+  #   # later:   product.update(image_key: GemStack::Storage.key_for_signed_id(params[:image]))
+  #   GemStack::Storage.url(product.image_key)   # short-lived signed download URL
+  #
+  # Services: :disk (development and tests; files under storage/, served and
+  # accepted by a signed endpoint at /api/storage) and :s3 (S3, R2, MinIO…).
+  module Storage
+    class Config < Settings
+      # :disk, :s3, or a service object.
+      setting :service, default: -> { ENV.fetch("STORAGE_SERVICE", GemStack.env.production? ? "s3" : "disk").to_sym }
+      setting :root, default: -> { File.join(GemStack.config.root, "storage", GemStack.env.test? ? "test" : "") }
+      # Where the disk service's signed URLs point (handled by Storage::Endpoint).
+      setting :path, default: -> { "#{GemStack.config.http.api_path}/storage" }
+      setting :bucket, default: -> { ENV.fetch("S3_BUCKET", nil) }
+      setting :region, default: -> { ENV.fetch("AWS_REGION", ENV.fetch("S3_REGION", "us-east-1")) }
+      # For S3-compatible services: https://<account>.r2.cloudflarestorage.com, http://localhost:9000
+      setting :endpoint, default: -> { ENV.fetch("S3_ENDPOINT", nil) }
+      # Credentials come from the usual AWS chain (AWS_ACCESS_KEY_ID…, instance roles) unless set.
+      setting :s3_options, default: {}
+      setting :url_expires_in, default: 300
+      setting :max_upload_size, default: 10 * 1024 * 1024
+      # MIME types accepted by direct_upload ("image/*" style wildcards).
+      # SVG and HTML are excluded on purpose: they can carry scripts.
+      setting :allowed_content_types, default: %w[image/png image/jpeg image/gif image/webp image/avif application/pdf]
+    end
+
+    class InvalidUpload < ValidationError; end
+
+    # Served inline by browsers; everything else is sent as an attachment.
+    INLINE_TYPES = %w[image/png image/jpeg image/gif image/webp image/avif application/pdf text/plain].freeze
+
+    class << self
+      def config = GemStack.config.storage
+
+      def service
+        @service ||= build_service(config.service)
+      end
+
+      attr_writer :service
+
+      def reset! = @service = nil
+
+      # Validates an upload request and returns what the browser needs:
+      #   { key:, signed_id:, url:, method: "PUT", headers: {…} }
+      def direct_upload(filename:, content_type:, byte_size:, prefix: "uploads")
+        content_type = content_type.to_s.downcase.split(";").first.to_s.strip
+        byte_size = Integer(byte_size, exception: false)
+        validate_upload!(content_type, byte_size)
+
+        key = generate_key(prefix, filename, content_type)
+        upload = service.presigned_upload(key, content_type: content_type, byte_size: byte_size,
+                                               expires_in: config.url_expires_in)
+        { key: key, signed_id: sign(key, purpose: "upload"), **upload }
+      end
+
+      # The key behind a signed_id from direct_upload; 422 when tampered with
+      # (so clients can't point records at other people's files).
+      def key_for_signed_id(signed_id)
+        verify(signed_id, purpose: "upload") ||
+          raise(InvalidUpload.new("Invalid upload reference", errors: { file: ["is invalid"] }))
+      end
+
+      def url(key, expires_in: config.url_expires_in, disposition: nil, filename: nil)
+        service.url(key, expires_in: expires_in, disposition: disposition || disposition_for(key), filename: filename)
+      end
+
+      def upload(key, io, content_type:) = service.upload(key, io, content_type: content_type)
+      def download(key) = service.download(key)
+      def delete(key) = service.delete(key)
+      def exist?(key) = service.exist?(key)
+
+      def allowed_content_type?(type)
+        Array(config.allowed_content_types).any? do |pattern|
+          pattern.end_with?("/*") ? type.start_with?(pattern.delete_suffix("*")) : type == pattern
+        end
+      end
+
+      # Tamper-proof, expiring tokens (HMAC with GemStack.key_for("storage")).
+      def sign(value, purpose:, expires_in: nil)
+        payload = { "v" => value, "p" => purpose }
+        payload["e"] = Time.now.to_i + expires_in if expires_in
+        data = [JSON.generate(payload)].pack("m0").tr("+/", "-_").delete("=")
+        "#{data}--#{digest(data)}"
+      end
+
+      def verify(token, purpose:)
+        data, mac = token.to_s.split("--", 2)
+        return nil unless data && mac && OpenSSL.fixed_length_secure_compare(digest(data), mac)
+
+        payload = JSON.parse(data.tr("-_", "+/").ljust((data.length + 3) & ~3, "=").unpack1("m0"))
+        return nil unless payload["p"] == purpose
+        return nil if payload["e"] && payload["e"] < Time.now.to_i
+
+        payload["v"]
+      rescue ArgumentError, JSON::ParserError
+        nil
+      end
+
+      # Keys are ours, not the client's: uploads/2026/09/<uuid>/<clean name>.
+      # The extension always matches the validated content type, so a file
+      # declared as image/png can't be served as HTML because it's named x.html.
+      def generate_key(prefix, filename, content_type)
+        base = File.basename(filename.to_s, ".*").unicode_normalize(:nfkc).gsub(/[^\w-]+/, "-").gsub(/\A-+|-+\z/, "")
+        base = "file" if base.empty?
+        [prefix, Time.now.utc.strftime("%Y/%m"), SecureRandom.uuid, "#{base[0, 100]}#{extension_for(content_type)}"]
+          .reject(&:empty?).join("/")
+      end
+
+      EXTENSIONS = { "image/jpeg" => ".jpg", "image/png" => ".png", "image/gif" => ".gif", "image/webp" => ".webp",
+                     "image/avif" => ".avif", "application/pdf" => ".pdf", "text/plain" => ".txt",
+                     "text/csv" => ".csv" }.freeze
+
+      def extension_for(content_type) = EXTENSIONS[content_type] || Rack::Mime::MIME_TYPES.key(content_type) || ".bin"
+
+      def content_type_for(key) = Rack::Mime.mime_type(File.extname(key.to_s), "application/octet-stream")
+
+      private
+
+      def build_service(service)
+        case service
+        when :disk, "disk" then Services::Disk.new(root: config.root, path: config.path)
+        when :s3, "s3"
+          require_relative "storage/services/s3"
+          Services::S3.new(bucket: config.bucket, region: config.region, endpoint: config.endpoint,
+                           **config.s3_options)
+        else
+          unless service.respond_to?(:presigned_upload)
+            raise ConfigurationError, "unknown config.storage.service #{service.inspect} (use :disk, :s3 or an object)"
+          end
+
+          service
+        end
+      end
+
+      def validate_upload!(content_type, byte_size)
+        errors = {}
+        errors[:content_type] = ["#{content_type.inspect} is not allowed"] unless allowed_content_type?(content_type)
+        max = config.max_upload_size
+        if byte_size.nil? || byte_size <= 0
+          errors[:byte_size] = ["must be a positive number of bytes"]
+        elsif byte_size > max
+          errors[:byte_size] = ["is too large (maximum #{max / 1024 / 1024} MB)"]
+        end
+        raise InvalidUpload.new("Upload refused", errors: errors) unless errors.empty?
+      end
+
+      # Browsers show images and PDFs inline; anything else downloads.
+      def disposition_for(key) = INLINE_TYPES.include?(content_type_for(key)) ? "inline" : "attachment"
+
+      def digest(data) = OpenSSL::HMAC.hexdigest("SHA256", GemStack.key_for("storage"), data)
+    end
+  end
+end
+
+require_relative "storage/services/disk"
+require_relative "storage/endpoint"
+
+GemStack::Config.namespace(:storage, GemStack::Storage::Config)
+
+GemStack::Plugins.register(:storage) do |app|
+  next unless app.respond_to?(:config)
+
+  stack = app.config.http.middleware
+  # Before BodyLimit: signed uploads carry their own size limit.
+  unless stack.include?(GemStack::Storage::Endpoint)
+    stack.insert_before(GemStack::HTTP::Middleware::BodyLimit, GemStack::Storage::Endpoint)
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-storage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  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: gemstack-http
+  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
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/storage.rb
+- lib/gemstack/storage/endpoint.rb
+- lib/gemstack/storage/services/disk.rb
+- lib/gemstack/storage/services/s3.rb
+- lib/gemstack/storage/testing.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-storage
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-storage/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack storage: disk and S3 services, signed URLs, direct uploads'
+test_files: []