gemstack 0.2.5 → 0.3.0

data/lib/gemstack/serializer.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Explicit, typed JSON representations. Nothing is exposed unless listed.
+  #
+  #   class ProductSerializer < GemStack::Serializer
+  #     attributes :id, :name, :price, :active, :created_at   # types inferred from Product's fields
+  #     attribute :display_price, :string do |product|
+  #       "€#{product.price}"
+  #     end
+  #     attribute :category, CategorySerializer                 # nested
+  #     attribute :reviews, [ReviewSerializer]                  # nested list
+  #   end
+  #
+  #   ProductSerializer.serialize(product)   # => { id: 1, name: "Lamp", price: "9.99", ... }
+  #   ProductSerializer.many(products)       # => [ {...}, ... ]
+  #
+  # Values are dumped by type: decimals become strings, times ISO 8601 UTC.
+  # Types come from an explicit type argument, else from the model's field
+  # declarations (the model is found by name: ProductSerializer → Product),
+  # and drive the generated TypeScript interfaces.
+  class Serializer
+    Attribute = Struct.new(:name, :type, :block, :nullable, keyword_init: true) do
+      def serializer? = type.is_a?(Class) && type <= Serializer
+      def list? = type.is_a?(Array)
+    end
+
+    CONVENTIONAL_TYPES = { id: [:bigint, false], created_at: [:datetime, false], updated_at: [:datetime, false] }.freeze
+
+    class << self
+      def attributes_list
+        @attributes_list ||= superclass.respond_to?(:attributes_list) ? superclass.attributes_list.dup : {}
+      end
+
+      # attributes :id, :name        (types inferred)
+      # attributes name: :string     (explicit)
+      def attributes(*names, **typed)
+        names.each { |name| attribute(name) }
+        typed.each { |name, type| attribute(name, type) }
+      end
+
+      def attribute(name, type = nil, nullable: nil, &block)
+        if type && !type.is_a?(Array) && !(type.is_a?(Class) && type <= Serializer)
+          type = Types::CLASS_ALIASES.fetch(type, type).to_sym
+          Types.fetch(type)
+        end
+        attributes_list[name.to_sym] = Attribute.new(name: name.to_sym, type: type, block: block, nullable: nullable)
+        @resolved_attributes = nil
+      end
+
+      # The model used for type inference. Defaults to the class named like
+      # the serializer without "Serializer" (Admin::ProductSerializer → Admin::Product, then Product).
+      def model(klass = nil)
+        @model = klass if klass
+        return @model if defined?(@model) && @model
+
+        base = name&.delete_suffix("Serializer")
+        return nil if base.nil? || base.empty?
+
+        [base, base.split("::").last].uniq.each do |candidate|
+          constant = Object.const_get(candidate) if Object.const_defined?(candidate)
+          return constant if constant.respond_to?(:gemstack_fields)
+        rescue NameError
+          next
+        end
+        nil
+      end
+
+      attr_writer :type_name
+
+      # TypeScript/OpenAPI name: ProductSerializer → "Product", Admin::ProductSerializer → "AdminProduct".
+      def type_name
+        @type_name || (name && name.delete_suffix("Serializer").split("::").join)
+      end
+
+      # Attributes with resolved types: [{name:, type:, nullable:}], type being
+      # a type Symbol, a Serializer class, or [Serializer]/[:type] for lists.
+      def resolved_attributes
+        @resolved_attributes ||= attributes_list.values.map do |attr|
+          type, nullable = infer(attr)
+          { name: attr.name, type: type, nullable: attr.nullable.nil? ? nullable : attr.nullable }
+        end.freeze
+      end
+
+      # [[name, block_or_nil, dumper_or_nil], ...] — types resolved to
+      # dumpers once, so serializing an object does no type lookups.
+      def compiled
+        @compiled ||= resolved_attributes.map do |attr|
+          [attr[:name], attributes_list[attr[:name]].block, dumper_for(attr[:type])]
+        end.freeze
+      end
+
+      def serialize(object, context = {})
+        object.nil? ? nil : new(object, context).to_h
+      end
+
+      def many(objects, context = {})
+        objects = objects.all if objects.respond_to?(:all) && !objects.is_a?(Array) # Sequel datasets
+        objects.map { |object| new(object, context).to_h }
+      end
+
+      # Convention-based rendering, shared by controllers (`render`) and
+      # realtime (`GemStack.broadcast`): an object of class Product uses
+      # ProductSerializer, arrays and datasets of them too; plain JSON values
+      # and objects without a serializer pass through unchanged.
+      def render(value, context = {})
+        case value
+        when Hash, String, Numeric, Symbol, true, false, nil then value
+        when Array
+          serializer = value.first && self.for(value.first.class)
+          serializer ? serializer.many(value, context) : value
+        else
+          if value.respond_to?(:model) && value.respond_to?(:all) # a dataset / query
+            serializer = self.for(value.model)
+            return serializer ? serializer.many(value, context) : value.all
+          end
+          serializer = self.for(value.class)
+          serializer ? serializer.serialize(value, context) : value
+        end
+      end
+
+      # Defaults for convention-based lookup: ProductSerializer for Product.
+      def for(object_class)
+        return nil unless object_class.name
+
+        name = "#{object_class.name}Serializer"
+        Object.const_defined?(name) ? Object.const_get(name) : nil
+      rescue NameError
+        nil
+      end
+
+      private
+
+      # A lambda (value, context) -> JSON value, or nil when values pass through.
+      def dumper_for(type)
+        case type
+        when Array
+          item = dumper_for(type.first)
+          return nil unless item
+
+          ->(values, ctx) { values.map { |v| v.nil? ? nil : item.call(v, ctx) } }
+        when Symbol then scalar_dumper(Types.fetch(type))
+        else ->(value, ctx) { type.serialize(value, ctx) } # nested serializer
+        end
+      end
+
+      def scalar_dumper(type)
+        if %i[string text].include?(type.name)
+          ->(value, _) { value.is_a?(String) ? value : type.coerce(value) }
+        elsif type.dumper
+          dump = type.dumper
+          ->(value, _) { dump.call(value) }
+        end
+      end
+
+      # Explicit types are non-null unless declared nullable or the model's
+      # field allows null; inferred types follow the model's field.
+      def infer(attr)
+        field = model&.gemstack_fields&.[](attr.name)
+        return [attr.type, field ? field.options[:null] != false : false] if attr.type
+        return [field.type, field.options[:null] != false] if field
+
+        CONVENTIONAL_TYPES.fetch(attr.name) { [:json, true] }
+      end
+    end
+
+    attr_reader :object, :context
+
+    def initialize(object, context = {})
+      @object = object
+      @context = context
+    end
+
+    # Hot path: iterates the plan compiled once per serializer class
+    # (docs/performance.md — this loop dominates JSON response time).
+    def to_h
+      hash = {}
+      self.class.compiled.each do |name, block, dumper|
+        value = block ? instance_exec(object, &block) : object.public_send(name)
+        hash[name] = value.nil? || dumper.nil? ? value : dumper.call(value, context)
+      end
+      hash
+    end
+    alias as_json to_h
+  end
+end

data/lib/gemstack/settings.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module GemStack
+  # A small DSL for declaring configuration with defaults.
+  #
+  #   class HTTPConfig < GemStack::Settings
+  #     setting :api_path, default: "/api"
+  #     setting :health_path, default: -> { "#{api_path}/health" }
+  #     namespace :cors do
+  #       setting :origins, default: []
+  #     end
+  #   end
+  #
+  # - A callable default is evaluated lazily, in the context of the settings
+  #   object, the first time it is read, and then memoized. This lets defaults
+  #   depend on ENV or on other settings.
+  # - Array/Hash defaults are duplicated per instance, so instances never share
+  #   mutable state.
+  # - Reading or writing an undeclared setting raises NoMethodError (with
+  #   Ruby's did_you_mean suggestions), so typos fail fast.
+  class Settings
+    class << self
+      def definitions
+        @definitions ||= superclass <= Settings ? superclass.definitions.dup : {}
+      end
+
+      def namespaces
+        @namespaces ||= superclass <= Settings ? superclass.namespaces.dup : {}
+      end
+
+      def setting(name, default: nil)
+        name = name.to_sym
+        definitions[name] = default
+        define_method(name) { read(name) }
+        define_method(:"#{name}=") { |value| @values[name] = value }
+        name
+      end
+
+      # Declares a nested settings group. Pass a Settings subclass, or a block
+      # that is evaluated in a new anonymous subclass. Modules use this to add
+      # their own namespace to GemStack::Config without core knowing about them.
+      def namespace(name, klass = nil, &)
+        name = name.to_sym
+        klass ||= Class.new(Settings, &)
+        namespaces[name] = klass
+        define_method(name) do |&configure|
+          group = (@groups[name] ||= klass.new)
+          configure&.call(group)
+          group
+        end
+        klass
+      end
+    end
+
+    def initialize
+      @values = {}
+      @groups = {}
+    end
+
+    def read(name)
+      return @values[name] if @values.key?(name)
+
+      default = self.class.definitions.fetch(name)
+      @values[name] =
+        case default
+        when Proc then instance_exec(&default)
+        when Array, Hash then default.dup
+        else default
+        end
+    end
+
+    def set?(name)
+      @values.key?(name.to_sym)
+    end
+
+    def settings
+      self.class.definitions.keys
+    end
+
+    def to_h
+      hash = settings.to_h { |name| [name, read(name)] }
+      self.class.namespaces.each_key { |name| hash[name] = public_send(name).to_h }
+      hash
+    end
+  end
+end

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