modern 0.4.2

data/lib/modern/descriptor/parameters.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "modern/struct"
+require "modern/errors/web_errors"
+
+module Modern
+  module Descriptor
+    module Parameters
+      class Base < Modern::Struct
+        # TODO: maybe do something behind-the-scenes where `required` is
+        #       expressed as part of dry-types (| Types::Nil); we need
+        #       the field for easily generating a doc later, but we could parse
+        #       it out of the type if we had to.
+        attribute :name, Types::Strict::String
+        attribute :type, Types::Type
+        attribute :description, Types::Strict::String.optional.default(nil)
+        attribute :deprecated, Types::Strict::Bool.default(false)
+
+        def friendly_name
+          name
+        end
+
+        def retrieve(request, route_captures)
+          ret = do_retrieve(request, route_captures)
+
+          raise Errors::BadRequestError, "Invalid/missing parameter '#{friendly_name}'." \
+            if required && ret.nil?
+
+          begin
+            ret.nil? ? nil : type[ret]
+          rescue StandardError => _err
+            raise Errors::InternalServiceError,
+                  "Couldn't interpret the value provided for parameter '#{friendly_name}': #{ret}."
+          end
+        end
+
+        def openapi3_in
+          self.class.name.split("::").last.downcase
+        end
+
+        def do_retrieve(_request, _route_captures)
+          raise "#{self.class.name}#do_retrieve(request, route_captures) must be implemented."
+        end
+
+        def to_openapi3(is_api_key = false)
+          {
+            name: friendly_name,
+            in: openapi3_in,
+            required: !is_api_key ? required : nil,
+            description: !is_api_key ? description : nil,
+            deprecated: !is_api_key ? deprecated : nil
+          }.compact
+        end
+      end
+
+      class Path < Base
+        # TODO: add 'matrix' and 'label'
+        attribute :style, Types::Coercible::String.default("simple").enum("simple")
+
+        def required
+          true
+        end
+
+        def do_retrieve(_request, route_captures)
+          route_captures[name]
+        end
+      end
+
+      class Cookie < Base
+        attribute :cookie_name, Types::Coercible::String
+        attribute :style, Types::Coercible::String.default("form").enum("form")
+        attribute :required, Types::Strict::Bool.default(false)
+
+        def friendly_name
+          cookie_name
+        end
+
+        def do_retrieve(request, _route_captures = nil)
+          request.cookies[cookie_name]
+        end
+      end
+
+      class Header < Base
+        attribute :header_name, Types::Coercible::String
+        attribute :style, Types::Coercible::String.default("simple").enum("simple")
+        attribute :required, Types::Strict::Bool.default(false)
+
+        attr_reader :rack_env_key
+
+        def initialize(fields)
+          super(fields)
+
+          @rack_env_key = "HTTP_" + header_name.upcase.tr("-", "_")
+        end
+
+        def friendly_name
+          header_name
+        end
+
+        def do_retrieve(request, _route_captures = nil)
+          request.env[@rack_env_key]
+        end
+      end
+
+      class Query < Base
+        # TODO: add 'space_delimited', 'pipe_delimited', 'deep_object'
+        attribute :style, Types::Coercible::String.default("form").enum("form")
+        attribute :required, Types::Strict::Bool.default(false)
+
+        attribute :allow_empty_value, Types::Strict::Bool.default(false)
+
+        attr_reader :parser
+
+        def initialize(fields)
+          super(fields)
+
+          @query_parser = Rack::QueryParser.make_default(99, 99)
+        end
+
+        def do_retrieve(request, _route_captures = nil)
+          @query_parser.parse_query(request.query_string)[name]
+        end
+
+        def to_openapi3(is_api_key = false)
+          super.merge(
+            allowEmptyValue: !is_api_key ? description : nil,
+          ).compact
+        end
+      end
+
+      def self.from_inputs(name, parameter_type, opts)
+        opts = opts.merge(name: name.to_s)
+
+        case parameter_type.to_sym
+        when :path
+          Modern::Descriptor::Parameters::Path.new(opts)
+        when :cookie
+          Modern::Descriptor::Parameters::Cookie.new(opts)
+        when :header
+          Modern::Descriptor::Parameters::Header.new(opts)
+        when :query
+          Modern::Descriptor::Parameters::Query.new(opts)
+        else
+          raise "Unrecognized parameter type '#{parameter_type}'.'"
+        end
+      end
+    end
+  end
+end

data/lib/modern/descriptor/request_body.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "modern/struct"
+
+module Modern
+  module Descriptor
+    class RequestBody < Modern::Struct
+      attribute :type, (Types::Type | Types::Struct).optional.default(nil)
+      attribute :required, Types::Strict::Bool.default(false)
+      attribute :description, Types::Strict::String.optional.default(nil)
+    end
+  end
+end

data/lib/modern/descriptor/response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "modern/struct"
+require "modern/descriptor/content"
+require "modern/descriptor/parameters"
+
+module Modern
+  module Descriptor
+    class Response < Modern::Struct
+      # TODO: figure out a good way to handle header responses
+      #       This is in part an API response type of thing; how do we ensure that
+      #       an action defines the header that it says it's defining?
+      attribute :http_code, Types::Strict::Int | Types.Value(:default)
+      attribute :description, Types::Strict::String.default("No description provided.")
+      attribute :content, Types.array_of(Content)
+
+      attr_reader :content_by_type
+
+      def initialize(fields)
+        super
+
+        @content_by_type = content.map { |c| [c.media_type, c] }.to_h.freeze
+      end
+    end
+  end
+end

data/lib/modern/descriptor/route.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "set"
+
+require "modern/struct"
+
+require "modern/descriptor/converters"
+require "modern/descriptor/response"
+require "modern/descriptor/parameters"
+require "modern/descriptor/request_body"
+require "modern/descriptor/security"
+
+module Modern
+  module Descriptor
+    class Route < Modern::Struct
+      # TODO: define OpenAPI-style callbacks
+      TEMPLATE_TOKEN = %r|\{.+\}|
+      OPENAPI_CAPTURE = %r|/\{(?<name>.+?)\}|
+
+      attribute :id, Types::String
+
+      attribute :http_method, Types::HttpMethod
+      attribute :path, Types::HttpPath
+
+      attribute :summary, Types::Strict::String.optional.default(nil)
+      attribute :description, Types::Strict::String.optional.default(nil)
+      attribute :deprecated, Types::Strict::Bool.default(false)
+      attribute :tags, Types.array_of(Types::Coercible::String)
+
+      attribute :parameters, Types.array_of(Parameters::Base)
+      attribute :request_body, RequestBody.optional.default(nil)
+      attribute :responses, Types.array_of(Response)
+
+      attribute :input_converters, Types.array_of(Modern::Descriptor::Converters::Input::Base)
+      attribute :output_converters, Types.array_of(Modern::Descriptor::Converters::Output::Base)
+
+      attribute :security, Types.array_of(Security::Base)
+      attribute :helpers, Types.array_of(Types.Instance(Module))
+      attribute :action, Types::RouteAction
+
+      attr_reader :path_matcher
+      attr_reader :route_tokens
+
+      attr_reader :content_types
+      attr_reader :responses_by_code
+
+      attr_reader :input_converters_by_type
+      attr_reader :output_converters_by_type
+
+      attr_reader :request_container_class
+
+      def initialize(fields)
+        super
+
+        @path_matcher = Regexp.new("^" + path.gsub(OPENAPI_CAPTURE, "/(?<\\k<name>>[^/]+)") + "$")
+        @route_tokens =
+          path.sub(%r|^/|, "").split("/").map do |token|
+            TEMPLATE_TOKEN =~ token ? :templated : token
+          end
+
+        @content_types = responses.map { |r| r.content.map(&:media_type) }.flatten.to_set.freeze
+        @responses_by_code = responses.map { |r| [r.http_code, r] }.to_h.freeze
+
+        raise "Cannot create a Route without a Response where http_code = :default." \
+          unless @responses_by_code.key?(:default)
+
+        _nondefault_content = @content_types - @responses_by_code[:default].content.map(&:media_type).to_set
+        # TODO: figure out how to better validate these
+        #       This might be a larger-scale problem. The DSL creates a route with this, and you can end
+        #       up in a case where you try to add a new content type to another response type. This causes
+        #       the commented test below to fail unless you defined the :default response, with that content
+        #       type, higher in the DSL. We might need some sort of intermediate builder class, or a way to
+        #       squelch this error somehow...
+        # require 'pry'; binding.pry
+        # raise "Missing content types in default HTTP response for #{id}: #{nondefault_content.to_a.join(', ')}" \
+        #     unless nondefault_content.empty?
+
+        @input_converters_by_type = input_converters.map { |c| [c.media_type.downcase.strip, c] }.to_h.freeze
+        @output_converters_by_type = output_converters.map { |c| [c.media_type.downcase.strip, c] }.to_h.freeze
+
+        @request_container_class =
+          if helpers.empty?
+            Modern::App::RequestHandling::FullRequestContainer
+          else
+            rcc = Class.new(Modern::App::RequestHandling::FullRequestContainer)
+            helpers.each { |h| rcc.send(:include, h) }
+
+            rcc
+          end
+      end
+    end
+  end
+end

data/lib/modern/descriptor/security.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "modern/descriptor/parameters"
+require "modern/errors/web_errors"
+require "modern/struct"
+
+module Modern
+  module Descriptor
+    module Security
+      # TODO: implement OAuth2 security, with flow objects
+      # TODO: implement OpenID Connect security
+
+      # Securities in Modern allow for specifying the "plumbing" bits of the
+      # security in a predictable, unsurprising way. If you specify that you use
+      # HTTP authorization with the `Foobar` scheme--great. Modern finds the
+      # authorization header, checks to see if it's Foobar type, and retrieves
+      # the value that signifies its authentication. This value will be passed
+      # to the validator, which can determine whether or not its a valid bit of
+      # authentication.
+      #
+      # The idea is that, given that the validation gets access to a
+      # `PartialRequestContainer` that includes both the request and the
+      # application service set, it can connect to the auth server/user
+      # database/whatever and make sure it's atually a legitimate user. Since
+      # {Modern::Request} has a mutable store in {Modern::Request#local_store},
+      # the validator can then store a User object (or whatever) into it for use
+      # in the actual application.
+      class Base < Modern::Struct
+        attribute :name, Types::Strict::String
+        attribute :description, Types::Strict::String.optional.default(nil)
+        attribute :validation, Types::SecurityAction
+
+        def validate(container)
+          value = do_credential_fetch(container.request)
+
+          if value.nil?
+            false
+          else
+            !!container.instance_exec(value, &validation)
+          end
+        end
+
+        def do_credential_fetch(_request)
+          raise "#{self.class.name}#do_credential_fetch(request) must be implemented."
+        end
+
+        def to_openapi3
+          {
+            description: description
+          }
+        end
+      end
+
+      class ApiKey < Base
+        attribute :parameter, Parameters::Query | Parameters::Header | Parameters::Cookie
+
+        def initialize(fields)
+          super
+
+          # I didn't want to rewrite all my parameter logic.
+          raise Modern::Errors::SetupError, "Parameter must not be 'required' (internal limitation)." \
+            if parameter.required
+        end
+
+        def do_credential_fetch(request)
+          parameter.do_retrieve(request)
+        end
+
+        def to_openapi3
+          parameter.to_openapi3(true).merge(type: "apiKey")
+        end
+      end
+
+      class Http < Base
+        # aside: some people think that the Authorization field can support multiple sets of credentials,
+        # as RFC 7230 suggests that headers can be sent "multiple" times by using a comma to split them.
+        # however, this is for headers like Accept-Encoding. We don't need to split Authorization.
+        SPLITTER = %r,([^\s]+?)\s+(.*+),
+
+        attribute :scheme, Types::Strict::String
+
+        def do_credential_fetch(request)
+          header = request.env["HTTP_AUTHORIZATION"]
+
+          if header.nil?
+            nil
+          else
+            match = SPLITTER.match(header)
+            # yields #<MatchData "Bearer foo" 1:"Bearer" 2:"foo">
+
+            match[2].strip if !match.nil? && match[1].casecmp(scheme).zero?
+          end
+        end
+
+        def to_openapi3
+          super.merge(
+            type: "http",
+            scheme: scheme
+          )
+        end
+      end
+    end
+  end
+end

data/lib/modern/descriptor/server.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "modern/struct"
+
+module Modern
+  module Descriptor
+    class Server < Modern::Struct
+      attribute :url, Modern::Types::Strict::String
+      attribute :description, Modern::Types::Strict::String.optional.default(nil)
+    end
+  end
+end

data/lib/modern/descriptor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'modern/struct'
+
+module Modern
+  module Descriptor
+    def self.define(title, version, &block)
+      require 'modern/dsl'
+
+      Modern::DSL::Root.build(title, version, &block)
+    end
+  end
+end
+
+Dir["#{__dir__}/descriptor/**/*.rb"].each { |f| require_relative f }

data/lib/modern/doc_generator/open_api3/operations.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Modern
+  module DocGenerator
+    class OpenAPI3
+      module Operations
+        def _operation(route)
+          {
+            operationId: route.id,
+            summary: route.summary,
+            description: route.description,
+            deprecated: route.deprecated,
+            tags: route.tags.uniq,
+
+            security: route.security.map { |s| _security_requirement(s) },
+
+            parameters: route.parameters.map { |p| _parameter(p) },
+            requestBody: _request_body(route),
+            responses:
+              route.responses_by_code.map do |code, response|
+                [code, _response(response)]
+              end.to_h,
+            # TODO: implement callbacks
+            callbacks: nil
+          }.compact
+        end
+
+        def _security_requirement(security)
+          # TODO: OAuth2
+          ret = {}
+          ret[security.name] = []
+
+          ret
+        end
+
+        def _parameter(parameter)
+          # TODO: this should be in the parameter class, or that logic should be here.
+
+          parameter.to_openapi3.merge(
+            schema: _build_schema_value({}, {}, parameter.type)
+          )
+        end
+
+        def _request_body(route)
+          body = route.request_body
+
+          if body.nil?
+            nil
+          else
+            schema =
+              if body.type.nil?
+                nil
+              elsif body.type.is_a?(Class) && body.type.ancestors.include?(Dry::Struct)
+                _struct_ref(body.type)
+              else
+                # TODO: make this less wasteful (see _response)
+                _build_schema_value({}, {}, body.type)
+              end
+
+            {
+              required: body.required,
+              content:
+                route.input_converters.map(&:media_type).map do |content_type|
+                  [
+                    content_type,
+                    {
+                      schema: schema
+                    }.compact
+                  ]
+                end.to_h.compact
+            }
+          end
+        end
+
+        def _response(response)
+          {
+            description: response.description,
+            # headers:
+            #   response.headers.map do |header|
+            #     [
+            #       header.name,
+            #       {
+            #         description: header.description
+            #       }.compact
+            #     ]
+            #   end.to_h,
+            content:
+              response.content_by_type.map do |content_type, content|
+                [
+                  content_type,
+                  {
+                    schema:
+                      if content.type.nil?
+                        nil
+                      elsif content.type.is_a?(Class) && content.type.ancestors.include?(Dry::Struct)
+                        _struct_ref(content.type)
+                      else
+                        # TODO: make this less wasteful
+                        #       Right now, this reuses the schema walking stuff. It totally will re-walk
+                        #       existing schemas as far as `content.type` will reach. Which is slower
+                        #       during startup than we'd like, but it's fixable later by converting
+                        #       the methods to using state (that's why `OpenAPI3` is an object in the
+                        #       first place, but I wrote myself into a corner here).
+                        _build_schema_value({}, {}, content.type)
+                      end
+                  }.compact
+                ]
+              end.to_h
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/modern/doc_generator/open_api3/paths.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative './operations'
+
+module Modern
+  module DocGenerator
+    class OpenAPI3
+      module Paths
+        include Operations
+
+        def _paths(descriptor)
+          descriptor.routes_by_path.map do |path, routes_by_method|
+            [
+              path,
+              routes_by_method.map do |method, route|
+                [method.downcase, _operation(route)]
+              end.to_h
+            ]
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/modern/doc_generator/open_api3/schema_default_types.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Modern
+  module DocGenerator
+    class OpenAPI3
+      module SchemaDefaultTypes
+        def _register_default_types!
+          # TODO: handle all default types
+          #       This misses a few types, mostly because I don't yet know how to
+          #       handle them:
+          #         - I don't understand the Types::Form set of types well enough.
+          #         - I have not provided a DateTime mapping because you shouldn't
+          #           use DateTime and I have no idea how to do so sanely.
+          #         - We can't coerce Symbols, so those are out.
+          [Types::String, Types::Strict::String, Types::Coercible::String].each do |t|
+            register_literal_type(t, type: "string")
+          end
+
+          [Types::Int, Types::Strict::Int, Types::Coercible::Int].each do |t|
+            register_literal_type(t, type: "integer", format: "int64")
+          end
+
+          [
+            Types::Bool, Types::Strict::Bool,
+            Types::True, Types::Strict::True,
+            Types::False, Types::Strict::False
+          ].each do |t|
+            register_literal_type(t, type: "boolean")
+          end
+
+          [Types::Float, Types::Strict::Float, Types::Coercible::Float].each do |t|
+            register_literal_type(t, type: "number", format: "double")
+          end
+
+          [Types::Date, Types::Strict::Date, Types::Json::Date].each do |t|
+            register_literal_type(t, type: "string", format: "date")
+          end
+
+          [Types::Time, Types::Strict::Time, Types::Json::Time].each do |t|
+            register_literal_type(t, type: "string", format: "date")
+          end
+
+          [Types::Decimal, Types::Strict::Decimal, Types::Coercible::Decimal].each do |t|
+            register_literal_type(t, type: "number")
+          end
+        end
+      end
+    end
+  end
+end