modern 0.4.2

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative './schema_default_types'
+
+module Modern
+  module DocGenerator
+    class OpenAPI3
+      module Schemas
+        # TODO: make all this not awful!
+        #       I am not a type theorist. I am also not a compiler writer
+        #       (though I've pretended to be in my day once or twice). dry-types
+        #       is a very dense language and parsing it to emit OpenAPI schemas is
+        #       really, really hard for me. This is a brute-force approach. There
+        #       is probably a better one. My approach is basically to allow for
+        #       the registration of literal types (which serve as my terminals) and
+        #       try to build rules on top of those literal types for more complex
+        #       ideas.
+        # TODO: parse the dry-logic in predicates to properly fill out the rest of
+        #       the JSON schema
+
+        include SchemaDefaultTypes
+
+        def register_literal_type(type, oapi3_value)
+          raise "`type` must be a Dry::Types::Type." unless type.is_a?(Dry::Types::Type)
+
+          @type_registry[type] = oapi3_value
+        end
+
+        # Only Dry::Struct
+        def _struct_schemas(descriptor)
+          ret = {}
+          name_to_class = {}
+
+          descriptor.root_schemas \
+                    .select { |type_or_structclass| type_or_structclass.is_a?(Class) } \
+                    .each do |structclass|
+            _build_struct(ret, name_to_class, structclass)
+          end
+
+          ret
+        end
+
+        def _build_struct(ret, name_to_class, structclass)
+          # TODO: allow overriding the name of the struct in #/components/schemas
+          #       This is actually trickier than it looks, because we need to also
+          #       make it referenceable in responses/contents. It probably means an
+          #       indirect mapping of classes to names and back again.
+
+          raise "not actually a Dry::Struct class" \
+            unless structclass.ancestors.include?(Dry::Struct)
+
+          name = structclass.name.split("::").last
+
+          if name_to_class[name] == structclass
+            name
+          else
+            if !name_to_class[name].nil?
+              raise "Duplicate schema name: '#{name}'. Only one class, regardless " \
+                    "of namespace, can be called this."
+            end
+
+            ret[name] = _build_object_from_schema(ret, name_to_class, structclass.schema)
+          end
+
+          name # necessary for recursive calls in _build_schema_value
+        end
+
+        def _build_object_from_schema(ret, name_to_class, dt_schema)
+          {
+            type: "object",
+            properties: dt_schema.map do |k, v|
+              [k, _build_schema_value(ret, name_to_class, v)]
+            end.to_h
+          }
+        end
+
+        def _struct_ref(structclass)
+          { "$ref": "#/components/schemas/#{structclass.name.split('::').last}" }
+        end
+
+        def _build_schema_value(ret, name_to_class, entry)
+          registered_type = @type_registry[entry]
+
+          if !registered_type.nil?
+            registered_type
+          elsif entry.is_a?(Dry::Types::Sum::Constrained)
+            if entry.left.type.primitive == NilClass
+              # it's a nullable field
+              _build_schema_value(ret, name_to_class, entry.right).merge(nullable: true)
+            else
+              {
+                anyOf: _flatten_any_of(
+                  [
+                    _build_schema_value(ret, name_to_class, entry.left),
+                    _build_schema_value(ret, name_to_class, entry.right)
+                  ]
+                )
+              }
+            end
+          elsif entry.is_a?(Dry::Types::Constrained)
+            # TODO: dig deeper into the actual behavior of Constrained (dry-logic)
+            #       This is probably a can of worms. More:
+            #       http://dry-rb.org/gems/dry-types/constraints/
+
+            _build_schema_value(ret, name_to_class, entry.type)
+          elsif entry.is_a?(Dry::Types::Default)
+            # this just unwraps the default value
+            _build_schema_value(ret, name_to_class, entry.type)
+          elsif entry.is_a?(Dry::Types::Definition)
+            primitive = entry.primitive
+
+            if primitive.ancestors.include?(Dry::Struct)
+              # TODO: make sure I'm understanding this correctly
+              #       It feels weird to have to oneOf a $ref, but I can't figure out a
+              #       syntax that doesn't require it.
+              _build_struct(ret, name_to_class, primitive)
+
+              {
+                oneOf: [
+                  _struct_ref(primitive)
+                ]
+              }
+            elsif primitive.ancestors.include?(Hash)
+              _build_object_from_schema(ret, name_to_class, entry.member_types)
+            elsif primitive.ancestors.include?(Array)
+              {
+                type: "array",
+                items: _build_schema_value(ret, name_to_class, entry.member)
+              }
+            else
+              raise "unrecognized primitive definition '#{primitive.name}'; probably needs a literal."
+            end
+          else
+            raise "Unrecognized schema class: #{entry.class.name}: #{entry.inspect}"
+          end
+        end
+
+        def _flatten_any_of(typehash_array)
+          # This is hacky, but it removes the incidence of something like this:
+          #
+          # :exsub => {
+          #   :anyOf => [
+          #       [0] {
+          #           :oneOf => [
+          #               [0] {
+          #                   :$ref => "#/components/schemas/ExclusiveSubA"
+          #               }
+          #           ]
+          #       },
+          #       [1] {
+          #           :oneOf => [
+          #               [0] {
+          #                   :$ref => "#/components/schemas/ExclusiveSubB"
+          #               }
+          #           ]
+          #       }
+          #   ]
+          # }
+
+          typehash_array.map do |typehash|
+            if typehash.length == 1 && typehash.first.first == :oneOf
+              typehash.first.last
+            else
+              typehash
+            end
+          end.flatten
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Modern
+  module DocGenerator
+    class OpenAPI3
+      module Schemas
+        def _security_schemes(descriptor)
+          descriptor.securities_by_name.map do |name, security|
+            [name, security.to_openapi3.compact]
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/modern/doc_generator/open_api3.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+require 'modern/descriptor'
+require 'modern/descriptor/converters'
+
+require 'modern/version'
+
+Dir["#{__dir__}/open_api3/*.rb"].each { |f| require_relative f }
+
+module Modern
+  module DocGenerator
+    class OpenAPI3
+      include Schemas
+      include Paths
+
+      # TODO: this is pretty inflexible. Eventually, consumers may want to
+      #       subclass Route, Content, etc., for their own use cases, and that
+      #       would make using an external/visiting doc generator impractical.
+      #       It's simple enough, though, so let's roll with it for now.
+
+      OPENAPI_VERSION = Modern::OPENAPI_VERSION
+
+      def initialize
+        @type_registry = {}
+        _register_default_types!
+      end
+
+      def json(descriptor)
+        JSON.pretty_generate(hash(descriptor))
+      end
+
+      def yaml(descriptor)
+        # TODO: this hack exists just to de-symbolize the output without spending
+        #       a bunch of time on it, because we don't have ActiveSupport and
+        #       #deep_stringify_keys. It happens once at startup, it's not a big
+        #       deal.
+        YAML.dump(JSON.parse(json(descriptor)))
+      end
+
+      def both(descriptor)
+        j = JSON.pretty_generate(hash(descriptor))
+
+        {
+          json: j,
+          yaml: YAML.dump(JSON.parse(j))
+        }
+      end
+
+      def hash(descriptor)
+        ret = {
+          openapi: OPENAPI_VERSION,
+
+          info: _info(descriptor.info),
+          servers: descriptor.servers.empty? ? nil : descriptor.servers.map(&:to_h),
+          paths: _paths(descriptor),
+          components: _components(descriptor)
+        }.compact
+
+        ret
+      end
+
+      def decorate_with_openapi_routes(configuration, descriptor)
+        docs = both(descriptor)
+
+        openapi3_json = docs[:json].freeze
+        openapi3_yaml = docs[:yaml].freeze
+
+        serve_json = Modern::Descriptor::Route.new(
+          id: "serveOpenApi3Json",
+          http_method: :GET,
+          path: configuration.open_api_json_path,
+          summary: "Serves the OpenAPI3 application spec in JSON form.",
+          responses: [
+            Modern::Descriptor::Response.new(
+              http_code: :default,
+              content: [Modern::Descriptor::Content.new(media_type: "application/json")]
+            )
+          ],
+          output_converters: [
+            Modern::Descriptor::Converters::Output::JSONBypass
+          ],
+          action:
+            proc do
+              response.bypass!
+              response.write(openapi3_json)
+            end
+        )
+
+        serve_yaml = Modern::Descriptor::Route.new(
+          id: "serveOpenApi3Yaml",
+          http_method: :GET,
+          path: configuration.open_api_yaml_path,
+          summary: "Serves the OpenAPI3 application spec in YAML form.",
+          responses: [
+            Modern::Descriptor::Response.new(
+              http_code: :default,
+              content: [Modern::Descriptor::Content.new(media_type: "application/yaml")]
+            )
+          ],
+          output_converters: [
+            Modern::Descriptor::Converters::Output::YAMLBypass
+          ],
+          action:
+            proc do
+              response.bypass!
+              response.write(openapi3_yaml)
+            end
+        )
+
+        [serve_json, serve_yaml, descriptor.routes].flatten
+      end
+
+      def _info(obj)
+        obj.to_h.compact
+      end
+
+      def _components(descriptor)
+        # TODO: figure out if we can omit the empty hashes below. We're probably never
+        #       going to emit a "minimal" doc; I can't see ever trying to dedupe request
+        #       bodies or whatever. (We do security schemes because it's easier and we
+        #       do schemas to provide a reason for using dry-struct over a bunch of
+        #       hashes.)
+        ret = {
+          schemas: _struct_schemas(descriptor),
+          responses: {},
+          parameters: {},
+          examples: {},
+          requestBodies: {},
+          securitySchemes: _security_schemes(descriptor),
+          links: {},
+          callbacks: {}
+        }
+
+        ret
+      end
+    end
+  end
+end

data/lib/modern/dsl/info.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'modern/descriptor/info'
+
+require 'docile'
+
+module Modern
+  module DSL
+    class Info
+      attr_reader :value
+
+      def initialize(title, version)
+        @value = Modern::Descriptor::Info.new(title: title, version: version)
+      end
+
+      def description(v)
+        @value = @value.copy(description: v)
+      end
+
+      def terms_of_service(v)
+        @value = @value.copy(terms_of_service: v)
+      end
+
+      def contact(name: nil, url: nil, email: nil)
+        @value = @value.copy(contact: { name: name, url: url, email: email }.compact)
+      end
+
+      def license(name, url: nil)
+        @value = @value.copy(license: { name: name, url: url }.compact)
+      end
+
+      def self.build(title, version, &block)
+        i = Info.new(title, version)
+        i.instance_exec(&block)
+        i.value
+      end
+    end
+  end
+end

data/lib/modern/dsl/response_builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'modern/descriptor/response'
+require 'modern/descriptor/content'
+
+require 'docile'
+
+module Modern
+  module DSL
+    class ResponseBuilder
+      attr_reader :value
+
+      def initialize(http_code_or_response)
+        @value =
+          if http_code_or_response.is_a?(Modern::Descriptor::Response)
+            http_code_or_response
+          else
+            Modern::Descriptor::Response.new(http_code: http_code_or_response)
+          end
+      end
+
+      def description(s)
+        @value = @value.copy(description: s)
+      end
+
+      def content(media_type, type = nil)
+        raise "Duplicate content type: #{media_type}" \
+          if @value.content.any? { |c| c.media_type.casecmp(media_type).zero? }
+
+        new_content = Modern::Descriptor::Content.new(media_type: media_type, type: type)
+        @value = @value.copy(content: @value.content + [new_content])
+      end
+
+      def self.evaluate(http_code_or_response, &block)
+        builder = ResponseBuilder.new(http_code_or_response)
+        builder.instance_exec(&block)
+        builder.value
+      end
+    end
+  end
+end

data/lib/modern/dsl/root.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'modern/dsl/info'
+require 'modern/dsl/scope'
+
+module Modern
+  module DSL
+    class Root < Scope
+      attr_reader :descriptor
+
+      def initialize(descriptor)
+        super(descriptor, nil)
+      end
+
+      def info(&block)
+        @descriptor = @descriptor.copy(
+          info: Info.build(descriptor.info.title, descriptor.info.version, &block).to_h
+        )
+      end
+
+      def server(url, description: nil)
+        raise "url is required for a server declaration." if url.nil?
+
+        @descriptor = @descriptor.copy(
+          servers: @descriptor.servers + [Modern::Descriptor::Server.new(url: url, description: description)]
+        )
+      end
+
+      def self.build(title, version, &block)
+        d = Modern::Descriptor::Core.new(info: { title: title, version: version })
+
+        r = Root.new(d)
+        r.instance_exec(&block)
+        r.descriptor
+      end
+    end
+  end
+end

data/lib/modern/dsl/route_builder.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'modern/descriptor/route'
+
+require 'modern/dsl/response_builder'
+
+require 'docile'
+
+module Modern
+  module DSL
+    class RouteBuilder
+      attr_reader :value
+
+      def initialize(id, http_method, path, settings)
+        new_path_segments = path&.split("/") || []
+        @value = Modern::Descriptor::Route.new(
+          id: id.to_s,
+          path: "/" + ([settings.path_segments] + new_path_segments).flatten.compact.join("/"),
+          http_method: http_method.upcase,
+          summary: nil,
+          description: nil,
+          deprecated: settings.deprecated,
+          tags: settings.tags,
+          parameters: settings.parameters,
+          request_body: nil,
+          responses: [settings.default_response],
+          input_converters: settings.input_converters,
+          output_converters: settings.output_converters,
+          security: settings.security,
+          helpers: settings.helpers,
+          action: proc {}
+        )
+      end
+
+      def summary(s)
+        @value = @value.copy(summary: s)
+      end
+
+      def description(s)
+        @value = @value.copy(description: s)
+      end
+
+      def deprecate!
+        @value = @value.copy(deprecated: true)
+      end
+
+      def tag(s)
+        @value = @value.copy(tags: @value.tags + [s])
+      end
+
+      def parameter(name, parameter_type, opts)
+        param = Modern::Descriptor::Parameters.from_inputs(name, parameter_type, opts)
+        raise "Duplicate parameter '#{name}'.'" if @value.parameters.any? { |p| p.name.casecmp(param.name).zero? }
+
+        @value = @value.copy(parameters: @value.parameters + [param])
+      end
+
+      def request_body(type, opts = { required: true })
+        opts = { required: true }.merge(opts).merge(type: type)
+        @value = @value.copy(request_body: Modern::Descriptor::RequestBody.new(opts))
+      end
+
+      def response(http_code, &block)
+        existing_response = @value.responses.find { |r| r.http_code == http_code }
+
+        resp = ResponseBuilder.evaluate(existing_response || http_code, &block)
+        @value = @value.copy(responses: @value.responses + [resp])
+      end
+
+      def input_converter(media_type_or_converter, &block)
+        if media_type_or_converter.is_a?(Modern::Descriptor::Converters::Input::Base)
+          @value = @value.copy(input_converters: @value.input_converters + [media_type_or_converter])
+        elsif media_type_or_converter.is_a?(String) && !block.nil?
+          input_converter(
+            Modern::Descriptor::Converters::Input::Base.new(
+              media_type: media_type_or_converter, converter: block
+            )
+          )
+        else
+          raise "must pass a String and block or a Modern::Descriptor::Converters::Input::Base."
+        end
+      end
+
+      def clear_input_converters!
+        @value = @value.copy(input_converters: [])
+      end
+
+      def output_converter(media_type_or_converter, &block)
+        if media_type_or_converter.is_a?(Modern::Descriptor::Converters::Output::Base)
+          @value = @value.copy(output_converters: @value.output_converters + [media_type_or_converter])
+        elsif media_type_or_converter.is_a?(String) && !block.nil?
+          output_converter(
+            Modern::Descriptor::Converters::Output::Base.new(
+              media_type: media_type_or_converter, converter: block
+            )
+          )
+        else
+          raise "must pass a String and block or a Modern::Descriptor::Converters::Output::Base."
+        end
+      end
+
+      def clear_output_converters!
+        @value = @value.copy(output_converters: [])
+      end
+
+      def clear_security!
+        @value = @value.copy(security: [])
+      end
+
+      def security(sec)
+        @value = @value.copy(security: @value.security + [sec])
+      end
+
+      def helper(h)
+        @value = @value.copy(helpers: @value.helpers + [h])
+      end
+
+      def action(&block)
+        @value = @value.copy(action: block)
+      end
+
+      def self.evaluate(id, http_method, path, settings, &block)
+        builder = RouteBuilder.new(id, http_method, path, settings)
+        builder.instance_exec(&block)
+
+        builder.value
+      end
+    end
+  end
+end