taro 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d810edb4a339ca65e24bed6cbecf1baf1f83f84f7894589e8db69a09bc9b3f23
-  data.tar.gz: eaef44afdc12b965d93fd4532efadf41025c30fd59eb87281ae5815c6f48bcf7
+  metadata.gz: 36e27c067e70b65d503a3c78b61e9efc05d8995f9927edfaf6f66ff4fae70b25
+  data.tar.gz: 131fc3d1bea432320046c4e5c220dff0a3ead87d8a2f3d12310cdd847b2e50c1
 SHA512:
-  metadata.gz: f2de8020efb8ede1493d10cb798d69fa92201d2b518177a527d0e2546e771afe8fa436f03dd839c4a75d655cc2eab26fdb35c4d37a830393fda4e37bfd6583c5
-  data.tar.gz: ca421c1f360b072570f7eab0b17c26ac2109f16a19d96efbe564d22e791f7fa0945d11eb914ff67b29602576499f03aed388fc10cad6f9b7b1f42bea4f905f7d
+  metadata.gz: 9d44a2c33be8175c6b59b1426921fd339c4e4125bf7fa076da27f4b9c17bcf1efb69aa0233c8e91f16804b086f250b37fddb0e6e6dce2debbf0349fc96ac832d
+  data.tar.gz: 59d1a63e68b5560ee7cf0243ff3ccf6684376249745727e6695576821285e8dc1d64018a5f8e8a962f9d7dcea74c1e6bc9d27dd664662d327c257d81505b6c23

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-11-03
+## [1.1.0] - 2024-11-16
+
+- Response validation refined
+- Bugfix for openapi export
+
+## [1.0.0] - 2024-11-14
 
 - Initial release

data/README.md

@@ -10,11 +10,6 @@ It is inspired by [`apipie-rails`](https://github.com/Apipie/apipie-rails) and [
 - conveniently check request and response data against the declaration
 - offer an up-to-date OpenAPI export with minimal configuration
 
-## ⚠️ This is a work in progress - TODO:
-
-- ISO8601Time, ISO8601Date types
-- ResponseValidation: allow rendering scalars directly (e.g. `render json: 42`)
-
 ## Installation
 
 ```bash
@@ -139,9 +134,9 @@ The following type names are available by default and can be used as `type:`/`ar
 - `'Float'`
 - `'FreeForm'` - accepts and renders any JSON-serializable object, use with care
 - `'Integer'`
-- `'NoContentType'` - renders an empty object, for use with `status: :no_content`
+- `'NoContent'` - renders an empty object, for use with `status: :no_content`
 - `'String'`
-- `'Timestamp'` - renders a `Time` as unix timestamp integer and turns into incoming integers into a `Time`
+- `'Timestamp'` - renders a `Time` as unix timestamp integer and turns incoming integers into a `Time`
 - `'UUID'` - accepts and renders UUIDs
 - `'Date'` - accepts and renders a date string in ISO8601 format
 - `'Time'` - accepts and renders a time string in ISO8601 format

data/lib/taro/errors.rb

@@ -1,4 +1,10 @@
-class Taro::Error < StandardError; end
+class Taro::Error < StandardError
+  def message
+    # clean up newlines introduced when setting the message with a heredoc
+    super.chomp.tr("\n", ' ')
+  end
+end
+
 class Taro::ArgumentError < Taro::Error; end
 class Taro::RuntimeError < Taro::Error; end
 class Taro::ValidationError < Taro::RuntimeError; end # not to be used directly

data/lib/taro/export/open_api_v3.rb

@@ -19,7 +19,8 @@ class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/Cla
   def export_paths(declarations)
     declarations.each_with_object({}) do |declaration, paths|
       declaration.routes.each do |route|
-        paths[route.openapi_path] = export_route(route, declaration)
+        paths[route.openapi_path] ||= {}
+        paths[route.openapi_path].merge! export_route(route, declaration)
       end
     end
   end

data/lib/taro/rails/active_declarations.rb

@@ -2,7 +2,7 @@ module Taro::Rails::ActiveDeclarations
   def apply(declaration:, controller_class:, action_name:)
     (declarations_map[controller_class] ||= {})[action_name] = declaration
     Taro::Rails::ParamParsing.install(controller_class:, action_name:)
-    Taro::Rails::ResponseValidation.install(controller_class:, action_name:)
+    Taro::Rails::ResponseValidation.install(controller_class:)
   end
 
   def declarations_map

data/lib/taro/rails/declaration.rb

@@ -89,12 +89,29 @@ class Taro::Rails::Declaration
   def return_type_from(nesting, **kwargs)
     if nesting
       # ad-hoc return type, requiring the actual return type to be nested
-      Class.new(Taro::Types::ObjectType).tap { |t| t.field(nesting, **kwargs) }
+      Class.new(Taro::Types::ObjectType).tap do |type|
+        type.field(nesting, null: false, **kwargs)
+      end
     else
+      check_return_kwargs(kwargs)
       Taro::Types::Coercion.call(kwargs)
     end
   end
 
+  def check_return_kwargs(kwargs)
+    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 defined_at desc])
+    return if bad_keys.empty?
+
+    raise Taro::ArgumentError, "Invalid `returns` options: #{bad_keys.join(', ')}"
+  end
+
   def raise_missing_route(controller_class, action_name)
     raise(Taro::ArgumentError, "No route found for #{controller_class}##{action_name}")
   end

data/lib/taro/rails/response_validation.rb

@@ -1,63 +1,13 @@
 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
+  def self.install(controller_class:)
+    controller_class.prepend(self) if Taro.config.validate_response
   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
+  def render(*, **kwargs, &)
+    result = super
+    if (declaration = Taro::Rails.declaration_for(self))
+      Taro::Rails::ResponseValidator.call(self, declaration, kwargs[:json])
     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
+    result
   end
 end

data/lib/taro/rails/response_validator.rb

@@ -0,0 +1,109 @@
+Taro::Rails::ResponseValidator = Struct.new(:controller, :declaration, :rendered) do
+  def self.call(*args)
+    new(*args).call
+  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
+    else
+      check_custom_type
+    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
+  end
+
+  def fail_with(message)
+    raise Taro::ResponseError, <<~MSG
+      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
+
+    if rendered.key?(nesting)
+      rendered[nesting]
+    elsif rendered.key?(nesting.to_s)
+      rendered[nesting.to_s]
+    else
+      fail_with_nesting_error
+    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}."
+  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)
+    case type.openapi_type
+    when :integer, :number then value.is_a?(Numeric)
+    when :string           then value.is_a?(String) || value.is_a?(Symbol)
+    when :boolean          then [true, false].include?(value)
+    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)
+  end
+
+  def check_enum
+    # coercion checks non-emptyness + enum match
+    declared_return_type.new(subject).coerce_response
+  rescue Taro::Error => e
+    fail_with(e.message)
+  end
+
+  # 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
+    # Ignore types without a specified structure.
+    return if declared_return_type <= Taro::Types::ObjectTypes::FreeFormType
+    return if declared_return_type <= Taro::Types::ObjectTypes::NoContentType
+
+    strict_check_custom_type
+  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
+      was: #{used_type || 'no type'}.
+    MSG
+
+    rendered_object_id == subject.__id__ || fail_with(<<~MSG)
+      #{declared_return_type}.render was called, but the result
+      of this call was not used in the response.
+    MSG
+  end
+end

data/lib/taro/rails.rb

@@ -12,7 +12,6 @@ module Taro::Rails
     buffered_declarations.clear
     declarations_map.clear
     RouteFinder.clear_cache
-    Taro::Types::BaseType.rendering = nil
-    Taro::Types::BaseType.used_in_response = nil
+    Taro::Types::BaseType.last_render = nil
   end
 end

data/lib/taro/types/coercion.rb

@@ -56,15 +56,16 @@ module Taro::Types::Coercion
       @shortcuts ||= {
         # rubocop:disable Layout/HashAlignment - buggy cop
         'Boolean'   => Taro::Types::Scalar::BooleanType,
+        'Date'      => Taro::Types::Scalar::ISO8601DateType,
+        'DateTime'  => Taro::Types::Scalar::ISO8601DateTimeType,
         'Float'     => Taro::Types::Scalar::FloatType,
         'FreeForm'  => Taro::Types::ObjectTypes::FreeFormType,
         'Integer'   => Taro::Types::Scalar::IntegerType,
+        'NoContent' => Taro::Types::ObjectTypes::NoContentType,
         'String'    => Taro::Types::Scalar::StringType,
+        'Time'      => Taro::Types::Scalar::ISO8601DateTimeType,
         '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

data/lib/taro/types/enum_type.rb

@@ -18,7 +18,7 @@ class Taro::Types::EnumType < Taro::Types::BaseType
     if self.class.values.include?(value)
       value
     else
-      input_error("must be one of #{self.class.values}")
+      input_error("must be #{self.class.values.map(&:inspect).join(' or ')}")
     end
   end
 
@@ -28,7 +28,7 @@ class Taro::Types::EnumType < Taro::Types::BaseType
     if self.class.values.include?(value)
       value
     else
-      response_error("must be one of #{self.class.values}")
+      response_error("must be #{self.class.values.map(&:inspect).join(' or ')}")
     end
   end
 

data/lib/taro/types/shared/rendering.rb

@@ -2,35 +2,21 @@
 # Special types (e.g. PageType) may accept kwargs for `#coerce_response`.
 module Taro::Types::Shared::Rendering
   def render(object, opts = {})
-    if (prev = rendering)
-      raise Taro::RuntimeError, <<~MSG
-        Type.render should only be called once per request.
-        (First called on #{prev}, then on #{self}.)
-      MSG
-    end
-
     result = new(object).coerce_response(**opts)
-
-    # Only mark this as the used type if coercion worked so that
-    # rescue_from can be used to render another type.
-    self.rendering = self
-
+    self.last_render = [self, result.__id__]
     result
   end
 
-  def rendering=(value)
-    ActiveSupport::IsolatedExecutionState[:taro_type_rendering] = value
-  end
-
-  def rendering
-    ActiveSupport::IsolatedExecutionState[:taro_type_rendering]
+  def last_render=(info)
+    ActiveSupport::IsolatedExecutionState[:taro_last_render] = info
   end
 
-  def used_in_response=(value)
-    ActiveSupport::IsolatedExecutionState[:taro_type_used_in_response] = value
+  def last_render
+    ActiveSupport::IsolatedExecutionState[:taro_last_render]
   end
 
+  # get the last used type for assertions in tests/specs
   def used_in_response
-    ActiveSupport::IsolatedExecutionState[:taro_type_used_in_response]
+    last_render.to_a.first
   end
 end

data/lib/taro/version.rb

@@ -1,4 +1,4 @@
 # :nocov:
 module Taro
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taro
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Janosch Müller
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-15 00:00:00.000000000 Z
+date: 2024-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -62,6 +62,7 @@ files:
 - lib/taro/rails/param_parsing.rb
 - lib/taro/rails/railtie.rb
 - lib/taro/rails/response_validation.rb
+- lib/taro/rails/response_validator.rb
 - lib/taro/rails/route_finder.rb
 - lib/taro/rails/tasks/export.rake
 - lib/taro/types.rb