openapi_kit-codegen 0.1.0.pre.1

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

@@ -0,0 +1,183 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      class Security
+        extend T::Sig
+        include Emitter
+
+        sig { params(document: Model::Document, config: Config).void }
+        def initialize(document:, config:)
+          @document = document
+          @config = config
+        end
+
+        sig { params(name: String).returns(String) }
+        def self.constant(name) = Naming.snake(name).upcase
+
+        sig { params(name: String).returns(String) }
+        def self.module_name(name) = Naming.pascal(name)
+
+        # The principal a protected operation carries. An anonymous alternative means the
+        # request may arrive without one.
+        sig do
+          params(requirements: T::Array[Model::SecurityRequirement], config: Config).returns(String)
+        end
+        def self.principal_type(requirements, config)
+          type = T.must(config.principal)
+          requirements.any?(&:anonymous?) ? "T.nilable(#{type})" : type
+        end
+
+        sig { override.returns(T::Array[SourceFile]) }
+        def render
+          return [] if @document.security_schemes.empty?
+
+          [
+            Source.file(path: "#{@config.module_path}/security.rb",
+                        modules: @config.modules + ["Security"]) { |buffer| emit_body(buffer) }
+          ]
+        end
+
+        private
+
+        sig { params(buffer: Buffer).void }
+        def emit_body(buffer)
+          buffer.line("extend T::Sig")
+
+          @document.security_schemes.each do |scheme|
+            buffer.blank
+            buffer.line("#{Security.constant(Model::SecurityScheme.name_of(scheme))} = T.let(")
+            buffer.indent do
+              type, arguments = constructor(scheme)
+              extensions = Model::SecurityScheme.extensions_of(scheme)
+              arguments += [["extensions", extensions.inspect]] unless extensions.empty?
+              buffer.nest_call("#{type}.new", arguments)
+              buffer.line(type)
+            end
+            buffer.line(")")
+          end
+
+          buffer.blank
+          emit_catalogue(buffer)
+
+          authenticated.each do |scheme|
+            buffer.blank
+            emit_authenticator(buffer, scheme)
+          end
+        end
+
+        # One interface per scheme, filled by a registry slot the same way handlers are.
+        # Returning nil means this alternative was not satisfied, so the next one is
+        # tried. Raise to refuse outright.
+        sig { params(buffer: Buffer, scheme: Model::SecurityScheme).void }
+        def emit_authenticator(buffer, scheme)
+          name = Model::SecurityScheme.name_of(scheme)
+
+          type, = constructor(scheme)
+
+          buffer.nest("module #{Security.module_name(name)}") do
+            buffer.line("extend T::Sig")
+            buffer.line("extend T::Helpers")
+            buffer.line("abstract!")
+            buffer.blank
+            buffer.line("sig { returns(#{type}) }")
+            buffer.line("def scheme = #{Security.constant(name)}")
+            buffer.blank
+            emit_credential(buffer, scheme)
+            buffer.blank
+            emit_authenticate(buffer)
+          end
+        end
+
+        sig { params(buffer: Buffer, scheme: Model::SecurityScheme).void }
+        def emit_credential(buffer, scheme)
+          buffer.line("sig { params(request: ::ActionDispatch::Request).returns(T.nilable(::String)) }")
+          buffer.line("def credential(request) = ::OpenAPIKit::Security.credential(scheme, request)")
+          return unless basic?(scheme)
+
+          buffer.blank
+          buffer.line("sig do")
+          buffer.indent do
+            buffer.line("params(request: ::ActionDispatch::Request)")
+            buffer.line("  .returns(T.nilable([::String, ::String]))")
+          end
+          buffer.line("end")
+          buffer.line("def basic_credential(request) = ::OpenAPIKit::Security.basic(scheme, request)")
+        end
+
+        sig { params(buffer: Buffer).void }
+        def emit_authenticate(buffer)
+          buffer.line("sig do")
+          buffer.indent do
+            buffer.line("abstract.params(request: ::ActionDispatch::Request, scopes: T::Array[::String])")
+            buffer.line("        .returns(T.nilable(#{T.must(@config.principal)}))")
+          end
+          buffer.line("end")
+          buffer.line("def authenticate(request:, scopes:); end")
+        end
+
+        # Undecoded base64 is no use, so a basic scheme gets the decoded pair instead.
+        sig { params(scheme: Model::SecurityScheme).returns(T::Boolean) }
+        def basic?(scheme) = scheme.is_a?(Model::HttpScheme) && scheme.scheme == "basic"
+
+        sig { params(name: String).returns(T::Boolean) }
+        def used?(name)
+          @document.operations.any? do |operation|
+            @document.security_for(operation).any? { |requirement| requirement.schemes.key?(name) }
+          end
+        end
+
+        sig { returns(T::Array[Model::SecurityScheme]) }
+        def authenticated
+          return [] if @config.principal.nil?
+
+          @document.security_schemes.select { |scheme| used?(Model::SecurityScheme.name_of(scheme)) }
+        end
+
+        sig { params(buffer: Buffer).void }
+        def emit_catalogue(buffer)
+          buffer.line("SCHEMES = T.let(")
+          buffer.indent do
+            buffer.line("{")
+            buffer.indent do
+              @document.security_schemes.each do |scheme|
+                name = Model::SecurityScheme.name_of(scheme)
+                buffer.line("#{name.inspect} => #{Security.constant(name)},")
+              end
+            end
+            buffer.line("}.freeze,")
+            buffer.line("T::Hash[::String, ::OpenAPIKit::Security::Scheme]")
+          end
+          buffer.line(")")
+        end
+
+        sig do
+          params(scheme: Model::SecurityScheme)
+            .returns([String, T::Array[[String, String]]])
+        end
+        def constructor(scheme)
+          case scheme
+          when Model::ApiKeyScheme
+            location = "::OpenAPIKit::Security::ApiKeyLocation::#{Naming.pascal(scheme.location.serialize)}"
+            ["::OpenAPIKit::Security::ApiKey",
+             [["name", scheme.name.inspect], ["location", location],
+              ["parameter_name", scheme.parameter_name.inspect]]]
+          when Model::HttpScheme
+            ["::OpenAPIKit::Security::Http",
+             [["name", scheme.name.inspect], ["scheme", scheme.scheme.inspect],
+              ["bearer_format", scheme.bearer_format.inspect]]]
+          when Model::OAuth2Scheme
+            ["::OpenAPIKit::Security::OAuth2",
+             [["name", scheme.name.inspect], ["scopes", scheme.scopes.inspect]]]
+          when Model::OpenIDConnectScheme
+            ["::OpenAPIKit::Security::OpenIDConnect",
+             [["name", scheme.name.inspect], ["url", scheme.url.inspect]]]
+          else T.absurd(scheme)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      class SourceFile < T::Struct
+        const :path, String
+        const :contents, String
+      end
+
+      module Source
+        extend T::Sig
+
+        sig do
+          params(path: String, modules: T::Array[String], block: T.proc.params(buffer: Buffer).void)
+            .returns(SourceFile)
+        end
+        def self.file(path:, modules:, &block)
+          buffer = Buffer.new
+          buffer.line("# typed: strict")
+          buffer.line("# frozen_string_literal: true")
+          buffer.blank
+          buffer.nest_modules(modules) { block.call(buffer) }
+          SourceFile.new(path: path, contents: buffer.to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,153 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    module Emit
+      class Types
+        extend T::Sig
+        include Emitter
+
+        sig { params(document: Model::Document, registry: TypeRegistry, config: Config).void }
+        def initialize(document:, registry:, config:)
+          @document = document
+          @registry = registry
+          @config = config
+          @codecs = T.let(Codecs.new(document: document, registry: registry, config: config), Codecs)
+          @forms = T.let(Forms.new(registry: registry), Forms)
+        end
+
+        sig { override.returns(T::Array[SourceFile]) }
+        def render
+          declared_types.map do |type|
+            name = Model::TypeDef.name_of(type)
+            Source.file(path: "#{@config.module_path}/types/#{Naming.snake(name)}.rb",
+                        modules: @config.modules + ["Types"]) do |buffer|
+              emit_declaration(buffer, type)
+            end
+          end
+        end
+
+        private
+
+        sig { returns(T::Array[Model::TypeDef]) }
+        def declared_types = @document.types.grep_v(Model::AliasDef)
+
+        sig { params(buffer: Buffer, type: Model::TypeDef).void }
+        def emit_declaration(buffer, type)
+          case type
+          when Model::EnumDef then emit_enum(buffer, type)
+          when Model::UnionDef then emit_union(buffer, type)
+          when Model::ObjectDef then emit_object(buffer, type)
+          when Model::FormDef then emit_form(buffer, type)
+          when Model::AliasDef then nil
+          else T.absurd(type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::EnumDef).void }
+        def emit_enum(buffer, type)
+          buffer.nest("class #{type.name} < T::Enum") do
+            buffer.nest("enums do") do
+              type.members.each { |member| buffer.line("#{member.constant} = new(#{member.value.inspect})") }
+            end
+            buffer.blank
+            @codecs.emit(buffer, type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::UnionDef).void }
+        def emit_union(buffer, type)
+          members = type.members.map { |member| @registry.sorbet_type(member) }.uniq
+          inner = members.one? ? T.must(members.first) : "T.any(#{members.join(", ")})"
+
+          buffer.nest("module #{type.name}") do
+            buffer.line("Value = T.type_alias { #{inner} }")
+            buffer.blank
+            @codecs.emit(buffer, type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::ObjectDef).void }
+        def emit_object(buffer, type)
+          buffer.nest("class #{type.name} < T::Struct") do
+            buffer.line("extend T::Sig")
+            buffer.blank
+            type.properties.each { |property| buffer.line(prop_line(property)) }
+            extra = type.additional_properties
+            buffer.line("const :additional_properties, #{additional_type(extra)}, factory: -> { {} }") if extra
+            buffer.blank
+            emit_equality(buffer, type.name)
+            buffer.blank
+            @codecs.emit(buffer, type)
+          end
+        end
+
+        sig { params(buffer: Buffer, type: Model::FormDef).void }
+        def emit_form(buffer, type)
+          buffer.nest("class #{type.name} < T::Struct") do
+            buffer.line("extend T::Sig")
+            buffer.blank
+            type.properties.each { |property| buffer.line(prop_line(property)) }
+            extra = type.additional_properties
+            buffer.line("const :additional_properties, #{additional_type(extra)}, factory: -> { {} }") if extra
+            buffer.blank
+            emit_equality(buffer, type.name)
+            buffer.blank
+            @forms.emit(buffer, type)
+          end
+        end
+
+        sig { params(buffer: Buffer, name: String).void }
+        def emit_equality(buffer, name)
+          buffer.line("sig { params(other: T.untyped).returns(T::Boolean) }")
+          buffer.line("def ==(other) = other.instance_of?(#{name}) && other.serialize == serialize")
+          buffer.blank
+          buffer.line("sig { params(other: T.untyped).returns(T::Boolean) }")
+          buffer.line("def eql?(other) = self == other")
+          buffer.blank
+          buffer.line("sig { returns(::Integer) }")
+          buffer.line("def hash = [self.class, serialize].hash")
+        end
+
+        sig { params(schema: Model::Schema).returns(String) }
+        def additional_type(schema) = "T::Hash[::String, #{@registry.sorbet_type(schema)}]"
+
+        sig { params(property: Model::Property).returns(String) }
+        def prop_line(property)
+          meta = Model::Schema.meta(property.schema)
+          declaration = "const :#{property.identifier}, #{prop_type(property)}"
+          default = meta.default
+
+          if default && !property.required
+            clause = Defaults.clause(schema: property.schema, default: default, registry: @registry)
+            return "#{declaration}, #{clause}"
+          end
+          return "#{declaration}, default: ::OpenAPIKit::ABSENT" if optional_nullable?(property)
+
+          declaration
+        end
+
+        sig { params(property: Model::Property).returns(String) }
+        def prop_type(property)
+          meta = Model::Schema.meta(property.schema)
+          base = if Model::Schema.file?(property.schema)
+                   TypeRegistry::UPLOADED_FILE
+                 else
+                   @registry.sorbet_type(property.schema)
+                 end
+
+          return "::OpenAPIKit::Optional[T.nilable(#{base})]" if optional_nullable?(property)
+          return "T.nilable(#{base})" if Defaults.nilable?(required: property.required, meta: meta)
+
+          base
+        end
+
+        sig { params(property: Model::Property).returns(T::Boolean) }
+        def optional_nullable?(property)
+          Decode.optional_nullable?(required: property.required, meta: Model::Schema.meta(property.schema))
+        end
+      end
+    end
+  end
+end

data/lib/openapi_kit/codegen/generator.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+module OpenAPIKit
+  module Codegen
+    class Generator
+      extend T::Sig
+
+      sig { returns(T::Array[String]) }
+      attr_reader :warnings
+
+      sig { params(config: Config).void }
+      def initialize(config:)
+        @config = config
+        @warnings = T.let([], T::Array[String])
+      end
+
+      sig { returns(T::Array[Emit::SourceFile]) }
+      def sources
+        loader = Loader.new(config: @config)
+        document = loader.parse
+        registry = TypeRegistry.for(document, @config)
+
+        files = emitters(document, registry).flat_map(&:render)
+        @warnings = loader.warnings + registry.warnings
+        files
+      end
+
+      sig { returns(T::Array[Pathname]) }
+      def generate = Writer.new(output: @config.output).write_all(sources)
+
+      private
+
+      sig { params(document: Model::Document, registry: TypeRegistry).returns(T::Array[Emit::Emitter]) }
+      def emitters(document, registry)
+        [
+          Emit::Types.new(document: document, registry: registry, config: @config),
+          Emit::Operations.new(document: document, registry: registry, config: @config),
+          Emit::Handlers.new(document: document, config: @config),
+          Emit::Security.new(document: document, config: @config),
+          Emit::Registry.new(document: document, config: @config),
+          Emit::Routes.new(document: document, config: @config),
+          Emit::Controllers.new(document: document, registry: registry, config: @config)
+        ]
+      end
+    end
+  end
+end