explicit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bdfcf17daab19ff8c25fa77a72b8e7d7bf085ee98726f898c7bc74819accda49
+  data.tar.gz: 2409883f725d14e47afc8509c3083c3e014713053b91b72bc48d13c1f1ea0b16
+SHA512:
+  metadata.gz: e50376405bd6f2305de7716df8f414f26fc4b660999ec673bc9f20f54d41ccd06f535704c382ab2f636b789db34ba1b39f7929cce974dfb3440b16aa4f53e774
+  data.tar.gz: 5a6c7fb91762aff2a883165288b2a4d3a6caa5058a243a185c82fa9a4e9acf14fa8db68a3bba7a43aff3935a936f954ff86f46c5c49845ec930515a4f60b2741

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Luiz Vasconcellos
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,389 @@
+# Explicit
+
+Explicit is a validation and documentation library for JSON APIs that enforces
+documented specs during runtime.
+
+1. [Installation](#installation)
+2. [Defining requests](#defining-requests)
+3. [Reusing specs](#reusing-specs)
+4. [Writing tests](#writing-tests)
+5. [Writing documentation](#writing-documentation)
+6. [Performance benchmark](#performance-benchmark)
+7. Specs
+   - [Agreement](#agreement)
+   - [Array](#array)
+   - [Boolean](#boolean)
+   - [Date Time ISO8601](#date-time-iso8601)
+   - [Date Time Posix](#date-time-posix)
+   - [Default](#default)
+   - [Hash](#hash)
+   - [Inclusion](#inclusion)
+   - [Integer](#integer)
+   - [Literal](#literal)
+   - [Nilable](#nilable)
+   - [One of](#one-of)
+   - [Record](#record)
+   - [String](#string)
+8. Advanced configuration
+   - [Customizing error messages](#customizing-error-messages)
+   - [Customizing error serialization](#customizing-error-serialization)
+
+# Installation
+
+Add the following line to your Gemfile and then run `bundle install`:
+
+```ruby
+gem "explicit", "~> 0.1"
+```
+
+# Defining requests
+
+You define request specs by inheriting from `Explicit::Request`. The following
+methods are available:
+
+- `get(path)` - Adds a route to the request. Use the syntax `:param` for path
+  params. For example: `get "/customers/:customer_id"`.
+  - There is also `head`, `post`, `put`, `delete`, `options` and `patch` for
+    other HTTP verbs.
+- `title(text)` - Adds a title to the request. Displayed in the documentation.
+- `description(text)` - Adds a description to the endpoint. Markdown supported.
+- `header(name, spec)` - Adds a header to the endpoint.
+- `param(name, spec, options = {})` - Adds the request param to the endpoint.
+  It works for params in the request body, query string and path params.
+- `response(status, spec)` - Adds a response spec. You can add multiple
+  responses with different formats.
+
+For example:
+
+```ruby
+class RegistrationsController < ActionController::API
+  class Request < Explicit::Request
+    post "/api/registrations"
+
+    description <<-MD
+    Attempts to register a new user in the system. If `payment_type` is not
+    specified a trial period of 30 days is started.
+    MD
+
+    param :name, [:string, empty: false]
+    param :email, [:string, format: URI::MailTo::EMAIL_REGEXP, strip: true]
+    param :payment_type, [:inclusion, ["free_trial", "credit_card"]], default: "free_trial"
+    param :terms_of_use, :agreement
+
+    response 200, { user: { id: :integer, email: :string } }
+    response 422, { error: "email_already_taken" }
+  end
+
+  def create
+    Request.validate!(params) => { name:, email:, payment_type: }
+
+    user = User.create!(name:, email:, payment_type:)
+
+    render json: user: { user.as_json(:id, :email) }
+  rescue ActiveRecord::RecordNotUnique
+    render json: { error: "email_already_taken" }, status: 422
+  end
+end
+```
+
+# Reusing specs
+
+Specs are just data. You can reuse specs the same way you reuse constants or
+configs in your app. For example:
+
+```ruby
+module MyApp::Spec
+  UUID = [:string, format: /^\h{8}-(\h{4}-){3}\h{12}$/].freeze
+  EMAIL = [:string, format: URI::MailTo::EMAIL_REGEXP, strip: true].freeze
+
+  ADDRESS = {
+    country_name: :string,
+    zipcode: [:string, format: /\d{6}-\d{3}/]
+  }.freeze
+end
+
+# ... and then reference the shared specs when needed
+class Request < Explicit::Request
+  param :customer_uuid, MyApp::Spec::UUID
+  param :email, MyApp::Spec::EMAIL
+  param :address, MyApp::Spec::ADDRESS
+end
+```
+
+# Writing tests
+
+Include `Explicit::TestHelper` in your `test/test_helper.rb` or
+`spec/rails_helper.rb`. This module provides the method
+`fetch(request, params:, headers:)` that let's you verify the endpoint works as
+expected and that it responds with a valid response according to the spec.
+
+Add the following line to your `test/test_helper.rb`.
+
+```diff
+module ActiveSupport
+  class TestCase
+    fixtures :all
+
+    # Run tests in parallel with specified workers
+    parallelize(workers: :number_of_processors)
+
++   include Explicit::TestHelper
+  end
+end
+```
+
+To test your controller, call `fetch(request, params:, headers:)` and write
+assertions against the response. If the endpoint sends a response that does not
+match expected spec the test fails with
+`Explicit::Request::InvalidResponseError`.
+
+The response object has a `status`, an integer value for the http status, and
+`data`, a hash with the response data.
+
+> Path params are matched by name, so if you have an endpoint configured with
+> `put "/customers/:customer_id"` you must call as
+> `fetch(CustomerController::UpdateRequest, { customer_id: 123 })`.
+
+> Note: Response specs are only verified in test environment with no
+> performance penalty when running in production.
+
+```ruby
+class RegistrationsControllerTest < ActionDispatch::IntegrationTest
+  test "successful registration" do
+    response = fetch(RegistrationsController::Request, params: {
+      name: "Bilbo Baggins",
+      email: "bilbo@shire.com",
+      payment_type: "free_trial",
+      terms_of_use: true
+    })
+
+    assert_equal 200, response.status
+
+    assert response.data[:id]
+    assert_equal "bilbo@shire.com", response.data[:email]
+  end
+end
+```
+
+# Writing documentation
+
+Documentation is written . To make documentation available to users
+you must configure it via `Explicit::Documentation.build` and then publish it
+mounting it in `routes.rb`.
+
+Inside `Explicit::Documentation.build` you have access to the following methods:
+
+- `page_title(text)`
+- `primary_color(hexcode)`
+- `section(&block)`
+- `add(request)`
+- `add(title:, partial:)`
+
+For example:
+
+```ruby
+module MyApp::API::V1
+  Documentation = Explicit::Documentation.build do
+    page_title "Acme Co. | API Docs"
+    primary_color "#6366f1"
+
+    section "Introduction" do
+      add title: "About", partial: "api/v1/introduction/about"
+    end
+
+    section "Auth" do
+      add SessionsController::CreateRequest
+      add RegistrationsController::CreateRequest
+    end
+
+    section "Posts" do
+      add PostsController::CreateRequest
+      add PostsController::UpdateRequest
+      add PostsController::DestroyRequest
+    end
+  end
+end
+```
+
+`Explicit::Documentation.build` returns a rails engine that you can mount in
+your `config/routes.rb`. For example:
+
+```ruby
+Rails.application.routes.draw do
+  mount MyApp::API::V1::Documentation => "api/v1/docs"
+end
+```
+
+# Specs
+
+### Agreement
+
+```ruby
+:agreement
+[:agreement, parse: true]
+```
+
+The `agreement` type is a boolean that must always be true. Useful for terms of
+use or agreement acceptances. If `parse: true` is specified then the following
+values are accepted alongisde `true`: "`true`", `"on"` and `"1"`.
+
+### Array
+
+```ruby
+[:array, subspec, options = {}]
+[:array, :string]
+[:array, :integer, empty: false]
+```
+
+All items in the array must be valid according to the subspec. If at least one
+value is invalid then the array is invalid.
+
+### Boolean
+
+```ruby
+:boolean
+[:boolean, parse: true]
+```
+
+If `parse: true` is specified then the following values are converted to `true`:
+`"true"`, `"on"` and `"1"`, and the following values are converted to `false`:
+`"false"`, `"off"` and `"0"`.
+
+### Date Time ISO8601
+
+```ruby
+:date_time_iso8601
+```
+
+String encoded date time following the ISO 8601 spec. For example:
+`"2024-12-10T14:21:00Z"`
+
+### Date Time Posix
+
+```ruby
+:date_time_posix
+```
+
+The number of elapsed seconds since January 1, 1970 in timezone UTC. For
+example: `1733923153`
+
+### Default
+
+```ruby
+[:default, default_value, subspec]
+[:default, "USD", :string]
+[:default, 0, :integer]
+[:default, -> { Time.current.iso8601 }, :date_time_iso8601]
+```
+
+Provides a default value for the param if the value is not present or it is
+`nil`. Other falsy values such as empty string or zero have precedence over
+the default value.
+
+If you provide a lambda it will execute in every `validate!` call.
+
+### Hash
+
+```ruby
+[:hash, keyspec, valuespec, options = {}]
+[:hash, :string, :string]
+[:hash, :string, :integer]
+[:hash, :string, :integer, empty: false]
+[:hash, :string, [:array, :date_time_iso8601]]
+```
+
+Hashes are key value pairs where all keys must match keyspec and all values must
+match valuespec. If you are expecting a hash with a specific set of keys it is
+best to use a [record](#record) instead.
+
+### Inclusion
+
+```ruby
+[:inclusion, allowed_values]
+[:inclusion, ["user", "admin"]]
+[:inclusion, [10, 20, 30, 40, 50]]
+```
+
+Value must be present in the set of allowed values.
+
+### Integer
+
+```ruby
+:integer
+[:integer, parse: true]
+[:integer, negative: false]
+[:integer, positive: false]
+[:integer, min: 0] # inclusive
+[:integer, max: 10] # inclusive
+```
+
+If `parse: true` is specified then integer encoded string values such as "10" or
+"-2" are automatically converted to integer.
+
+### Literal
+
+```ruby
+[:literal, value]
+[:literal, 6379]
+[:literal, "value"]
+"value" # literal strings can use shorter syntax
+```
+
+A literal value behaves similar to inclusion with a single value. Useful for
+declaring multiple types in `one_of`.
+
+### Nilable
+
+```ruby
+[:nilable, subspec]
+[:nilable, :string]
+[:nilable, [:array, :integer]]
+```
+
+Value must be `nil` or valid according to the subspec.
+
+### One of
+
+```ruby
+[:one_of, spec1, spec2, ..., specN]
+[:one_of, :string, :integer]
+[:one_of, { email: :string }, { phone_number: :string }]
+```
+
+Attempts to validate against each spec in order stopping at the first spec that
+successfully matches the value. If none of the specs match, an error is
+returned.
+
+### Record
+
+```ruby
+user_spec = {
+  name: :string,
+  email: [:string, format: URI::MailTo::EMAIL_REGEXP]
+}
+
+address_spec = {
+  country_name: :string,
+  zipcode: [:string, { format: /\d{6}-\d{3}/, strip: true }]
+}
+
+payment_spec = {
+  currency: [:nilable, :string], # use :nilable for optional attribute
+  amount: :bigdecimal
+}
+```
+
+Records are hashes with predefined attributes. Records support recursive
+definitions, that is, you can have records inside records, array of records,
+records with array of records, etc.
+
+### String
+
+```ruby
+:string
+[:string, strip: true]
+[:string, empty: false]
+[:string, format: URI::MailTo::EMAIL_REGEXP]
+[:string, minlength: 8] # inclusive
+[:string, maxlength: 20] # inclusive
+```

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/explicit/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Explicit
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/explicit/application_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Explicit
+  module ApplicationHelper
+  end
+end

data/app/views/explicit/application/_documentation.html.erb

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= local_assigns[:page_title] || "API Documentation" %></title>
+</head>
+
+<body>
+  <h1>Hello world</h1>
+</body>
+</html>

data/config/locales/en.yml

@@ -0,0 +1,23 @@
+en:
+  explicit:
+    errors:
+      agreement: "must be accepted"
+      array: "invalid item at index(%{index}): %{error}"
+      boolean: "must be a boolean"
+      date_time_iso8601: "must be a valid iso8601 date time"
+      date_time_posix: "must be a valid posix timestamps"
+      hash: "must be a map"
+      hash_key: "invalid key (%{key}): %{error}"
+      hash_value: "invalid value at key (%{key}): %{error}"
+      inclusion: "must be one of: %{values}"
+      integer: "must be an integer"
+      min: "must be bigger than or equal to %{min}"
+      max: "must be smaller than or equal to %{max}"
+      negative: "must not be negative"
+      positive: "must not be positive"
+      literal: "must be %{value}"
+      string: "must be a string"
+      empty: "must not be empty"
+      minlength: "length must be greater than or equal to %{minlength}"
+      maxlength: "length must be smaller than or equal to %{maxlength}"
+      format: "must have format %{regex}"

data/config/routes.rb

@@ -0,0 +1,2 @@
+Explicit::Engine.routes.draw do
+end

data/lib/explicit/documentation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Explicit::Documentation
+  class Builder
+    def page_title(page_title)
+      @page_title = page_title
+    end
+
+    def primary_color(primary_color)
+      @primary_color = primary_color
+    end
+
+    def section(name)
+    end
+
+    def add(**opts)
+    end
+
+    def call(request)
+      html = Explicit::ApplicationController.render(
+        partial: "documentation",
+        locals: {
+          page_title: @page_title,
+          primary_color: @primary_color,
+          sections: @sections
+        }
+      )
+
+      [200, {}, [html]]
+    end
+  end
+
+  def self.build(&block)
+    builder = Builder.new.tap { _1.instance_eval &block }
+
+    ::Class.new(::Rails::Engine).tap do |engine|
+      engine.routes.draw { root to: builder }
+    end
+  end
+end

data/lib/explicit/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Explicit::Engine < ::Rails::Engine
+  initializer "explicit.rescue_from_invalid_params" do
+    ActiveSupport.on_load(:action_controller_api) do
+      include Explicit::Request::InvalidParams::Handler
+    end
+  end
+end

data/lib/explicit/request/invalid_params.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Explicit::Request::InvalidParams
+  class Error < ::RuntimeError
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+    end
+  end
+
+  module Handler
+    extend ::ActiveSupport::Concern
+
+    included do
+      rescue_from Error do |err|
+        params = Explicit::Spec::Error.translate(err.errors)
+
+        render json: { error: "invalid_params", params: }, status: 422
+      end
+    end
+  end
+end

data/lib/explicit/request/invalid_response_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Explicit::Request::InvalidResponseError < ::RuntimeError
+  def initialize(response, error)
+    super <<-TXT
+      Response did not match expected spec.
+
+      Got:
+
+      #{response.inspect}
+
+      Expected:
+
+      #{error.inspect}
+    TXT
+  end
+end

data/lib/explicit/request.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+class Explicit::Request
+  Route = ::Data.define(:method, :path)
+
+  class << self
+    def get(path)     = routes << Route.new(method: :get, path:)
+    def head(path)    = routes << Route.new(method: :head, path:)
+    def post(path)    = routes << Route.new(method: :post, path:)
+    def put(path)     = routes << Route.new(method: :put, path:)
+    def delete(path)  = routes << Route.new(method: :delete, path:)
+    def options(path) = routes << Route.new(method: :options, path:)
+    def patch(path)   = routes << Route.new(method: :patch, path:)
+
+    def title(text)
+      # TODO
+    end
+
+    def description(markdown)
+      # TODO
+    end
+
+    def header(name, format)
+      raise ArgumentError("duplicated header #{name}") if headers.key?(name)
+
+      headers[name] = format
+    end
+
+    def param(name, format, **options)
+      raise ArgumentError("duplicated param #{name}") if params.key?(name)
+
+      params[name] = format
+    end
+
+    def response(status, format)
+      responses << { status: [:literal, status], data: format }
+    end
+
+    def validate!(values)
+      params_validator = Explicit::Spec.build(params)
+
+      case params_validator.call(values)
+      in [:ok, validated_data] then validated_data
+      in [:error, err] then raise InvalidParams::Error.new(err)
+      end
+    end
+
+    private
+      def routes
+        @routes ||= []
+      end
+
+      def headers
+        @headers ||= {}
+      end
+
+      def params
+        @params ||= {}
+      end
+
+      INVALID_PARAMS_SPEC = {
+        status: [:literal, 422],
+        data: {
+          error: "invalid_params",
+          params: [:hash, :string, :string]
+        }
+      }.freeze
+
+      def responses
+        @responses ||= [INVALID_PARAMS_SPEC]
+      end
+  end
+end

data/lib/explicit/spec/agreement.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Agreement
+  extend self
+
+  VALUES = {
+    "true" => true,
+    "on" => true,
+    "1" => true
+  }.freeze
+
+  def build(options)
+    lambda do |value|
+      value =
+        if value.is_a?(TrueClass)
+          value
+        elsif value.is_a?(::String) && options[:parse]
+          VALUES[value]
+        else
+          nil
+        end
+
+      return [:error, :agreement] if value.nil?
+
+      [:ok, value]
+    end
+  end
+end