taro 0.0.0 → 1.0.0

data/lib/taro/rails/declaration_buffer.rb

@@ -0,0 +1,24 @@
+# Buffers api declarations in rails controllers (e.g. `param :foo, ...`)
+# until the next action method is defined (e.g. `def create`).
+module Taro::Rails::DeclarationBuffer
+  def buffered_declaration(controller_class)
+    buffered_declarations[controller_class] ||= Taro::Rails::Declaration.new
+  end
+
+  def buffered_declarations
+    @buffered_declarations ||= {}
+  end
+
+  def apply_buffered_declaration(controller_class, action_name)
+    declaration = pop_buffered_declaration(controller_class)
+    return unless declaration
+
+    declaration.finalize(controller_class:, action_name:)
+
+    Taro::Rails.apply(declaration:, controller_class:, action_name:)
+  end
+
+  def pop_buffered_declaration(controller_class)
+    buffered_declarations.delete(controller_class)
+  end
+end

data/lib/taro/rails/dsl.rb

@@ -0,0 +1,18 @@
+module Taro::Rails::DSL
+  def api(summary, **kwargs)
+    Taro::Rails.buffered_declaration(self).add_info(summary, **kwargs)
+  end
+
+  def param(param_name, **kwargs)
+    Taro::Rails.buffered_declaration(self).add_param(param_name, **kwargs)
+  end
+
+  def returns(field_name = nil, **kwargs)
+    Taro::Rails.buffered_declaration(self).add_return(field_name, **kwargs)
+  end
+
+  def method_added(method_name)
+    Taro::Rails.apply_buffered_declaration(self, method_name)
+    super
+  end
+end

data/lib/taro/rails/generators/install_generator.rb

@@ -0,0 +1,19 @@
+require 'rails/generators'
+require 'rails/generators/base'
+
+class Taro::Rails::Generators::InstallGenerator < ::Rails::Generators::Base
+  desc 'Set up Taro base type files in your Rails app'
+
+  class_option :dir, type: :string, default: "app/types"
+
+  source_root File.expand_path("templates", __dir__)
+
+  # :nocov:
+  def create_type_files
+    Dir["#{self.class.source_root}/**/*.erb"].each do |tmpl|
+      dest_dir = options[:dir].chomp('/')
+      copy_file tmpl, "#{dest_dir}/#{File.basename(tmpl).sub('erb', 'rb')}"
+    end
+  end
+  # :nocov:
+end

data/lib/taro/rails/generators/templates/enum_type.erb

@@ -0,0 +1,4 @@
+# This file is generated by taro so you don't have to inherit from
+# Taro::Types::EnumType directly. You can customize or delete it.
+class EnumType < Taro::Types::EnumType
+end

data/lib/taro/rails/generators/templates/error_type.erb

@@ -0,0 +1,10 @@
+# This file is generated by taro.
+# This and ErrorsType are a starting point for unified error presentation.
+# You can use them to render errors from various sources (ActiveRecord etc.)
+# and render error responses in rescue_from in a consistent way.
+# You can customize these files to fit your needs, or delete them.
+class ErrorType < ObjectType
+  field :attribute, type: 'String', null: true, desc: 'Attribute name'
+  field :code, type: 'String', null: false, method: :type, desc: 'Error code'
+  field :message, type: 'String', null: true, desc: 'Error message'
+end

data/lib/taro/rails/generators/templates/errors_type.erb

@@ -0,0 +1,25 @@
+# This file is generated by taro.
+# This and ErrorType are a starting point for unified error presentation.
+# You can use them to render errors from various sources (ActiveRecord etc.)
+# and render error responses in rescue_from in a consistent way.
+# You can customize these files to fit your needs, or delete them.
+class ErrorsType < Taro::Types::ListType
+  self.item_type = ErrorType
+
+  def coerce_input
+    input_error 'ErrorsType cannot be used as input type'
+  end
+
+  def coerce_response
+    case object.class.name
+    when 'ActiveRecord::Base'
+      super(object.errors.errors)
+    when 'ActiveModel::Errors'
+      super(object.errors)
+    when 'Hash', 'Interactor::Context'
+      super(object[:errors])
+    else # e.g. Array
+      super(object)
+    end
+  end
+end

data/lib/taro/rails/generators/templates/input_type.erb

@@ -0,0 +1,4 @@
+# This file is generated by taro so you don't have to inherit from
+# Taro::Types::InputType directly. You can customize or delete it.
+class InputType < Taro::Types::InputType
+end

data/lib/taro/rails/generators/templates/no_content_type.erb

@@ -0,0 +1,4 @@
+# This file is generated by taro so you can do `NoContentType.render`
+# without using the deeply nested original type. You can customize or delete it.
+class NoContentType < Taro::Types::ObjectTypes::NoContentType
+end

data/lib/taro/rails/generators/templates/object_type.erb

@@ -0,0 +1,4 @@
+# This file is generated by taro so you don't have to inherit from
+# Taro::Types::ObjectType directly. You can customize or delete it.
+class ObjectType < Taro::Types::ObjectType
+end

data/lib/taro/rails/generators/templates/scalar_type.erb

@@ -0,0 +1,4 @@
+# This file is generated by taro so you don't have to inherit from
+# Taro::Types::ScalarType directly. You can customize or delete it.
+class ScalarType < Taro::Types::ScalarType
+end

data/lib/taro/rails/generators.rb

@@ -0,0 +1,3 @@
+module Taro::Rails::Generators
+  Dir[File.join(__dir__, 'generators', '**', '*.rb')].each { |f| require f }
+end

data/lib/taro/rails/normalized_route.rb

@@ -0,0 +1,29 @@
+Taro::Rails::NormalizedRoute = Data.define(:rails_route) do
+  def ignored?
+    verb.to_s.empty? || patch_update?
+  end
+
+  # Journey::Route#verb is a String. Its usually something like 'POST', but
+  # manual matched routes may have e.g. 'GET|POST' (🤢). We only need one copy.
+  def verb
+    rails_route.verb.to_s.scan(/\w+/).sort.last&.downcase
+  end
+
+  # Rails has both PATCH and PUT routes for updates. We only need one copy.
+  def patch_update?
+    verb == 'patch' && rails_route.requirements[:action] == 'update'
+  end
+
+  def openapi_path
+    rails_route.path.spec.to_s.gsub('(.:format)', '').gsub(/:(\w+)/, '{\1}')
+  end
+
+  def path_params
+    openapi_path.scan(/{(\w+)}/).flatten.map(&:to_sym)
+  end
+
+  def endpoint
+    controller, action = rails_route.requirements.values_at(:controller, :action)
+    "#{controller}##{action}"
+  end
+end

data/lib/taro/rails/param_parsing.rb

@@ -0,0 +1,19 @@
+module Taro::Rails::ParamParsing
+  def self.install(controller_class:, action_name:)
+    return unless Taro.config.parse_params
+
+    key = [controller_class, action_name]
+    return if installed[key]
+
+    installed[key] = true
+
+    controller_class.before_action(only: action_name) do
+      declaration = Taro::Rails.declaration_for(self)
+      @api_params = declaration.parse_params(params)
+    end
+  end
+
+  def self.installed
+    @installed ||= {}
+  end
+end

data/lib/taro/rails/railtie.rb

@@ -0,0 +1,15 @@
+class Taro::Rails::Railtie < ::Rails::Railtie
+  initializer("taro") do |app|
+    # The `:action_controller` hook fires for both ActionController::API
+    # and ActionController::Base, executing the block in their context.
+    ActiveSupport.on_load(:action_controller) do
+      extend Taro::Rails::DSL
+    end
+
+    app.reloader.to_prepare do
+      Taro::Rails.reset
+    end
+  end
+
+  rake_tasks { Dir["#{__dir__}/tasks/**/*.rake"].each { |f| load f } }
+end

data/lib/taro/rails/response_validation.rb

@@ -0,0 +1,63 @@
+module Taro::Rails::ResponseValidation
+  def self.install(controller_class:, action_name:)
+    return unless Taro.config.validate_response
+
+    key = [controller_class, action_name]
+    return if installed[key]
+
+    installed[key] = true
+
+    controller_class.around_action(only: action_name) do |_, block|
+      Taro::Types::BaseType.rendering = nil
+      block.call
+      Taro::Rails::ResponseValidation.call(self)
+    ensure
+      Taro::Types::BaseType.rendering = nil
+    end
+  end
+
+  def self.installed
+    @installed ||= {}
+  end
+
+  def self.call(controller)
+    declaration = Taro::Rails.declaration_for(controller)
+    nesting = declaration.return_nestings[controller.status]
+    expected = declaration.returns[controller.status]
+    if nesting
+      # case: `returns :some_nesting, type: 'SomeType'` (ad-hoc return type)
+      check_nesting(controller.response, nesting)
+      expected = expected.fields[nesting].type
+    end
+
+    check_expected_type_was_used(controller, expected)
+  end
+
+  def self.check_nesting(response, nesting)
+    return unless /json/.match?(response.media_type)
+
+    first_key = response.body.to_s[/\A{\s*"([^"]+)"/, 1]
+    first_key == nesting.to_s || raise(Taro::ResponseError, <<~MSG)
+      Expected response to be nested in "#{nesting}" key, but it was not.
+      (First JSON key in response: "#{first_key}".)
+    MSG
+  end
+
+  def self.check_expected_type_was_used(controller, expected)
+    used = Taro::Types::BaseType.rendering
+
+    if expected.nil?
+      raise(Taro::ResponseError, <<~MSG)
+        No matching return type declared in #{controller.class}##{controller.action_name}\
+        for status #{controller.status}.
+      MSG
+    end
+
+    used&.<=(expected) || raise(Taro::ResponseError, <<~MSG)
+      Expected #{controller.class}##{controller.action_name} to use #{expected}.render,
+      but #{used ? "#{used}.render" : 'no type render method'} was called.
+    MSG
+
+    Taro::Types::BaseType.used_in_response = used # for comparisons in specs
+  end
+end

data/lib/taro/rails/route_finder.rb

@@ -0,0 +1,35 @@
+module Taro::Rails::RouteFinder
+  class << self
+    def call(controller_class:, action_name:)
+      endpoint = "#{controller_class.controller_path}##{action_name}"
+      cache[endpoint] || []
+    end
+
+    def clear_cache
+      @cache = nil
+    end
+
+    private
+
+    def cache
+      @cache ||= build_cache
+    end
+
+    def build_cache
+      # Build a Hash like
+      # { 'users#show' } => [#<NormalizedRoute>, #<NormalizedRoute>] }
+      rails_routes.each_with_object({}) do |rails_route, hash|
+        route = Taro::Rails::NormalizedRoute.new(rails_route:)
+        next if route.ignored?
+
+        (hash[route.endpoint] ||= []) << route
+      end
+    end
+
+    def rails_routes
+      # make sure routes are loaded
+      Rails.application.reload_routes! unless Rails.application.routes.routes.any?
+      Rails.application.routes.routes
+    end
+  end
+end

data/lib/taro/rails/tasks/export.rake

@@ -0,0 +1,15 @@
+desc 'Export all taro API declarations to a file'
+task 'taro:export' => :environment do
+  # make sure all declarations have been seen
+  Rails.application.eager_load!
+
+  # the generator / openapi version might become a config option later
+  export = Taro::Export::OpenAPIv3.call(
+    declarations: Taro::Rails.declarations,
+    title: Taro.config.api_name,
+    version: Taro.config.api_version,
+  )
+
+  data = export.result.send("to_#{Taro.config.export_format}")
+  File.write(Taro.config.export_path, data)
+end

data/lib/taro/rails.rb

@@ -0,0 +1,18 @@
+# :nocov:
+return unless defined?(::Rails)
+# :nocov:
+
+module Taro::Rails
+  Dir[File.join(__dir__, "rails", "*.rb")].each { |f| require f }
+
+  extend ActiveDeclarations
+  extend DeclarationBuffer
+
+  def self.reset
+    buffered_declarations.clear
+    declarations_map.clear
+    RouteFinder.clear_cache
+    Taro::Types::BaseType.rendering = nil
+    Taro::Types::BaseType.used_in_response = nil
+  end
+end

data/lib/taro/types/base_type.rb

@@ -0,0 +1,17 @@
+# Abstract base class for all types.
+#
+# Concrete type classes must set `self.openapi_type` and implement
+# the `#coerce_input` and `#coerce_response` methods.
+#
+# Instances of types are initialized with the object that they represent.
+# The object is a parameter hash for inputs and a manually passed hash
+# or object when rendering a response.
+Taro::Types::BaseType = Data.define(:object) do
+  require_relative "shared"
+  extend Taro::Types::Shared::AdditionalProperties
+  extend Taro::Types::Shared::Description
+  extend Taro::Types::Shared::OpenAPIName
+  extend Taro::Types::Shared::OpenAPIType
+  extend Taro::Types::Shared::Rendering
+  include Taro::Types::Shared::Errors
+end

data/lib/taro/types/coercion.rb

@@ -0,0 +1,72 @@
+module Taro::Types::Coercion
+  KEYS = %i[type array_of page_of].freeze
+
+  class << self
+    def call(arg)
+      validate_hash(arg)
+      from_hash(arg)
+    end
+
+    private
+
+    def validate_hash(arg)
+      arg.is_a?(Hash) || raise(Taro::ArgumentError, <<~MSG)
+        Type coercion argument must be a Hash, got: #{arg.inspect} (#{arg.class})
+      MSG
+
+      types = arg.slice(*KEYS)
+      types.size == 1 || raise(Taro::ArgumentError, <<~MSG)
+        Exactly one of type, array_of, or page_of must be given, got: #{types}
+      MSG
+    end
+
+    def from_hash(hash)
+      if hash[:type]
+        from_string(hash[:type])
+      elsif (inner_type = hash[:array_of])
+        from_string(inner_type).array
+      elsif (inner_type = hash[:page_of])
+        from_string(inner_type).page
+      else
+        raise NotImplementedError, 'Unsupported type coercion'
+      end
+    end
+
+    def from_string(arg)
+      shortcuts[arg] || from_class(Object.const_get(arg.to_s))
+    rescue NameError
+      raise Taro::ArgumentError, <<~MSG
+        Unsupported type: #{arg}. It should be a type-class name
+        or one of #{shortcuts.keys.map(&:inspect).join(', ')}.
+      MSG
+    end
+
+    def from_class(arg)
+      arg < Taro::Types::BaseType || raise(Taro::ArgumentError, <<~MSG)
+        Unsupported type: #{arg}. It should be a subclass of Taro::Types::BaseType.
+      MSG
+
+      arg
+    end
+
+    # Map some Ruby class names and other shortcuts to built-in types
+    # to support e.g. `returns 'String'`, or `field :foo, type: 'Boolean'` etc.
+    require 'date'
+    def shortcuts
+      @shortcuts ||= {
+        # rubocop:disable Layout/HashAlignment - buggy cop
+        'Boolean'   => Taro::Types::Scalar::BooleanType,
+        'Float'     => Taro::Types::Scalar::FloatType,
+        'FreeForm'  => Taro::Types::ObjectTypes::FreeFormType,
+        'Integer'   => Taro::Types::Scalar::IntegerType,
+        'String'    => Taro::Types::Scalar::StringType,
+        'Timestamp' => Taro::Types::Scalar::TimestampType,
+        'UUID'      => Taro::Types::Scalar::UUIDv4Type,
+        'Date'      => Taro::Types::Scalar::ISO8601DateType,
+        'Time'      => Taro::Types::Scalar::ISO8601DateTimeType,
+        'DateTime'  => Taro::Types::Scalar::ISO8601DateTimeType,
+        # rubocop:enable Layout/HashAlignment - buggy cop
+      }.freeze
+    end
+  end
+end

data/lib/taro/types/enum_type.rb

@@ -0,0 +1,43 @@
+# Abstract class.
+class Taro::Types::EnumType < Taro::Types::BaseType
+  extend Taro::Types::Shared::ItemType
+
+  def self.value(value)
+    self.item_type = Taro::Types::Coercion.call(type: value.class.name)
+    @openapi_type ||= item_type.openapi_type
+    values << value
+  end
+
+  def self.values
+    @values ||= []
+  end
+
+  def coerce_input
+    self.class.raise_if_empty_enum
+    value = self.class.item_type.new(object).coerce_input
+    if self.class.values.include?(value)
+      value
+    else
+      input_error("must be one of #{self.class.values}")
+    end
+  end
+
+  def coerce_response
+    self.class.raise_if_empty_enum
+    value = self.class.item_type.new(object).coerce_response
+    if self.class.values.include?(value)
+      value
+    else
+      response_error("must be one of #{self.class.values}")
+    end
+  end
+
+  def self.raise_if_empty_enum
+    values.empty? && raise(Taro::RuntimeError, "Enum #{self} has no values")
+  end
+
+  def self.inherited(subclass)
+    subclass.instance_variable_set(:@values, values.dup)
+    super
+  end
+end

data/lib/taro/types/field.rb

@@ -0,0 +1,78 @@
+require_relative 'field_validation'
+
+Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc) do
+  include Taro::Types::FieldValidation
+
+  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil)
+    enum = coerce_to_enum(enum)
+    super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:)
+  end
+
+  def value_for_input(object)
+    value = object[name] if object
+    value = coerce_value(value, true)
+    validated_value(value)
+  end
+
+  def value_for_response(object, context: nil, object_is_hash: true)
+    value = retrieve_response_value(object, context, object_is_hash)
+    value = coerce_value(value, false)
+    validated_value(value, false)
+  end
+
+  def default_specified?
+    !default.equal?(:none)
+  end
+
+  def openapi_type
+    type.openapi_type
+  end
+
+  private
+
+  def coerce_to_enum(arg)
+    return if arg.nil?
+
+    enum = arg.to_a
+    test = Class.new(Taro::Types::EnumType) { arg.each { |v| value(v) } }
+    test.raise_if_empty_enum
+    enum
+  end
+
+  def retrieve_response_value(object, context, object_is_hash)
+    if object_is_hash
+      retrieve_hash_value(object)
+    elsif context&.resolve?(method)
+      context.public_send(method)
+    elsif object.respond_to?(method, true)
+      object.public_send(method)
+    else
+      raise_response_coercion_error(object)
+    end
+  end
+
+  def retrieve_hash_value(object)
+    if object.key?(method.to_s)
+      object[method.to_s]
+    else
+      object[method]
+    end
+  end
+
+  def coerce_value(value, from_input)
+    return if value.nil? && null
+    return default if value.nil? && default_specified?
+
+    type_obj = type.new(value)
+    from_input ? type_obj.coerce_input : type_obj.coerce_response
+  rescue Taro::Error => e
+    raise e.class, "#{e.message}, after using method/key `:#{method}` to resolve field `#{name}`"
+  end
+
+  def raise_response_coercion_error(object)
+    raise Taro::ResponseError, <<~MSG
+      Failed to coerce value #{object.inspect} for field `#{name}` using method/key `:#{method}`.
+      It is not a valid #{type} value.
+    MSG
+  end
+end

data/lib/taro/types/field_validation.rb

@@ -0,0 +1,27 @@
+module Taro::Types::FieldValidation
+  # Validate the value against the field properties. This method will raise
+  # a Taro::InputError or Taro::ResponseError if the value is not matching.
+  def validated_value(value, for_input = true)
+    validate_null_and_ok?(value, for_input)
+    validate_enum_inclusion(value, for_input)
+    value
+  end
+
+  private
+
+  def validate_null_and_ok?(value, for_input)
+    return if null || !value.nil?
+
+    raise for_input ? Taro::InputError : Taro::ResponseError, <<~MSG
+      Field #{name} is not nullable (got #{value.inspect})
+    MSG
+  end
+
+  def validate_enum_inclusion(value, for_input)
+    return if enum.nil? || enum.include?(value)
+
+    raise for_input ? Taro::InputError : Taro::ResponseError, <<~MSG
+      Field #{name} has an invalid value #{value.inspect} (expected one of #{enum.inspect})
+    MSG
+  end
+end

data/lib/taro/types/input_type.rb

@@ -0,0 +1,13 @@
+# Abstract base class for input types, i.e. types without response rendering.
+class Taro::Types::InputType < Taro::Types::BaseType
+  require_relative "shared"
+  extend Taro::Types::Shared::Fields
+  include Taro::Types::Shared::CustomFieldResolvers
+  include Taro::Types::Shared::ObjectCoercion
+
+  self.openapi_type = :object
+
+  def coerce_response
+    response_error 'InputTypes cannot be used as response types'
+  end
+end

data/lib/taro/types/list_type.rb

@@ -0,0 +1,30 @@
+# Abstract base class for List types (arrays in OpenAPI terms).
+# Unlike other types, this one should not be manually inherited from,
+# but is used indirectly via `array_of: SomeType`.
+class Taro::Types::ListType < Taro::Types::BaseType
+  extend Taro::Types::Shared::DerivableType
+  extend Taro::Types::Shared::ItemType
+
+  self.openapi_type = :array
+
+  def coerce_input
+    object.instance_of?(Array) || input_error('must be an Array')
+
+    item_type = self.class.item_type
+    object.map { |el| item_type.new(el).coerce_input }
+  end
+
+  def coerce_response
+    object.respond_to?(:map) || response_error('must be an Enumerable')
+
+    item_type = self.class.item_type
+    object.map { |el| item_type.new(el).coerce_response }
+  end
+end
+
+# add shortcut to other types
+class Taro::Types::BaseType
+  def self.array
+    Taro::Types::ListType.for(self)
+  end
+end

data/lib/taro/types/object_type.rb

@@ -0,0 +1,19 @@
+# Abstract base class for renderable types with fields.
+class Taro::Types::ObjectType < Taro::Types::BaseType
+  require_relative "shared"
+  extend Taro::Types::Shared::Fields
+  include Taro::Types::Shared::CustomFieldResolvers
+  include Taro::Types::Shared::ObjectCoercion
+
+  self.openapi_type = :object
+
+  def self.inherited(subclass)
+    subclass.instance_variable_set(:@response_types, [Hash])
+    subclass.instance_variable_set(:@input_types, [Hash])
+    super
+  end
+end
+
+module Taro::Types::ObjectTypes
+  Dir[File.join(__dir__, 'object_types', '**', '*.rb')].each { |f| require f }
+end

data/lib/taro/types/object_types/free_form_type.rb

@@ -0,0 +1,13 @@
+class Taro::Types::ObjectTypes::FreeFormType < Taro::Types::ObjectType
+  self.desc = 'An arbitrary, unvalidated Hash or JSON object. Use with care.'
+  self.additional_properties = true
+
+  def coerce_input
+    object.is_a?(Hash) && object || input_error('must be a Hash')
+  end
+
+  def coerce_response
+    object.respond_to?(:as_json) && (res = object.as_json).is_a?(Hash) && res ||
+      response_error('must return a Hash from #as_json')
+  end
+end