meta-api 0.0.1

data/lib/meta/application/route.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'execution'
+require_relative 'path_matching_mod'
+require_relative 'meta'
+
+module Meta
+  class Route
+    include PathMatchingMod.new(path_method: :path, matching_mode: :full)
+
+    attr_reader :path, :method, :meta, :actions
+
+    def initialize(path: '', method: :all, meta: {}, actions: [])
+      @path = Utils::Path.normalize_path(path)
+      @method = method
+      @meta = Meta.new(meta)
+      @actions = actions
+    end
+
+    def execute(execution, remaining_path)
+      path_matching.merge_path_params(remaining_path, execution.request)
+
+      # 依次执行这个环境
+      begin
+        execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
+        execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
+
+        actions.each { |b| execution.instance_eval(&b) }
+
+        render_entity(execution) if @meta[:responses]
+      rescue Execution::Abort
+        execution
+      end
+    end
+
+    def match?(execution, remaining_path)
+      request = execution.request
+      remaining_path = '' if remaining_path == '/'
+      method = request.request_method
+
+      return false unless path_matching.match?(remaining_path)
+      return false unless @method == :all || @method.to_s.upcase == method
+      return true
+    end
+
+    private
+
+    def render_entity(execution)
+      responses = @meta[:responses]
+      status = execution.response.status
+      codes = responses.keys
+      return unless codes.include?(status)
+
+      entity_schema = responses[status]
+      execution.render_entity(entity_schema) if entity_schema
+    end
+  end
+end

data/lib/meta/application.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'route_dsl/route_builder'
+require_relative 'route_dsl/application_builder'
+require_relative 'application/application'
+
+# 结构组织如下：
+# - lib/application.rb: 模块实例
+# - route_dsl/application_builder.rb: DSL 语法的 Builder
+# - application.rb(本类): 综合以上两个类q的方法到一个类当中
+module Meta
+  class Application
+    class << self
+      extend Forwardable
+
+      include Execution::MakeToRackMiddleware
+
+      attr_reader :builder
+
+      def inherited(mod)
+        super
+
+        mod.instance_variable_set(:@builder, RouteDSL::ApplicationBuilder.new)
+      end
+
+      # 读取应用的元信息
+      def_delegators :app, :prefix, :routes, :applications, :execute, :to_swagger_doc
+
+      # DSL 调用委托给内部 Builder
+      builder_methods = (RouteDSL::ApplicationBuilder.public_instance_methods(false) - ['build'])
+      def_delegators :builder, *builder_methods
+
+      def app
+        @app || @app = builder.build
+      end
+
+      def build(**args)
+        @app = builder.build(**args)
+      end
+    end
+  end
+end

data/lib/meta/entity.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'errors'
+require_relative 'json_schema/schemas'
+
+# Meta::Entity 是 ObjectSchemaBuilder 的一个类封装，它不应有自己的逻辑
+module Meta
+  class Entity
+    class << self
+      extend Forwardable
+
+      attr_reader :schema_builder
+
+      def inherited(base)
+        base.instance_eval do
+          @schema_builder = JsonSchema::ObjectSchemaBuilder.new
+          @schema_builder.schema_name(proc { |locked_scope, stage|
+            generate_schema_name(locked_scope, stage)
+          })
+        end
+      end
+
+      def_delegators :schema_builder, :property, :param, :expose, :use, :lock, :locked, :schema_name, :to_schema
+
+      def method_missing(method, *args)
+        if method =~ /^lock_(\w+)$/
+          schema_builder.send(method, *args)
+        else
+          super
+        end
+      end
+
+      private
+
+      def generate_schema_name(stage, locked_scopes)
+        # 匿名类不考虑自动生成名称
+        return nil unless self.name
+
+        schema_name = self.name.gsub('::', '_')
+        schema_name = schema_name.delete_suffix('Entity') unless schema_name == 'Entity'
+
+        # 先考虑 stage
+        case stage
+        when :param
+          schema_name += 'Params'
+        when :render
+          schema_name += 'Entity'
+        end
+
+        # 再考虑 locked_scope
+        scope_suffix = locked_scopes.join('_')
+        schema_name = "#{schema_name}_#{scope_suffix}" unless scope_suffix.empty?
+
+        schema_name
+      end
+    end
+  end
+end

data/lib/meta/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'json_schema/schemas'
+
+module Meta
+  module Errors
+    class NoMatchingRoute < StandardError; end
+
+    class ParameterInvalid < JsonSchema::ValidationErrors
+      def initialize(errors)
+        super(errors, "参数异常：#{errors}")
+      end
+    end
+
+    class RenderingInvalid < JsonSchema::ValidationErrors
+      def initialize(errors)
+        super(errors, "渲染实体异常：#{errors}")
+      end
+    end
+
+    class RenderingError < StandardError; end
+
+    class NotAuthorized < StandardError; end
+
+    class ResourceNotFound < StandardError; end
+
+    class UnsupportedContentType < StandardError; end
+  end
+end

data/lib/meta/json_schema/builders/array_schema_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ArraySchemaBuilder
+      def initialize(options, &block)
+        raise 'type 选项必须是 array' if !options[:type].nil? && options[:type] != 'array'
+
+        options = options.merge(type: 'array')
+        @options = options
+
+        items_options = options.delete(:items) || {}
+        if object_property?(items_options, block)
+          @items = ObjectSchemaBuilder.new(items_options, &block).to_schema
+        else
+          @items = BaseSchema.new(items_options)
+        end
+      end
+
+      def to_schema
+        ArraySchema.new(@items, @options)
+      end
+
+      def object_property?(options, block)
+        (options && !options[:properties].nil?) || !block.nil?
+      end
+    end
+  end
+end

data/lib/meta/json_schema/builders/object_schema_builder.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ObjectSchemaBuilder
+      def initialize(options = {}, &)
+        raise 'type 选项必须是 object' if !options[:type].nil? && options[:type] != 'object'
+
+        @properties = {}
+        @required = []
+        @validations = {}
+
+        options = options.merge(type: 'object')
+        properties = options.delete(:properties)
+        @options = options
+
+        properties&.each do |name, property_options|
+          property name, property_options
+        end
+
+        instance_exec(&) if block_given?
+      end
+
+      # 设置 schema_name.
+      #
+      # 一、可以传递一个块，该块会接收 locked_scope 参数，需要返回一个带有 param 和 render 键的 Hash.
+      # 二、可以传递一个 Hash，它包含 param 和 render 键。
+      # 三、可以传递一个字符串。
+      def schema_name(schema_name_resolver)
+        if schema_name_resolver.is_a?(Proc)
+          @schema_name_resolver = schema_name_resolver
+        elsif schema_name_resolver.is_a?(Hash)
+          @schema_name_resolver = proc { |stage, locked_scopes| schema_name_resolver[stage] }
+        elsif schema_name_resolver.is_a?(String)
+          @schema_name_resolver = proc { |stage, locked_scopes| schema_name_resolver }
+        elsif schema_name_resolver.nil?
+          @schema_name_resolver = proc { nil }
+        else
+          raise TypeError, "schema_name_resolver 必须是一个 Proc、Hash 或 String，当前是：#{schema_name_resolver.class}"
+        end
+      end
+
+      def property(name, options = {}, &block)
+        name = name.to_sym
+        options = options.dup
+
+        # 能且仅能 ObjectSchemaBuilder 内能使用 using 选项
+        block = options[:using] unless block_given?
+        if block.nil? || block.is_a?(Proc)
+          @properties[name] = SchemaBuilderTool.build(options, &block)
+        elsif block.respond_to?(:to_schema)
+          schema = block.to_schema
+          if options[:type] == 'array'
+            @properties[name] = ArraySchema.new(schema, options)
+          else
+            @properties[name] = schema.dup(options)
+          end
+        else
+          raise "非法的参数。应传递代码块，或通过 using 选项传递 Proc、ObjectScope 或接受 `to_schema` 方法的对象。当前传递：#{block}"
+        end
+      end
+
+      alias expose property
+      alias param property
+
+      # 能且仅能 ObjectSchemaBuilder 内能使用 use 方法
+      def use(proc)
+        proc = proc.to_proc if proc.respond_to?(:to_proc)
+        instance_exec(&proc)
+      end
+
+      def to_schema(locked_options = nil)
+        ObjectSchema.new(properties: @properties, object_validations: @validations, options: @options, locked_options: locked_options, schema_name_resolver: @schema_name_resolver)
+      end
+
+      def lock(key, value)
+        locked(key => value)
+      end
+
+      def locked(options)
+        Locked.new(self, options)
+      end
+
+      private
+
+      def apply_array_scope?(options, block)
+        options[:type] == 'array' && (options[:items] || block)
+      end
+
+      def apply_object_scope?(options, block)
+        (options[:type] == 'object' || block) && (options[:properties] || block)
+      end
+
+      def method_missing(method, *args)
+        if method =~ /^lock_(\w+)$/
+          key = Regexp.last_match(1)
+          lock(key.to_sym, *args)
+        else
+          super
+        end
+      end
+
+      class Locked
+        attr_reader :builder, :locked_options
+
+        def initialize(builder, locked_options)
+          @builder = builder
+          @locked_options = locked_options
+        end
+
+        # 当调用 Entity.locked 方法后，生成 schema 的方法会掉到这里面来。
+        # 在生成 schema 时，locked_options 会覆盖；当生成 schema 文档时，由于缺失 schema_name 的
+        # 信息，故而 schema_name 相关的影响就消失不见了。
+        def to_schema
+          builder.to_schema(locked_options)
+        end
+      end
+    end
+  end
+end

data/lib/meta/json_schema/builders/schema_builder_tool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class SchemaBuilderTool
+      class << self
+        def build(options = {}, &block)
+          if apply_array_schema?(options, block)
+            ArraySchemaBuilder.new(options, &block).to_schema
+          elsif apply_object_schema?(options, block)
+            ObjectSchemaBuilder.new(options, &block).to_schema
+          else
+            BaseSchema.new(options)
+          end
+        end
+
+        private
+
+        def apply_array_schema?(options, block)
+          options[:type] == 'array' && (options[:items] || block)
+        end
+
+        def apply_object_schema?(options, block)
+          (options[:type] == 'object' || options[:type].nil?) && (options[:properties] || block)
+        end
+      end
+    end
+  end
+end

data/lib/meta/json_schema/schemas/array_schema.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ArraySchema < BaseSchema
+      attr_reader :items
+
+      def initialize(items, options = {})
+        super(options)
+
+        @items = items
+      end
+
+      def filter(array_value, options = {})
+        array_value = super(array_value, options)
+        return nil if array_value.nil?
+        raise ValidationError.new('参数应该传递一个数组') unless array_value.respond_to?(:each_with_index)
+
+        array_value.each_with_index.map do |item, index|
+          begin
+            @items.filter(item, **options)
+          rescue ValidationErrors => e
+            raise e.prepend_root("[#{index}]")
+          end
+        end
+      end
+
+      def to_schema_doc(user_options = {})
+        stage_options = user_options[:stage] == :param ? @param_options : @render_options
+
+        schema = {
+          type: 'array',
+          items: @items ? @items.to_schema_doc(user_options) : {}
+        }
+        schema[:description] = stage_options[:description] if stage_options[:description]
+        schema
+      end
+    end
+  end
+end

data/lib/meta/json_schema/schemas/base_schema.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative '../support/schema_options'
+
+module Meta
+  module JsonSchema
+    class BaseSchema
+      # `options` 包含了转换器、验证器、文档、选项。
+      #
+      # 由于本对象可继承，基于不同的继承可分别表示基本类型、对象和数组，所以该属
+      # 性可用在不同类型的对象上。需要时刻留意的是，无论是用在哪种类型的对象内，
+      # `options` 属性都是描述该对象的本身，而不是深层的属性。
+      #
+      # 较常出现错误的是数组，`options` 是描述数组的，而不是描述数组内部元素的。
+      attr_reader :param_options, :render_options
+
+      # 传递 path 参数主要是为了渲染 Parameter 文档时需要
+      def initialize(options = {})
+        @param_options, @render_options = SchemaOptions.normalize_to_param_and_render(options)
+      end
+
+      def options(stage, key = nil)
+        stage_options = case stage 
+                        when :param 
+                          param_options
+                        when :render
+                          render_options
+                        when nil
+                          merged_options
+                        else
+                          raise "非法的 stage 参数，它只允许取值 :param、:render 或 nil，却收到 #{stage.inspect}"
+                        end
+        if key
+          stage_options ? stage_options[key] : nil
+        else
+          stage_options
+        end
+      end
+
+      # 将 params 和 render 的选项合并
+      def merged_options
+        (param_options || {}).merge(render_options || {})
+      end
+
+      def filter(value, user_options = {})
+        stage_options = options(user_options[:stage])
+
+        value = resolve_value(user_options) if stage_options[:value]
+        value = JsonSchema::Presenters.present(stage_options[:presenter], value) if stage_options[:presenter]
+        value = stage_options[:default] if value.nil? && stage_options.key?(:default)
+        value = stage_options[:convert].call(value) if stage_options[:convert]
+
+        # 这一步转换值。需要注意的是，对象也可能被转换，因为并没有深层次的结构被声明。
+        type = stage_options[:type]
+        unless type.nil? || value.nil?
+          begin
+            value = JsonSchema::TypeConverter.convert_value(value, type)
+          rescue JsonSchema::TypeConvertError => e
+            raise JsonSchema::ValidationError.new(e.message)
+          end
+        end
+
+        validate!(value, stage_options)
+
+        value
+      end
+
+      def value?(stage)
+        options(stage, :value) != nil
+      end
+
+      def resolve_value(user_options)
+        value_proc = options(user_options[:stage], :value)
+        value_proc_params = (value_proc.lambda? && value_proc.arity == 0) ?  [] : [user_options[:object_value]]
+
+        if user_options[:execution]
+          user_options[:execution].instance_exec(*value_proc_params, &value_proc)
+        else
+          value_proc.call(*value_proc_params)
+        end
+      end
+
+      def to_schema_doc(user_options = {})
+        stage_options = options(user_options[:stage])
+
+        return Presenters.to_schema_doc(stage_options[:presenter], stage_options) if stage_options[:presenter]
+
+        schema = {}
+        schema[:type] = stage_options[:type] if stage_options[:type]
+        schema[:description] = stage_options[:description] if stage_options[:description]
+        schema[:enum] = stage_options[:allowable] if stage_options[:allowable]
+
+        schema
+      end
+
+      def to_schema
+        self
+      end
+
+      private
+
+        def validate!(value, stage_options)
+          stage_options.each do |key, option|
+            validator = JsonSchema::Validators[key]
+            validator&.call(value, option, stage_options)
+          end
+        end
+    end
+  end
+end

data/lib/meta/json_schema/schemas/object_schema.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ObjectSchema < BaseSchema
+      attr_reader :properties, :object_validations, :locked_options
+
+      def initialize(properties: {}, object_validations: {}, options: {}, locked_options: {}, schema_name_resolver: proc { nil })
+        super(options)
+
+        @properties = properties || {}
+        @object_validations = object_validations || {}
+        @locked_options = locked_options || {}
+        @schema_name_resolver = schema_name_resolver || proc { nil }
+      end
+
+      # 复制一个新的 ObjectSchema，只有 options 不同
+      def dup(options)
+        self.class.new(
+          properties: properties,
+          object_validations: object_validations,
+          options: options,
+          locked_options: locked_options,
+          schema_name_resolver: @schema_name_resolver
+        )
+      end
+
+      def filter(object_value, user_options = {})
+        # 合并 user_options
+        user_options = user_options.merge(locked_options) if locked_options
+
+        object_value = super(object_value, user_options)
+        return nil if object_value.nil?
+
+        # 第一步，根据 user_options[:scope] 需要过滤一些字段
+        # user_options[:scope] 应是一个数组
+        user_scope = user_options[:scope] || []
+        user_scope = [user_scope] unless user_scope.is_a?(Array)
+        stage = user_options[:stage]
+        exclude = user_options.delete(:exclude) # 这里删除 exclude 选项
+        filtered_properties = @properties.filter do |name, property_schema|
+          # 通过 discard_missing 过滤
+          next false if user_options[:discard_missing] && !object_value.key?(name.to_s)
+
+          # 通过 stage 过滤。
+          property_schema_options = property_schema.options(stage)
+          next false unless property_schema_options
+
+          # 通过 locked_exclude 选项过滤
+          next false if exclude && exclude.include?(name)
+
+          # 通过 scope 过滤
+          scope_option = property_schema_options[:scope]
+          next true if scope_option.empty?
+          next false if user_scope.empty?
+          (user_scope - scope_option).empty? # user_scope 应被消耗殆尽
+        end
+
+        # 第二步，递归过滤每一个属性
+        object = {}
+        errors = {}
+        filtered_properties.each do |name, property_schema|
+          value = resolve_property_value(object_value, name, property_schema, stage)
+
+          begin
+            object[name] = property_schema.filter(value, **user_options, object_value: object_value)
+          rescue JsonSchema::ValidationErrors => e
+            errors.merge! e.prepend_root(name).errors
+          end
+        end.to_h
+
+        if errors.empty?
+          object
+        else
+          raise JsonSchema::ValidationErrors.new(errors)
+        end
+      end
+
+      # 合并其他的属性，并返回一个新的 ObjectSchema
+      def merge(properties)
+        ObjectSchema.new(properties: self.properties.merge(properties))
+      end
+
+      # 生成 Swagger 文档的 schema 格式。
+      #
+      # 选项：
+      # - stage: 传递 :param 或 :render
+      # - schemas: 用于保存已经生成的 Schema
+      # - to_ref: 是否生成 $ref 格式，默认为“是”
+      #
+      # 提示：
+      # > 每个 ObjectSchema 拥有一个 @schema_name_resolver 实例变量，如果由它解析出来的名称不为 nil，
+      # > 则该 Schema 生成文档时会使用 $ref 格式。除非 to_ref 选项设置为 false.
+      #
+      def to_schema_doc(user_options)
+        stage = user_options[:stage]
+        # HACK: 标准化选项的工作进行得怎样？
+        locked_scopes = (locked_options || {})[:scope] || []
+        locked_scopes = [locked_scopes] unless locked_scope.nil? && locked_scopes.is_a?(Array)
+        schema_name = @schema_name_resolver.call(stage, locked_scopes)
+        if schema_name && user_options[:to_ref] != false
+          # 首先将 Schema 写进 schemas 选项中去
+          schemas = user_options[:schemas]
+          unless schemas.key?(schema_name)
+            schemas[schema_name] = nil # 首先设置 schemas 防止出现无限循环
+            schemas[schema_name] = to_schema_doc(**user_options, to_ref: false) # 原地修改 schemas，无妨
+          end
+
+          return { '$ref': "#/components/schemas/#{schema_name}" }
+        end
+
+        stage_options = options(stage)
+        properties = @properties.filter do |name, property_schema|
+          # 根据 stage 过滤
+          next false if stage.nil?
+          next false if stage == :param && !property_schema.options(:param)
+          next false if stage == :render && !property_schema.options(:render)
+
+          # 根据 locked_scope 过滤
+          next true if locked_scopes.empty? # locked_scope 未提供时不过滤
+          property_scope = property_schema.options(stage, :scope)
+          property_scope = [property_scope] unless property_scope.is_a?(Array)
+          next true if property_scope.empty?
+          (locked_scopes - property_scope).empty? # user_scope 应被消耗殆尽
+        end
+        required_keys = properties.filter do |key, property_schema|
+          property_schema.options(stage, :required)
+        end.keys
+        properties = properties.transform_values do |property_schema|
+          property_schema.to_schema_doc(**user_options, to_ref: true)
+        end
+
+        schema = { type: 'object' }
+        schema[:description] = stage_options[:description] if stage_options[:description]
+        schema[:properties] = properties unless properties.empty?
+        schema[:required] = required_keys unless required_keys.empty?
+        schema
+      end
+
+      def locked_scope
+        locked_options && locked_options[:scope]
+      end
+
+      def locked_exclude
+        locked_options && locked_options[:exclude]
+      end
+
+      private
+
+        def resolve_property_value(object_value, name, property_schema, stage)
+          if property_schema.value?(stage)
+            nil
+          elsif object_value.is_a?(Hash) || object_value.is_a?(ObjectWrapper)
+            object_value.key?(name.to_s) ? object_value[name.to_s] : object_value[name.to_sym]
+          else
+            raise "不应该还有其他类型了，已经在类型转换中将其转换为 Meta::JsonSchema::ObjectWrapper 了"
+          end
+        end
+    end
+  end
+end

data/lib/meta/json_schema/schemas.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'support/errors'
+require_relative 'support/type_converter'
+require_relative 'support/validators'
+require_relative 'support/presenters'
+require_relative 'schemas/base_schema'
+require_relative 'schemas/object_schema'
+require_relative 'schemas/array_schema'
+require_relative 'builders/object_schema_builder'
+require_relative 'builders/array_schema_builder'
+require_relative 'builders/schema_builder_tool'