ruby-object-framework 1.0.0

data/lib/object_framework/http/presentation.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module HTTP
+    Response = Data.define(:status, :headers, :body)
+
+    class JSONPresenter
+      def call(value)
+        Response.new(status: 200, headers: { "Content-Type" => "application/json" }, body: JSON.generate(json_value(value)))
+      end
+
+      private
+
+      def json_value(value)
+        case value
+        when Data then json_value(value.to_h)
+        when Hash then value.to_h { |key, item| [key, json_value(item)] }
+        when Array then value.map { |item| json_value(item) }
+        else value
+        end
+      end
+    end
+
+    class ProblemPresenter
+      STATUSES = {
+        bad_request: 400, invalid_input: 422, unauthenticated: 401, forbidden: 403,
+        not_found: 404, conflict: 409, duplicate: 409, transaction_conflict: 409,
+        rate_limited: 429, capacity: 503, unavailable: 503, deadline: 503,
+        cancelled: 503, unimplemented: 501, internal: 500
+      }.freeze
+
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      def call(exception, context:)
+        description = @registry.resolve(exception)
+        status = exception.is_a?(Error) ? exception.class::STATUS : STATUSES.fetch(description.category)
+        problem = description.details.transform_keys(&:to_s).merge(
+          "type" => "urn:object-framework:error:#{description.code}", "title" => description.title,
+          "status" => status, "instance" => "urn:uuid:#{context.operation_id}",
+          "code" => description.code, "operation_id" => context.operation_id
+        )
+        headers = { "Content-Type" => "application/problem+json" }
+        headers.merge!(exception.headers) if exception.is_a?(Error)
+        Response.new(status:, headers:, body: JSON.generate(problem))
+      end
+
+      def self.fallback(context:)
+        body = '{"type":"urn:object-framework:error:internal_error","title":"Internal server error","status":500,"code":"internal_error","operation_id":"' + context.operation_id + '","instance":"urn:uuid:' + context.operation_id + '"}'
+        Response.new(status: 500, headers: { "Content-Type" => "application/problem+json" }, body:)
+      end
+    end
+  end
+end

data/lib/object_framework/http/protocol.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+
+module ObjectFramework
+  module HTTP
+    class Error < StandardError
+      attr_reader :headers
+      def initialize(message = nil, headers: {})
+        super(message || self.class::TITLE)
+        @headers = headers
+      end
+    end
+
+    ERROR_TYPES = {
+      BadRequest: [400, "Bad request"], MethodNotAllowed: [405, "Method not allowed"],
+      RequestTimeout: [408, "Request timeout"], PayloadTooLarge: [413, "Payload too large"],
+      URITooLong: [414, "Request target too long"], UnsupportedMediaType: [415, "Unsupported media type"],
+      ExpectationFailed: [417, "Expectation failed"], HeadersTooLarge: [431, "Request headers too large"],
+      NotImplemented: [501, "Transfer coding not implemented"], VersionNotSupported: [505, "HTTP version not supported"]
+    }.freeze
+    ERROR_TYPES.each do |name, (status, title)|
+      type = Class.new(Error)
+      type.const_set(:STATUS, status)
+      type.const_set(:TITLE, title.freeze)
+      const_set(name, type)
+    end
+
+    def self.register_errors(registry)
+      ERROR_TYPES.each_key do |name|
+        type = const_get(name)
+        code = name.to_s.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        registry.register(type, category: :bad_request, code: "http_#{code}", title: type::TITLE)
+      end
+    end
+
+    Head = Data.define(:method, :path, :query, :headers, :length, :chunked, :keep_alive)
+    Input = Data.define(:params, :query, :body)
+
+    class Parser
+      TOKEN = /\A[!#$%&'*+.^_`|~0-9A-Za-z-]+\z/
+      attr_reader :line_limit, :header_limit, :body_limit
+
+      def initialize(line_limit: 8 * 1024, header_limit: 32 * 1024, body_limit: 1024 * 1024)
+        @line_limit, @header_limit, @body_limit = line_limit, header_limit, body_limit
+        raise ConfigurationError, "HTTP limits must be positive integers" unless [line_limit, header_limit, body_limit].all? { |limit| limit.is_a?(Integer) && limit.positive? }
+      end
+
+      def parse_head(raw)
+        raise BadRequest unless raw.end_with?("\r\n\r\n")
+        lines = raw.b.split("\r\n", -1)
+        request_line = lines.shift
+        raise URITooLong if request_line.bytesize > line_limit
+        raise HeadersTooLarge if raw.bytesize - request_line.bytesize - 2 > header_limit
+        method, target, version = request_line.split(" ", -1)
+        raise BadRequest unless method && TOKEN.match?(method) && target && version && request_line == "#{method} #{target} #{version}"
+        raise VersionNotSupported unless version == "HTTP/1.1"
+        raise BadRequest if target.match?(/[\x00-\x20\x7f-\xff#]/n)
+        headers = {}
+        lines[0...-2].each do |line|
+          name, value = parse_field(line)
+          if headers.key?(name)
+            raise BadRequest if %w[host content-length transfer-encoding].include?(name)
+            headers[name] = "#{headers[name]}, #{value}"
+          else
+            headers[name] = value
+          end
+        end
+        host = headers["host"]
+        raise BadRequest unless host && /\A(?:\[[0-9a-fA-F:.]+\]|[A-Za-z0-9.-]+)(?::\d{1,5})?\z/.match?(host)
+        raise BadRequest if headers.key?("content-length") && headers.key?("transfer-encoding")
+        length = 0
+        if headers.key?("content-length")
+          raise BadRequest unless /\A[0-9]+\z/.match?(headers["content-length"])
+          length = Integer(headers["content-length"], 10)
+          raise PayloadTooLarge if length > body_limit
+        end
+        encoding = headers["transfer-encoding"]&.downcase
+        if encoding && encoding != "chunked"
+          raise BadRequest if encoding.split(",").map(&:strip).count("chunked") != 1 || !encoding.end_with?("chunked")
+          raise NotImplemented
+        end
+        expect = headers["expect"]
+        raise ExpectationFailed if expect && expect.downcase != "100-continue"
+        path, query = parse_target(method, target)
+        Head.new(method:, path:, query:, headers: Values.detach(headers), length:, chunked: encoding == "chunked",
+                 keep_alive: !headers.fetch("connection", "").downcase.split(",").map(&:strip).include?("close"))
+      end
+
+      def parse_field(line)
+        name, value = line.split(":", 2)
+        raise BadRequest unless name && TOKEN.match?(name) && value && !value.match?(/[\x00-\x08\x0a-\x1f\x7f]/)
+        [name.downcase, value.strip]
+      end
+
+      def read_body(reader, head, deadline:)
+        return reader.read_exact(head.length, deadline:) unless head.chunked
+        body, trailer_size = +"".b, 0
+        loop do
+          line = reader.read_line(limit: line_limit, deadline:)
+          size, extension = line.split(";", 2)
+          raise BadRequest unless /\A[0-9a-fA-F]+\z/.match?(size)
+          if extension && !/\A(?:[!#$%&'*+.^_`|~0-9A-Za-z-]+(?:=(?:[!#$%&'*+.^_`|~0-9A-Za-z-]+|"(?:[^"\\\r\n]|\\[\x20-\x7e])*"))?)(?:;[!#$%&'*+.^_`|~0-9A-Za-z-]+(?:=(?:[!#$%&'*+.^_`|~0-9A-Za-z-]+|"(?:[^"\\\r\n]|\\[\x20-\x7e])*"))?)*\z/.match?(extension)
+            raise BadRequest
+          end
+          count = Integer(size, 16)
+          raise PayloadTooLarge if body.bytesize + count > body_limit
+          if count.zero?
+            loop do
+              trailer = reader.read_line(limit: header_limit, deadline:)
+              trailer_size += trailer.bytesize + 2
+              raise HeadersTooLarge if trailer_size > header_limit
+              break if trailer.empty?
+              name, = parse_field(trailer)
+              raise BadRequest if %w[content-length transfer-encoding host connection content-type authorization].include?(name)
+            end
+            return body
+          end
+          body << reader.read_exact(count, deadline:)
+          raise BadRequest unless reader.read_exact(2, deadline:) == "\r\n"
+        end
+      rescue EOFError
+        raise BadRequest
+      end
+
+      private
+
+      def parse_target(method, target)
+        return ["*", ""] if method == "OPTIONS" && target == "*"
+        uri = URI.parse(target)
+        if uri.absolute?
+          raise BadRequest unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo
+          path = uri.path.empty? ? "/" : uri.path
+        else
+          raise BadRequest unless target.start_with?("/") && !target.start_with?("//")
+          path = uri.path
+        end
+        raise BadRequest if target.match?(/%(?![0-9a-fA-F]{2})/)
+        [path, uri.query || ""]
+      rescue URI::InvalidURIError
+        raise BadRequest
+      end
+    end
+
+    class JSONDecoder
+      def call(body, content_type: nil)
+        return {} if body.empty?
+        raise UnsupportedMediaType unless content_type&.split(";", 2)&.first&.strip&.downcase == "application/json"
+        value = JSON.parse(body.dup.force_encoding(Encoding::UTF_8))
+        raise InvalidInput, "Expected a JSON object" unless value.is_a?(Hash)
+        value
+      rescue JSON::ParserError, EncodingError
+        raise BadRequest
+      end
+    end
+
+    Parameter = Data.define(:name, :source, :key, :type, :required)
+
+    class Parameters
+      def initialize(&declaration)
+        @fields = []
+        instance_eval(&declaration) if declaration
+        @fields.freeze
+        freeze
+      end
+
+      def field(name, source: :body, key: name, type: String, required: true)
+        raise ConfigurationError, "Invalid parameter source" unless %i[path query body].include?(source)
+        raise ConfigurationError, "Duplicate parameter" if @fields.any? { |field| field.name == name }
+        @fields << Parameter.new(name:, source:, key:, type:, required:)
+      end
+
+      def normalize(input)
+        @fields.each_with_object({}) do |field, result|
+          source = input.public_send(field.source == :path ? :params : field.source)
+          key = field.source == :path ? field.key.to_sym : field.key.to_s
+          unless source.key?(key)
+            raise InvalidInput, "Missing required parameter" if field.required
+            next
+          end
+          value = source.fetch(key)
+          if field.source != :body
+            value = Integer(value, 10) if field.type == Integer
+            value = Float(value) if field.type == Float
+          end
+          raise InvalidInput, "Invalid parameter type" unless value.is_a?(field.type)
+          result[field.name] = value
+        end
+      rescue ArgumentError, TypeError
+        raise InvalidInput, "Invalid parameter value"
+      end
+    end
+
+    class Controller
+      def initialize(application:, operation:, parameters: Parameters.new)
+        @application, @operation, @parameters = application, operation, parameters
+      end
+
+      def call(input, context:)
+        @application.invoke(@operation, context:, **@parameters.normalize(input))
+      end
+
+      def validate!
+        @application.validate_operation!(@operation)
+      end
+    end
+  end
+end

data/lib/object_framework/http/router.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module HTTP
+    Route = Data.define(:method, :pattern, :controller, :expression, :names)
+    Match = Data.define(:controller, :params, :allow)
+
+    class Router
+      def initialize
+        @controllers, @routes = {}, []
+      end
+
+      def controller(name, instance)
+        mutable!
+        raise ConfigurationError, "Duplicate controller: #{name}" if @controllers.key?(name)
+        @controllers[name] = instance
+        self
+      end
+
+      def route(method, pattern, controller:)
+        mutable!
+        method = method.to_s.upcase
+        raise ConfigurationError, "Invalid route" unless Parser::TOKEN.match?(method) && pattern.start_with?("/") && !pattern.include?("?")
+        names = []
+        expression = pattern.split("/", -1).map do |part|
+          if part.start_with?(":")
+            name = Persistence::Query.identifier(part.delete_prefix(":"))
+            raise ConfigurationError, "Duplicate route parameter" if names.include?(name)
+            names << name
+            "([^/]+)"
+          else
+            Regexp.escape(part)
+          end
+        end.join("/")
+        raise ConfigurationError, "Duplicate route" if @routes.any? { |route| route.method == method && route.expression.source == "\\A#{expression}\\z" }
+        @routes << Route.new(method:, pattern: pattern.dup.freeze, controller:, expression: /\A#{expression}\z/, names: names.freeze)
+        self
+      end
+
+      def validate!
+        @routes.each do |route|
+          controller = @controllers.fetch(route.controller) { raise ConfigurationError, "Unknown route controller" }
+          raise ConfigurationError, "Controller must implement call" unless controller.respond_to?(:call)
+          controller.validate! if controller.respond_to?(:validate!)
+        end
+        @controllers.freeze
+        @routes.sort_by! { |route| route.names.size } unless @routes.frozen?
+        @routes.freeze
+        self
+      end
+
+      def resolve(method, path)
+        matching = path == "*" ? @routes : @routes.select { |route| route.expression.match?(path) }
+        raise NotFound, "Route not found" if matching.empty?
+        allow = (matching.map(&:method) + ["OPTIONS"]).uniq
+        allow << "HEAD" if allow.include?("GET")
+        allow.sort!
+        return Match.new(controller: nil, params: {}, allow:) if method == "OPTIONS"
+        route = matching.find { |candidate| candidate.method == method }
+        route ||= matching.find { |candidate| candidate.method == "GET" } if method == "HEAD"
+        raise MethodNotAllowed.new(headers: { "Allow" => allow.join(", ") }) unless route
+        captures = route.expression.match(path).captures
+        params = route.names.zip(captures).to_h.transform_values do |value|
+          decoded = URI.decode_www_form_component(value.gsub("+", "%2B"))
+          raise BadRequest unless decoded.valid_encoding? && !decoded.match?(/[\x00-\x1f\x7f]/)
+          decoded
+        end
+        Match.new(controller: @controllers.fetch(route.controller), params:, allow:)
+      rescue ArgumentError
+        raise BadRequest
+      end
+
+      private
+
+      def mutable!
+        raise ConfigurationError, "Router is finalized" if @routes.frozen?
+      end
+    end
+  end
+end

data/lib/object_framework/http/server.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "socket"
+require "openssl"
+
+module ObjectFramework
+  module HTTP
+    Connection = Struct.new(:io, :buffer, :fiber, :context, keyword_init: true) do
+      def close
+        io.close unless io.closed?
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+
+    class Server
+      attr_reader :port, :name
+
+      def initialize(application:, router:, host: "127.0.0.1", port: 0, name: :http,
+                     parser: Parser.new, presenter: JSONPresenter.new, problem_presenter: nil,
+                     max_requests: 128, max_connections: 1024, header_timeout: 10,
+                     body_timeout: 30, execution_timeout: 30, idle_timeout: 30,
+                     write_timeout: 30, shutdown_timeout: 5, tls_context: nil,
+                     writer_factory: ->(reader) { Writer.new(reader:) })
+        @application, @router, @host, @port, @name = application, router, host, port, name
+        @parser, @presenter, @problem_presenter = parser, presenter, problem_presenter
+        @max_requests, @max_connections = max_requests, max_connections
+        @header_timeout, @body_timeout, @execution_timeout = header_timeout, body_timeout, execution_timeout
+        @idle_timeout, @write_timeout, @shutdown_timeout = idle_timeout, write_timeout, shutdown_timeout
+        @tls_context, @writer_factory = tls_context, writer_factory
+        @mutex, @workers, @admitted_count = Mutex.new, {}, 0
+        @completed = Queue.new
+        @connections, @waiting = {}.compare_by_identity, {}.compare_by_identity
+      end
+
+      def requires; []; end
+
+      def configure(application)
+        HTTP.register_errors(application.errors)
+        @problem_presenter ||= ProblemPresenter.new(registry: application.errors)
+      end
+
+      def validate!
+        @router.validate!
+        unless [@max_requests, @max_connections].all? { |value| value.is_a?(Integer) && value.positive? }
+          raise ConfigurationError, "Admission limits must be positive integers"
+        end
+        unless [@header_timeout, @body_timeout, @execution_timeout, @idle_timeout, @write_timeout, @shutdown_timeout].all? { |value| value.is_a?(Numeric) && value.positive? }
+          raise ConfigurationError, "HTTP timeouts must be positive"
+        end
+        if @tls_context
+          raise ConfigurationError, "TLS requires an application certificate and private key" unless @tls_context.cert && @tls_context.key
+          @tls_context.setup
+        end
+      end
+
+      def start
+        @listener = TCPServer.new(@host, @port)
+        @port = @listener.local_address.ip_port
+        @wake_reader, @wake_writer = IO.pipe
+        @running = true
+        @dispatcher = Thread.new { dispatch }
+        self
+      rescue Exception
+        @listener&.close
+        @wake_reader&.close
+        @wake_writer&.close
+        raise
+      end
+
+      def active_count; @mutex.synchronize { @workers.size }; end
+      def admitted_count; @mutex.synchronize { @admitted_count }; end
+      def connection_count; @connections.size; end
+
+      def stop
+        return unless @dispatcher
+        @running = false
+        wake
+        @dispatcher.join
+        workers = @mutex.synchronize do
+          @workers.each_value { |context, connection| context.cancellation.cancel; connection.close }
+          @workers.keys
+        end
+        deadline = Timing.now + @shutdown_timeout
+        workers.each { |thread| thread.join([deadline - Timing.now, 0].max) }
+        @wake_reader.close
+        @wake_writer.close
+        @dispatcher = nil
+      end
+
+      private
+
+      def dispatch
+        while @running
+          complete_requests
+          now = Timing.now
+          @waiting.dup.each { |connection, (_, deadline)| resume_connection(connection) if deadline <= now }
+          reads = [@listener, @wake_reader] + @waiting.select { |_, (mode, _)| mode == :read }.keys.map(&:io)
+          writes = @waiting.select { |_, (mode, _)| mode == :write }.keys.map(&:io)
+          deadline = @waiting.values.map(&:last).min
+          timeout = deadline ? [[deadline - Timing.now, 0].max, 0.5].min : 0.5
+          readable, writable = IO.select(reads, writes, nil, timeout)
+          next unless readable
+          drain_wake if readable.delete(@wake_reader)
+          accept_connections if readable.delete(@listener)
+          ready = readable + writable
+          @waiting.keys.each { |connection| resume_connection(connection) if ready.include?(connection.io) }
+        end
+      ensure
+        @connections.each_key(&:close)
+        @connections.clear
+        @waiting.clear
+        @listener.close unless @listener.closed?
+      end
+
+      def accept_connections
+        loop do
+          socket = @listener.accept_nonblock(exception: false)
+          break if socket == :wait_readable
+          if @connections.size >= @max_connections
+            socket.close
+            next
+          end
+          io = @tls_context ? OpenSSL::SSL::SSLSocket.new(socket, @tls_context) : socket
+          io.sync_close = true if @tls_context
+          connection = Connection.new(io:, buffer: +"".b, context: ExecutionContext.new)
+          @connections[connection] = true
+          connection.fiber = connection_fiber(connection)
+          resume_connection(connection)
+        end
+      end
+
+      def connection_fiber(connection)
+        Fiber.new do
+          reader = Reader.new(io: connection.io, buffer: connection.buffer,
+            waiter: ->(mode, deadline) { Fiber.yield([mode, deadline]) })
+          begin
+            handshake(connection, reader) if @tls_context
+            idle = false
+            loop do
+              connection.context = ExecutionContext.new
+              head = reader.read_head(@parser, header_timeout: @header_timeout, idle_timeout: @idle_timeout, idle:)
+              raise CapacityExceeded if Fiber.yield([:request, head]) == :rejected
+              idle = true
+            end
+          rescue EOFError
+            nil
+          rescue StandardError => error
+            @application.reporter.report(error, context: connection.context)
+            response = problem(error, context: connection.context)
+            Writer.new(reader:).call(response, keep_alive: false, deadline: Timing.now + @write_timeout)
+          end
+          nil
+        end
+      end
+
+      def handshake(connection, reader)
+        deadline = Timing.now + @header_timeout
+        loop do
+          raise RequestTimeout if Timing.now >= deadline
+          result = connection.io.accept_nonblock(exception: false)
+          break unless %i[wait_readable wait_writable].include?(result)
+          reader.waiter.call(result == :wait_readable ? :read : :write, deadline)
+        end
+      end
+
+      def resume_connection(connection, value = nil)
+        @waiting.delete(connection)
+        result = connection.fiber.resume(value)
+        if result && result.first == :request
+          resume_connection(connection, :rejected) unless admit(connection, result.last)
+        elsif result
+          @waiting[connection] = result
+        else
+          forget(connection)
+        end
+      rescue StandardError => error
+        @application.reporter.report(error, context: connection.context)
+        forget(connection)
+      end
+
+      def admit(connection, head)
+        @mutex.synchronize do
+          return false if @workers.size >= @max_requests
+          @admitted_count += 1
+          thread = Thread.new { serve(connection, head) }
+          @workers[thread] = [connection.context, connection]
+        end
+        true
+      end
+
+      def serve(connection, head)
+        context = connection.context
+        reader = Reader.new(io: connection.io, buffer: connection.buffer)
+        writer = nil
+        keep_alive, body_read = false, false
+        begin
+          writer = @writer_factory.call(reader)
+          reader.write("HTTP/1.1 100 Continue\r\n\r\n", deadline: Timing.now + @write_timeout) if head.headers["expect"]
+          body = @parser.read_body(reader, head, deadline: Timing.now + @body_timeout)
+          body_read = true
+          context.cancellation.deadline = Timing.now + @execution_timeout
+          context.cancellation.check!
+          match = @router.resolve(head.method, head.path)
+          if head.method == "OPTIONS"
+            response = Response.new(status: 204, headers: { "Allow" => match.allow.join(", ") }, body: "")
+          else
+            input = Input.new(params: match.params, query: query_parameters(head.query),
+              body: JSONDecoder.new.call(body, content_type: head.headers["content-type"]))
+            result = match.controller.call(input, context:)
+            context.cancellation.check!
+            response = @presenter.call(result)
+          end
+          writer.call(response, head: head.method == "HEAD", keep_alive: head.keep_alive, deadline: Timing.now + @write_timeout)
+          keep_alive = head.keep_alive
+        rescue StandardError => error
+          @application.reporter.report(error, context:)
+          writer ||= Writer.new(reader:)
+          unless writer.started
+            begin
+              writer.call(problem(error, context:), head: head.method == "HEAD", keep_alive: body_read && head.keep_alive, deadline: Timing.now + @write_timeout)
+              keep_alive = body_read && head.keep_alive
+            rescue StandardError => secondary
+              @application.reporter.report(secondary, context:, secondary: true)
+              keep_alive = false
+            end
+          end
+        ensure
+          @mutex.synchronize { @workers.delete(Thread.current) }
+          reuse = keep_alive && @running
+          connection.close unless reuse
+          @completed << [reuse ? :reuse : :close, connection]
+          wake
+        end
+      end
+
+      def query_parameters(query)
+        URI.decode_www_form(query).each_with_object({}) do |(key, value), result|
+          result[key] = result.key?(key) ? Array(result[key]) + [value] : value
+        end
+      rescue ArgumentError
+        raise BadRequest
+      end
+
+      def problem(error, context:)
+        @problem_presenter.call(error, context:)
+      rescue StandardError => secondary
+        @application.reporter.report(secondary, context:, secondary: true)
+        ProblemPresenter.fallback(context:)
+      end
+
+      def complete_requests
+        until @completed.empty?
+          action, connection = @completed.pop
+          action == :reuse && @running ? resume_connection(connection) : forget(connection)
+        end
+      end
+
+      def forget(connection)
+        @waiting.delete(connection)
+        @connections.delete(connection)
+        connection.close
+      end
+
+      def wake
+        @wake_writer&.write_nonblock(".", exception: false)
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      def drain_wake
+        loop do
+          result = @wake_reader.read_nonblock(1024, exception: false)
+          break if result == :wait_readable || result.nil?
+        end
+      end
+    end
+  end
+end