rage-rb 1.10.0 → 1.11.0

data/lib/rage/openapi/openapi.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "erb"
+require "yaml"
+
+if !defined?(Prism)
+  fail <<~ERR
+
+    rage-rb depends on Prism to build OpenAPI specifications. Add the following line to your Gemfile:
+    gem "prism"
+
+  ERR
+end
+
+module Rage::OpenAPI
+  # Create a new OpenAPI application.
+  #
+  # @param namespace [String, Module] limit the parser to a specific namespace
+  # @example
+  #   map "/publicapi" do
+  #     run Rage.openapi.application
+  #   end
+  # @example
+  #   map "/publicapi/v1" do
+  #     run Rage.openapi.application(namespace: "Api::V1")
+  #   end
+  #
+  #   map "/publicapi/v2" do
+  #     run Rage.openapi.application(namespace: "Api::V2")
+  #   end
+  def self.application(namespace: nil)
+    html_app = ->(env) do
+      __data_cache[[:page, namespace]] ||= begin
+        scheme, host, path = env["rack.url_scheme"], env["HTTP_HOST"], env["SCRIPT_NAME"]
+        spec_url = "#{scheme}://#{host}#{path}/json"
+        page = ERB.new(File.read("#{__dir__}/index.html.erb")).result(binding)
+
+        [200, { "Content-Type" => "text/html; charset=UTF-8" }, [page]]
+      end
+    end
+
+    json_app = ->(env) do
+      spec = (__data_cache[[:spec, namespace]] ||= build(namespace:).to_json)
+      [200, { "Content-Type" => "application/json" }, [spec]]
+    end
+
+    app = ->(env) do
+      if env["PATH_INFO"] == ""
+        html_app.call(env)
+      elsif env["PATH_INFO"] == "/json"
+        json_app.call(env)
+      else
+        [404, {}, ["Not Found"]]
+      end
+    end
+
+    if Rage.config.middleware.include?(Rage::Reloader)
+      Rage.with_middlewares(app, [Rage::Reloader])
+    elsif defined?(ActionDispatch::Reloader) && Rage.config.middleware.include?(ActionDispatch::Reloader)
+      Rage.with_middlewares(app, [ActionDispatch::Reloader])
+    else
+      app
+    end
+  end
+
+  # Build an OpenAPI specification for the application.
+  # @param namespace [String, Module] limit the parser to a specific namespace
+  # @return [Hash]
+  def self.build(namespace: nil)
+    Builder.new(namespace:).run
+  end
+
+  # @private
+  def self.__shared_components
+    __data_cache[:shared_components] ||= begin
+      components_file = Rage.root.join("config").glob("openapi_components.*")[0]
+
+      if components_file.nil?
+        {}
+      else
+        case components_file.extname
+        when ".yml", ".yaml"
+          YAML.safe_load(components_file.read)
+        when ".json"
+          JSON.parse(components_file.read)
+        else
+          Rage::OpenAPI.__log_warn "unrecognized file extension: #{components_file.relative_path_from(Rage.root)}; expected either .yml or .json"
+          {}
+        end
+      end
+    end
+  end
+
+  # @private
+  def self.__data_cache
+    @__data_cache ||= {}
+  end
+
+  # @private
+  def self.__reset_data_cache
+    __data_cache.clear
+  end
+
+  # @private
+  def self.__try_parse_collection(str)
+    if str =~ /^Array<([\w\s:\(\)]+)>$/ || str =~ /^\[([\w\s:\(\)]+)\]$/
+      [true, $1]
+    else
+      [false, str]
+    end
+  end
+
+  # @private
+  def self.__module_parent(klass)
+    klass.name =~ /::[^:]+\z/ ? Object.const_get($`) : Object
+  rescue NameError
+    Object
+  end
+
+  # @private
+  def self.__log_warn(log)
+    puts "WARNING: #{log}"
+  end
+
+  module Nodes
+  end
+
+  module Parsers
+    module Ext
+    end
+  end
+end
+
+require_relative "builder"
+require_relative "collector"
+require_relative "parser"
+require_relative "converter"
+require_relative "nodes/root"
+require_relative "nodes/parent"
+require_relative "nodes/method"
+require_relative "parsers/ext/alba"
+require_relative "parsers/ext/active_record"
+require_relative "parsers/yaml"
+require_relative "parsers/shared_reference"
+require_relative "parsers/request"
+require_relative "parsers/response"

data/lib/rage/openapi/parser.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Parser
+  def parse_dangling_comments(node, comments)
+    i = 0
+
+    while i < comments.length
+      children = nil
+      expression = comments[i].slice.delete_prefix("#").strip
+
+      if expression =~ /@deprecated\b/
+        if node.deprecated
+          Rage::OpenAPI.__log_warn "duplicate @deprecated tag detected at #{location_msg(comments[i])}"
+        else
+          node.deprecated = true
+        end
+        children = find_children(comments[i + 1..])
+
+      elsif expression =~ /@private\b/
+        if node.private
+          Rage::OpenAPI.__log_warn "duplicate @private tag detected at #{location_msg(comments[i])}"
+        else
+          node.private = true
+        end
+        children = find_children(comments[i + 1..])
+
+      elsif expression =~ /@version\s/
+        if node.root.version
+          Rage::OpenAPI.__log_warn "duplicate @version tag detected at #{location_msg(comments[i])}"
+        else
+          node.root.version = expression[9..]
+        end
+
+      elsif expression =~ /@title\s/
+        if node.root.title
+          Rage::OpenAPI.__log_warn "duplicate @title tag detected at #{location_msg(comments[i])}"
+        else
+          node.root.title = expression[7..]
+        end
+
+      elsif expression =~ /@auth\s/
+        method, name, tail_name = expression[6..].split(" ", 3)
+        children = find_children(comments[i + 1..])
+
+        if tail_name
+          Rage::OpenAPI.__log_warn "incorrect `@auth` name detected at #{location_msg(comments[i])}; security scheme name cannot contain spaces"
+        end
+
+        auth_entry = {
+          method:,
+          name: name || method,
+          definition: children.any? ? YAML.safe_load(children.join("\n")) : { "type" => "http", "scheme" => "bearer" }
+        }
+
+        if !node.controller.__before_action_exists?(method.to_sym)
+          Rage::OpenAPI.__log_warn "referenced before action `#{method}` is not defined in #{node.controller} at #{location_msg(comments[i])}; ensure a corresponding `before_action` call exists"
+        elsif node.auth.include?(auth_entry) || node.root.parent_nodes.any? { |parent_node| parent_node.auth.include?(auth_entry) }
+          Rage::OpenAPI.__log_warn "duplicate @auth tag detected at #{location_msg(comments[i])}"
+        else
+          node.auth << auth_entry
+        end
+      end
+
+      if children&.any?
+        i += children.length + 1
+      else
+        i += 1
+      end
+    end
+  end
+
+  def parse_method_comments(node, comments)
+    i = 0
+
+    while i < comments.length
+      children = nil
+      expression = comments[i].slice.delete_prefix("#").strip
+
+      if !expression.start_with?("@")
+        if node.summary
+          Rage::OpenAPI.__log_warn "invalid summary entry detected at #{location_msg(comments[i])}; summary should only be one line"
+        else
+          node.summary = expression
+        end
+
+      elsif expression =~ /@deprecated\b/
+        if node.parents.any?(&:deprecated)
+          Rage::OpenAPI.__log_warn "duplicate `@deprecated` tag detected at #{location_msg(comments[i])}; tag already exists in a parent class"
+        else
+          node.deprecated = true
+        end
+        children = find_children(comments[i + 1..])
+
+      elsif expression =~ /@private\b/
+        if node.parents.any?(&:private)
+          Rage::OpenAPI.__log_warn "duplicate `@private` tag detected at #{location_msg(comments[i])}; tag already exists in a parent class"
+        else
+          node.private = true
+        end
+        children = find_children(comments[i + 1..])
+
+      elsif expression =~ /@description\s/
+        children = find_children(comments[i + 1..])
+        node.description = [expression[13..]] + children
+
+      elsif expression =~ /@response\s/
+        response = expression[10..].strip
+        status, response_data = if response =~ /^\d{3}$/
+          [response, nil]
+        elsif response =~ /^\d{3}/
+          response.split(" ", 2)
+        else
+          ["200", response]
+        end
+
+        if node.responses.has_key?(status)
+          Rage::OpenAPI.__log_warn "duplicate `@response` tag detected at #{location_msg(comments[i])}"
+        elsif response_data.nil?
+          node.responses[status] = nil
+        else
+          parsed = Rage::OpenAPI::Parsers::Response.parse(
+            response_data,
+            namespace: Rage::OpenAPI.__module_parent(node.controller)
+          )
+
+          if parsed
+            node.responses[status] = parsed
+          else
+            Rage::OpenAPI.__log_warn "unrecognized `@response` tag detected at #{location_msg(comments[i])}"
+          end
+        end
+
+      elsif expression =~ /@request\s/
+        request = expression[9..]
+        if node.request
+          Rage::OpenAPI.__log_warn "duplicate `@request` tag detected at #{location_msg(comments[i])}"
+        else
+          parsed = Rage::OpenAPI::Parsers::Request.parse(
+            request,
+            namespace: Rage::OpenAPI.__module_parent(node.controller)
+          )
+
+          if parsed
+            node.request = parsed
+          else
+            Rage::OpenAPI.__log_warn "unrecognized `@request` tag detected at #{location_msg(comments[i])}"
+          end
+        end
+
+      elsif expression =~ /@internal\b/
+        # no-op
+        children = find_children(comments[i + 1..])
+
+      else
+        Rage::OpenAPI.__log_warn "unrecognized `#{expression.split(" ")[0]}` tag detected at #{location_msg(comments[i])}"
+      end
+
+      if children&.any?
+        i += children.length + 1
+      else
+        i += 1
+      end
+    end
+  end
+
+  private
+
+  def find_children(comments)
+    children = []
+
+    comments.each do |comment|
+      expression = comment.slice.sub(/^#\s/, "")
+
+      if expression.start_with?(/\s{2}/)
+        children << expression.strip
+      elsif expression.start_with?("@")
+        break
+      else
+        Rage::OpenAPI.__log_warn "unrecognized expression detected at #{location_msg(comment)}; use two spaces to mark multi-line expressions"
+        break
+      end
+    end
+
+    children
+  end
+
+  def location_msg(comment)
+    location = comment.location
+    relative_path = Pathname.new(location.__source_path).relative_path_from(Rage.root)
+
+    "#{relative_path}:#{location.start_line}"
+  end
+end

data/lib/rage/openapi/parsers/ext/active_record.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Parsers::Ext::ActiveRecord
+  BLACKLISTED_ATTRIBUTES = %w(id created_at updated_at)
+
+  def initialize(namespace: Object, **)
+    @namespace = namespace
+  end
+
+  def known_definition?(str)
+    _, str = Rage::OpenAPI.__try_parse_collection(str)
+    defined?(ActiveRecord::Base) && @namespace.const_get(str).ancestors.include?(ActiveRecord::Base)
+  rescue NameError
+    false
+  end
+
+  def parse(klass_str)
+    is_collection, klass_str = Rage::OpenAPI.__try_parse_collection(klass_str)
+    klass = @namespace.const_get(klass_str)
+
+    schema = {}
+
+    klass.attribute_types.each do |attr_name, attr_type|
+      next if BLACKLISTED_ATTRIBUTES.include?(attr_name) ||
+              attr_name.end_with?("_id") ||
+              attr_name == klass.inheritance_column ||
+              klass.defined_enums.include?(attr_name)
+
+      schema[attr_name] = case attr_type.type
+      when :integer
+        { "type" => "integer" }
+      when :boolean
+        { "type" => "boolean" }
+      when :binary
+        { "type" => "string", "format" => "binary" }
+      when :date
+        { "type" => "string", "format" => "date" }
+      when :datetime, :time
+        { "type" => "string", "format" => "date-time" }
+      when :float
+        { "type" => "number", "format" => "float" }
+      when :decimal
+        { "type" => "number" }
+      when :json
+        { "type" => "object" }
+      else
+        { "type" => "string" }
+      end
+    end
+
+    klass.defined_enums.each do |attr_name, mapping|
+      schema[attr_name] = { "type" => "string", "enum" => mapping.keys }
+    end
+
+    result = { "type" => "object" }
+    result["properties"] = schema if schema.any?
+
+    result = { "type" => "array", "items" => result } if is_collection
+
+    result
+  end
+end

data/lib/rage/openapi/parsers/ext/alba.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Parsers::Ext::Alba
+  attr_reader :namespace
+
+  def initialize(namespace: Object, **)
+    @namespace = namespace
+  end
+
+  def known_definition?(str)
+    _, str = Rage::OpenAPI.__try_parse_collection(str)
+    defined?(Alba::Resource) && @namespace.const_get(str).ancestors.include?(Alba::Resource)
+  rescue NameError
+    false
+  end
+
+  def parse(klass_str)
+    __parse(klass_str).build_schema
+  end
+
+  def __parse_nested(klass_str)
+    __parse(klass_str).tap { |visitor|
+      visitor.root_key = visitor.root_key_for_collection = visitor.key_transformer = nil
+    }.build_schema
+  end
+
+  def __parse(klass_str)
+    is_collection, klass_str = Rage::OpenAPI.__try_parse_collection(klass_str)
+
+    klass = @namespace.const_get(klass_str)
+    source_path, _ = Object.const_source_location(klass.name)
+    ast = Prism.parse_file(source_path)
+
+    visitor = Visitor.new(self, is_collection)
+    ast.value.accept(visitor)
+
+    visitor
+  end
+
+  class VisitorContext
+    attr_accessor :symbols, :hashes, :keywords, :consts, :nil
+
+    def initialize
+      @symbols = []
+      @hashes = []
+      @keywords = {}
+      @consts = []
+      @nil = false
+    end
+  end
+
+  class Visitor < Prism::Visitor
+    attr_accessor :schema, :root_key, :root_key_for_collection, :key_transformer, :collection_key, :meta
+
+    def initialize(parser, is_collection)
+      @parser = parser
+      @is_collection = is_collection
+
+      @schema = {}
+      @segment = @schema
+      @context = nil
+      @prev_contexts = []
+
+      @self_name = nil
+      @root_key = nil
+      @root_key_for_collection = nil
+      @key_transformer = nil
+      @collection_key = false
+      @meta = {}
+    end
+
+    def visit_class_node(node)
+      @self_name ||= node.name.to_s
+
+      if node.name =~ /Resource$|Serializer$/ && node.superclass
+        visitor = @parser.__parse(node.superclass.name)
+        @root_key, @root_key_for_collection = visitor.root_key, visitor.root_key_for_collection
+        @key_transformer, @collection_key, @meta = visitor.key_transformer, visitor.collection_key, visitor.meta
+        @schema.merge!(visitor.schema)
+      end
+
+      super
+    end
+
+    def build_schema
+      result = { "type" => "object" }
+
+      result["properties"] = @schema if @schema.any?
+
+      if @is_collection
+        result = if @collection_key && @root_key_for_collection
+          { "type" => "object", "properties" => { @root_key_for_collection => { "type" => "object", "additionalProperties" => result }, **@meta } }
+        elsif @collection_key
+          { "type" => "object", "additionalProperties" => result }
+        elsif @root_key_for_collection
+          { "type" => "object", "properties" => { @root_key_for_collection => { "type" => "array", "items" => result }, **@meta } }
+        else
+          { "type" => "array", "items" => result }
+        end
+      elsif @root_key
+        result = { "type" => "object", "properties" => { @root_key => result, **@meta } }
+      end
+
+      result = deep_transform_keys(result) if @key_transformer
+
+      result
+    end
+
+    def visit_call_node(node)
+      case node.name
+      when :root_key
+        context = with_context { visit(node.arguments) }
+        @root_key, @root_key_for_collection = context.symbols
+
+      when :attributes, :attribute
+        context = with_context { visit(node.arguments) }
+        context.symbols.each { |symbol| @segment[symbol] = { "type" => "string" } }
+        context.keywords.except("if").each { |key, type| @segment[key] = get_type_definition(type) }
+
+      when :nested, :nested_attribute
+        context = with_context { visit(node.arguments) }
+        with_inner_segment(context.symbols[0]) { visit(node.block) }
+
+      when :meta
+        context = with_context do
+          visit(node.arguments)
+          visit(node.block)
+        end
+
+        key = context.symbols[0] || "meta"
+        unless context.nil
+          @meta = { key => hash_to_openapi_schema(context.hashes[0]) }
+        end
+
+      when :many, :has_many, :one, :has_one, :association
+        is_array = node.name == :many || node.name == :has_many
+        context = with_context { visit(node.arguments) }
+        key = context.keywords["key"] || context.symbols[0]
+
+        if node.block
+          with_inner_segment(key, is_array:) { visit(node.block) }
+        else
+          resource = context.keywords["resource"] || (::Alba.inflector && "#{::Alba.inflector.classify(key.to_s)}Resource")
+          is_valid_resource = @parser.namespace.const_get(resource) rescue false
+
+          @segment[key] = if is_array
+            @parser.__parse_nested(is_valid_resource ? "[#{resource}]" : "[Rage]") # TODO
+          else
+            @parser.__parse_nested(is_valid_resource ? resource : "Rage")
+          end
+        end
+
+      when :transform_keys
+        context = with_context { visit(node.arguments) }
+        @key_transformer = get_key_transformer(context.symbols[0])
+
+      when :collection_key
+        @collection_key = true
+
+      when :root_key!
+        if (inflector = ::Alba.inflector)
+          suffix = @self_name.end_with?("Resource") ? "Resource" : "Serializer"
+          name = inflector.demodulize(@self_name).delete_suffix(suffix)
+          @root_key = inflector.underscore(name)
+          @root_key_for_collection = inflector.pluralize(@root_key) if @is_collection
+        end
+      end
+    end
+
+    def visit_hash_node(node)
+      parsed_hash = YAML.safe_load(node.slice) rescue nil
+      @context.hashes << parsed_hash if parsed_hash
+    end
+
+    def visit_assoc_node(node)
+      value = case node.value
+      when Prism::StringNode
+        node.value.content
+      when Prism::ArrayNode
+        context = with_context { visit(node.value) }
+        context.symbols[0] || context.consts[0]
+      else
+        node.value.slice
+      end
+
+      @context.keywords[node.key.value] = value
+    end
+
+    def visit_constant_read_node(node)
+      return unless @context
+      @context.consts << node.name.to_s
+    end
+
+    def visit_symbol_node(node)
+      @context.symbols << node.value
+    end
+
+    def visit_nil_node(node)
+      @context.nil = true
+    end
+
+    private
+
+    def with_inner_segment(key, is_array: false)
+      prev_segment = @segment
+
+      properties = {}
+      if is_array
+        @segment[key] = { "type" => "array", "items" => { "type" => "object", "properties" => properties } }
+      else
+        @segment[key] = { "type" => "object", "properties" => properties }
+      end
+      @segment = properties
+
+      yield
+      @segment = prev_segment
+    end
+
+    def with_context
+      @prev_contexts << @context if @context
+      @context = VisitorContext.new
+      yield
+      current_context = @context
+      @context = @prev_contexts.pop
+      current_context
+    end
+
+    def hash_to_openapi_schema(hash)
+      return { "type" => "object" } unless hash
+
+      schema = hash.each_with_object({}) do |(key, value), memo|
+        memo[key.to_s] = if value.is_a?(Hash)
+          hash_to_openapi_schema(value)
+        elsif value.is_a?(Array)
+          { "type" => "array", "items" => { "type" => "string" } }
+        else
+          { "type" => "string" }
+        end
+      end
+
+      { "type" => "object", "properties" => schema }
+    end
+
+    def deep_transform_keys(schema)
+      schema.each_with_object({}) do |(key, value), memo|
+        transformed_key = %w(type properties items additionalProperties).include?(key) ? key : @key_transformer.call(key)
+        memo[transformed_key] = value.is_a?(Hash) ? deep_transform_keys(value) : value
+      end
+    end
+
+    def get_key_transformer(transformer_id)
+      return nil unless ::Alba.inflector
+
+      case transformer_id
+      when "camel"
+        ->(key) { ::Alba.inflector.camelize(key) }
+      when "lower_camel"
+        ->(key) { ::Alba.inflector.camelize_lower(key) }
+      when "dash"
+        ->(key) { ::Alba.inflector.dasherize(key) }
+      when "snake"
+        ->(key) { ::Alba.inflector.underscore(key) }
+      end
+    end
+
+    def get_type_definition(type_id)
+      case type_id
+      when "Integer"
+        { "type" => "integer" }
+      when "Boolean", ":Boolean"
+        { "type" => "boolean" }
+      when "Numeric"
+        { "type" => "number" }
+      when "Float"
+        { "type" => "number", "format" => "float" }
+      else
+        { "type" => "string" }
+      end
+    end
+  end
+end

data/lib/rage/openapi/parsers/request.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Rage::OpenAPI::Parsers::Request
+  AVAILABLE_PARSERS = [
+    Rage::OpenAPI::Parsers::SharedReference,
+    Rage::OpenAPI::Parsers::YAML,
+    Rage::OpenAPI::Parsers::Ext::ActiveRecord
+  ]
+
+  def self.parse(request_tag, namespace:)
+    parser = AVAILABLE_PARSERS.find do |parser_class|
+      parser = parser_class.new(namespace:)
+      break parser if parser.known_definition?(request_tag)
+    end
+
+    parser.parse(request_tag) if parser
+  end
+end