openapi_kit 0.1.0.pre.1

data/lib/openapi_kit/codec/float.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/codec/contract"
+
+module OpenAPIKit
+  module Codec
+    module Float
+      extend T::Sig
+      extend T::Generic
+      extend Contract
+
+      Value = type_template { { fixed: ::Float } }
+
+      sig { override.params(value: OpenAPIKit::Wire).returns(::Float) }
+      def self.from_wire(value)
+        return value.to_f if value.is_a?(::Numeric)
+
+        if value.is_a?(::String)
+          begin
+            return Kernel.Float(value)
+          rescue ArgumentError, TypeError
+            raise DecodeError.new("expected a number, got #{value.inspect}")
+          end
+        end
+
+        raise DecodeError.new("expected a number, got #{value.inspect}")
+      end
+
+      sig { override.params(value: ::Float).returns(OpenAPIKit::Wire) }
+      def self.to_wire(value) = value
+    end
+  end
+end

data/lib/openapi_kit/codec/integer.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/codec/contract"
+
+module OpenAPIKit
+  module Codec
+    module Integer
+      extend T::Sig
+      extend T::Generic
+      extend Contract
+
+      Value = type_template { { fixed: ::Integer } }
+
+      sig { override.params(value: OpenAPIKit::Wire).returns(::Integer) }
+      def self.from_wire(value)
+        return value if value.is_a?(::Integer)
+        return value.to_i if value.is_a?(::String) && value.match?(/\A[+-]?\d+\z/)
+
+        raise DecodeError.new("expected an integer, got #{value.inspect}")
+      end
+
+      sig { override.params(value: ::Integer).returns(OpenAPIKit::Wire) }
+      def self.to_wire(value) = value
+    end
+  end
+end

data/lib/openapi_kit/codec/string.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/codec/contract"
+
+module OpenAPIKit
+  module Codec
+    module String
+      extend T::Sig
+      extend T::Generic
+      extend Contract
+
+      Value = type_template { { fixed: ::String } }
+
+      sig { override.params(value: OpenAPIKit::Wire).returns(::String) }
+      def self.from_wire(value)
+        return value if value.is_a?(::String)
+
+        raise DecodeError.new("expected a string, got #{value.inspect}")
+      end
+
+      sig { override.params(value: ::String).returns(OpenAPIKit::Wire) }
+      def self.to_wire(value) = value
+    end
+  end
+end

data/lib/openapi_kit/codec/uuid.rb

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/codec/contract"
+
+module OpenAPIKit
+  module Codec
+    module Uuid
+      extend T::Sig
+      extend T::Generic
+      extend Contract
+
+      Value = type_template { { fixed: ::String } }
+
+      PATTERN = T.let(/\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/, Regexp)
+
+      sig { override.params(value: OpenAPIKit::Wire).returns(::String) }
+      def self.from_wire(value)
+        return value if value.is_a?(::String) && value.match?(PATTERN)
+
+        raise DecodeError.new("expected a UUID, got #{value.inspect}")
+      end
+
+      sig { override.params(value: ::String).returns(OpenAPIKit::Wire) }
+      def self.to_wire(value) = value
+    end
+  end
+end

data/lib/openapi_kit/codec.rb

@@ -0,0 +1,13 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/codec/contract"
+require "openapi_kit/codec/string"
+require "openapi_kit/codec/integer"
+require "openapi_kit/codec/float"
+require "openapi_kit/codec/decimal"
+require "openapi_kit/codec/boolean"
+require "openapi_kit/codec/date_time"
+require "openapi_kit/codec/date"
+require "openapi_kit/codec/uuid"
+require "openapi_kit/codec/byte"

data/lib/openapi_kit/decode.rb

@@ -0,0 +1,171 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "action_dispatch"
+
+module OpenAPIKit
+  module Decode
+    extend T::Sig
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T::Hash[String, T.untyped], key: String,
+                block: T.proc.params(value: T.untyped).returns(T.type_parameter(:T)))
+        .returns(T.type_parameter(:T))
+    end
+    def self.required(raw, key, &block)
+      raise DecodeError.new("is required", json_pointer: "/#{key}") unless raw.key?(key)
+
+      value = raw[key]
+      raise DecodeError.new("must not be null", json_pointer: "/#{key}") if value.nil?
+
+      at("/#{key}") { block.call(value) }
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T::Hash[String, T.untyped], key: String,
+                block: T.proc.params(value: T.untyped).returns(T.type_parameter(:T)))
+        .returns(T.nilable(T.type_parameter(:T)))
+    end
+    def self.required_nullable(raw, key, &block)
+      raise DecodeError.new("is required", json_pointer: "/#{key}") unless raw.key?(key)
+
+      value = raw[key]
+      return nil if value.nil?
+
+      at("/#{key}") { block.call(value) }
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T::Hash[String, T.untyped], key: String, fallback: T.type_parameter(:T),
+                block: T.proc.params(value: T.untyped).returns(T.type_parameter(:T)))
+        .returns(T.type_parameter(:T))
+    end
+    def self.defaulted(raw, key, fallback, &block)
+      value = raw[key]
+      return fallback if value.nil?
+
+      at("/#{key}") { block.call(value) }
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T::Hash[String, T.untyped], key: String,
+                block: T.proc.params(value: T.untyped).returns(T.type_parameter(:T)))
+        .returns(T.nilable(T.type_parameter(:T)))
+    end
+    def self.optional(raw, key, &block)
+      value = raw[key]
+      return nil if value.nil?
+
+      at("/#{key}") { block.call(value) }
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T::Hash[String, T.untyped], key: String,
+                block: T.proc.params(value: T.untyped).returns(T.type_parameter(:T)))
+        .returns(OpenAPIKit::Optional[T.nilable(T.type_parameter(:T))])
+    end
+    def self.optional_nullable(raw, key, &block)
+      return OpenAPIKit::ABSENT unless raw.key?(key)
+
+      value = raw[key]
+      return Present[T.nilable(T.type_parameter(:T))].new(nil) if value.nil?
+
+      Present[T.nilable(T.type_parameter(:T))].new(at("/#{key}") { block.call(value) })
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T.untyped, block: T.proc.params(item: T.untyped).returns(T.type_parameter(:T)))
+        .returns(T::Array[T.type_parameter(:T)])
+    end
+    def self.each(raw, &block)
+      array(raw).each_with_index.map { |item, index| at("/#{index}") { block.call(item) } }
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(raw: T.untyped, block: T.proc.params(item: T.untyped).returns(T.type_parameter(:T)))
+        .returns(T::Hash[String, T.type_parameter(:T)])
+    end
+    def self.values(raw, &block)
+      object(raw).to_h { |key, item| [key, at("/#{key}") { block.call(item) }] }
+    end
+
+    sig do
+      type_parameters(:T)
+        .params(prefix: String, block: T.proc.returns(T.type_parameter(:T)))
+        .returns(T.type_parameter(:T))
+    end
+    def self.at(prefix, &block)
+      block.call
+    rescue DecodeError => e
+      raise e.at(prefix)
+    rescue ArgumentError, TypeError => e
+      raise DecodeError.new(e.message, json_pointer: prefix)
+    end
+
+    sig do
+      params(names: T::Array[String],
+             lookup: T.proc.params(name: String).returns(T.untyped))
+        .returns(T::Hash[String, T.untyped])
+    end
+    def self.gather(names, &lookup)
+      names.each_with_object({}) do |name, found|
+        value = lookup.call(name)
+        found[name] = value unless value.nil?
+      end
+    end
+
+    sig { params(raw: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def self.object(raw)
+      return raw if raw.is_a?(Hash)
+
+      raise DecodeError.new("expected an object, got #{raw.class}")
+    end
+
+    sig do
+      params(value: T.untyped, name: String,
+             candidates: T::Array[T.proc.params(value: T.untyped).returns(T.untyped)])
+        .returns(T.untyped)
+    end
+    def self.first_of(value, name, candidates)
+      candidates.each do |candidate|
+        return candidate.call(value)
+      rescue DecodeError
+        next
+      end
+
+      raise DecodeError.new("did not match any member of #{name}")
+    end
+
+    sig do
+      type_parameters(:Enum)
+        .params(enum: T.all(T::Class[T.type_parameter(:Enum)], T.class_of(T::Enum)), value: T.untyped)
+        .returns(T.type_parameter(:Enum))
+    end
+    def self.enum(enum, value)
+      enum.try_deserialize(value) ||
+        raise(DecodeError.new("expected one of #{enum.values.map(&:serialize).join(", ")}, " \
+                              "got #{value.inspect}"))
+    end
+
+    sig { params(value: T.untyped).returns(::ActionDispatch::Http::UploadedFile) }
+    def self.file(value)
+      return value if value.is_a?(::ActionDispatch::Http::UploadedFile)
+
+      raise DecodeError.new("expected an uploaded file, got #{value.class}")
+    end
+
+    sig { params(raw: T.untyped).returns(T::Array[T.untyped]) }
+    def self.array(raw)
+      return raw if raw.is_a?(Array)
+
+      raise DecodeError.new("expected an array, got #{raw.class}")
+    end
+  end
+end

data/lib/openapi_kit/errors.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  class Error < StandardError; end
+
+  class ConfigError < Error; end
+
+  class SchemaError < Error; end
+
+  class SecurityError < Error; end
+
+  class DecodeError < Error
+    extend T::Sig
+
+    ROOT = T.let("", String)
+
+    sig { returns(String) }
+    attr_reader :json_pointer
+
+    sig { returns(String) }
+    attr_reader :detail
+
+    sig { params(detail: String, json_pointer: String).void }
+    def initialize(detail, json_pointer: ROOT)
+      @detail = detail
+      @json_pointer = json_pointer
+      super(json_pointer == ROOT ? detail : "#{json_pointer}: #{detail}")
+    end
+
+    sig { params(prefix: String).returns(DecodeError) }
+    def at(prefix) = DecodeError.new(detail, json_pointer: "#{prefix}#{json_pointer}")
+  end
+end

data/lib/openapi_kit/form.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "action_dispatch"
+
+require "openapi_kit/wire"
+
+module OpenAPIKit
+  module Form
+    Parts = T.type_alias do
+      T::Hash[::String, T.any(OpenAPIKit::Wire, ::ActionDispatch::Http::UploadedFile)]
+    end
+
+    module Contract
+      extend T::Sig
+      extend T::Generic
+      interface!
+
+      Value = type_member
+
+      sig { abstract.params(parts: OpenAPIKit::Form::Parts).returns(Value) }
+      def from_parts(parts); end
+    end
+  end
+end

data/lib/openapi_kit/optional.rb

@@ -0,0 +1,67 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Optional
+    extend T::Sig
+    extend T::Generic
+    include Kernel
+    abstract!
+    sealed!
+
+    Value = type_member
+
+    sig { abstract.params(fallback: Value).returns(Value) }
+    def value_or(fallback); end
+  end
+
+  class Present
+    extend T::Sig
+    extend T::Generic
+    include Optional
+
+    Value = type_member
+
+    sig { returns(Value) }
+    attr_reader :value
+
+    sig { params(value: Value).void }
+    def initialize(value)
+      @value = value
+    end
+
+    sig { override.params(fallback: Value).returns(Value) }
+    def value_or(fallback) = value
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other) = other.is_a?(Present) && T.unsafe(other).value == T.unsafe(self).value
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def eql?(other) = self == other
+
+    sig { returns(Integer) }
+    def hash = [Present, T.unsafe(self).value].hash
+  end
+
+  class Absent
+    extend T::Sig
+    extend T::Generic
+    include Optional
+
+    Value = type_member
+
+    sig { override.params(fallback: Value).returns(Value) }
+    def value_or(fallback) = fallback
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other) = other.is_a?(Absent)
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def eql?(other) = self == other
+
+    sig { returns(Integer) }
+    def hash = Absent.hash
+  end
+
+  ABSENT = T.let(Absent.new.freeze, Absent[T.untyped])
+end

data/lib/openapi_kit/rendering.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/body"
+require "openapi_kit/response"
+
+module OpenAPIKit
+  module Rendering
+    extend T::Sig
+
+    Controller = T.type_alias do
+      T.all(::ActionController::Metal, ::ActionController::Head, ::ActionController::Rendering)
+    end
+
+    sig { params(result: OpenAPIKit::Response).void }
+    def render_response(result)
+      T.bind(self, Controller)
+
+      case (body = result.to_body)
+      when OpenAPIKit::Body::Empty
+        head(result.status)
+      when OpenAPIKit::Body::Json
+        render(json: body.wire, status: result.status, content_type: result.content_type)
+      when OpenAPIKit::Body::Stream
+        response.headers["Content-Type"] = result.content_type.to_s
+        response.status = result.status
+        self.response_body = body
+      when OpenAPIKit::Body::File
+        response.headers["Content-Type"] = result.content_type.to_s
+        response.headers["Content-Length"] = body.size.to_s
+        response.status = result.status
+        response.send_file(body.path.to_s)
+      else T.absurd(body)
+      end
+    end
+  end
+end

data/lib/openapi_kit/response.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/body"
+
+module OpenAPIKit
+  module Response
+    extend T::Sig
+    extend T::Helpers
+    interface!
+
+    sig { abstract.returns(::Integer) }
+    def status; end
+
+    sig { abstract.returns(OpenAPIKit::Body) }
+    def to_body; end
+
+    sig { abstract.returns(T.nilable(::String)) }
+    def content_type; end
+  end
+end

data/lib/openapi_kit/runtime.rb

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "openapi_kit/version"
+require "openapi_kit/errors"
+require "openapi_kit/wire"
+require "openapi_kit/form"
+require "openapi_kit/body"
+require "openapi_kit/response"
+require "openapi_kit/optional"
+require "openapi_kit/codec"
+require "openapi_kit/decode"
+require "openapi_kit/security"
+require "openapi_kit/rendering"

data/lib/openapi_kit/security.rb

@@ -0,0 +1,122 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "action_dispatch"
+
+module OpenAPIKit
+  module Security
+    extend T::Sig
+
+    sig do
+      type_parameters(:Principal)
+        .params(attempts: T::Array[T.proc.returns(T.nilable(T.type_parameter(:Principal)))])
+        .returns(T.nilable(T.type_parameter(:Principal)))
+    end
+    def self.first_of(attempts) = attempts.lazy.filter_map(&:call).first
+
+    sig { params(scheme: Scheme, request: ::ActionDispatch::Request).returns(T.nilable(String)) }
+    def self.credential(scheme, request)
+      case scheme
+      when ApiKey then api_key(scheme, request)
+      when Http then authorization(request, scheme.scheme)
+      when OAuth2, OpenIDConnect then authorization(request, "bearer")
+      else T.absurd(scheme)
+      end
+    end
+
+    sig { params(scheme: Http, request: ::ActionDispatch::Request).returns(T.nilable([String, String])) }
+    def self.basic(scheme, request)
+      encoded = credential(scheme, request)
+      return nil if encoded.nil?
+
+      decoded = begin
+        encoded.unpack1("m0")
+      rescue ArgumentError
+        nil
+      end
+      user, password = decoded.to_s.split(":", 2)
+      user.nil? || password.nil? ? nil : [user, password]
+    end
+
+    sig { params(scheme: ApiKey, request: ::ActionDispatch::Request).returns(T.nilable(String)) }
+    def self.api_key(scheme, request)
+      location = scheme.location
+      case location
+      when ApiKeyLocation::Header then present(request.headers[scheme.parameter_name])
+      when ApiKeyLocation::Query then present(request.query_parameters[scheme.parameter_name])
+      when ApiKeyLocation::Cookie then present(request.cookies[scheme.parameter_name])
+      else T.absurd(location)
+      end
+    end
+
+    sig { params(request: ::ActionDispatch::Request, scheme: String).returns(T.nilable(String)) }
+    def self.authorization(request, scheme)
+      header = present(request.headers["Authorization"])
+      return nil if header.nil?
+
+      prefix = "#{scheme} "
+      return nil unless header.downcase.start_with?(prefix.downcase)
+
+      present(header[prefix.length..])
+    end
+
+    sig { params(value: T.untyped).returns(T.nilable(String)) }
+    def self.present(value)
+      string = value.to_s
+      string.empty? ? nil : string
+    end
+
+    module Scheme
+      extend T::Sig
+      extend T::Helpers
+      include Kernel
+      sealed!
+
+      sig { params(scheme: Scheme).returns(String) }
+      def self.name_of(scheme)
+        case scheme
+        when ApiKey, Http, OAuth2, OpenIDConnect then scheme.name
+        else T.absurd(scheme)
+        end
+      end
+    end
+
+    class ApiKeyLocation < T::Enum
+      enums do
+        Query  = new("query")
+        Header = new("header")
+        Cookie = new("cookie")
+      end
+    end
+
+    class ApiKey < T::Struct
+      include Scheme
+      const :name, String
+      const :location, ApiKeyLocation
+      const :parameter_name, String
+      const :extensions, T::Hash[String, T.untyped], default: {}
+    end
+
+    class Http < T::Struct
+      include Scheme
+      const :name, String
+      const :scheme, String
+      const :bearer_format, T.nilable(String), default: nil
+      const :extensions, T::Hash[String, T.untyped], default: {}
+    end
+
+    class OAuth2 < T::Struct
+      include Scheme
+      const :name, String
+      const :scopes, T::Hash[String, String], default: {}
+      const :extensions, T::Hash[String, T.untyped], default: {}
+    end
+
+    class OpenIDConnect < T::Struct
+      include Scheme
+      const :name, String
+      const :url, String
+      const :extensions, T::Hash[String, T.untyped], default: {}
+    end
+  end
+end

data/lib/openapi_kit/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  VERSION = "0.1.0.pre.1"
+end

data/lib/openapi_kit/wire.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  # The parsed value model every supported media type leaves behind: application/json and
+  # +json, form-urlencoded, and a multipart body's text fields all arrive as these shapes,
+  # as do path, query and header values. A codec converts between one of them and a Ruby
+  # type, both ways. An uploaded file is the one thing outside it, so it never reaches a
+  # codec.
+  Wire = T.type_alias do
+    T.any(NilClass, String, Integer, Float, T::Boolean,
+          T::Array[T.untyped], T::Hash[String, T.untyped])
+  end
+end

data/lib/openapi_kit.rb

@@ -0,0 +1,4 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openapi_kit/runtime"