openapi_kit-codegen 0.1.0.pre.1

data/lib/openapi_kit/codegen/emit/codecs.rb

@@ -0,0 +1,221 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      class Codecs
+        extend T::Sig
+
+        sig { params(document: Model::Document, registry: TypeRegistry, config: Config).void }
+        def initialize(document:, registry:, config:)
+          @document = document
+          @registry = registry
+          @config = config
+        end
+
+        Codecable = T.type_alias do
+          T.any(Model::ObjectDef, Model::EnumDef, Model::UnionDef, Model::AliasDef)
+        end
+
+        sig { params(buffer: Buffer, type: Codecable).void }
+        def emit(buffer, type) = emit_codec(buffer, type)
+
+        private
+
+        sig { params(buffer: Buffer, type: Codecable).void }
+        def emit_codec(buffer, type)
+          name = Model::TypeDef.name_of(type)
+          buffer.nest("module Codec") do
+            buffer.line("extend T::Sig")
+            buffer.line("extend T::Generic")
+            buffer.line("extend ::OpenAPIKit::Codec::Contract")
+            buffer.blank
+            buffer.line("Value = type_template { { fixed: #{qualified(name)} } }")
+            buffer.blank
+            emit_codec_constants(buffer, type)
+            buffer.line("sig { override.params(value: ::OpenAPIKit::Wire).returns(#{qualified(name)}) }")
+            emit_from_wire(buffer, type)
+            buffer.blank
+            buffer.line("sig { override.params(value: #{qualified(name)}).returns(::OpenAPIKit::Wire) }")
+            emit_to_wire(buffer, type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Codecable).void }
+        def emit_codec_constants(buffer, type)
+          tag = type.is_a?(Model::UnionDef) ? type.tag : nil
+          return unless tag.is_a?(Model::Tagged)
+
+          tags = tag.mapping.keys.map(&:inspect).join(", ")
+          buffer.line("TAGS = T.let([#{tags}].freeze, T::Array[::String])")
+          buffer.blank
+        end
+
+        sig { params(name: String).returns(String) }
+        def qualified(name) = @registry.sorbet_type(Model::Ref.new(name: name))
+
+        sig { params(buffer: Buffer, type: Codecable).void }
+        def emit_from_wire(buffer, type)
+          case type
+          when Model::EnumDef then emit_enum_from_wire(buffer, type)
+          when Model::ObjectDef then emit_object_from_wire(buffer, type)
+          when Model::UnionDef then emit_union_from_wire(buffer, type)
+          when Model::AliasDef
+            buffer.line("def self.from_wire(value) = #{@registry.from_wire_expr(type.target, value: "value")}")
+          else T.absurd(type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Codecable).void }
+        def emit_to_wire(buffer, type)
+          case type
+          when Model::EnumDef then buffer.line("def self.to_wire(value) = value.serialize")
+          when Model::ObjectDef then emit_object_to_wire(buffer, type)
+          when Model::UnionDef then emit_union_to_wire(buffer, type)
+          when Model::AliasDef
+            buffer.line("def self.to_wire(value) = #{@registry.to_wire_expr(type.target, value: "value")}")
+          else T.absurd(type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::EnumDef).void }
+        def emit_enum_from_wire(buffer, type)
+          buffer.line("def self.from_wire(value) = ::OpenAPIKit::Decode.enum(#{qualified(type.name)}, value)")
+        end
+
+        sig { params(buffer: Buffer, type: Model::ObjectDef).void }
+        def emit_object_from_wire(buffer, type)
+          buffer.nest("def self.from_wire(value)") do
+            buffer.line("raw = ::OpenAPIKit::Decode.object(value)")
+            buffer.line("#{qualified(type.name)}.new(")
+            buffer.indent do
+              type.properties.each do |property|
+                buffer.line("#{property.identifier}: #{decode_from(property, source: "raw")},")
+              end
+              extra = type.additional_properties
+              buffer.line("additional_properties: #{additional_decode(type, extra)},") if extra
+            end
+            buffer.line(")")
+          end
+        end
+
+        sig { params(type: Model::ObjectDef, schema: Model::Schema).returns(String) }
+        def additional_decode(type, schema)
+          known = type.properties.map { |property| property.name.inspect }.join(", ")
+          inner = @registry.from_wire_expr(schema, value: "item")
+          "::OpenAPIKit::Decode.values(raw.except(#{known})) { |item| #{inner} }"
+        end
+
+        sig { params(schema: Model::Schema).returns(String) }
+        def additional_encode(schema)
+          inner = @registry.to_wire_expr(schema, value: "item")
+          return "value.additional_properties" if inner == "item"
+
+          "value.additional_properties.transform_values { |item| #{inner} }"
+        end
+
+        sig { params(property: Model::Property, source: String).returns(String) }
+        def decode_from(property, source:)
+          Decode.expression(source: source, key: property.name, schema: property.schema,
+                            required: property.required, registry: @registry)
+        end
+
+        sig { params(buffer: Buffer, type: Model::ObjectDef).void }
+        def emit_object_to_wire(buffer, type)
+          buffer.nest("def self.to_wire(value)") do
+            buffer.line("wire = T.let({}, T::Hash[::String, ::OpenAPIKit::Wire])")
+            type.properties.each { |property| emit_property_to_wire(buffer, property) }
+            extra = type.additional_properties
+            buffer.line("wire.merge!(#{additional_encode(extra)})") if extra
+            buffer.line("wire")
+          end
+        end
+
+        sig { params(buffer: Buffer, property: Model::Property).void }
+        def emit_property_to_wire(buffer, property)
+          meta = Model::Schema.meta(property.schema)
+          key = property.name.inspect
+          reader = property.identifier.to_s
+
+          if Decode.optional_nullable?(required: property.required, meta: Model::Schema.meta(property.schema))
+            buffer.line("#{reader} = value.#{reader}")
+            buffer.nest("if #{reader}.is_a?(::OpenAPIKit::Present)") do
+              buffer.line("inner = #{reader}.value")
+              buffer.line("wire[#{key}] = inner.nil? ? nil : #{@registry.to_wire_expr(property.schema,
+                                                                                      value: "inner")}")
+            end
+            return
+          end
+
+          if property.required && !meta.nullable
+            buffer.line("wire[#{key}] = #{@registry.to_wire_expr(property.schema, value: "value.#{reader}")}")
+            return
+          end
+
+          buffer.line("#{reader} = value.#{reader}")
+          dumped = @registry.to_wire_expr(property.schema, value: reader)
+
+          if property.required
+            buffer.line("wire[#{key}] = #{reader}.nil? ? nil : #{dumped}")
+          else
+            buffer.line("wire[#{key}] = #{dumped} unless #{reader}.nil?")
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::UnionDef).void }
+        def emit_union_from_wire(buffer, type)
+          tag = type.tag
+          buffer.nest("def self.from_wire(value)") do
+            case tag
+            when Model::Tagged then emit_tagged_from_wire(buffer, tag)
+            when Model::Untagged then emit_untagged_from_wire(buffer, type)
+            else T.absurd(tag)
+            end
+          end
+        end
+
+        sig { params(buffer: Buffer, tag: Model::Tagged).void }
+        def emit_tagged_from_wire(buffer, tag)
+          buffer.line("raw = ::OpenAPIKit::Decode.object(value)")
+          buffer.line("tag = raw[#{tag.property_name.inspect}]")
+          buffer.case_of("tag") do
+            tag.mapping.each do |wire_value, name|
+              buffer.line("when #{wire_value.inspect} then #{codec_for(name)}.from_wire(raw)")
+            end
+            message = Literal.string("expected #{tag.property_name} to be one of ",
+                                     Literal.expr(%(TAGS.join(", "))), ", got ", Literal.expr("tag.inspect"))
+            buffer.line("else raise(::OpenAPIKit::DecodeError.new(#{message}))")
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::UnionDef).void }
+        def emit_untagged_from_wire(buffer, type)
+          buffer.line("::OpenAPIKit::Decode.first_of(value, #{type.name.inspect}, [")
+          buffer.indent do
+            type.members.each do |member|
+              buffer.line("->(candidate) { #{@registry.from_wire_expr(member, value: "candidate")} },")
+            end
+          end
+          buffer.line("])")
+        end
+
+        sig { params(buffer: Buffer, type: Model::UnionDef).void }
+        def emit_union_to_wire(buffer, type)
+          buffer.nest("def self.to_wire(value)") do
+            buffer.case_of("value") do
+              type.members.each do |member|
+                buffer.line("when #{@registry.sorbet_type(member)} then " \
+                            "#{@registry.to_wire_expr(member, value: "value")}")
+              end
+              buffer.line("else T.absurd(value)")
+            end
+          end
+        end
+
+        sig { params(name: String).returns(String) }
+        def codec_for(name) = @registry.codec_reference(name)
+      end
+    end
+  end
+end

data/lib/openapi_kit/codegen/emit/controllers.rb

@@ -0,0 +1,263 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      class Controllers
+        extend T::Sig
+        include Emitter
+
+        SOURCES = T.let(
+          {
+            "Path" => "path_params",
+            "Query" => "query_params",
+            "Headers" => "header_params",
+            "Cookies" => "cookie_params"
+          }.freeze,
+          T::Hash[String, String]
+        )
+
+        sig { params(document: Model::Document, registry: TypeRegistry, config: Config).void }
+        def initialize(document:, registry:, config:)
+          @document = document
+          @registry = registry
+          @config = config
+        end
+
+        sig { override.returns(T::Array[SourceFile]) }
+        def render
+          @document.operations.group_by(&:tag).map do |tag, operations|
+            Source.file(path: "#{@config.module_path}/controllers/#{Naming.snake(tag)}_controller.rb",
+                        modules: @config.modules + ["Controllers"]) do |buffer|
+              emit_controller(buffer, tag, operations)
+            end
+          end
+        end
+
+        private
+
+        sig { params(buffer: Buffer, tag: String, operations: T::Array[Model::Operation]).void }
+        def emit_controller(buffer, tag, operations)
+          buffer.nest("class #{Naming.pascal(tag)}Controller < #{controller_base}") do
+            buffer.line("extend T::Sig")
+            buffer.line("include ::OpenAPIKit::Rendering")
+
+            operations.each do |operation|
+              buffer.blank
+              emit_action(buffer, operation)
+            end
+
+            buffer.blank
+            buffer.line("private")
+            buffer.blank
+            emit_handler(buffer, tag)
+
+            operations.select { |operation| principal?(operation) }.each do |operation|
+              buffer.blank
+              emit_authenticator(buffer, operation)
+            end
+          end
+        end
+
+        sig { returns(String) }
+        def controller_base
+          base = @config.controller_base
+          base.start_with?("::") ? base : "::#{base}"
+        end
+
+        sig { params(buffer: Buffer, tag: String).void }
+        def emit_handler(buffer, tag)
+          interface = "#{@config.namespace}::Handlers::#{Handlers.module_name(tag)}"
+
+          buffer.line("sig { returns(#{interface}) }")
+          buffer.line("def handler = #{@config.namespace}.registry.#{Naming.snake(tag)}")
+        end
+
+        sig { params(buffer: Buffer, operation: Model::Operation).void }
+        def emit_action(buffer, operation)
+          scope = "#{@config.namespace}::Operations::#{Operations.module_name(operation)}"
+          groups = grouped_parameters(operation)
+
+          buffer.line("sig { void }")
+          buffer.nest("def #{Naming.identifier(operation.id)}") do
+            emit_authentication(buffer, operation)
+
+            groups.each { |name, parameters| buffer.line(source_line(name, parameters)) }
+            buffer.blank unless groups.empty?
+
+            emit_decoded(buffer, operation, scope, groups)
+            buffer.blank
+            emit_dispatch(buffer, operation)
+          end
+        end
+
+        sig { params(buffer: Buffer, operation: Model::Operation).void }
+        def emit_authentication(buffer, operation)
+          return unless principal?(operation)
+
+          buffer.line("principal = #{authenticator_name(operation)}")
+          buffer.blank
+        end
+
+        sig { params(operation: Model::Operation).returns(String) }
+        def authenticator_name(operation) = "authenticate_#{Naming.identifier(operation.id)}"
+
+        # Each alternative is one attempt, tried in the order the document lists them.
+        sig { params(buffer: Buffer, operation: Model::Operation).void }
+        def emit_authenticator(buffer, operation)
+          requirements = @document.security_for(operation)
+
+          buffer.line("sig { returns(#{Security.principal_type(requirements, @config)}) }")
+          buffer.nest("def #{authenticator_name(operation)}") do
+            buffer.line("::OpenAPIKit::Security.first_of(")
+            buffer.indent do
+              buffer.line("[")
+              buffer.indent do
+                requirements.reject(&:anonymous?).each { |requirement| buffer.line("#{attempt(requirement)},") }
+              end
+              buffer.line("]")
+            end
+            buffer.line(requirements.any?(&:anonymous?) ? ")" : ") || raise(::OpenAPIKit::SecurityError)")
+          end
+        end
+
+        sig { params(requirement: Model::SecurityRequirement).returns(String) }
+        def attempt(requirement)
+          name = T.must(requirement.schemes.keys.first)
+          scopes = T.must(requirement.schemes[name])
+          reader = "#{@config.namespace}.registry.#{Naming.snake(name)}"
+
+          "-> { #{reader}.authenticate(request: request, scopes: #{scopes.inspect}) }"
+        end
+
+        sig do
+          params(buffer: Buffer, operation: Model::Operation, scope: String,
+                 groups: T::Hash[String, T::Array[Model::Parameter]]).void
+        end
+        def emit_decoded(buffer, operation, scope, groups)
+          buffer.line("decoded = #{scope}::Request.new(")
+          buffer.indent do
+            groups.each_key do |name|
+              buffer.line("#{Naming.identifier(name)}: #{scope}::#{name}.new(")
+              buffer.indent { emit_group_arguments(buffer, name, T.must(groups[name])) }
+              buffer.line("),")
+            end
+            buffer.line("body: #{body_expression(operation)},") if body?(operation)
+            buffer.line("principal: principal,") if principal?(operation)
+            buffer.line("http_request: request")
+          end
+          buffer.line(")")
+        end
+
+        sig { params(buffer: Buffer, operation: Model::Operation).void }
+        def emit_dispatch(buffer, operation)
+          buffer.line("render_response(handler.#{Naming.identifier(operation.id)}(request: decoded))")
+        end
+
+        sig { params(buffer: Buffer, group: String, parameters: T::Array[Model::Parameter]).void }
+        def emit_group_arguments(buffer, group, parameters)
+          source = T.must(SOURCES[group])
+          parameters.each do |parameter|
+            info = Model::Parameter.info(parameter)
+            expression = Decode.expression(source: source, key: info.name, schema: info.schema,
+                                           required: Model::Parameter.required?(parameter), registry: @registry)
+            buffer.line("#{info.identifier}: #{expression},")
+          end
+        end
+
+        sig { params(group: String, parameters: T::Array[Model::Parameter]).returns(String) }
+        def source_line(group, parameters)
+          names = parameters.map { |parameter| Model::Parameter.info(parameter).name }
+
+          "#{T.must(SOURCES[group])} = ::OpenAPIKit::Decode.gather(#{names.inspect}) " \
+            "{ |name| #{lookup(group)} }"
+        end
+
+        sig { params(group: String).returns(String) }
+        def lookup(group)
+          case group
+          when "Path" then "request.path_parameters[name.to_sym]"
+          when "Query" then "request.query_parameters[name]"
+          when "Headers" then "request.headers[name]"
+          when "Cookies" then "request.cookies[name]"
+          else raise SchemaError, "unknown parameter group #{group}"
+          end
+        end
+
+        sig { params(operation: Model::Operation).returns(T::Hash[String, T::Array[Model::Parameter]]) }
+        def grouped_parameters(operation)
+          reject_unsupported_styles(operation)
+
+          {
+            "Path" => Model::PathParameter, "Query" => Model::QueryParameter,
+            "Headers" => Model::HeaderParameter, "Cookies" => Model::CookieParameter
+          }.filter_map do |name, kind|
+            found = operation.parameters.grep(kind)
+            found.empty? ? nil : [name, found]
+          end.to_h
+        end
+
+        sig { params(operation: Model::Operation).void }
+        def reject_unsupported_styles(operation)
+          operation.parameters.each do |parameter|
+            style = unsupported_style(parameter)
+            next if style.nil?
+
+            raise SchemaError,
+                  "#{operation.id} declares parameter " \
+                  "#{Model::Parameter.info(parameter).name.inspect} with style #{style.inspect}, which " \
+                  "openapi_kit does not decode yet. Supported styles are simple for path and form for query."
+          end
+        end
+
+        sig { params(parameter: Model::Parameter).returns(T.nilable(String)) }
+        def unsupported_style(parameter)
+          case parameter
+          when Model::PathParameter
+            parameter.style == Model::PathStyle::Simple ? nil : parameter.style.serialize
+          when Model::QueryParameter
+            parameter.style == Model::QueryStyle::Form ? nil : parameter.style.serialize
+          end
+        end
+
+        sig { params(operation: Model::Operation).returns(T::Boolean) }
+        def principal?(operation)
+          !@config.principal.nil? && !@document.security_for(operation).empty?
+        end
+
+        sig { params(operation: Model::Operation).returns(T::Boolean) }
+        def body?(operation)
+          body = operation.request_body
+          !body.nil? && !body.contents.empty?
+        end
+
+        sig { params(operation: Model::Operation).returns(String) }
+        def body_expression(operation)
+          body = T.must(operation.request_body)
+          schema = T.must(body.contents.first).schema
+          return "nil" if schema.nil?
+
+          source = body_source(schema)
+          inner = @registry.from_form_expr(schema, value: source) ||
+                  @registry.from_wire_expr(schema, value: source)
+          body.required ? inner : "(#{inner} if #{body_present(schema)})"
+        end
+
+        # Rails' JSON parameter parser wraps a body that is not a JSON object as
+        # { _json: parsed }, so a top-level array or scalar arrives under that key.
+        sig { params(schema: Model::Schema).returns(String) }
+        def body_source(schema)
+          @registry.object?(schema) ? "request.request_parameters" : %(request.request_parameters["_json"])
+        end
+
+        sig { params(schema: Model::Schema).returns(String) }
+        def body_present(schema)
+          return "request.request_parameters.any?" if @registry.object?(schema)
+
+          %(request.request_parameters.key?("_json"))
+        end
+      end
+    end
+  end
+end

data/lib/openapi_kit/codegen/emit/decode.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      module Decode
+        extend T::Sig
+
+        sig { params(required: T::Boolean, meta: Model::Meta).returns(T::Boolean) }
+        def self.optional_nullable?(required:, meta:) = !required && meta.nullable && meta.default.nil?
+
+        sig do
+          params(source: String, key: String, schema: Model::Schema, required: T::Boolean,
+                 registry: TypeRegistry).returns(String)
+        end
+        def self.expression(source:, key:, schema:, required:, registry:)
+          meta = Model::Schema.meta(schema)
+          inner = if Model::Schema.file?(schema)
+                    "::OpenAPIKit::Decode.file(v)"
+                  else
+                    registry.from_wire_expr(schema, value: "v")
+                  end
+          quoted = key.inspect
+          default = meta.default
+
+          if default && !required
+            fallback = Defaults.expression(schema: schema, default: default, registry: registry)
+            return "::OpenAPIKit::Decode.defaulted(#{source}, #{quoted}, #{fallback}) { |v| #{inner} }"
+          end
+
+          return "::OpenAPIKit::Decode.optional_nullable(#{source}, #{quoted}) { |v| #{inner} }" if
+            optional_nullable?(required: required, meta: meta)
+          return "::OpenAPIKit::Decode.required_nullable(#{source}, #{quoted}) { |v| #{inner} }" if
+            required && meta.nullable
+          return "::OpenAPIKit::Decode.required(#{source}, #{quoted}) { |v| #{inner} }" if required
+
+          "::OpenAPIKit::Decode.optional(#{source}, #{quoted}) { |v| #{inner} }"
+        end
+      end
+    end
+  end
+end

data/lib/openapi_kit/codegen/emit/defaults.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      module Defaults
+        extend T::Sig
+
+        sig do
+          params(schema: Model::Schema, default: Model::Default, registry: TypeRegistry).returns(String)
+        end
+        def self.expression(schema:, default:, registry:)
+          literal = default.value
+          return "nil" if literal.nil?
+          return literal.inspect if registry.literal_matches_type?(schema, literal)
+
+          registry.from_wire_expr(schema, value: literal.inspect)
+        end
+
+        sig do
+          params(schema: Model::Schema, default: Model::Default, registry: TypeRegistry).returns(String)
+        end
+        def self.clause(schema:, default:, registry:)
+          literal = default.value
+          return "default: nil" if literal.nil?
+          return "default: #{literal.inspect}" if registry.literal_matches_type?(schema, literal)
+
+          "factory: -> { #{expression(schema: schema, default: default, registry: registry)} }"
+        end
+
+        sig { params(required: T::Boolean, meta: Model::Meta).returns(T::Boolean) }
+        def self.nilable?(required:, meta:)
+          default = meta.default
+          return true if default && default.value.nil?
+
+          meta.nullable || (!required && default.nil?)
+        end
+      end
+    end
+  end
+end

data/lib/openapi_kit/codegen/emit/emitter.rb

@@ -0,0 +1,17 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      module Emitter
+        extend T::Sig
+        extend T::Helpers
+        interface!
+
+        sig { abstract.returns(T::Array[SourceFile]) }
+        def render; end
+      end
+    end
+  end
+end

data/lib/openapi_kit/codegen/emit/forms.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      class Forms
+        extend T::Sig
+
+        sig { params(registry: TypeRegistry).void }
+        def initialize(registry:)
+          @registry = registry
+        end
+
+        sig { params(buffer: Buffer, type: Model::FormDef).void }
+        def emit(buffer, type)
+          qualified = @registry.sorbet_type(Model::Ref.new(name: type.name))
+
+          buffer.nest("module Form") do
+            buffer.line("extend T::Sig")
+            buffer.line("extend T::Generic")
+            buffer.line("extend ::OpenAPIKit::Form::Contract")
+            buffer.blank
+            buffer.line("Value = type_template { { fixed: #{qualified} } }")
+            buffer.blank
+            buffer.line("sig { override.params(parts: ::OpenAPIKit::Form::Parts).returns(#{qualified}) }")
+            buffer.nest("def self.from_parts(parts)") do
+              buffer.line("#{qualified}.new(")
+              buffer.indent do
+                type.properties.each { |property| buffer.line("#{property.identifier}: #{decode(property)},") }
+                extra = type.additional_properties
+                buffer.line("additional_properties: #{decode_extra(type, extra)},") if extra
+              end
+              buffer.line(")")
+            end
+          end
+        end
+
+        private
+
+        sig { params(property: Model::Property).returns(String) }
+        def decode(property)
+          Decode.expression(source: "parts", key: property.name, schema: property.schema,
+                            required: property.required, registry: @registry)
+        end
+
+        sig { params(type: Model::FormDef, schema: Model::Schema).returns(String) }
+        def decode_extra(type, schema)
+          known = type.properties.map { |property| property.name.inspect }.join(", ")
+          inner = @registry.from_wire_expr(schema, value: "item")
+          "::OpenAPIKit::Decode.values(parts.except(#{known})) { |item| #{inner} }"
+        end
+      end
+    end
+  end
+end