taro 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 809337809eb0579bb4de8b3f6879d8fb8d4600e6ad149e20a382e229dc779e7b
-  data.tar.gz: 434beec1c8620de344819a9ce65962076fabb33acc1e5f62655b54a5cf0af9c3
+  metadata.gz: d810edb4a339ca65e24bed6cbecf1baf1f83f84f7894589e8db69a09bc9b3f23
+  data.tar.gz: eaef44afdc12b965d93fd4532efadf41025c30fd59eb87281ae5815c6f48bcf7
 SHA512:
-  metadata.gz: 1a9cb8892c86197acfaab877d51d0d80e6f79862a5d6202d9d66ea90e27801de3b84ca414ae63a89addabf8d2410330413e1b5516f3c5d3b6e6c49e775730d25
-  data.tar.gz: ab5d134d03c0c6f84cf64c0a6a77faa9e7f4f713e40761f95b7ff2ceac644727913f433be8b02db2712515dbe8f6d09bd64323fb06e83ab7df74a891c5c677de
+  metadata.gz: f2de8020efb8ede1493d10cb798d69fa92201d2b518177a527d0e2546e771afe8fa436f03dd839c4a75d655cc2eab26fdb35c4d37a830393fda4e37bfd6583c5
+  data.tar.gz: ca421c1f360b072570f7eab0b17c26ac2109f16a19d96efbe564d22e791f7fa0945d11eb914ff67b29602576499f03aed388fc10cad6f9b7b1f42bea4f905f7d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,22 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.2
+
+Layout/LineLength:
+  Enabled: false
+
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude: ['spec/**/*', 'tasks/**/*']
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Style:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-11-03
+
+- Initial release

data/README.md

@@ -1 +1,262 @@
-placeholder gem
+# Taro - Typed Api using Ruby Objects
+
+This library provides an object-based type system for RESTful Ruby APIs, with built-in parameter parsing, response rendering, and OpenAPI schema export.
+
+It is inspired by [`apipie-rails`](https://github.com/Apipie/apipie-rails) and [`graphql-ruby`](https://github.com/rmosolgo/graphql-ruby).
+
+## Goals
+
+- provide a simple, declarative way to describe API endpoints
+- 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
+bundle add taro
+```
+
+Then, if using rails, generate type files to inherit from:
+
+```bash
+bundle exec rails g taro:rails:install [ --dir app/my_types_dir ]
+```
+
+## Usage
+
+The core concept of Taro are type classes.
+
+This is how type classes can be used in a Rails controller:
+
+```ruby
+class BikesController < ApplicationController
+  # This adds an endpoint summary, description, and tags to the docs (all optional)
+  api     'Update a bike', desc: 'My longer text', tags: ['Bikes']
+  # Params can come from the path, e.g. /bike/:id)
+  param   :id, type: 'UUID', null: false, desc: 'ID of the bike to update'
+  # They can also come from the query string or request body
+  param   :bike, type: 'BikeInputType', null: false
+  # Return types can differ by status code and can be nested as in this case:
+  returns :bike, code: :ok, type: 'BikeType', desc: 'update success'
+  # This one is not nested:
+  returns code: :unprocessable_content, type: 'MyErrorType', desc: 'failure'
+  def update
+    # defined params are available as @api_params
+    bike = Bike.find(@api_params[:id])
+    success = bike.update(@api_params[:bike])
+
+    # Types can be used to render responses.
+    # The object
+    if success
+      render json: { bike: BikeType.render(bike) }, status: :ok
+    else
+      render json: MyErrorType.render(bike.errors.first), status: :unprocessable_entity
+    end
+  end
+
+  # Support for arrays and paginated lists is built-in.
+  api     'List all bikes'
+  returns code: :ok, array_of: 'BikeType', desc: 'list of bikes'
+  def index
+    render json: BikeType.array.render(Bike.all)
+  end
+end
+```
+
+Notice the multiple roles of types: They are used to define the structure of API requests and responses, and render the response. Both the input and output of the API can be validated against the schema if desired (see below).
+
+Here is an example of the `BikeType` from that controller:
+
+```ruby
+class BikeType < ObjectType
+  # Optional description of BikeType (for API docs and the OpenAPI export)
+  self.desc = 'A bike and all relevant information about it'
+
+  # Object types have fields. Each field has a name, its own type,
+  # and a `null:` setting to indicate if it can be nil.
+  # Providing a desc is optional.
+  field :brand, type: 'String', null: true, desc: 'The brand name'
+
+  # Fields can reference other types and arrays of values
+  field :users, array_of: 'UserType', null: false
+
+  # Pagination is built-in for big lists
+  field :parts, page_of: 'PartType', null: false
+
+  # Custom methods can be chosen to resolve fields
+  field :has_brand, type: 'Boolean', null: false, method: :brand?
+
+  # Field resolvers can also be implemented or overridden on the type.
+  # The object passed in to `BikeType.render` is available as `object`.
+  field :fancy_info, type: 'String', null: false
+  def fancy_info
+    "A bike named #{object.name} with #{object.parts.count} parts."
+  end
+end
+```
+
+### Input types
+
+Note the use of `BikeInputType` in the `param` declaration above? It could look like so:
+
+```ruby
+class BikeInputType < InputType
+  field :brand,  type: 'String',  null: true,  desc: 'The brand name'
+  field :wheels, type: 'Integer', null: false, default: 2
+end
+```
+
+The usage of such dedicated InputTypes is optional. Object types can also be used to define accepted parameters, or parts of them, depending on what you want to allow API clients to send.
+
+### Validation
+
+#### Request validation
+
+Requests are automatically validated to match the declared input schema, unless you disable the automatic parsing of parameters into the `@api_params` hash:
+
+```ruby
+Taro.config.parse_params = false
+```
+
+#### Response validation
+
+Responses are automatically validated to use the correct type for rendering, which guarantees that they match the declaration. This can be disabled:
+
+```ruby
+Taro.config.validate_responses = false
+```
+
+### Included type options
+
+The following type names are available by default and can be used as `type:`/`array_of:`/`page_of:` arguments:
+
+- `'Boolean'` - accepts and renders `true` or `false`
+- `'Float'`
+- `'FreeForm'` - accepts and renders any JSON-serializable object, use with care
+- `'Integer'`
+- `'NoContentType'` - 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`
+- `'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
+- `'DateTime'` - an alias for `'Time'`
+
+### Enums
+
+`EnumType` can be inherited from to define shared enums:
+
+```ruby
+class SeverityEnumType < EnumType
+  value 'info'
+  value 'warning'
+  value 'debacle'
+end
+
+class ErrorType < ObjectType
+  field :severity, type: 'SeverityEnumType', null: false
+end
+```
+
+Inline enums are also possible. Unlike EnumType classes, these are inlined in the OpenAPI export and not extracted into refs.
+
+```ruby
+class ErrorType < ObjectType
+  field :severity, type: 'String', enum: %w[info warning debacle], null: false
+end
+```
+
+### FAQ
+
+#### How to avoid repeating common error declarations?
+
+Hook into the DSL in your base controller(s):
+
+```ruby
+class ApiBaseController < ApplicationController
+  def self.api(...)
+    super
+    returns code: :not_found, type: 'MyErrorType', desc: 'The record was not found'
+  end
+
+  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+
+  def render_not_found
+    render json: MyErrorType.render(something), status: :not_found
+  end
+end
+```
+
+```ruby
+class AuthenticatedApiController < ApiBaseController
+  def self.api(...)
+    super
+    returns code: :unauthorized, type: 'MyErrorType'
+  end
+  # ... rescue_from ... render ...
+end
+```
+
+#### How to use context in my types?
+
+Use [ActiveSupport::CurrentAttributes](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
+
+```ruby
+class BikeType < ObjectType
+  field :secret_name, type: 'String', null: true
+
+  def secret_name
+    Current.user.superuser? ? object.secret_name : nil
+  end
+end
+```
+
+#### Why do I have to use type name strings instead of the type constants?
+
+Why e.g. `field :id, type: 'UUID'` instead of `field :id, type: UUID`?
+
+The purpose of this is to reduce unnecessary autoloading of the whole type dependency tree in dev and test environments.
+
+This already works fo type classes – they don't trigger loading of referenced types unless used. The API declarations in controller classes still trigger auto-loading for now, but we aim to improve this in the future.
+
+## Possible future features
+
+- warning/raising for undeclared input params (currently they are ignored)
+- usage without rails is possible but not convenient yet
+- rspec matchers for testing
+- sum types
+- api doc rendering based on export (e.g. rails engine with web ui)
+- [query logs metadata](https://github.com/rmosolgo/graphql-ruby/blob/dcaaed1cea47394fad61fceadf291ff3cb5f2932/lib/generators/graphql/install_generator.rb#L48-L52)
+- deprecation feature
+- maybe make `type:` optional for path params as they're always strings anyway
+- various openapi features
+  - non-JSON content types (e.g. for file uploads)
+  - [examples](https://swagger.io/specification/#example-object)
+  - array minItems, maxItems, uniqueItems
+  - mixed arrays
+  - mixed enums
+  - nullable enums
+  - string format specifications (e.g. binary, int64, password ...)
+  - string pattern specifications
+  - string minLength and maxLength
+  - number minimum, exclusiveMinimum, maximum, multipleOf
+  - readOnly, writeOnly
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/taro-rb/taro.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -1 +1,12 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+Dir['tasks/**/*.rake'].each { |file| load(file) }
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/taro/config.rb

@@ -0,0 +1,22 @@
+module Taro::Config
+  singleton_class.attr_accessor(
+    :api_name,
+    :api_version,
+    :export_format,
+    :export_path,
+    :parse_params,
+    :validate_response,
+  )
+
+  # defaults
+  self.api_name = 'Taro-based API'
+  self.api_version = '1.0'
+  self.export_format = :yaml
+  self.export_path = 'api.yml'
+  self.parse_params = true
+  self.validate_response = true
+end
+
+def Taro.config
+  Taro::Config
+end

data/lib/taro/errors.rb

@@ -0,0 +1,6 @@
+class Taro::Error < StandardError; end
+class Taro::ArgumentError < Taro::Error; end
+class Taro::RuntimeError < Taro::Error; end
+class Taro::ValidationError < Taro::RuntimeError; end # not to be used directly
+class Taro::InputError < Taro::ValidationError; end
+class Taro::ResponseError < Taro::ValidationError; end

data/lib/taro/export/base.rb

@@ -0,0 +1,29 @@
+class Taro::Export::Base
+  attr_reader :result
+
+  def self.call(declarations:, title: 'Taro-based API', version: '1.0', **)
+    new.call(declarations:, title:, version:, **)
+  end
+
+  def to_json(*)
+    require 'json'
+    JSON.pretty_generate(result)
+  end
+
+  def to_yaml
+    require 'yaml'
+    desymbolize(result).to_yaml
+  end
+
+  private
+
+  # https://github.com/ruby/psych/issues/396
+  def desymbolize(arg)
+    case arg
+    when Hash   then arg.to_h { |k, v| [desymbolize(k), desymbolize(v)] }
+    when Array  then arg.map { |v| desymbolize(v) }
+    when Symbol then arg.to_s
+    else             arg
+    end
+  end
+end

data/lib/taro/export/open_api_v3.rb

@@ -0,0 +1,189 @@
+class Taro::Export::OpenAPIv3 < Taro::Export::Base # rubocop:disable Metrics/ClassLength
+  attr_reader :schemas
+
+  def initialize
+    super
+    @schemas = {}
+  end
+
+  # TODO:
+  # - use json-schema gem to validate overall result against OpenAPIv3 schema
+  def call(declarations:, title:, version:)
+    @result = { openapi: '3.1.0', info: { title:, version: } }
+    paths = export_paths(declarations)
+    @result[:paths] = paths if paths.any?
+    @result[:components] = { schemas: } if schemas.any?
+    self
+  end
+
+  def export_paths(declarations)
+    declarations.each_with_object({}) do |declaration, paths|
+      declaration.routes.each do |route|
+        paths[route.openapi_path] = export_route(route, declaration)
+      end
+    end
+  end
+
+  def export_route(route, declaration)
+    {
+      route.verb.to_sym => {
+        description: declaration.desc,
+        summary: declaration.summary,
+        tags: declaration.tags,
+        parameters: path_parameters(declaration, route),
+        requestBody: request_body(declaration, route),
+        responses: responses(declaration),
+      }.compact,
+    }
+  end
+
+  def path_parameters(declaration, route)
+    route.path_params.map do |param_name|
+      param_field = declaration.params.fields[param_name] || raise(<<~MSG)
+        Declaration missing for path param #{param_name} of route #{route.endpoint}
+      MSG
+
+      {
+        name: param_field.name,
+        in: 'path',
+        description: param_field.desc,
+        required: true, # path params are always required in rails
+        schema: { type: param_field.openapi_type },
+      }.compact
+    end
+  end
+
+  def request_body(declaration, route)
+    params = declaration.params
+    body_param_fields = params.fields.reject do |name, _field|
+      route.path_params.include?(name)
+    end
+    return unless body_param_fields.any?
+
+    body_input_type = Class.new(params)
+    body_input_type.fields.replace(body_param_fields)
+    body_input_type.openapi_name = params.openapi_name
+
+    # For polymorphic routes (more than one for the same declaration),
+    # we can't use refs because they request body might differ.
+    # Different params might be in the path vs. in the request body.
+    use_refs = !declaration.polymorphic_route?
+    schema = request_body_schema(body_input_type, use_refs:)
+    { content: { 'application/json': { schema: } } }
+  end
+
+  def request_body_schema(type, use_refs:)
+    if use_refs
+      extract_component_ref(type)
+    else
+      type_details(type)
+    end
+  end
+
+  def responses(declaration)
+    declaration.returns.to_h do |code, type|
+      [
+        code.to_s,
+        {
+          description: declaration.return_descriptions[code],
+          content: { 'application/json': { schema: export_type(type) } },
+        }
+      ]
+    end
+  end
+
+  def export_type(type)
+    if type < Taro::Types::ScalarType
+      { type: type.openapi_type }
+    else
+      extract_component_ref(type)
+    end
+  end
+
+  def export_field(field)
+    if field.type < Taro::Types::ScalarType
+      export_scalar_field(field)
+    else
+      export_complex_field_ref(field)
+    end
+  end
+
+  def export_scalar_field(field)
+    base = { type: field.openapi_type }
+    # Using oneOf seems more correct than an array of types
+    # as it puts props like format together with the main type.
+    # https://github.com/OAI/OpenAPI-Specification/issues/3148
+    base = { oneOf: [base, { type: 'null' }] } if field.null
+    base[:description] = field.desc if field.desc
+    base[:default] = field.default if field.default_specified?
+    base[:enum] = field.enum if field.enum
+    base
+  end
+
+  def export_complex_field_ref(field)
+    ref = extract_component_ref(field.type)
+    if field.null
+      # RE nullable: https://stackoverflow.com/a/70658334
+      { description: field.desc, oneOf: [ref, { type: 'null' }] }.compact
+    elsif field.desc
+      # https://github.com/OAI/OpenAPI-Specification/issues/2033
+      { description: field.desc, allOf: [ref] }
+    else
+      ref
+    end
+  end
+
+  def extract_component_ref(type)
+    assert_unique_openapi_name(type)
+    schemas[type.openapi_name.to_sym] ||= type_details(type)
+    { '$ref': "#/components/schemas/#{type.openapi_name}" }
+  end
+
+  def type_details(type)
+    if type.respond_to?(:fields) # InputType or ObjectType
+      object_type_details(type)
+    elsif type < Taro::Types::EnumType
+      enum_type_details(type)
+    elsif type < Taro::Types::ListType
+      list_type_details(type)
+    else
+      raise NotImplementedError, "Unsupported type: #{type}"
+    end
+  end
+
+  def object_type_details(type)
+    required = type.fields.values.reject(&:null).map(&:name)
+    {
+      type: type.openapi_type,
+      description: type.desc,
+      required: (required if required.any?),
+      properties: type.fields.to_h { |name, f| [name, export_field(f)] },
+      additionalProperties: (true if type.additional_properties?),
+    }.compact
+  end
+
+  def enum_type_details(enum)
+    {
+      type: enum.item_type.openapi_type,
+      description: enum.desc,
+      enum: enum.values,
+    }.compact
+  end
+
+  def list_type_details(list)
+    {
+      type: 'array',
+      description: list.desc,
+      items: export_type(list.item_type),
+    }.compact
+  end
+
+  def assert_unique_openapi_name(type)
+    @name_to_type_map ||= {}
+    if (prev = @name_to_type_map[type.openapi_name]) && type != prev
+      raise("Duplicate openapi_name \"#{type.openapi_name}\" for types #{prev} and #{type}")
+    else
+      @name_to_type_map[type.openapi_name] = type
+    end
+  end
+end

data/lib/taro/export.rb

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

data/lib/taro/rails/active_declarations.rb

@@ -0,0 +1,19 @@
+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:)
+  end
+
+  def declarations_map
+    @declarations_map ||= {}
+  end
+
+  def declarations
+    declarations_map.values.flat_map(&:values)
+  end
+
+  def declaration_for(controller)
+    declarations_map[controller.class].to_h[controller.action_name.to_sym]
+  end
+end

data/lib/taro/rails/declaration.rb

@@ -0,0 +1,101 @@
+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 { |t| t.field(nesting, **kwargs) }
+    else
+      Taro::Types::Coercion.call(kwargs)
+    end
+  end
+
+  def raise_missing_route(controller_class, action_name)
+    raise(Taro::ArgumentError, "No route found for #{controller_class}##{action_name}")
+  end
+end