meta-api 0.0.1

data/lib/meta/json_schema/support/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ValidationErrors < StandardError
+      attr_reader :errors
+
+      def initialize(errors, message = nil)
+        raise ArgumentError, '参数 errors 应传递一个 Hash' unless errors.is_a?(Hash)
+
+        super(message)
+        @errors = errors
+      end
+
+      def prepend_root(root)
+        errors_prepend_root = errors.transform_keys do |name|
+          return name.to_s if root.empty?
+
+          path = name[0] == '[' ? "#{root}#{name}" : "#{root}.#{name}"
+          path = path[1..] if path[0] == '.'
+          path = path[0..-2] if path[-1] == '.'
+          path
+        end
+        ValidationErrors.new(errors_prepend_root)
+      end
+    end
+
+    class ValidationError < ValidationErrors
+      def initialize(message)
+        super('' => message)
+      end
+
+      def message
+        errors['']
+      end
+    end
+  end
+end

data/lib/meta/json_schema/support/presenters.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    module Presenters
+      @presenter_handlers = []
+
+      class << self
+        def register(presenter_handler)
+          @presenter_handlers << presenter_handler
+        end
+
+        def unregister(presenter_handler)
+          @presenter_handlers.delete(presenter_handler)
+        end
+
+        def present(presenter, value)
+          @presenter_handlers.each do |presenter_handler|
+            next unless presenter_handler.handle?(presenter)
+
+            return presenter_handler.present(presenter, value)
+          end
+        end
+
+        def to_schema_doc(presenter, other_options)
+          @presenter_handlers.each do |presenter_handler|
+            next unless presenter_handler.handle?(presenter)
+
+            return presenter_handler.to_schema_doc(presenter, other_options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/meta/json_schema/support/schema_options.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    module SchemaOptions
+      @default_options = {
+        scope: [],
+        required: false
+      }
+      @allowable_options = (
+        %i[type description in value using default presenter convert scope items] +
+        @default_options.keys + 
+        JsonSchema::Validators.keys
+      ).uniq
+
+      class << self
+        def normalize_to_param_and_render(options)
+          common_opts = (options || {}).dup
+          param_opts = common_opts.delete(:param)
+          render_opts = common_opts.delete(:render)
+
+          param_opts = merge_common_to_stage(common_opts, param_opts)
+          render_opts = merge_common_to_stage(common_opts, render_opts)
+          [param_opts, render_opts]
+        end
+
+        def merge_common_to_stage(common_opts, stage_opts)
+          stage_opts = {} if stage_opts.nil? || stage_opts == true
+          stage_opts = common_opts.merge(stage_opts) if stage_opts
+          stage_opts = normalize(stage_opts) if stage_opts
+          stage_opts
+        end
+
+        def normalize(options)
+          # 只要 options 中设置为 nil 的选项没有明确的意义，则下行代码是永远有效的
+          options = (@default_options.compact).merge(options.compact)
+          options[:scope] = [options[:scope]] unless options[:scope].is_a?(Array)
+          if options[:using]
+            if options[:type].nil?
+              options[:type] = 'object'
+            elsif options[:type] != 'object' && options[:type] != 'array'
+              raise "当使用 using 时，type 必须声明为 object 或 array"
+            end
+          end
+
+          # 处理 validators
+          unknown_validators = options.keys - @allowable_options
+          raise "未知的选项：#{unknown_validators.join(', ')}" unless unknown_validators.empty?
+
+          options
+        end
+      end
+    end
+  end
+end

data/lib/meta/json_schema/support/type_converter.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ObjectWrapper
+      def initialize(target)
+        @target = target
+      end
+
+      def __target__
+        @target
+      end
+
+      def key?(key)
+        @target.respond_to?(key)
+      end
+
+      def [](key)
+        @target.__send__(key)
+      end
+
+      def method_missing(method, *args)
+        @target.__send__(method, *args)
+      end
+    end
+
+    module TypeConverter
+      # 定义客户类型对应的 Ruby 类型
+      @definity_types = {
+        'boolean' => [TrueClass, FalseClass],
+        'integer' => [Integer],
+        'number' => [Integer, Float],
+        'string' => [String],
+        'array' => [Array],
+        'object' => [Hash, ObjectWrapper]
+      }
+
+      # 定义从 Ruby 类型转化为对应类型的逻辑
+      @boolean_converters = {
+        [String] => lambda do |value|
+          unless %w[true True TRUE false False FALSE].include?(value)
+            raise TypeConvertError, "类型转化失败，期望得到一个 `boolean` 类型，但值 `#{value}` 无法转化"
+          end
+
+          value.downcase == 'true'
+        end
+      }
+
+      @integer_converters = {
+        [String] => lambda do |value|
+          # 允许的格式：+34、-34、34、34.0 等
+          unless value =~ /^[+-]?\d+(\.0+)?$/
+            raise TypeConvertError, "类型转化失败，期望得到一个 `integer` 类型，但值 `#{value}` 无法转化"
+          end
+
+          value.to_i
+        end,
+        [Float] => lambda do |value|
+          unless value.to_i == value
+            raise TypeConvertError, "类型转化失败，期望得到一个 `integer` 类型，但值 `#{value}` 无法转化"
+          end
+
+          value.to_i
+        end
+      }
+
+      @number_converters = {
+        [String] => lambda do |value|
+          unless value =~ /^[+-]?\d+(\.\d+)?$/
+            raise TypeConvertError, "类型转化失败，期望得到一个 `number` 类型，但值 `#{value}` 无法转化"
+          end
+
+          float = value.to_f
+          float.to_i == float ? float.to_i : float
+        end
+      }
+
+      @string_converters = {
+        [Object] => lambda do |value|
+          value.to_s
+        end
+      }
+
+      @array_converters = {
+        [Object] => lambda do |value|
+          unless value.respond_to?(:to_a)
+            raise TypeConvertError, "转化为数组类型时期望对象拥有 `to_a` 方法"
+          end
+
+          value.to_a
+        end
+      }
+
+      @object_converters = {
+        [Object] => lambda do |value|
+          if [TrueClass, FalseClass, Integer, Float, String].any? { |ruby_type| value.is_a?(ruby_type) }
+            raise TypeConvertError, "类型转化失败，期望得到一个 `object` 类型，但值 `#{value}` 是一个基本类型"
+          elsif value.is_a?(Array)
+            raise TypeConvertError, "类型转化失败，期望得到一个 `object` 类型，但值 `#{value}` 是一个 `array` 类型"
+          end
+
+          ObjectWrapper.new(value)
+        end
+      }
+
+      class << self
+        def convert_value(value, target_type)
+          return nil if value.nil?
+          raise JsonSchema::TypeConvertError, "未知的目标类型 `#{target_type}`" unless @definity_types.keys.include?(target_type)
+          return value if match_definity_types?(value, target_type)
+
+          convert_to_definity_type(value, target_type)
+        end
+
+        private
+
+          def match_definity_types?(value, target_type)
+            ruby_types = @definity_types[target_type]
+            return ruby_types.any?{ |ruby_type| value.is_a?(ruby_type) }
+          end
+
+          def convert_to_definity_type(value, target_type)
+            converters = instance_variable_get(:"@#{target_type}_converters")
+            converters.each do |ruby_types, converter|
+              if ruby_types.any?{ |ruby_type| value.is_a?(ruby_type) }
+                return converter.call(value)
+              end
+            end
+            raise TypeConvertError, "类型转化失败，期望得到一个 `#{target_type}` 类型，但值 `#{value}` 无法转化"
+          end
+      end
+    end
+
+    class TypeConvertError < StandardError
+    end
+  end
+end

data/lib/meta/json_schema/support/validators.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    module Validators
+      @validators = {
+        validate: proc { |value, p|
+          next if value.nil?
+          p.call(value)
+        },
+        required: proc { |value, options, full_options|
+          next if options == false
+
+          full_options ||= {}
+          options = {} if options == true
+          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.required') if value.nil?
+
+          if full_options[:type] == 'string' && (!options[:allow_empty]) && value.empty?
+            raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.required')
+          end
+          if full_options[:type] == 'array' && (options[:allow_empty] == false) && value.empty?
+            raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.required')
+          end
+        },
+        format: proc { |value, format|
+          next if value.nil?
+          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.format') unless value =~ format
+        },
+        allowable: proc { |value, allowable_values|
+          next if value.nil?
+          raise JsonSchema::ValidationError, I18n.t(:'json_schema.errors.allowable') unless allowable_values.include?(value)
+        }
+      }
+
+      class << self
+        def [](key)
+          @validators[key]
+        end
+
+        def []=(key, validator)
+          @validators[key] = validator
+        end
+
+        def delete(key)
+          @validators.delete(key)
+        end
+
+        def keys
+          @validators.keys
+        end
+      end
+    end
+  end
+end

data/lib/meta/load_i18n.rb

@@ -0,0 +1,8 @@
+require 'pathname'
+require 'i18n'
+require "i18n/backend/fallbacks"
+
+I18n::Backend::Simple.send(:include, I18n::Backend::Fallbacks)
+I18n.fallbacks.map(:'zh-CN' => [:zh, :en])
+
+I18n.load_path << Pathname.new(__dir__).join('../../config/locales/zh-CN.yml')

data/lib/meta/route_dsl/action_builder.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Meta
+  module RouteDSL
+    class ActionBuilder
+      def initialize(&block)
+        @block = block
+      end
+
+      def build
+        @block
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/application_builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative 'route_builder'
+require_relative 'meta_builder'
+
+module Meta
+  module RouteDSL
+    class ApplicationBuilder
+      include MetaBuilder::Delegator
+
+      def initialize(prefix = nil, &block)
+        @mod_prefix = prefix
+        @before_callbacks = []
+        @after_callbacks = []
+        @error_guards = []
+        @meta_builder = MetaBuilder.new
+        @mod_builders = []
+        @shared_mods = []
+
+        instance_exec &block if block_given?
+      end
+
+      def build(parent_path: '', meta: {}, before_callbacks: [], after_callbacks: [])
+        # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
+        meta2 = (meta || {}).merge(@meta_builder.build)
+        if meta[:parameters] && meta2[:parameters]
+          meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
+        end
+
+        # 构建子模块
+        before_callbacks += @before_callbacks
+        after_callbacks = @after_callbacks + after_callbacks
+        mods = @mod_builders.map { |builder| builder.build(parent_path: Utils::Path.join(parent_path, @mod_prefix), meta: meta2, before_callbacks: before_callbacks, after_callbacks: after_callbacks) }
+
+        Application.new(
+          prefix: @mod_prefix,
+          mods: mods,
+          shared_mods: @shared_mods,
+          error_guards: @error_guards
+        )
+      end
+
+      def shared(*mods, &block)
+        @shared_mods += mods
+        @shared_mods << Module.new(&block) if block_given?
+      end
+
+      # 定义路由块
+      def route(path, method = nil, &block)
+        route_builder = RouteDSL::RouteBuilder.new(path, method, &block)
+        @mod_builders << route_builder
+        route_builder
+      end
+
+      # 定义子模块
+      def namespace(path, &block)
+        @mod_builders << ApplicationBuilder.new(path, &block)
+      end
+
+      # 应用另一个模块
+      def apply(builder, tags: nil)
+        @mod_builders << BindingMeta.new(builder, tags ? { tags: tags } : {})
+      end
+
+      # 定义模块内的公共逻辑
+      def before(&block)
+        @before_callbacks << block
+      end
+
+      def after(&block)
+        @after_callbacks << block
+      end
+
+      def rescue_error(error_class, &block)
+        @error_guards << { error_class: error_class, caller: block }
+      end
+
+      # 定义应用到子模块的公共逻辑
+      def meta(&block)
+        @meta_builder.instance_exec &block
+      end
+
+      # 添加 get、post、put、patch、delete 路由方法
+      [:get, :post, :put, :patch, :delete].each do |method|
+        define_method(method) do |path = '', &block|
+          route(path, method, &block)
+        end
+      end
+
+      # 绑定 Meta，绑定的 Meta 会覆盖父级的 Meta，用于 Application.apply 方法
+      class BindingMeta
+        def initialize(builder, meta)
+          @builder = builder
+          @meta = meta
+        end
+
+        def build(parent_path: '', meta: {}, before_callbacks: [], after_callbacks: [])
+          # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
+          meta2 = (meta || {}).merge(@meta)
+          if meta[:parameters] && meta2[:parameters]
+            meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
+          end
+          @builder.build(parent_path: parent_path, meta: meta2, before_callbacks: before_callbacks, after_callbacks: after_callbacks)
+        end
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/chain_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Meta
+  module RouteDSL
+    class ChainBuilder
+      def initialize
+        @blocks = []
+      end
+
+      def build
+        blocks = @blocks
+        proc do
+          blocks.each { |b| instance_exec &b }
+        end
+      end
+
+      def do_any(&block)
+        @blocks << block
+
+        self
+      end
+
+      def resource(&block)
+        do_any {
+          resource = instance_exec(&block)
+
+          raise Errors::ResourceNotFound if resource.nil?
+
+          # 为 execution 添加一个 resource 方法
+          define_singleton_method(:resource) { resource }
+        }
+      end
+
+      def authorize(&block)
+        do_any {
+          permitted = instance_eval(&block)
+          raise Errors::NotAuthorized unless permitted
+        }
+      end
+
+      def set_status(&block)
+        do_any {
+          response.status = instance_exec(&block)
+        }
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/helpers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Meta
+  module RouteDSL
+    module Helpers
+      class << self
+        def join_path(*parts)
+          parts = parts.map { |p| (p || '').delete_prefix('/').delete_suffix('/') }
+          parts = parts.reject { |p| p.nil? || p.empty? }
+          '/' + parts.join('/')
+        end
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/meta_builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'parameters_builder'
+require_relative 'uniformed_params_builder'
+
+module Meta
+  module RouteDSL
+    class MetaBuilder
+      def initialize(&block)
+        @meta = {}
+
+        instance_exec &block if block_given?
+      end
+
+      def build
+        @meta
+      end
+
+      def parameters(&block)
+        @meta[:parameters] = ParametersBuilder.new(&block).build
+      end
+
+      def request_body(options = {}, &block)
+        @meta[:request_body] = JsonSchema::SchemaBuilderTool.build(options, &block)
+      end
+
+      # params 宏是一个遗留的宏，它在一个宏定义块内同时定义 parameters 和 request_body
+      def params(&block)
+        @meta[:parameters], @meta[:request_body] = UniformedParamsBuilder.new(&block).build
+      end
+
+      def status(code, *other_codes, &block)
+        codes = [code, *other_codes]
+        entity_schema = JsonSchema::SchemaBuilderTool.build(&block)
+        @meta[:responses] = @meta[:responses] || {}
+        codes.each { |code| @meta[:responses][code] = entity_schema }
+      end
+
+      [:tags, :title, :description].each do |method_name|
+        define_method(method_name) do |value|
+          @meta[method_name] = value
+        end
+      end
+
+      # 别的模块引入该模块时可直接调用 MetaBuilder 的方法。
+      # 由于该模块是动态实现的，其务必要在 MetaBuilder 类构建完毕后再声明，故而放在文件的最后声明。
+      module Delegator
+        method_names = MetaBuilder.public_instance_methods(false) - ['build']
+        method_names.each do |method_name|
+          define_method(method_name) do |*args, &block|
+            @meta_builder.send(method_name, *args, &block) and self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/parameters_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Meta
+  module RouteDSL
+    class ParametersBuilder
+      def initialize(&block)
+        @parameters = {}
+
+        instance_exec &block if block_given?
+      end
+
+      def param(name, options)
+        options = options.dup
+        op_in = options.delete(:in) || 'query'
+
+        @parameters[name] = { in: op_in, schema: JsonSchema::BaseSchema.new(options) }
+      end
+
+      def build
+        @parameters
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/route_builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../entity'
+require_relative '../application/route'
+require_relative 'helpers'
+require_relative 'chain_builder'
+require_relative 'action_builder'
+require_relative 'meta_builder'
+
+module Meta
+  module RouteDSL
+    class RouteBuilder
+      include MetaBuilder::Delegator
+
+      alias :if_status :status
+
+      def initialize(path = '', method = :all, &block)
+        @path = path || ''
+        @method = method || :all
+        @action_builder = nil
+        @meta_builder = MetaBuilder.new
+
+        instance_exec &block if block_given?
+      end
+
+      def build(parent_path: '', meta: {}, before_callbacks: [], after_callbacks: [])
+        # 合并 meta 时不仅仅是覆盖，比如 parameters 参数需要合并
+        meta2 = (meta || {}).merge(@meta_builder.build)
+        if meta[:parameters] && meta2[:parameters]
+          meta2[:parameters] = meta[:parameters].merge(meta2[:parameters])
+        end
+
+        # 合并 parameters 参数
+        meta2[:parameters] ||= {}
+        path_params = Utils::Path.join(parent_path, @path).split('/')
+          .filter { |part| part =~ /[:*].+/ }
+          .map { |part| part[1..-1].to_sym }
+        path_params.each do |name|
+          unless meta2[:parameters].key?(name)
+            meta2[:parameters][name] = {
+              in: 'path',
+              schema: JsonSchema::BaseSchema.new(required: true)
+            }
+          end
+        end
+
+        # 将 before_callbacks、action、after_callbacks 合并为 actions
+        action = @action_builder&.build
+        actions = before_callbacks + (action ? [action] : []) + after_callbacks
+
+        Route.new(
+          path: @path,
+          method: @method,
+          meta: meta2,
+          actions: actions
+        )
+      end
+
+      def chain
+        @action_builder || @action_builder = ChainBuilder.new
+      end
+
+      def action(&block)
+        @action_builder = ActionBuilder.new(&block)
+      end
+
+      # 将 chain 的方法转交给 ChainBuilder
+      [:do_any, :resource, :authorize, :set_status].each do |method_name|
+        define_method(method_name) do |&block|
+          chain.send(method_name, &block)
+          self
+        end
+      end
+
+      private
+
+      def clone_meta(meta)
+        meta = meta.clone
+        meta[:responses] = meta[:responses].clone if meta[:responses]
+        meta
+      end
+    end
+  end
+end