gemstack-http 0.1.0

data/lib/gemstack/http/error_renderer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GemStack
+  module HTTP
+    # Turns an exception into the standard JSON error envelope (DECISIONS D-015):
+    #
+    #   {"error": {"code": "not_found", "message": "Not Found", "request_id": "..."},
+    #    "errors": {"name": ["is required"]}}
+    #
+    # Any exception responding to #status and #code is rendered with that
+    # status. Everything else is a 500 whose message is hidden unless
+    # show_exceptions is on.
+    module ErrorRenderer
+      BACKTRACE_LINES = 30
+
+      module_function
+
+      def render(exception, request_id: nil, show_exceptions: false)
+        original = exception
+        exception = ErrorMapping.translate(exception)
+        status, code, message = describe(exception)
+        body = { error: { code: code, message: message, request_id: request_id }.compact }
+        details = exception.respond_to?(:details) ? exception.details : nil
+        body[:errors] = details if details && !details.empty?
+        body[:exception] = debug_info(original) if show_exceptions && status >= 500
+
+        headers = { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }
+        headers.merge!(exception.headers) if exception.respond_to?(:headers) && exception.headers
+        [status, headers, [::JSON.generate(body)]]
+      end
+
+      def describe(exception)
+        if exception.respond_to?(:status) && exception.respond_to?(:code) && exception.status.is_a?(Integer)
+          status = exception.status
+          exposed = exception.respond_to?(:expose_message?) ? exception.expose_message? : status < 500
+          message = exposed ? exception.message : Rack::Utils::HTTP_STATUS_CODES.fetch(status, "Error")
+          [status, exception.code.to_s, message]
+        else
+          [500, "internal_error", "Internal Server Error"]
+        end
+      end
+
+      # 404 => "not_found"; unknown statuses => "error"
+      def code_for(status)
+        Rack::Utils::SYMBOL_TO_STATUS_CODE.key(status)&.name || "error"
+      end
+
+      def debug_info(exception)
+        {
+          class: exception.class.name,
+          message: exception.message,
+          backtrace: Array(exception.backtrace).first(BACKTRACE_LINES)
+        }
+      end
+
+      def json_error(status, code, message, request_id: nil, headers: {})
+        render(GemStack::Error.new(message, status: status, code: code, headers: headers), request_id: request_id)
+      end
+    end
+  end
+end

data/lib/gemstack/http/json_codec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "date"
+
+module GemStack
+  module HTTP
+    # JSON encoding/decoding behind a two-method interface (dump / load), so the
+    # implementation can be swapped with `config.http.json = :oj | codec`.
+    module JSONCodec
+      # How non-JSON-native Ruby objects are encoded. Objects must opt in by
+      # defining #as_json (or #to_h); anything else raises instead of silently
+      # leaking #inspect/#to_s output into API responses.
+      def self.coerce(object)
+        case object
+        when Symbol then object.name
+        when Time, DateTime then object.iso8601(3)
+        when Date then object.iso8601
+        when Set then object.to_a
+        else
+          if object.respond_to?(:as_json) then object.as_json
+          elsif defined?(BigDecimal) && object.is_a?(BigDecimal) then object.to_s("F")
+          elsif object.respond_to?(:to_h) then object.to_h
+          else
+            raise TypeError, "#{object.class} is not JSON serializable; define #as_json or use a serializer"
+          end
+        end
+      end
+
+      # Default codec, backed by the json gem's JSON::Coder: native types are
+      # encoded in C and the coerce block only runs for other objects.
+      class Stdlib
+        def initialize(max_nesting: 64)
+          @max_nesting = max_nesting
+          @coder = ::JSON::Coder.new { |object| JSONCodec.coerce(object) }
+        end
+
+        def dump(object) = @coder.dump(object)
+
+        def load(source)
+          ::JSON.parse(source, max_nesting: @max_nesting)
+        end
+      end
+
+      class Oj
+        def initialize(max_nesting: 64)
+          require "oj"
+          @max_nesting = max_nesting
+        end
+
+        # Serializer output is already JSON-native, so try Oj's C strict mode
+        # first; only values with Time, BigDecimal, models... take the slower
+        # normalising path.
+        def dump(object)
+          ::Oj.dump(object, mode: :strict)
+        rescue TypeError, EncodingError
+          ::Oj.dump(normalize(object), mode: :strict)
+        end
+
+        def load(source)
+          # Oj has no depth limit option in strict mode; enforce it with the
+          # stdlib parser's semantics by checking depth after parsing.
+          result = ::Oj.load(source, mode: :strict)
+          raise ::JSON::NestingError, "nesting too deep" if depth(result) > @max_nesting
+
+          result
+        rescue ::Oj::ParseError, EncodingError => e
+          raise ::JSON::ParserError, e.message
+        end
+
+        private
+
+        def normalize(object)
+          case object
+          when Hash then object.to_h { |k, v| [k.is_a?(Symbol) ? k.name : k, normalize(v)] }
+          when Array then object.map { |v| normalize(v) }
+          when String, Integer, Float, true, false, nil then object
+          else normalize(JSONCodec.coerce(object))
+          end
+        end
+
+        # Same definition as the json gem: `{}` and `[]` have depth 1.
+        def depth(object)
+          case object
+          when Hash then 1 + (object.each_value.map { |v| depth(v) }.max || 0)
+          when Array then 1 + (object.map { |v| depth(v) }.max || 0)
+          else 0
+          end
+        end
+      end
+
+      BUILT_IN = { json: Stdlib, oj: Oj }.freeze
+
+      def self.resolve(setting, max_nesting: 64)
+        case setting
+        when Symbol, String
+          BUILT_IN.fetch(setting.to_sym) { raise ConfigurationError, "unknown JSON codec #{setting.inspect}" }
+                  .new(max_nesting: max_nesting)
+        else
+          unless setting.respond_to?(:dump) && setting.respond_to?(:load)
+            raise ConfigurationError, "a JSON codec must respond to dump and load"
+          end
+
+          setting
+        end
+      end
+
+      def self.default
+        @default ||= Stdlib.new
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/body_limit.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # Rejects request bodies larger than config.http.max_body_size.
+      # Declared sizes (Content-Length) are rejected up front; bodies of
+      # unknown size (chunked) are counted while being read.
+      class BodyLimit
+        # Wraps rack.input and raises PayloadTooLarge once the limit is passed.
+        class LimitedInput
+          def initialize(input, limit)
+            @input = input
+            @limit = limit
+            @read = 0
+          end
+
+          def read(length = nil, buffer = nil)
+            data = @input.read(length, buffer)
+            count(data)
+          end
+
+          def gets
+            count(@input.gets)
+          end
+
+          def each
+            while (line = gets)
+              yield line
+            end
+          end
+
+          def rewind
+            @read = 0
+            @input.rewind
+          end
+
+          def close = @input.close
+
+          private
+
+          def count(data)
+            @read += data.bytesize if data
+            raise PayloadTooLarge if @read > @limit
+
+            data
+          end
+        end
+
+        def initialize(app, config)
+          @app = app
+          @limit = config.max_body_size
+        end
+
+        def call(env)
+          return @app.call(env) unless @limit
+
+          length = env["CONTENT_LENGTH"]
+          if length && !length.empty?
+            raise PayloadTooLarge if length.to_i > @limit
+          elsif (input = env[Rack::RACK_INPUT])
+            env[Rack::RACK_INPUT] = LimitedInput.new(input, @limit)
+          end
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/compression.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module GemStack
+  module HTTP
+    module Middleware
+      # Response compression with content negotiation (DECISIONS D-033).
+      #
+      # - Negotiates Accept-Encoding (with q-values): Brotli when the `brotli`
+      #   gem is available, otherwise gzip.
+      # - Compresses only compressible types (JSON, text, JS, XML, SVG) with a
+      #   known body at least `min_size` bytes long.
+      # - Never touches: HEAD, 1xx/204/304, responses that already have a
+      #   Content-Encoding, `Cache-Control: no-transform`, Server-Sent Events,
+      #   or streamed bodies of unknown length.
+      # - Always sends `Vary: Accept-Encoding` for compressible types, and
+      #   weakens strong ETags of compressed responses.
+      class Compression
+        COMPRESSIBLE = %r{
+          \A\s*(?:
+            text/(?!event-stream)                                        # any text/*, except Server-Sent Events
+          | application/(?:json|javascript|xml|[\w.+-]+\+(?:json|xml))  # JSON, JS, XML and +json/+xml types
+          | image/svg\+xml
+          )
+        }xi
+
+        def self.brotli_available?
+          return @brotli_available if defined?(@brotli_available)
+
+          @brotli_available = begin
+            require "brotli"
+            true
+          rescue LoadError
+            false
+          end
+        end
+
+        def initialize(app, config)
+          @app = app
+          settings = config.compression
+          @enabled = settings.enabled
+          @min_size = settings.min_size
+          @gzip_level = settings.gzip_level
+          @brotli_quality = settings.brotli_quality
+          @encodings = settings.encodings.map(&:to_s).select do |encoding|
+            encoding == "gzip" || (encoding == "br" && self.class.brotli_available?)
+          end
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+          return [status, headers, body] unless @enabled && eligible?(env, status, headers)
+
+          vary(headers)
+          encoding = negotiate(env["HTTP_ACCEPT_ENCODING"])
+          return [status, headers, body] unless encoding && body.respond_to?(:to_ary)
+
+          content = read(body)
+          return [status, headers, [content]] if content.bytesize < @min_size
+
+          compressed = encode(encoding, content)
+          headers["content-encoding"] = encoding
+          headers["content-length"] = compressed.bytesize.to_s
+          headers["etag"] = "W/#{headers["etag"]}" if headers["etag"]&.start_with?('"')
+          [status, headers, [compressed]]
+        end
+
+        # "gzip;q=0.5, br" → "br". Server preference order breaks ties; q=0 refuses.
+        def negotiate(header)
+          return nil if header.nil? || header.empty? || @encodings.empty?
+
+          accepted = header.split(",").to_h do |part|
+            name, *params = part.strip.split(";")
+            q = params.find { |p| p.strip.start_with?("q=") }&.then { |p| p.strip[2..].to_f } || 1.0
+            [name.to_s.strip.downcase, q]
+          end
+          wildcard = accepted.fetch("*", 0.0)
+          ranked = @encodings.map { |encoding| [encoding, accepted.fetch(encoding, wildcard)] }
+          best = ranked.select { |_, q| q.positive? }.max_by { |encoding, q| [q, -@encodings.index(encoding)] }
+          best&.first
+        end
+
+        private
+
+        def eligible?(env, status, headers)
+          return false if env[Rack::REQUEST_METHOD] == "HEAD"
+          return false if status < 200 || status == 204 || status == 304
+          return false if headers["content-encoding"]
+          return false if headers["cache-control"]&.include?("no-transform")
+
+          COMPRESSIBLE.match?(headers["content-type"].to_s)
+        end
+
+        def vary(headers)
+          current = headers["vary"]
+          return if current&.split(",")&.any? { |v| %w[accept-encoding *].include?(v.strip.downcase) }
+
+          headers["vary"] = current ? "#{current}, Accept-Encoding" : "Accept-Encoding"
+        end
+
+        def read(body)
+          content = String.new(encoding: Encoding::BINARY)
+          body.each { |part| content << part }
+          content
+        ensure
+          body.close if body.respond_to?(:close)
+        end
+
+        def encode(encoding, content)
+          case encoding
+          when "br" then Brotli.deflate(content, quality: @brotli_quality)
+          else gzip(content)
+          end
+        end
+
+        def gzip(content)
+          io = StringIO.new(String.new(encoding: Encoding::BINARY))
+          writer = Zlib::GzipWriter.new(io, @gzip_level)
+          writer.write(content)
+          writer.finish
+          io.string
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/cors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # Cross-Origin Resource Sharing, driven by config.http.cors. It does
+      # nothing until origins are configured — same-origin GemStack apps
+      # (the default architecture) never need CORS.
+      class Cors
+        def initialize(app, config)
+          @app = app
+          cors = config.cors
+          @origins = Array(cors.origins)
+          @methods = cors.methods.map(&:upcase).join(", ")
+          @headers = cors.headers.join(", ")
+          @expose = cors.expose_headers.join(", ")
+          @credentials = cors.credentials
+          @max_age = cors.max_age.to_s
+          return unless @credentials && @origins.include?("*")
+
+          raise ConfigurationError, "CORS: credentials cannot be combined with the \"*\" origin"
+        end
+
+        def call(env)
+          origin = env["HTTP_ORIGIN"]
+          return @app.call(env) if @origins.empty? || origin.nil?
+
+          allowed = allowed?(origin)
+          return preflight(allowed ? origin : nil) if preflight?(env)
+
+          status, headers, body = @app.call(env)
+          vary(headers)
+          apply(headers, origin) if allowed
+          [status, headers, body]
+        end
+
+        private
+
+        def preflight?(env)
+          env[Rack::REQUEST_METHOD] == "OPTIONS" && env["HTTP_ACCESS_CONTROL_REQUEST_METHOD"]
+        end
+
+        def preflight(origin)
+          headers = { "vary" => "Origin" }
+          if origin
+            apply(headers, origin)
+            headers["access-control-allow-methods"] = @methods
+            headers["access-control-allow-headers"] = @headers
+            headers["access-control-max-age"] = @max_age
+          end
+          [204, headers, []]
+        end
+
+        def apply(headers, origin)
+          headers["access-control-allow-origin"] = @origins.include?("*") ? "*" : origin
+          headers["access-control-allow-credentials"] = "true" if @credentials
+          headers["access-control-expose-headers"] = @expose unless @expose.empty?
+        end
+
+        def vary(headers)
+          current = headers["vary"]
+          headers["vary"] = current ? "#{current}, Origin" : "Origin" unless current&.include?("Origin")
+        end
+
+        def allowed?(origin)
+          @origins.any? do |allowed|
+            case allowed
+            when "*" then true
+            when Regexp then allowed.match?(origin)
+            else allowed == origin
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/error_handler.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # The exception boundary. Everything raised below it becomes a JSON
+      # error response; server errors are logged with their backtrace.
+      # Internals (class, message, backtrace) reach the client only when
+      # config.http.show_exceptions is on (development/test by default).
+      class ErrorHandler
+        def initialize(app, config)
+          @app = app
+          @show_exceptions = config.show_exceptions
+        end
+
+        def call(env)
+          @app.call(env)
+        rescue StandardError, ScriptError => e # ScriptError: syntax errors while reloading in development
+          response = ErrorRenderer.render(e, request_id: env[REQUEST_ID], show_exceptions: @show_exceptions)
+          return response if response[0] < 500
+
+          report(e, env)
+          # Development: a browser opening the URL gets a readable page (DECISIONS D-055).
+          @show_exceptions && ErrorPage.browser?(env) ? ErrorPage.render(e, env, request_id: env[REQUEST_ID]) : response
+        end
+
+        private
+
+        def report(exception, env)
+          GemStack.logger.error(
+            "#{exception.class}: #{exception.message}",
+            id: env[REQUEST_ID],
+            backtrace: Array(exception.backtrace).first(ErrorRenderer::BACKTRACE_LINES)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/etags.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # ETags and conditional GET, using Rack's own middleware: Rack::ETag adds
+      # a weak ETag (SHA-256 of the body) to buffered 200/201 responses that
+      # don't set one, and Rack::ConditionalGet answers matching
+      # If-None-Match / If-Modified-Since requests with 304 and no body.
+      # Controllers can set ETags themselves (see Controller#stale?).
+      #
+      # Responses without Cache-Control get Rack's
+      # "max-age=0, private, must-revalidate": clients may keep a copy but
+      # must revalidate it — the safe default for API data.
+      class ETags
+        def initialize(app, config)
+          @app = config.etags ? Rack::ConditionalGet.new(Rack::ETag.new(app)) : app
+        end
+
+        def call(env) = @app.call(env)
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/health_check.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # Answers GET/HEAD config.http.health_path with 200 {"status":"ok"}
+      # without touching the router (DECISIONS D-016).
+      class HealthCheck
+        BODY = '{"status":"ok"}'
+
+        def initialize(app, config)
+          @app = app
+          @path = config.health_path
+        end
+
+        def call(env)
+          return @app.call(env) unless @path && env[Rack::PATH_INFO] == @path
+
+          method = env[Rack::REQUEST_METHOD]
+          return @app.call(env) unless %w[GET HEAD].include?(method)
+
+          headers = { "content-type" => "application/json", "cache-control" => "no-store" }
+          [200, headers, method == "HEAD" ? [] : [BODY]]
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/request_id.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GemStack
+  module HTTP
+    module Middleware
+      # Assigns every request an id (env["gemstack.request_id"]), echoed in the
+      # X-Request-Id response header and included in logs and error bodies.
+      # An incoming X-Request-Id (e.g. from a load balancer) is reused when
+      # trusted and well-formed.
+      class RequestId
+        VALID = /\A[A-Za-z0-9\-_.:]{1,128}\z/
+
+        def initialize(app, config)
+          @app = app
+          @trust = config.trust_request_id
+        end
+
+        def call(env)
+          incoming = env["HTTP_X_REQUEST_ID"]
+          id = @trust && incoming&.match?(VALID) ? incoming : SecureRandom.uuid
+          env[REQUEST_ID] = id
+          status, headers, body = @app.call(env)
+          headers["x-request-id"] = id
+          [status, headers, body]
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/request_logger.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # One structured log line per request, written when the response body is
+      # closed so streamed responses are timed correctly:
+      #
+      #   INFO  GET /api/products status=200 ms=1.84 id=5f0c...
+      #
+      # Query strings are not logged (they often carry tokens).
+      class RequestLogger
+        def initialize(app, logger: nil)
+          @app = app
+          @logger = logger
+        end
+
+        def call(env)
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          status, headers, body = @app.call(env)
+          body = Rack::BodyProxy.new(body) { log(env, status, started) }
+          [status, headers, body]
+        end
+
+        private
+
+        def log(env, status, started)
+          logger = @logger || GemStack.logger
+          return unless logger.info?
+
+          ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(2)
+          severity = status >= 500 ? :error : :info
+          logger.public_send(severity, "#{env[Rack::REQUEST_METHOD]} #{env[Rack::PATH_INFO]}",
+                             status: status, ms: ms, id: env[REQUEST_ID])
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/http/middleware/security_headers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GemStack
+  module HTTP
+    module Middleware
+      # Adds config.http.security_headers to responses that don't already set
+      # them, plus Strict-Transport-Security on HTTPS requests when
+      # config.http.hsts is set (production by default).
+      class SecurityHeaders
+        def initialize(app, config)
+          @app = app
+          @headers = config.security_headers.transform_keys { |key| key.to_s.downcase }.freeze
+          @hsts = config.hsts
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+          @headers.each { |key, value| headers[key] = value unless headers.key?(key) }
+          headers["strict-transport-security"] ||= @hsts if @hsts && https?(env)
+          [status, headers, body]
+        end
+
+        private
+
+        def https?(env)
+          env[Rack::RACK_URL_SCHEME] == "https" || env["HTTP_X_FORWARDED_PROTO"]&.start_with?("https")
+        end
+      end
+    end
+  end
+end