taro 1.4.0 → 2.0.0

data/lib/taro/rails/declaration.rb

@@ -1,122 +1,17 @@
-class Taro::Rails::Declaration
-  attr_reader :desc, :summary, :params, :return_defs, :return_descriptions, :return_nestings, :routes, :tags
-
-  def initialize
-    @params = Class.new(Taro::Types::InputType)
-    @return_defs = {}
-    @return_descriptions = {}
-    @return_nestings = {}
-  end
-
-  def add_info(summary, desc: nil, tags: nil)
-    summary.is_a?(String) || raise(Taro::ArgumentError, 'api summary must be a String')
-    @summary = summary
-    @desc = desc
-    @tags = Array(tags) if tags
-  end
-
-  def add_param(param_name, **kwargs)
-    kwargs[:defined_at] = caller_locations(1..2)[1]
-    @params.field(param_name, **kwargs)
-  end
-
-  def add_return(nesting = nil, code:, desc: nil, **kwargs)
-    status = self.class.coerce_status_to_int(code)
-    raise_if_already_declared(status)
-
-    kwargs[:nesting] = nesting
-    check_return_kwargs(kwargs)
-
-    kwargs[:defined_at] = caller_locations(1..2)[1]
-    return_defs[status] = kwargs
-
-    # response desc is required in openapi 3 – fall back to status code
-    return_descriptions[status] = desc || code.to_s
-
-    # if a field name is provided, the response should be nested
-    return_nestings[status] = nesting if nesting
-  end
-
-  # Return types are evaluated lazily to avoid unnecessary autoloading
-  # of all types in dev/test envs.
-  def returns
-    @returns ||= evaluate_return_defs
-  end
-
-  def raise_if_already_declared(status)
-    return_defs[status] &&
-      raise(Taro::ArgumentError, "response for status #{status} already declared")
-  end
-
-  def parse_params(rails_params)
-    params.new(rails_params.to_unsafe_h).coerce_input
-  end
+class Taro::Rails::Declaration < Taro::Declaration
+  attr_reader :controller_class, :action_name
 
   def finalize(controller_class:, action_name:)
-    routes = Taro::Rails::RouteFinder.call(controller_class:, action_name:)
-    routes.any? || raise_missing_route(controller_class, action_name)
-    self.routes = routes
-  end
-
-  def routes=(arg)
-    arg.is_a?(Array) || raise(Taro::ArgumentError, 'routes must be an Array')
-    @routes = arg
-  end
-
-  def polymorphic_route?
-    routes.size > 1
-  end
-
-  require 'rack'
-  def self.coerce_status_to_int(status)
-    # support using http status numbers directly
-    return status if ::Rack::Utils::SYMBOL_TO_STATUS_CODE.key(status)
-
-    # support using symbols, but coerce them to numbers
-    ::Rack::Utils::SYMBOL_TO_STATUS_CODE[status] ||
-      raise(Taro::ArgumentError, "Invalid status: #{status.inspect}")
-  end
-
-  private
-
-  def check_return_kwargs(kwargs)
-    # For nested returns, evaluate_return_def calls ::field, which validates
-    # field options, but does not trigger type autoloading.
-    return evaluate_return_def(**kwargs) if kwargs[:nesting]
-
-    if kwargs.key?(:null)
-      raise Taro::ArgumentError, <<~MSG
-        `null:` is not supported for top-level returns. If you want a nullable return
-        value, nest it, e.g. `returns :str, type: 'String', null: true`.
-      MSG
-    end
-
-    bad_keys = kwargs.keys - (Taro::Types::Coercion.keys + %i[code desc nesting])
-    return if bad_keys.empty?
-
-    raise Taro::ArgumentError, "Invalid `returns` options: #{bad_keys.join(', ')}"
-  end
-
-  def evaluate_return_defs
-    return_defs.transform_values { |defi| evaluate_return_def(**defi) }
-  end
-
-  def evaluate_return_def(nesting:, **kwargs)
-    if nesting
-      # ad-hoc return type, requiring the actual return type to be nested
-      Class.new(Taro::Types::ObjectType).tap do |type|
-        type.field(nesting, null: false, **kwargs)
-      end
-    else
-      Taro::Types::Coercion.call(kwargs)
-    end
+    @controller_class = controller_class
+    @action_name = action_name
+    @params.define_name("InputType(#{endpoint})")
   end
 
-  def raise_missing_route(controller_class, action_name)
-    raise(Taro::ArgumentError, "No route found for #{controller_class}##{action_name}")
+  def endpoint
+    action_name && "#{controller_class}##{action_name}"
   end
 
-  def <=>(other)
-    routes.first.openapi_operation_id <=> other.routes.first.openapi_operation_id
+  def routes
+    @routes ||= Taro::Rails::RouteFinder.call(controller_class:, action_name:)
   end
 end

data/lib/taro/rails/declaration_buffer.rb

@@ -2,7 +2,8 @@
 # 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
+    buffered_declarations[controller_class] ||=
+      Taro::Rails::Declaration.new(controller_class)
   end
 
   def buffered_declarations

data/lib/taro/rails/dsl.rb

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

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

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

data/lib/taro/rails/generators.rb

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

data/lib/taro/rails/normalized_route.rb

@@ -1,49 +1,31 @@
-Taro::Rails::NormalizedRoute = Data.define(:rails_route) do
-  def ignored?
-    verb.to_s.empty? || patch_update?
-  end
+require_relative '../route'
 
-  # 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
+class Taro::Rails::NormalizedRoute < Taro::Route
+  def initialize(rails_route)
+    action, controller = rails_route.requirements.values_at(:action, :controller)
+    # 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.
+    verb = rails_route.verb.to_s.scan(/\w+/).sort.last.to_s.downcase
+    openapi_operation_id = "#{verb}_#{action}_#{controller}".gsub('/', '__')
+    openapi_path = rails_route.path.spec.to_s.gsub('(.:format)', '').gsub(/:(\w+)/, '{\1}')
+    endpoint = "#{controller}##{action}"
 
-  def openapi_operation_id
-    "#{verb}_#{action}_#{controller.gsub('/', '__')}"
+    super(endpoint:, openapi_operation_id:, openapi_path:, verb:)
   end
 
-  def path_params
-    openapi_path.scan(/{(\w+)}/).flatten.map(&:to_sym)
-  end
-
-  def endpoint
-    "#{controller}##{action}"
-  end
-
-  def action
-    rails_route.requirements[:action]
+  def ignored?
+    internal? || patch_update?
   end
 
-  def controller
-    rails_route.requirements[:controller]
-  end
+  private
 
-  def can_have_request_body?
-    %w[patch post put].include?(verb)
+  # Internal routes of rails sometimes have no verb.
+  def internal?
+    verb.empty?
   end
 
-  def inspect
-    %(#<#{self.class} "#{verb} #{openapi_path}">)
+  # Rails has both PATCH and PUT routes for updates. We only need one copy.
+  def patch_update?
+    verb == 'patch' && endpoint.end_with?('#update')
   end
-  alias to_s inspect
 end

data/lib/taro/rails/param_parsing.rb

@@ -7,9 +7,11 @@ module Taro::Rails::ParamParsing
 
     installed[key] = true
 
-    controller_class.before_action(only: action_name) do
-      declaration = Taro::Rails.declaration_for(self)
-      @api_params = declaration.parse_params(params)
+    controller_class.prepend_before_action(only: action_name) do
+      declaration = Taro::Rails.declaration_for(self) || raise(
+        Taro::InvariantError, "missing Declaration for #{controller_class}##{action_name}"
+      )
+      @api_params = declaration.params.new(params.to_unsafe_h).coerce_input
     end
   end
 

data/lib/taro/rails/response_validator.rb

@@ -4,62 +4,67 @@ Taro::Rails::ResponseValidator = Struct.new(:controller, :declaration, :rendered
   end
 
   def call
-    if declared_return_type < Taro::Types::ScalarType
-      check_scalar
-    elsif declared_return_type < Taro::Types::ListType &&
-          declared_return_type.item_type < Taro::Types::ScalarType
-      check_scalar_array
-    elsif declared_return_type < Taro::Types::EnumType
-      check_enum
+    if declared_return_type.nil?
+      fail_if_declaration_expected
+    elsif declared_return_type < Taro::Types::NestedResponseType
+      field = declared_return_type.nesting_field
+      check(field.type, denest_rendered(field.name))
     else
-      check_custom_type
+      check(declared_return_type, rendered)
     end
   end
 
   def declared_return_type
-    @declared_return_type ||= begin
-      return_type = declaration.returns[controller.status] ||
-                    fail_with('No return type declared for this status.')
-      nesting ? return_type.fields.fetch(nesting).type : return_type
-    end
+    @declared_return_type ||= declaration.returns[controller.status]
+  end
+
+  # Rack, Rails and gems commonly trigger rendering of 400, 404, 500 etc.
+  # Declaring these codes should be optional. Otherwise the api schema would get
+  # bloated as there are no "global" return declarations in OpenAPI v3, and we'd
+  # need to export all of these for every single endpoint. v4 might change this.
+  # https://github.com/OAI/OpenAPI-Specification/issues/521
+  def fail_if_declaration_expected
+    controller.status.to_s.match?(/^[123]|422/) && fail_with(<<~MSG)
+      No return type declared for this status.
+    MSG
   end
 
   def fail_with(message)
-    raise Taro::ResponseError, <<~MSG
+    raise Taro::ResponseError.new(<<~MSG, rendered, self)
       Response validation error for
       #{controller.class}##{controller.action_name}, code #{controller.status}":
       #{message}
     MSG
   end
 
-  # support `returns :some_nesting, type: 'SomeType'` (ad-hoc return type)
-  def nesting
-    @nesting ||= declaration.return_nestings[controller.status]
-  end
-
-  def denest_rendered
-    assert_rendered_is_a_hash
+  # support `returns :some_nesting, type: 'SomeType'`
+  # used like `render json: { some_nesting: SomeType.render(some_object) }`
+  def denest_rendered(nesting)
+    rendered.is_a?(Hash) || fail_with("Expected Hash, got #{rendered.class}.")
 
     if rendered.key?(nesting)
       rendered[nesting]
-    elsif rendered.key?(nesting.to_s)
-      rendered[nesting.to_s]
     else
-      fail_with_nesting_error
+      fail_with "Expected key :#{nesting}, got: #{rendered.keys}."
     end
   end
 
-  def assert_rendered_is_a_hash
-    rendered.is_a?(Hash) || fail_with("Expected Hash, got #{rendered.class}.")
-  end
-
-  def fail_with_nesting_error
-    fail_with "Expected key :#{nesting}, got: #{rendered.keys}."
+  def check(type, value)
+    if type < Taro::Types::ScalarType
+      check_scalar(type, value)
+    elsif type < Taro::Types::ListType &&
+          type.item_type < Taro::Types::ScalarType
+      check_scalar_array(type, value)
+    elsif type < Taro::Types::EnumType
+      check_enum(type, value)
+    else
+      check_custom_type(type, value)
+    end
   end
 
   # For scalar and enum types, we want to support e.g. `render json: 42`,
   # and not require using the type as in `BeautifulNumbersEnum.render(42)`.
-  def check_scalar(type = declared_return_type, value = subject)
+  def check_scalar(type, value)
     case type.openapi_type
     when :integer, :number then value.is_a?(Numeric)
     when :string           then value.is_a?(String) || value.is_a?(Symbol)
@@ -67,18 +72,14 @@ Taro::Rails::ResponseValidator = Struct.new(:controller, :declaration, :rendered
     end || fail_with("Expected a #{type.openapi_type}, got: #{value.class}.")
   end
 
-  def subject
-    @subject ||= nesting ? denest_rendered : rendered
-  end
-
-  def check_scalar_array
-    subject.is_a?(Array) || fail_with('Expected an Array.')
-    subject.empty? || check_scalar(declared_return_type.item_type, subject.first)
+  def check_scalar_array(type, value)
+    value.is_a?(Array) || fail_with('Expected an Array.')
+    value.empty? || check_scalar(type.item_type, value.first)
   end
 
-  def check_enum
+  def check_enum(type, value)
     # coercion checks non-emptyness + enum match
-    declared_return_type.new(subject).coerce_response
+    type.new(value).coerce_response
   rescue Taro::Error => e
     fail_with(e.message)
   end
@@ -86,23 +87,23 @@ Taro::Rails::ResponseValidator = Struct.new(:controller, :declaration, :rendered
   # For complex/object types, we ensure conformance by checking whether
   # the type was used for rendering. This has performance benefits compared
   # to going over the structure a second time.
-  def check_custom_type
+  def check_custom_type(type, value)
     # Ignore types without a specified structure.
-    return if declared_return_type <= Taro::Types::ObjectTypes::FreeFormType
-    return if declared_return_type <= Taro::Types::ObjectTypes::NoContentType
+    return if type <= Taro::Types::ObjectTypes::FreeFormType
+    return if type <= Taro::Types::ObjectTypes::NoContentType
 
-    strict_check_custom_type
+    strict_check_custom_type(type, value)
   end
 
-  def strict_check_custom_type
-    used_type, rendered_object_id = declared_return_type.last_render
-    used_type&.<=(declared_return_type) || fail_with(<<~MSG)
-      Expected to use #{declared_return_type}.render, but the last type rendered
+  def strict_check_custom_type(type, value)
+    used_type, rendered_object_id = type.last_render
+    used_type == type || used_type&.<(type) || fail_with(<<~MSG)
+      Expected to use #{type}.render, but the last type rendered
       was: #{used_type || 'no type'}.
     MSG
 
-    rendered_object_id == subject.__id__ || fail_with(<<~MSG)
-      #{declared_return_type}.render was called, but the result
+    rendered_object_id == value.__id__ || fail_with(<<~MSG)
+      #{type}.render was called, but the result
       of this call was not used in the response.
     MSG
   end

data/lib/taro/rails/route_finder.rb

@@ -19,7 +19,7 @@ module Taro::Rails::RouteFinder
       # Build a Hash like
       # { 'users#show' } => [#<NormalizedRoute>, #<NormalizedRoute>] }
       rails_routes.each_with_object({}) do |rails_route, hash|
-        route = Taro::Rails::NormalizedRoute.new(rails_route:)
+        route = Taro::Rails::NormalizedRoute.new(rails_route)
         next if route.ignored?
 
         (hash[route.endpoint] ||= []) << route

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

@@ -3,17 +3,18 @@ task 'taro:export' => :environment do
   # make sure all declarations have been seen
   Rails.application.eager_load!
 
+  title = Taro.config.api_name
+  version = Taro.config.api_version
+  format = Taro.config.export_format
+  path = Taro.config.export_path
   # 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.send("to_#{Taro.config.export_format}")
+  export = Taro::Export::OpenAPIv3.call(title:, version:)
 
-  FileUtils.mkdir_p(File.dirname(Taro.config.export_path))
-  File.write(Taro.config.export_path, data)
+  data = export.send("to_#{format}")
 
-  puts "Exported #{Taro.config.api_name} to #{Taro.config.export_path}"
+  FileUtils.mkdir_p(File.dirname(path))
+  File.write(path, data)
+
+  puts "Exported the API #{title} v#{version} to #{path}"
 end

data/lib/taro/rails.rb

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

data/lib/taro/return_def.rb

@@ -0,0 +1,43 @@
+# Lazily-evaluated response type definition.
+class Taro::ReturnDef
+  attr_reader :code, :defined_at, :desc, :nesting, :params
+
+  def initialize(code:, defined_at: nil, desc: nil, nesting: nil, **params)
+    @code = Taro::StatusCode.coerce_to_int(code)
+    @defined_at = defined_at
+    @desc = desc
+    @nesting = nesting
+    @params = params
+    validate
+  end
+
+  def evaluate
+    if nesting
+      Class.new(Taro::Types::NestedResponseType).tap do |type|
+        type.field(nesting, defined_at:, null: false, **params)
+      end
+    else
+      Taro::Types::Coercion.call(params)
+    end
+  end
+
+  private
+
+  def validate
+    # For nested returns, call ::field, which validates
+    # field options, but does not trigger type auto-loading.
+    return evaluate if nesting
+
+    if params.key?(:null)
+      raise Taro::ArgumentError, <<~MSG
+        `null:` is not supported for top-level returns. If you want a nullable return
+        value, nest it, e.g. `returns :str, type: 'String', null: true`.
+      MSG
+    end
+
+    bad_keys = params.keys - (Taro::Types::Coercion.keys + %i[defined_at])
+    return if bad_keys.empty?
+
+    raise Taro::ArgumentError, "Invalid `returns` options: #{bad_keys.join(', ')}"
+  end
+end

data/lib/taro/route.rb

@@ -0,0 +1,32 @@
+class Taro::Route
+  attr_reader :endpoint, :openapi_operation_id, :openapi_path, :verb
+
+  def initialize(endpoint:, openapi_operation_id:, openapi_path:, verb:)
+    @endpoint = validate_string(endpoint:)
+    @openapi_operation_id = validate_string(openapi_operation_id:)
+    @openapi_path = validate_string(openapi_path:)
+    @verb = validate_string(verb:).downcase
+  end
+
+  def path_params
+    openapi_path.scan(/{(\w+)}/).flatten.map(&:to_sym)
+  end
+
+  def can_have_request_body?
+    %w[patch post put].include?(verb)
+  end
+
+  def inspect
+    %(#<#{self.class} "#{verb} #{openapi_path}">)
+  end
+  alias to_s inspect
+
+  private
+
+  def validate_string(**kwarg)
+    name, arg = kwarg.first
+    return arg if arg.is_a?(String)
+
+    raise(Taro::ArgumentError, "#{name} must be a String, got #{arg.class}")
+  end
+end

data/lib/taro/status_code.rb

@@ -0,0 +1,16 @@
+require 'rack'
+
+module Taro::StatusCode
+  def self.coerce_to_int(arg)
+    # support using http status numbers directly
+    return arg if ::Rack::Utils::SYMBOL_TO_STATUS_CODE.key(arg)
+
+    # support using symbols, but coerce them to numbers
+    ::Rack::Utils::SYMBOL_TO_STATUS_CODE[arg] ||
+      raise(Taro::ArgumentError, "Invalid status: #{arg.inspect}")
+  end
+
+  def self.coerce_to_message(arg)
+    ::Rack::Utils::HTTP_STATUS_CODES.fetch(coerce_to_int(arg))
+  end
+end

data/lib/taro/types/base_type.rb

@@ -6,12 +6,17 @@
 # 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
+#
+# Using Struct instead of Data here for performance reasons:
+# https://bugs.ruby-lang.org/issues/19693
+Taro::Types::BaseType = Struct.new(:object) do
   require_relative "shared"
   extend Taro::Types::Shared::AdditionalProperties
   extend Taro::Types::Shared::Deprecation
   extend Taro::Types::Shared::DerivedTypes
   extend Taro::Types::Shared::Description
+  extend Taro::Types::Shared::Equivalence
+  extend Taro::Types::Shared::Name
   extend Taro::Types::Shared::OpenAPIName
   extend Taro::Types::Shared::OpenAPIType
   extend Taro::Types::Shared::Rendering

data/lib/taro/types/field.rb

@@ -2,8 +2,9 @@ require_relative 'field_validation'
 
 Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum, :defined_at, :desc, :deprecated) do
   include Taro::Types::FieldValidation
+  include Taro::Types::Shared::Errors
 
-  def initialize(name:, type:, null:, method: name, default: :none, enum: nil, defined_at: nil, desc: nil, deprecated: nil)
+  def initialize(name:, type:, null:, method: name, default: Taro::None, enum: nil, defined_at: nil, desc: nil, deprecated: nil)
     enum = coerce_to_enum(enum)
     super(name:, type:, null:, method:, default:, enum:, defined_at:, desc:, deprecated:)
   end
@@ -21,7 +22,7 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
   end
 
   def default_specified?
-    !default.equal?(:none)
+    !default.equal?(Taro::None)
   end
 
   def openapi_type
@@ -47,8 +48,7 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
     elsif object.respond_to?(method, true)
       object.public_send(method)
     else
-      # Note that the ObjectCoercion module rescues this and adds context.
-      raise Taro::ResponseError, "No such method or resolver `:#{method}`."
+      response_error "No such method or resolver `:#{method}`", object
     end
   end
 
@@ -66,5 +66,17 @@ Taro::Types::Field = Data.define(:name, :type, :null, :method, :default, :enum,
 
     type_obj = type.new(value)
     from_input ? type_obj.coerce_input : type_obj.coerce_response
+  rescue Taro::ValidationError => e
+    reraise_recursively_with_path_info(e)
+  end
+
+  def reraise_recursively_with_path_info(error)
+    msg =
+      error
+      .message
+      .sub(/ at `\K/, "#{name}.")
+      .sub(/(is not valid as [^`]+)(?=: )/, "\\1 at `#{name}`")
+
+    raise error.class.new(msg, error.object, error.origin)
   end
 end