taro 0.0.0 → 1.1.0

data/lib/taro/rails/declaration.rb

@@ -0,0 +1,118 @@
+class Taro::Rails::Declaration
+  attr_reader :desc, :summary, :params, :returns, :return_descriptions, :return_nestings, :routes, :tags
+
+  def initialize
+    @params = Class.new(Taro::Types::InputType)
+    @returns = {}
+    @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[:defined_at] = caller_locations(1..2)[1]
+    returns[status] = return_type_from(nesting, **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
+
+  def raise_if_already_declared(status)
+    returns[status] &&
+      raise(Taro::ArgumentError, "response for status #{status} already declared")
+  end
+
+  def parse_params(rails_params)
+    hash = params.new(rails_params.to_unsafe_h).coerce_input
+    hash
+  end
+
+  def finalize(controller_class:, action_name:)
+    add_routes(controller_class:, action_name:)
+    add_openapi_names(controller_class:, action_name:)
+  end
+
+  def add_routes(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
+
+  # TODO: these change when the controller class is renamed.
+  # We might need a way to set `base`. Perhaps as a kwarg to `::api`?
+  def add_openapi_names(controller_class:, action_name:)
+    base = "#{controller_class.name.chomp('Controller').sub('::', '_')}_#{action_name}"
+    params.openapi_name = "#{base}_Input"
+    returns.each do |status, return_type|
+      return_type.openapi_name = "#{base}_#{status}_Response"
+    end
+  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 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 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
+end

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,13 @@
+module Taro::Rails::ResponseValidation
+  def self.install(controller_class:)
+    controller_class.prepend(self) if Taro.config.validate_response
+  end
+
+  def render(*, **kwargs, &)
+    result = super
+    if (declaration = Taro::Rails.declaration_for(self))
+      Taro::Rails::ResponseValidator.call(self, declaration, kwargs[:json])
+    end
+    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/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,17 @@
+# :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.last_render = 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,73 @@
+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,
+        '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,
+        # 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 #{self.class.values.map(&:inspect).join(' or ')}")
+    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 #{self.class.values.map(&:inspect).join(' or ')}")
+    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