rubst_api 0.1.0

data/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported versions
+
+RubstAPI is currently in initial development. Security fixes are applied to the
+latest released version.
+
+| Version | Supported |
+| --- | --- |
+| 0.1.x | Yes |
+| Earlier versions | No |
+
+## Reporting a vulnerability
+
+Please do not report suspected vulnerabilities in a public GitHub issue.
+
+Use GitHub's private vulnerability reporting for
+[joryleech/RubstApi](https://github.com/joryleech/RubstApi/security/advisories/new).
+Include:
+
+- the affected RubstAPI version;
+- a minimal reproduction;
+- the expected and observed behavior;
+- the potential impact;
+- any known mitigation.
+
+Please allow a reasonable period for investigation and remediation before
+public disclosure. Receipt will be acknowledged through GitHub when private
+vulnerability reporting is available for the repository.

data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Third-Party Notices
+
+RubstAPI is an independent Ruby implementation inspired by the design and
+developer experience of the Python FastAPI project.
+
+## FastAPI
+
+- Project: FastAPI
+- Source: <https://github.com/fastapi/fastapi>
+- Copyright: Copyright (c) 2018 Sebastián Ramírez
+- License: MIT
+- Included license: [LICENSES/FASTAPI-MIT.txt](LICENSES/FASTAPI-MIT.txt)
+
+The original FastAPI MIT license and copyright notice are reproduced verbatim
+and distributed with this project. FastAPI is not bundled as a runtime
+dependency. Inclusion of its license does not imply endorsement, affiliation,
+or trademark permission.
+
+RubstAPI's own source code is distributed under the separate project license
+in [LICENSE](LICENSE).

data/exe/rubst_api

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "rubst_api"
+
+options = { host: "127.0.0.1", port: 8000 }
+command = ARGV.shift || "help"
+OptionParser.new do |parser|
+  parser.on("--host HOST") { |value| options[:host] = value }
+  parser.on("--port PORT", Integer) { |value| options[:port] = value }
+end.parse!
+
+if %w[run dev].include?(command)
+  file = ARGV.shift || "app.rb"
+  require File.expand_path(file)
+  app = Object.const_defined?(:APP) ? APP : Object.const_defined?(:App) ? App : nil
+  abort "Define APP = RubstApi::App.new in #{file}" unless app
+  begin
+    require "rack"
+    require "rackup"
+    handler = Rackup::Handler.get("webrick")
+    handler.run(app, Host: options[:host], Port: options[:port])
+  rescue LoadError
+    abort "The server command requires the optional rack and rackup gems."
+  end
+else
+  puts "Usage: rubst_api [dev|run] [app.rb] [--host HOST] [--port PORT]"
+end

data/lib/rubst_api/app.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module RubstApi
+  class App < APIRouter
+    attr_reader :title, :description, :version, :openapi_url, :docs_url, :redoc_url,
+                :openapi_version, :servers, :openapi_tags, :dependency_overrides
+
+    def initialize(title: "RubstAPI", description: nil, version: "0.1.0", openapi_url: "/openapi.json",
+                   docs_url: "/docs", redoc_url: "/redoc", openapi_version: "3.1.0",
+                   servers: [], openapi_tags: [], dependencies: [], **router_options)
+      super(dependencies:, **router_options)
+      @title, @description, @version = title, description, version
+      @openapi_url, @docs_url, @redoc_url, @openapi_version = openapi_url, docs_url, redoc_url, openapi_version
+      @servers, @openapi_tags, @dependency_overrides = servers, openapi_tags, {}
+      @exception_handlers, @user_middleware, @startup_handlers, @shutdown_handlers = {}, [], [], []
+      @mounts = []
+      @openapi_schema = nil
+      install_default_handlers
+    end
+
+    def call(env)
+      build_stack.call(env)
+    rescue StandardError => error
+      handle_exception(error)
+    end
+
+    def route_request(env)
+      request_path, request_method = env.fetch("PATH_INFO", "/"), env.fetch("REQUEST_METHOD", "GET").upcase
+      if (mounted = @mounts.find { |prefix, _| request_path == prefix || request_path.start_with?("#{prefix}/") })
+        prefix, application = mounted
+        child_path = request_path.delete_prefix(prefix)
+        child_env = env.merge("SCRIPT_NAME" => "#{env["SCRIPT_NAME"]}#{prefix}",
+                              "PATH_INFO" => child_path.empty? ? "/" : child_path)
+        return application.call(child_env)
+      end
+      return JSONResponse.new(openapi).finish if openapi_url && request_path == openapi_url
+      return HTMLResponse.new(swagger_html).finish if docs_url && request_path == docs_url
+      return HTMLResponse.new(redoc_html).finish if redoc_url && request_path == redoc_url
+
+      path_matches = routes.filter_map { |route| [route, route.match(request_path)] if route.match(request_path) }
+      raise HTTPException.new(status_code: 404) if path_matches.empty?
+      route, captures = path_matches.find { |candidate, _| candidate.allowed?(request_method) }
+      unless route
+        allowed = path_matches.flat_map { |candidate, _| candidate.methods }.uniq.join(", ")
+        raise HTTPException.new(status_code: 405, headers: { "Allow" => allowed })
+      end
+      request = Request.new(env, path_params: captures)
+      execute_route(route, request)
+    end
+
+    def execute_route(route, request)
+      resolver = DependencyResolver.new(request, dependency_overrides)
+      values = {}
+      errors = []
+      body_parameter_count = route.params.values.count { |value| value.is_a?(Param) && value.location == :body }
+      route.dependencies.each { |dependency| resolver.resolve(dependency) }
+      route.params.each do |name, declaration|
+        if declaration.is_a?(Dependency)
+          values[name] = resolver.resolve(declaration)
+          next
+        end
+        raw = extract_parameter(name, declaration, request, body_parameter_count:)
+        if raw.equal?(UNDEFINED)
+          if declaration.required?
+            errors << { type: "missing", loc: [declaration.location, declaration.name_for(name)], msg: "Field required", input: nil }
+          else
+            values[name] = declaration.default.equal?(UNDEFINED) ? nil : declaration.default
+          end
+          next
+        end
+        begin
+          values[name] = Validator.coerce(raw, declaration.type, declaration.constraints)
+        rescue ValidationError => error
+          errors.concat(error.errors.map { |item| item.merge(loc: [declaration.location, declaration.name_for(name)] + Array(item[:loc])) })
+        end
+      end
+      raise RequestValidationError.new(errors, body: request.body) unless errors.empty?
+      inject_special_arguments(route.endpoint, values, request)
+      result = invoke(route.endpoint, values)
+      response = prepare_response(result, route)
+      if (injected = values[:response])
+        response.status_code = injected.status_code if injected.status_code != 200
+        injected.headers.each { |key, value| response.headers[key] = value }
+      end
+      resolver.close
+      finished = response.finish
+      values[:background_tasks]&.call
+      finished
+    ensure
+      resolver&.close
+    end
+
+    def openapi
+      @openapi_schema ||= OpenAPI.generate(self)
+    end
+
+    def add_api_route(...)
+      @openapi_schema = nil
+      super
+    end
+
+    def include_router(...)
+      @openapi_schema = nil
+      super
+    end
+
+    def add_middleware(middleware_class, **options)
+      @user_middleware << [middleware_class, options]
+      @middleware_stack = nil
+      self
+    end
+
+    def exception_handler(exception_class, callable = nil, &block)
+      @exception_handlers[exception_class] = callable || block
+    end
+
+    def on_event(event, callable = nil, &block)
+      handlers = event.to_sym == :startup ? @startup_handlers : @shutdown_handlers
+      handlers << (callable || block)
+    end
+
+    def startup = @startup_handlers.each(&:call)
+    def shutdown = @shutdown_handlers.reverse_each(&:call)
+
+    def mount(path, application, name: nil)
+      prefix = path.end_with?("/") ? path.chomp("/") : path
+      @mounts << [prefix, application]
+      application
+    end
+
+    private
+
+    def build_stack
+      @middleware_stack ||= @user_middleware.reverse.inject(method(:route_request)) do |inner, (klass, options)|
+        klass.new(inner, **options)
+      end
+    end
+
+    def install_default_handlers
+      exception_handler(HTTPException) do |error|
+        JSONResponse.new({ detail: error.detail }, status_code: error.status_code, headers: error.headers)
+      end
+      exception_handler(RequestValidationError) do |error|
+        JSONResponse.new({ detail: error.errors }, status_code: 422)
+      end
+      exception_handler(ResponseValidationError) do |error|
+        JSONResponse.new({ detail: error.errors }, status_code: 500)
+      end
+    end
+
+    def handle_exception(error)
+      pair = @exception_handlers.find { |klass, _| error.is_a?(klass) }
+      raise error unless pair
+      response = pair.last.call(error)
+      response = JSONResponse.new(response) unless response.is_a?(Response)
+      response.finish
+    end
+
+    def extract_parameter(name, param, request, body_parameter_count: 0)
+      key = param.name_for(name)
+      value = case param.location
+              when :path then request.path_params[key]
+              when :query then request.query_params[key]
+              when :header then request.headers[key.tr("_", "-")]
+              when :cookie then request.cookies[key]
+              when :body then extract_body(name, param, request, embedded: body_parameter_count > 1)
+              when :form then form_data(request)[key]
+              when :file then multipart_data(request)[key]
+              end
+      value.nil? ? UNDEFINED : value
+    end
+
+    def extract_body(name, param, request, embedded: false)
+      parsed = request.json
+      return parsed unless embedded && parsed.is_a?(Hash)
+      parsed.fetch(param.name_for(name)) { parsed.fetch(param.name_for(name).to_sym, UNDEFINED) }
+    rescue JSON::ParserError
+      raise RequestValidationError.new([{ type: "json_invalid", loc: [:body], msg: "JSON decode error", input: request.body }])
+    end
+
+    def route_like_model?(type) = type.is_a?(Class) && type <= Model
+
+    def form_data(request)
+      @form_cache ||= {}
+      @form_cache[request.object_id] ||= URI.decode_www_form(request.body).to_h
+    end
+
+    def multipart_data(request)
+      boundary = request.headers["content-type"].to_s[/boundary=(?:"([^"]+)"|([^;]+))/, 1] ||
+                 request.headers["content-type"].to_s[/boundary=(?:"([^"]+)"|([^;]+))/, 2]
+      return {} unless boundary
+      request.body.split("--#{boundary}").each_with_object({}) do |part, output|
+        head, content = part.split("\r\n\r\n", 2)
+        next unless head && content
+        name = head[/name="([^"]+)"/, 1]
+        next unless name
+        content = content.sub(/\r\n\z/, "")
+        filename = head[/filename="([^"]*)"/, 1]
+        output[name] = filename ? UploadFile.new(filename:, io: StringIO.new(content),
+                                                 content_type: head[/Content-Type:\s*([^\r\n]+)/i, 1] || "application/octet-stream") : content
+      end
+    end
+
+    def inject_special_arguments(callable, values, request)
+      names = callable.parameters.map(&:last)
+      values[:request] = request if names.include?(:request) && !values.key?(:request)
+      values[:response] = Response.new if names.include?(:response) && !values.key?(:response)
+      values[:background_tasks] = BackgroundTasks.new if names.include?(:background_tasks) && !values.key?(:background_tasks)
+      values[:websocket] = WebSocket.new(request.env, path_params: request.path_params) if names.include?(:websocket) && !values.key?(:websocket)
+    end
+
+    def invoke(callable, values)
+      parameters = callable.parameters
+      if parameters.any? { |kind, _| %i[key keyreq keyrest].include?(kind) }
+        callable.call(**values)
+      elsif parameters.empty?
+        callable.call
+      else
+        callable.call(*parameters.map { |_, name| values[name] })
+      end
+    end
+
+    def prepare_response(result, route)
+      return result if result.is_a?(Response)
+      if route.response_model
+        begin
+          result = Validator.coerce(result, route.response_model, {})
+        rescue ValidationError => error
+          raise ResponseValidationError, error.errors
+        end
+      end
+      JSONResponse.new(result, status_code: route.status_code)
+    end
+
+    def swagger_html
+      <<~HTML
+        <!doctype html><html><head><title>#{title} - Swagger UI</title>
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css"></head>
+        <body><div id="swagger-ui"></div><script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+        <script>SwaggerUIBundle({url: #{openapi_url.to_json}, dom_id: '#swagger-ui', deepLinking: true})</script></body></html>
+      HTML
+    end
+
+    def redoc_html
+      <<~HTML
+        <!doctype html><html><head><title>#{title} - ReDoc</title></head>
+        <body><redoc spec-url="#{openapi_url}"></redoc>
+        <script src="https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js"></script></body></html>
+      HTML
+    end
+  end
+
+end

data/lib/rubst_api/background_tasks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubstApi
+  class BackgroundTask
+    def initialize(callable = nil, *args, **kwargs, &block)
+      @callable, @args, @kwargs = callable || block, args, kwargs
+    end
+    def call = @callable.call(*@args, **@kwargs)
+  end
+
+  class BackgroundTasks
+    def initialize = @tasks = []
+    def add_task(callable = nil, *args, **kwargs, &block)
+      @tasks << BackgroundTask.new(callable, *args, **kwargs, &block)
+    end
+    def call = @tasks.each(&:call)
+  end
+end

data/lib/rubst_api/dependencies.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubstApi
+  class Dependency
+    attr_reader :callable, :use_cache, :dependencies
+    def initialize(callable, use_cache: true, dependencies: {})
+      raise ArgumentError, "dependency must be callable" unless callable.respond_to?(:call)
+      @callable, @use_cache, @dependencies = callable, use_cache, dependencies
+    end
+  end
+
+  class DependencyResolver
+    def initialize(request, overrides = {})
+      @request, @overrides, @cache, @cleanups = request, overrides, {}, []
+    end
+
+    def resolve(dependency)
+      callable = @overrides.fetch(dependency.callable, dependency.callable)
+      return @cache[callable] if dependency.use_cache && @cache.key?(callable)
+      signature = callable.respond_to?(:parameters) ? callable : callable.method(:call)
+      arguments = dependency.dependencies.to_h { |name, child| [name, resolve(child)] }
+      signature.parameters.each do |kind, name|
+        next unless %i[key keyreq].include?(kind)
+        arguments[name] = @request if name == :request
+      end
+      value = callable.call(**arguments)
+      value = consume_generator(value) if value.is_a?(Enumerator)
+      @cache[callable] = value if dependency.use_cache
+      value
+    end
+
+    def close
+      return if @closed
+      @closed = true
+      @cleanups.reverse_each(&:call)
+    end
+
+    private
+
+    def consume_generator(generator)
+      value = generator.next
+      @cleanups << proc { generator.next rescue StopIteration }
+      value
+    end
+  end
+
+  class SecurityDependency < Dependency
+    attr_reader :scopes
+    def initialize(callable, scopes: [], **options)
+      super(callable, **options)
+      @scopes = scopes
+    end
+  end
+
+  def self.Depends(...) = RubstApi.Depends(...)
+  def self.Security(...) = RubstApi.Security(...)
+end

data/lib/rubst_api/errors.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RubstApi
+  class HTTPException < StandardError
+    attr_reader :status_code, :detail, :headers
+
+    def initialize(status_code:, detail: nil, headers: {})
+      @status_code = status_code
+      @detail = detail || default_detail(status_code)
+      @headers = headers
+      super(@detail.to_s)
+    end
+
+    private
+
+    def default_detail(code)
+      { 400 => "Bad Request", 401 => "Unauthorized", 403 => "Forbidden",
+        404 => "Not Found", 405 => "Method Not Allowed", 409 => "Conflict",
+        422 => "Unprocessable Entity", 500 => "Internal Server Error" }[code] || "HTTP Error"
+    end
+  end
+
+  class WebSocketException < StandardError
+    attr_reader :code, :reason
+    def initialize(code:, reason: nil)
+      @code, @reason = code, reason
+      super(reason)
+    end
+  end
+
+  class RequestValidationError < StandardError
+    attr_reader :errors, :body
+    def initialize(errors, body: nil)
+      @errors, @body = errors, body
+      super("Request validation failed")
+    end
+  end
+
+  class ResponseValidationError < StandardError
+    attr_reader :errors
+    def initialize(errors)
+      @errors = errors
+      super("Response validation failed")
+    end
+  end
+end

data/lib/rubst_api/http.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+require "uri"
+
+module RubstApi
+  class Headers
+    include Enumerable
+    def initialize(values = {})
+      @values = values.to_h { |key, value| [key.to_s.downcase.tr("_", "-"), value.to_s] }
+    end
+    def [](name) = @values[name.to_s.downcase.tr("_", "-")]
+    def []=(name, value)
+      @values[name.to_s.downcase.tr("_", "-")] = value.to_s
+    end
+    def each(&) = @values.each(&)
+    def to_h = @values.dup
+  end
+
+  class Request
+    attr_reader :env, :path_params, :state
+    def initialize(env, path_params: {})
+      @env, @path_params, @state = env, path_params, {}
+    end
+    def method = env.fetch("REQUEST_METHOD", "GET").upcase
+    def path = env.fetch("PATH_INFO", "/")
+    def query_string = env.fetch("QUERY_STRING", "")
+    def query_params = @query_params ||= URI.decode_www_form(query_string).each_with_object({}) { |(k, v), h| h[k] = h.key?(k) ? Array(h[k]) << v : v }
+    def headers
+      @headers ||= Headers.new(env.filter_map do |key, value|
+        next unless key.start_with?("HTTP_") || %w[CONTENT_TYPE CONTENT_LENGTH].include?(key)
+        [key.sub(/\AHTTP_/, "").downcase, value]
+      end.to_h)
+    end
+    def cookies
+      @cookies ||= (headers["cookie"] || "").split(/;\s*/).filter_map { |pair| pair.split("=", 2) if pair.include?("=") }.to_h
+    end
+    def body
+      @body ||= begin
+        io = env["rack.input"] || StringIO.new
+        value = io.read
+        io.rewind if io.respond_to?(:rewind)
+        value
+      end
+    end
+    def json = body.empty? ? nil : JSON.parse(body)
+    def content_type = headers["content-type"]&.split(";")&.first
+    def client = [env["REMOTE_ADDR"], env["REMOTE_PORT"]]
+    def url = "#{env["rack.url_scheme"] || "http"}://#{env["HTTP_HOST"] || "localhost"}#{path}#{query_string.empty? ? "" : "?#{query_string}"}"
+  end
+end

data/lib/rubst_api/middleware.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubstApi
+  module Middleware
+    class CORSMiddleware
+      def initialize(app, allow_origins: [], allow_methods: ["GET"], allow_headers: [], allow_credentials: false,
+                     expose_headers: [], max_age: 600, allow_origin_regex: nil)
+        @app, @origins, @methods, @headers = app, allow_origins, allow_methods, allow_headers
+        @credentials, @expose, @max_age, @origin_regex = allow_credentials, expose_headers, max_age, allow_origin_regex
+      end
+      def call(env)
+        origin = env["HTTP_ORIGIN"]
+        return @app.call(env) unless origin
+        allowed = @origins.include?("*") || @origins.include?(origin) || (@origin_regex && Regexp.new(@origin_regex).match?(origin))
+        return @app.call(env) unless allowed
+        cors = {
+          "access-control-allow-origin" => @credentials ? origin : (@origins.include?("*") ? "*" : origin),
+          "vary" => "Origin"
+        }
+        if env["REQUEST_METHOD"] == "OPTIONS" && env["HTTP_ACCESS_CONTROL_REQUEST_METHOD"]
+          cors.merge!("access-control-allow-methods" => @methods.join(", "),
+                      "access-control-allow-headers" => @headers.join(", "),
+                      "access-control-max-age" => @max_age.to_s)
+          cors["access-control-allow-credentials"] = "true" if @credentials
+          [200, cors.merge("content-length" => "2"), ["OK"]]
+        else
+          status, headers, body = @app.call(env)
+          headers.merge!(cors)
+          headers["access-control-expose-headers"] = @expose.join(", ") unless @expose.empty?
+          headers["access-control-allow-credentials"] = "true" if @credentials
+          [status, headers, body]
+        end
+      end
+    end
+
+    class GZipMiddleware
+      def initialize(app, minimum_size: 500, compresslevel: 9)
+        @app, @minimum_size, @level = app, minimum_size, compresslevel
+      end
+      def call(env)
+        status, headers, body = @app.call(env)
+        content = body.respond_to?(:each) ? body.to_a.join : body.to_s
+        return [status, headers, [content]] unless env["HTTP_ACCEPT_ENCODING"].to_s.include?("gzip") && content.bytesize >= @minimum_size
+        require "zlib"
+        require "stringio"
+        io = StringIO.new
+        writer = Zlib::GzipWriter.new(io, @level)
+        writer.write(content)
+        writer.close
+        headers = headers.merge("content-encoding" => "gzip", "content-length" => io.string.bytesize.to_s, "vary" => "Accept-Encoding")
+        [status, headers, [io.string]]
+      end
+    end
+
+    class TrustedHostMiddleware
+      def initialize(app, allowed_hosts: ["*"], www_redirect: true)
+        @app, @hosts, @redirect = app, allowed_hosts, www_redirect
+      end
+      def call(env)
+        host = env["HTTP_HOST"].to_s.split(":").first
+        allowed = @hosts.include?("*") || @hosts.any? { |pattern| pattern.start_with?("*.") ? host.end_with?(pattern.delete_prefix("*")) : host == pattern }
+        return PlainTextResponse.new("Invalid host header", status_code: 400).finish unless allowed
+        @app.call(env)
+      end
+    end
+
+    class HTTPSRedirectMiddleware
+      def initialize(app) = @app = app
+      def call(env)
+        return @app.call(env) if env["rack.url_scheme"] == "https"
+        host, path, query = env["HTTP_HOST"], env["PATH_INFO"], env["QUERY_STRING"]
+        RedirectResponse.new("https://#{host}#{path}#{query.to_s.empty? ? "" : "?#{query}"}").finish
+      end
+    end
+  end
+end