gemstack-http 0.1.0

data/lib/gemstack/http/middleware_stack.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # An ordered, editable list of Rack middleware, compiled once into a
+    # nested Rack app when the application is built.
+    #
+    #   config.http.middleware.use Rack::Attack
+    #   config.http.middleware.insert_before GemStack::HTTP::Middleware::ErrorHandler, MyTiming
+    #   config.http.middleware.swap GemStack::HTTP::Middleware::RequestLogger, MyLogger
+    #   config.http.middleware.delete GemStack::HTTP::Middleware::SecurityHeaders
+    #
+    # Targets are middleware classes or integer positions. Any Rack
+    # middleware (`new(app, *args)`, `#call(env)`) works.
+    class MiddlewareStack
+      include Enumerable
+
+      Entry = Struct.new(:klass, :args, :kwargs, :block) do
+        def build(app) = klass.new(app, *args, **kwargs, &block)
+        def name = klass.respond_to?(:name) && klass.name ? klass.name : klass.inspect
+      end
+
+      def self.default(config)
+        new.tap do |stack|
+          stack.use Middleware::RequestId, config
+          stack.use Middleware::RequestLogger
+          stack.use Middleware::Compression, config
+          stack.use Middleware::ErrorHandler, config
+          stack.use Middleware::SecurityHeaders, config
+          stack.use Middleware::Cors, config
+          stack.use Middleware::BodyLimit, config
+          stack.use Middleware::HealthCheck, config
+          stack.use Middleware::ETags, config
+        end
+      end
+
+      def initialize
+        @entries = []
+      end
+
+      def use(klass, *args, **kwargs, &block)
+        @entries << Entry.new(klass, args, kwargs, block)
+        self
+      end
+
+      def unshift(klass, *args, **kwargs, &block)
+        @entries.unshift(Entry.new(klass, args, kwargs, block))
+        self
+      end
+
+      def insert_before(target, klass, *args, **kwargs, &block)
+        @entries.insert(index!(target), Entry.new(klass, args, kwargs, block))
+        self
+      end
+
+      def insert_after(target, klass, *args, **kwargs, &block)
+        @entries.insert(index!(target) + 1, Entry.new(klass, args, kwargs, block))
+        self
+      end
+
+      def swap(target, klass, *args, **kwargs, &block)
+        @entries[index!(target)] = Entry.new(klass, args, kwargs, block)
+        self
+      end
+
+      def delete(target)
+        @entries.delete_at(index!(target))
+        self
+      end
+
+      def include?(klass) = @entries.any? { |entry| entry.klass == klass }
+      def each(&) = @entries.each(&)
+      def size = @entries.size
+      def names = @entries.map(&:name)
+
+      # Wraps endpoint so that the first middleware in the list runs first.
+      def build(endpoint)
+        @entries.reverse.inject(endpoint) { |app, entry| entry.build(app) }
+      end
+
+      def initialize_copy(source)
+        super
+        @entries = source.to_a.dup
+      end
+
+      private
+
+      def index!(target)
+        index = target.is_a?(Integer) ? target : @entries.index { |entry| entry.klass == target }
+        raise ArgumentError, "no middleware #{target.inspect} in the stack" unless index && @entries[index]
+
+        index
+      end
+    end
+  end
+end

data/lib/gemstack/http/page.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # One page of a collection, rendered as the pagination envelope
+    # (DECISIONS D-034):
+    #
+    #   { "data": [ ... ], "meta": { "page": 2, "per_page": 25, "total": 180, "total_pages": 8 } }
+    #
+    # Built by Controller#paginate. `GemStack::Page[ProductSerializer]` is the
+    # matching type for `returns`, so the TypeScript client gets `Paginated<Product>`.
+    # Always namespaced, so an app's own Page model never collides with it.
+    class Page
+      # Type marker for the contract: Page[ProductSerializer].
+      Type = Struct.new(:item)
+
+      def self.[](item_type) = Type.new(item_type)
+
+      attr_reader :items, :page, :per_page, :total
+
+      def initialize(items, page:, per_page:, total:)
+        @items = items
+        @page = page
+        @per_page = per_page
+        @total = total
+      end
+
+      def total_pages = total.zero? ? 0 : (total.to_f / per_page).ceil
+
+      def meta = { page: page, per_page: per_page, total: total, total_pages: total_pages }
+    end
+  end
+
+  # Public name, used in controllers: `returns :index, GemStack::Page[ProductSerializer]`.
+  Page = HTTP::Page
+end

data/lib/gemstack/http/params.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # Request parameters with indifferent (string/symbol) key access and
+    # explicit allow-listing for anything that reaches the application:
+    #
+    #   params[:id]                              # path, query or body
+    #   params.require(:product)                 # 400 if missing/blank
+    #   params.permit(:name, :price, tags: [], dimensions: [:width, :height])
+    #   # => { name: "Lamp", price: "9.99", tags: ["home"], dimensions: { width: 3, height: 5 } }
+    #
+    # #permit only returns scalars (and arrays/hashes that are explicitly
+    # declared), so unexpected nested structures never reach models.
+    class Params
+      include Enumerable
+
+      class ParameterMissing < BadRequest
+        def initialize(key)
+          super("Missing parameter: #{key}", code: "parameter_missing", details: { key.to_s => ["is required"] })
+        end
+      end
+
+      SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+      def initialize(hash = {})
+        @hash = hash.transform_keys(&:to_s)
+      end
+
+      def [](key) = wrap(@hash[key.to_s])
+      def key?(key) = @hash.key?(key.to_s)
+      alias has_key? key?
+      alias include? key?
+      def keys = @hash.keys
+      def empty? = @hash.empty?
+      def size = @hash.size
+      def each(&) = @hash.each { |key, value| yield key, wrap(value) }
+
+      def fetch(key, *default, &)
+        wrap(@hash.fetch(key.to_s, *default, &))
+      end
+
+      def dig(key, *rest)
+        value = self[key]
+        rest.empty? || value.nil? ? value : value.dig(*rest)
+      end
+
+      # Returns the value for key, raising ParameterMissing (400) when it is
+      # absent, nil, or an empty string/collection.
+      def require(key)
+        value = @hash[key.to_s]
+        raise ParameterMissing, key if blank?(value)
+
+        wrap(value)
+      end
+
+      def slice(*keys) = Params.new(@hash.slice(*keys.map(&:to_s)))
+      def except(*keys) = Params.new(@hash.except(*keys.map(&:to_s)))
+
+      # Allow-list. Returns a plain Hash with symbol keys.
+      def permit(*filters)
+        filters.each_with_object({}) do |filter, result|
+          case filter
+          when Symbol, String
+            key = filter.to_s
+            value = @hash[key]
+            result[filter.to_sym] = value if @hash.key?(key) && scalar?(value)
+          when Hash
+            filter.each { |key, nested| permit_nested(result, key, nested) }
+          else
+            raise ArgumentError, "invalid permit filter #{filter.inspect}"
+          end
+        end
+      end
+
+      # Validates and coerces against a schema (see GemStack::Schema), returning
+      # a symbol-keyed Hash of declared fields or raising a 422 ValidationError:
+      #
+      #   attrs = params.validate do
+      #     required :name, :string
+      #     required :price, :decimal, gt: 0
+      #   end
+      #   attrs = params.validate(ProductInput)
+      def validate(schema = nil, &)
+        schema ||= Schema.define(&)
+        schema.call(@hash)
+      end
+
+      # Unfiltered, deep copy with string keys. Prefer #permit for input
+      # that will be persisted.
+      def to_h = deep_dup(@hash)
+      alias to_unsafe_h to_h
+
+      def ==(other)
+        to_h == (other.is_a?(Params) ? other.to_h : other)
+      end
+
+      def inspect = "#<#{self.class.name} #{@hash.inspect}>"
+
+      private
+
+      def permit_nested(result, key, nested)
+        value = @hash[key.to_s]
+        return unless @hash.key?(key.to_s)
+
+        if nested == [] # array of scalars
+          result[key.to_sym] = value.select { |v| scalar?(v) } if value.is_a?(Array)
+        elsif value.is_a?(Hash)
+          result[key.to_sym] = Params.new(value).permit(*nested)
+        elsif value.is_a?(Array) && value.all?(Hash) # array of objects
+          result[key.to_sym] = value.map { |item| Params.new(item).permit(*nested) }
+        end
+      end
+
+      def wrap(value)
+        case value
+        when Hash then Params.new(value)
+        when Array then value.map { |v| wrap(v) }
+        else value
+        end
+      end
+
+      def scalar?(value) = SCALARS.any? { |type| value.is_a?(type) } || uploaded_file?(value)
+
+      def uploaded_file?(value) = defined?(Rack::Multipart::UploadedFile) && value.is_a?(Rack::Multipart::UploadedFile)
+
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) || (value.is_a?(String) && value.strip.empty?)
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash then value.transform_values { |v| deep_dup(v) }
+        when Array then value.map { |v| deep_dup(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/request.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # Rack::Request plus GemStack conveniences. Bodies are parsed lazily:
+    # nothing is read from the socket until params or #json is used.
+    class Request < Rack::Request
+      JSON_TYPE = %r{\Aapplication/(?:[\w.+-]+\+)?json\b}i
+
+      def request_id = get_header(REQUEST_ID)
+      def path_params = get_header(PATH_PARAMS) || {}
+      def route = get_header(ROUTE)
+
+      def json?
+        JSON_TYPE.match?(content_type.to_s)
+      end
+
+      # The parsed JSON body (any JSON value), or nil for an empty body.
+      # Raises BadRequest for malformed JSON or excessive nesting.
+      def json
+        return @json if defined?(@json)
+
+        raw = body&.read.to_s
+        body&.rewind if body.respond_to?(:rewind)
+        @json = raw.strip.empty? ? nil : codec.load(raw)
+      rescue ::JSON::NestingError
+        raise BadRequest.new("JSON body is nested too deeply", code: "invalid_json")
+      rescue ::JSON::ParserError, EncodingError
+        raise BadRequest.new("Request body is not valid JSON", code: "invalid_json")
+      end
+
+      # Parameters from the body: a JSON object, or form/multipart fields.
+      # Non-object JSON bodies (arrays, scalars) are available via #json.
+      def body_params
+        @body_params ||=
+          if json?
+            value = json
+            value.is_a?(Hash) ? value : {}
+          elsif form_data? || parseable_data?
+            self.POST
+          else
+            {}
+          end
+      end
+
+      # Query, then body, then path parameters (later sources win).
+      def all_params
+        query = self.GET
+        body = body_params
+        path = path_params
+        return query if body.empty? && path.empty?
+
+        query.merge(body).merge(path)
+      rescue Rack::QueryParser::ParameterTypeError, Rack::QueryParser::InvalidParameterError,
+             Rack::Multipart::MultipartPartLimitError => e
+        raise BadRequest.new(e.message, code: "invalid_parameters")
+      end
+
+      private
+
+      def codec = get_header(JSON_CODEC) || JSONCodec.default
+    end
+  end
+end

data/lib/gemstack/http/router.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    # Routes requests to controllers or Rack apps (DECISIONS D-004, D-005).
+    #
+    #   router = Router.new(prefix: "/api")
+    #   router.draw do
+    #     get "/status", to: "status#show"
+    #     resources :products do
+    #       member { post "/publish", action: :publish }
+    #       resources :reviews, only: %i[index create]
+    #     end
+    #     namespace :admin do
+    #       resources :orders, only: %i[index]
+    #     end
+    #     mount SomeRackApp, at: "/webhooks"
+    #   end
+    #
+    # Matching: fully static paths are an O(1) hash lookup; paths with
+    # :params or a trailing *glob are matched through a per-verb segment trie.
+    class Router
+      VERBS = %w[GET POST PUT PATCH DELETE OPTIONS HEAD].freeze
+
+      Route = Struct.new(:verb, :path, :controller, :action, :app, :name, :param_names, keyword_init: true) do
+        def target = app ? app.inspect : "#{controller}##{action}"
+        def static? = param_names.empty?
+      end
+
+      class Node
+        attr_accessor :route, :param, :glob
+
+        def children = @children ||= {}
+        def child(segment) = @children&.[](segment)
+      end
+
+      attr_reader :prefix, :routes
+
+      def initialize(prefix: "", resolver: nil)
+        @prefix = normalize(prefix)
+        @prefix = "" if @prefix == "/"
+        @resolver = resolver || method(:resolve_controller)
+        @routes = []
+        @static = {}
+        @trees = {}
+        @endpoints = {}
+        @mutex = Mutex.new
+      end
+
+      def draw(&)
+        Mapper.new(self).instance_exec(&)
+        self
+      end
+
+      # Low-level registration; the DSL (Mapper) is built on top of it.
+      def add(verb, path, controller: nil, action: nil, app: nil, name: nil)
+        verb = verb.to_s.upcase
+        raise ArgumentError, "unknown HTTP verb #{verb}" unless VERBS.include?(verb)
+        raise ArgumentError, "route needs a controller#action or an app" unless app || (controller && action)
+
+        full = join(@prefix, path)
+        segments = split(full)
+        params = segments.filter_map { |s| s[1..] if s.start_with?(":", "*") }
+        route = Route.new(verb: verb, path: full, controller: controller&.to_s, action: action&.to_s, app: app,
+                          name: name, param_names: params.freeze)
+        insert(route, segments)
+        @routes << route
+        route
+      end
+
+      # Returns [route, params] or nil.
+      def recognize(verb, path)
+        path = normalize(path)
+        if (route = @static[verb]&.[](path))
+          return [route, {}]
+        end
+
+        tree = @trees[verb] or return
+        segments = split(path).map { |s| Rack::Utils.unescape_path(s) }
+        values = []
+        route = walk(tree, segments, 0, values)
+        route && [route, route.param_names.zip(values).to_h]
+      end
+
+      def allowed_verbs(path)
+        VERBS.select { |verb| recognize(verb, path) }
+      end
+
+      # Rack interface.
+      def call(env)
+        verb = env[Rack::REQUEST_METHOD]
+        path = env[Rack::PATH_INFO]
+        route, params = recognize(verb, path)
+        route, params = recognize("GET", path) if route.nil? && verb == "HEAD"
+        return no_route(verb, path) unless route
+
+        env[PATH_PARAMS] = params
+        env[ROUTE] = route
+        status, headers, body = dispatch(route, env)
+        if verb == "HEAD" && route.verb != "HEAD"
+          body.close if body.respond_to?(:close)
+          body = []
+        end
+        [status, headers, body]
+      end
+
+      private
+
+      def dispatch(route, env)
+        return route.app.call(env) if route.app
+
+        controller = @endpoints[route.controller] || @mutex.synchronize do
+          @endpoints[route.controller] ||= @resolver.call(route.controller)
+        end
+        controller.dispatch(route.action, env)
+      end
+
+      def resolve_controller(name)
+        const = "#{Inflector.camelize(name)}Controller"
+        Object.const_get(const)
+      rescue NameError => e
+        raise unless e.name.to_s == const.split("::").last || e.message.include?(const)
+
+        raise ConfigurationError, "route points to #{const}, which is not defined"
+      end
+
+      def no_route(verb, path)
+        allowed = allowed_verbs(path)
+        raise NotFound.new("No route matches #{verb} #{path}", code: "route_not_found") if allowed.empty?
+
+        allowed << "HEAD" if allowed.include?("GET") && !allowed.include?("HEAD")
+        raise MethodNotAllowed.new("#{verb} is not allowed for #{path}", headers: { "allow" => allowed.join(", ") })
+      end
+
+      def insert(route, segments)
+        return insert_static(route) if route.static?
+
+        glob = segments.last.start_with?("*") ? segments.pop : nil
+        if segments.any? { |segment| segment.start_with?("*") }
+          raise ArgumentError, "glob must be the last segment in #{route.path}"
+        end
+
+        node = segments.inject(@trees[route.verb] ||= Node.new) do |current, segment|
+          segment.start_with?(":") ? (current.param ||= Node.new) : (current.children[segment] ||= Node.new)
+        end
+        slot = glob ? :glob : :route
+        duplicate!(route) if node.public_send(slot)
+        node.public_send(:"#{slot}=", route)
+      end
+
+      def insert_static(route)
+        static = (@static[route.verb] ||= {})
+        duplicate!(route) if static.key?(route.path)
+        static[route.path] = route
+      end
+
+      def duplicate!(route)
+        raise ArgumentError, "duplicate route #{route.verb} #{route.path}"
+      end
+
+      # Depth-first: static segments beat params, params beat globs.
+      # A glob matches one or more remaining segments.
+      def walk(node, segments, index, values)
+        return node.route if index == segments.size
+
+        segment = segments[index]
+        if (child = node.child(segment)) && (found = walk(child, segments, index + 1, values))
+          return found
+        end
+
+        if node.param
+          values.push(segment)
+          found = walk(node.param, segments, index + 1, values)
+          return found if found
+
+          values.pop
+        end
+
+        finish_glob(node, segments, index, values) if node.glob
+      end
+
+      def finish_glob(node, segments, index, values)
+        values.push(segments[index..].join("/"))
+        node.glob
+      end
+
+      def join(prefix, path)
+        path = normalize(path)
+        return prefix.empty? ? "/" : prefix if path == "/"
+
+        prefix + path
+      end
+
+      def normalize(path)
+        path = path.to_s
+        path = "/#{path}" unless path.start_with?("/")
+        path = path.squeeze("/")
+        path.length > 1 ? path.chomp("/") : path
+      end
+
+      def split(path) = path.split("/").reject(&:empty?)
+
+      # The routing DSL. Kept separate from Router so the DSL's method names
+      # (get, delete, resources, ...) never collide with the router's own API.
+      class Mapper
+        RESOURCE_ACTIONS = {
+          index: [["GET", ""]],
+          create: [["POST", ""]],
+          show: [["GET", "/:id"]],
+          update: [["PATCH", "/:id"], ["PUT", "/:id"]],
+          destroy: [["DELETE", "/:id"]]
+        }.freeze
+
+        def initialize(router, path: "", module_name: nil, controller: nil)
+          @router = router
+          @path = path
+          @module = module_name
+          @controller = controller
+        end
+
+        VERBS.each do |verb|
+          define_method(verb.downcase) do |path, to: nil, action: nil, controller: nil, as: nil|
+            map(verb, path, to: to, action: action, controller: controller, as: as)
+          end
+        end
+
+        def scope(path = "", module: nil, &)
+          Mapper.new(@router, path: @path + clean(path), module_name: join_module(binding.local_variable_get(:module)),
+                              controller: @controller).instance_exec(&)
+        end
+
+        def namespace(name, &)
+          scope("/#{name}", module: name.to_s, &)
+        end
+
+        # A conventional REST resource: index, create, show, update, destroy.
+        def resources(name, only: nil, except: nil, path: nil, controller: nil, &block)
+          actions = RESOURCE_ACTIONS.keys
+          actions &= Array(only).map(&:to_sym) if only
+          actions -= Array(except).map(&:to_sym) if except
+          base = @path + (path ? clean(path) : "/#{Inflector.dasherize(name)}")
+          controller_name = qualify(controller || name.to_s)
+
+          actions.each do |action|
+            RESOURCE_ACTIONS.fetch(action).each do |verb, suffix|
+              @router.add(verb, base + suffix, controller: controller_name, action: action,
+                                               name: route_name(name, action))
+            end
+          end
+          return unless block
+
+          ResourceMapper.new(@router, base: base, controller: controller_name, module_name: @module,
+                                      param: "#{Inflector.singularize(name.to_s)}_id").instance_exec(&block)
+        end
+
+        # Mounts any Rack app under a path. The app receives the full path.
+        def mount(app, at:)
+          base = @path + clean(at)
+          VERBS.each do |verb|
+            @router.add(verb, base, app: app)
+            @router.add(verb, "#{base}/*path", app: app)
+          end
+        end
+
+        private
+
+        def map(verb, path, to:, action:, controller:, as:)
+          return @router.add(verb, @path + clean(path), app: to, name: as) if to.respond_to?(:call)
+
+          if to
+            controller, action = to.to_s.split("#", 2)
+            raise ArgumentError, "to: must look like \"controller#action\", got #{to.inspect}" unless action
+          end
+          controller = controller ? qualify(controller.to_s) : @controller
+          raise ArgumentError, "route #{verb} #{path} needs to: \"controller#action\"" unless controller && action
+
+          @router.add(verb, @path + clean(path), controller: controller, action: action, name: as)
+        end
+
+        def qualify(controller) = @module && !controller.include?("/") ? "#{@module}/#{controller}" : controller
+        def join_module(mod) = [@module, mod].compact.join("/").then { |m| m.empty? ? nil : m }
+        def clean(path) = path.to_s.empty? || path == "/" ? "" : "/#{path.to_s.delete_prefix("/").chomp("/")}"
+
+        def route_name(name, action)
+          singular = Inflector.singularize(name.to_s)
+          { index: name.to_s, show: singular }[action]&.then { |n| [@module&.tr("/", "_"), n].compact.join("_") }
+        end
+      end
+
+      # DSL inside a `resources` block: member/collection routes and nesting.
+      class ResourceMapper < Mapper
+        def initialize(router, base:, controller:, module_name:, param:)
+          super(router, path: base, module_name: module_name, controller: controller)
+          @base = base
+          @param = param
+        end
+
+        # Routes on a single record: /products/:id/<path>
+        def member(&)
+          Mapper.new(@router, path: "#{@base}/:id", module_name: @module, controller: @controller).instance_exec(&)
+        end
+
+        # Routes on the collection: /products/<path>
+        def collection(&)
+          Mapper.new(@router, path: @base, module_name: @module, controller: @controller).instance_exec(&)
+        end
+
+        # Nested resources: /products/:product_id/reviews
+        def resources(name, **, &)
+          Mapper.new(@router, path: "#{@base}/:#{@param}", module_name: @module).resources(name, **, &)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rack"
+require "gemstack/core"
+require "gemstack/schema"
+
+module GemStack
+  # The API layer: a Rack application composed of a middleware stack and a
+  # router that dispatches to controllers.
+  module HTTP
+    # Rack env keys owned by GemStack.
+    REQUEST_ID = "gemstack.request_id"
+    PATH_PARAMS = "gemstack.path_params"
+    JSON_CODEC = "gemstack.json"
+    ROUTE = "gemstack.route"
+    CONFIG = "gemstack.http_config"
+  end
+end
+
+require_relative "http/json_codec"
+require_relative "http/error_renderer"
+require_relative "http/error_page"
+require_relative "http/middleware_stack"
+require_relative "http/middleware/request_id"
+require_relative "http/middleware/request_logger"
+require_relative "http/middleware/compression"
+require_relative "http/middleware/error_handler"
+require_relative "http/middleware/security_headers"
+require_relative "http/middleware/cors"
+require_relative "http/middleware/body_limit"
+require_relative "http/middleware/health_check"
+require_relative "http/middleware/etags"
+require_relative "http/config"
+require_relative "http/request"
+require_relative "http/params"
+require_relative "http/router"
+require_relative "http/page"
+require_relative "http/controller"
+require_relative "http/app"
+
+GemStack::Config.namespace(:http, GemStack::HTTP::Config)