typed_params 0.2.0

data/SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you find a vulnerability in `typed_params`, please contact Keygen via
+[email](mailto:security@keygen.sh).
+
+You will be given public credit for your disclosure.

data/lib/typed_params/bouncer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'typed_params/mapper'
+
+module TypedParams
+  class Bouncer < Mapper
+    def call(params)
+      depth_first_map(params) do |param|
+        next unless
+          param.schema.if? || param.schema.unless?
+
+        cond = param.schema.if? ? param.schema.if : param.schema.unless
+        res  = case cond
+               in Proc => method
+                 controller.instance_exec(&method)
+               in Symbol => method
+                 controller.send(method)
+               else
+                 raise InvalidMethodError, "invalid method: #{cond.inspect}"
+               end
+
+        next if
+          param.schema.unless? && !res ||
+          param.schema.if? && res
+
+        if param.schema.strict?
+          raise UnpermittedParameterError.new('unpermitted parameter', path: param.path, source: schema.source)
+        else
+          param.delete
+        end
+      end
+    end
+  end
+end

data/lib/typed_params/coercer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'typed_params/mapper'
+
+module TypedParams
+  class Coercer < Mapper
+    def call(params)
+      depth_first_map(params) do |param|
+        schema = param.schema
+        next unless
+          schema.coerce?
+
+        param.value = schema.type.coerce(param.value)
+      rescue CoercionError
+        type = Types.for(param.value)
+
+        raise InvalidParameterError.new("failed to coerce #{type} to #{schema.type}", path: param.path, source: schema.source)
+      end
+    end
+  end
+end

data/lib/typed_params/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Configuration
+    include ActiveSupport::Configurable
+
+    ##
+    # ignore_nil_optionals defines how nil optionals are handled.
+    # When enabled, optional params that are nil will be dropped
+    # given the schema does not allow_nil. Essentially, they
+    # will be treated as if they weren't provided.
+    config_accessor(:ignore_nil_optionals) { false }
+
+    ##
+    # path_transform defines the casing for parameter paths.
+    #
+    # One of:
+    #
+    #   - :underscore
+    #   - :camel
+    #   - :lower_camel
+    #   - :dash
+    #   - nil
+    #
+    config_accessor(:path_transform) { nil }
+
+    ##
+    # key_transform defines the casing for parameter keys.
+    #
+    # One of:
+    #
+    #   - :underscore
+    #   - :camel
+    #   - :lower_camel
+    #   - :dash
+    #   - nil
+    #
+    config_accessor(:key_transform) { nil }
+  end
+end

data/lib/typed_params/controller.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'typed_params/handler'
+require 'typed_params/handler_set'
+require 'typed_params/schema_set'
+
+module TypedParams
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_accessor :typed_handlers, default: HandlerSet.new
+      cattr_accessor :typed_schemas,  default: SchemaSet.new
+
+      def typed_params(format: AUTO)
+        handler = typed_handlers.params[self.class, action_name.to_sym]
+
+        raise UndefinedActionError, "params have not been defined for action: #{action_name.inspect}" if
+          handler.nil?
+
+        schema    = handler.schema
+        processor = Processor.new(controller: self, schema:)
+        paramz    = Parameterizer.new(schema:)
+        # TODO(ezekg) Add a config here that accepts a block, similar to a Rack app
+        #             so that users can define their own parameter source. E.g.
+        #             using and parsing request.body can allow array roots.
+        params    = paramz.call(value: request.request_parameters.deep_symbolize_keys)
+        formatter = case format
+                    when Symbol, String
+                      Formatters[format]
+                    when AUTO
+                      schema.formatter
+                    else
+                      nil
+                    end
+
+        processor.call(params)
+
+        params.unwrap(
+          controller: self,
+          formatter:,
+        )
+      end
+
+      def typed_query(format: AUTO)
+        handler = typed_handlers.query[self.class, action_name.to_sym]
+
+        raise UndefinedActionError, "query has not been defined for action: #{action_name.inspect}" if
+          handler.nil?
+
+        schema    = handler.schema
+        processor = Processor.new(controller: self, schema:)
+        paramz    = Parameterizer.new(schema:)
+        params    = paramz.call(value: request.query_parameters.deep_symbolize_keys)
+        formatter = case format
+                    when Symbol, String
+                      Formatters[format]
+                    when AUTO
+                      schema.formatter
+                    else
+                      nil
+                    end
+
+        processor.call(params)
+
+        params.unwrap(
+          controller: self,
+          formatter:,
+        )
+      end
+
+      private
+
+      def typed_namespace = self.class
+
+      def respond_to_missing?(method_name, *)
+        return super unless
+          /_(params|query)\z/.match?(method_name)
+
+        name = controller_name&.classify&.underscore
+        return super unless
+          name.present?
+
+        aliases = [
+          :"#{name}_params",
+          :"#{name}_query",
+        ]
+
+        aliases.include?(method_name) || super
+      end
+
+      def method_missing(method_name, ...)
+        return super unless
+          /_(params|query)\z/.match?(method_name)
+
+        name = controller_name&.classify&.underscore
+        return super unless
+          name.present?
+
+        case method_name
+        when :"#{name}_params"
+          typed_params(...)
+        when :"#{name}_query"
+          typed_query(...)
+        else
+          super
+        end
+      end
+    end
+
+    class_methods do
+      def typed_params(on: nil, schema: nil, format: nil, **kwargs, &)
+        schema = case schema
+                 in Array(Symbol, Symbol) => namespace, key
+                   typed_schemas[namespace, key] || raise(ArgumentError, "schema does not exist: #{namespace.inspect}/#{key.inspect}")
+                 in Symbol => key
+                   typed_schemas[self, key] || raise(ArgumentError, "schema does not exist: #{key.inspect}")
+                 in nil
+                   Schema.new(**kwargs, controller: self, source: :params, &)
+                 end
+
+        case on
+        in Array => actions
+          actions.each do |action|
+            typed_handlers.params[self, action] = Handler.new(for: :params, action:, schema:, format:)
+          end
+        in Symbol => action
+          typed_handlers.params[self, action] = Handler.new(for: :params, action:, schema:, format:)
+        in nil
+          typed_handlers.deferred << Handler.new(for: :params, schema:, format:)
+        end
+      end
+
+      def typed_query(on: nil, schema: nil, **kwargs, &)
+        schema = case schema
+                 in Array(Symbol, Symbol) => namespace, key
+                   typed_schemas[namespace, key] || raise(ArgumentError, "schema does not exist: #{namespace.inspect}/#{key.inspect}")
+                 in Symbol => key
+                   typed_schemas[self, key] || raise(ArgumentError, "schema does not exist: #{key.inspect}")
+                 in nil
+                   # FIXME(ezekg) Should query params :coerce by default?
+                   Schema.new(nilify_blanks: true, strict: false, **kwargs, controller: self, source: :query, &)
+                 end
+
+        case on
+        in Array => actions
+          actions.each do |action|
+            typed_handlers.query[self, action] = Handler.new(for: :query, action:, schema:)
+          end
+        in Symbol => action
+          typed_handlers.query[self, action] = Handler.new(for: :query, action:, schema:)
+        in nil
+          typed_handlers.deferred << Handler.new(for: :query, schema:)
+        end
+      end
+
+      def typed_schema(key, namespace: self, **kwargs, &)
+        raise ArgumentError, "schema already exists: #{key.inspect}" if
+          typed_schemas.exists?(namespace, key)
+
+        typed_schemas[namespace, key] = Schema.new(**kwargs, controller: self, &)
+      end
+
+      private
+
+      def method_added(method_name)
+        return super unless
+          typed_handlers.deferred?
+
+        while handler = typed_handlers.deferred.shift
+          handler.action = method_name
+
+          case handler.for
+          when :params
+            typed_handlers.params[self, handler.action] = handler
+          when :query
+            typed_handlers.query[self, handler.action] = handler
+          end
+        end
+
+        super
+      end
+    end
+
+    def self.included(klass)
+      raise ArgumentError, "cannot be used outside of controller (got #{klass.ancestors})" unless
+        klass < ::ActionController::Metal
+
+      super(klass)
+    end
+  end
+end

data/lib/typed_params/formatters/formatter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TypedParams
+  module Formatters
+    class Formatter
+      attr_reader :decorator,
+                  :format
+
+      def initialize(format, transform:, decorate:)
+        @format    = format
+        @transform = transform
+        @decorator = decorate
+      end
+
+      def decorator? = decorator.present?
+
+      delegate :arity, :call, to: :@transform
+    end
+  end
+end

data/lib/typed_params/formatters/jsonapi.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'typed_params/formatters/formatter'
+
+module TypedParams
+  module Formatters
+    ##
+    # The JSONAPI formatter transforms a JSONAPI document into Rails'
+    # standard params format that can be passed to a model.
+    #
+    # For example, given the following params:
+    #
+    #   {
+    #     data: {
+    #       type: 'users',
+    #       id: '1',
+    #       attributes: { email: 'foo@bar.example' },
+    #       relationships: {
+    #         friends: {
+    #           data: [{ type: 'users', id: '2' }]
+    #         }
+    #       }
+    #     }
+    #   }
+    #
+    # The final params would become:
+    #
+    #   {
+    #     id: '1',
+    #     email: 'foo@bar.example',
+    #     friend_ids: ['2']
+    #   }
+    #
+    module JSONAPI
+      def self.call(params)
+        case params
+        in data: Array => data
+          format_array_data(data)
+        in data: Hash => data
+          format_hash_data(data)
+        else
+          params
+        end
+      end
+
+      private
+
+      def self.format_array_data(data)
+        data.map { format_hash_data(_1) }
+      end
+
+      def self.format_hash_data(data)
+        rels  = data[:relationships]
+        attrs = data[:attributes]
+        res   = data.except(
+          :attributes,
+          :links,
+          :meta,
+          :relationships,
+          :type,
+        )
+
+        # Move attributes over to top-level params
+        attrs&.each do |key, attr|
+          res[key] = attr
+        end
+
+        # Move relationships over. This will use x_id and x_ids when the
+        # relationship data only contains :type and :id, otherwise it
+        # will use the x_attributes key.
+        rels&.each do |key, rel|
+          case rel
+          # FIXME(ezekg) We need https://bugs.ruby-lang.org/issues/18961 to
+          #              clean this up (i.e. remove the if guard).
+          in data: [{ type:, id:, **nil }, *] => linkage if linkage.all? { _1 in type:, id:, **nil }
+            res[:"#{key.to_s.singularize}_ids"] = linkage.map { _1[:id] }
+          in data: []
+            res[:"#{key.to_s.singularize}_ids"] = []
+          # FIXME(ezekg) Not sure how to make this cleaner, but this handles polymorphic relationships.
+          in data: { type:, id:, **nil } if key.to_s.underscore.classify != type.underscore.classify
+            res[:"#{key}_type"], res[:"#{key}_id"] = type.underscore.classify, id
+          in data: { type:, id:, **nil }
+            res[:"#{key}_id"] = id
+          in data: nil
+            res[:"#{key}_id"] = nil
+          else
+            # NOTE(ezekg) Embedded relationships are non-standard as per the
+            #             JSONAPI spec, but I don't really care. :)
+            res[:"#{key}_attributes"] = call(rel)
+          end
+        end
+
+        res
+      end
+    end
+
+    register(:jsonapi,
+      transform: JSONAPI.method(:call),
+      decorate: -> {
+        next if
+          respond_to?(:typed_meta)
+
+        mod = Module.new
+
+        mod.define_method :respond_to_missing? do |method_name, *args|
+          next super(method_name, *args) unless
+            /_meta\z/.match?(method_name)
+
+          name = controller_name&.classify&.underscore
+          next super(method_name, *args) unless
+            name.present?
+
+          aliases = %I[
+            #{name}_meta
+            typed_meta
+          ]
+
+          aliases.include?(method_name) || super(method_name, *args)
+        end
+
+        mod.define_method :method_missing do |method_name, *args|
+          next super(method_name, *args) unless
+            /_meta\z/.match?(method_name)
+
+          name = controller_name&.classify&.underscore
+          next super(method_name, *args) unless
+            name.present?
+
+          case method_name
+          when :"#{name}_meta",
+               :typed_meta
+            typed_params(format: nil).fetch(:meta) { {} }
+          else
+            super(method_name, *args)
+          end
+        end
+
+        include mod
+      },
+    )
+  end
+end

data/lib/typed_params/formatters/rails.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'typed_params/formatters/formatter'
+
+module TypedParams
+  module Formatters
+    ##
+    # The Rails formatter wraps the params in a key matching the current
+    # controller's name.
+    #
+    # For example, in a UsersController context, given the params:
+    #
+    #   { email: 'foo@bar.example' }
+    #
+    # The final params would become:
+    #
+    #   { user: { email: 'foo@bar.example' } }
+    #
+    module Rails
+      def self.call(params, controller:)
+        key = controller.controller_name.singularize.to_sym
+
+        { key => params }
+      end
+    end
+
+    register(:rails,
+      transform: Rails.method(:call),
+    )
+  end
+end

data/lib/typed_params/formatters.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'typed_params/formatters/formatter'
+
+module TypedParams
+  module Formatters
+    cattr_reader :formats, default: {}
+
+    def self.register(format, transform:, decorate: nil)
+      raise ArgumentError, "format is already registered: #{format.inspect}" if
+        formats.key?(format)
+
+      formats[format] = Formatter.new(format, transform:, decorate:)
+    end
+
+    def self.unregister(type) = formats.delete(type)
+
+    def self.[](format) = formats[format] || raise(ArgumentError, "invalid format: #{format.inspect}")
+  end
+end

data/lib/typed_params/handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Handler
+    attr_reader :for,
+                :action,
+                :schema,
+                :format
+
+    def initialize(for:, schema:, action: nil, format: nil)
+      @for    = binding.local_variable_get(:for)
+      @schema = schema
+      @action = action
+      @format = format
+    end
+
+    def action=(action)
+      raise ArgumentError, 'cannot redefine action' if
+        @action.present?
+
+      @action = action
+    end
+  end
+end

data/lib/typed_params/handler_set.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'typed_params/namespaced_set'
+
+module TypedParams
+  class HandlerSet
+    attr_reader :deferred,
+                :params,
+                :query
+
+    def initialize
+      @deferred = []
+      @params   = NamespacedSet.new
+      @query    = NamespacedSet.new
+    end
+
+    def deferred? = @deferred.any?
+  end
+end

data/lib/typed_params/mapper.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module TypedParams
+  class Mapper
+    def initialize(schema:, controller: nil)
+      @controller = controller
+      @schema     = schema
+    end
+
+    def call(*, &) = raise NotImplementedError
+
+    def self.call(*args, **kwargs, &block)
+      new(**kwargs).call(*args, &block)
+    end
+
+    private
+
+    attr_reader :controller,
+                :schema
+
+    ##
+    # depth_first_map performs a postorder DFS-like traversal algorithm
+    # over the params. A postorder DFS starts at the leftmost leaf, and
+    # works its way through to the rightmost sibling, then it backtracks
+    # to the parent node and performs the same all the way up the tree
+    # until it reaches the root.
+    #
+    # The algorithm is used to perform bouncing, coercing, validations
+    # and transforms. For example, with transforms, this ensures that
+    # the node's children are transformed before the parent.
+    #
+    # Visualized, the traversal algorithm would look like this:
+    #
+    #                  ┌───┐
+    #                  │ 9 │
+    #                  └─┬─┘
+    #                    │
+    #                  ┌─▼─┐
+    #          ┌────┬──┤ 8 ├───────┐
+    #          │    │  └─┬─┘       │
+    #          │    │    │         │
+    #        ┌─▼─┐┌─▼─┐┌─▼─┐     ┌─▼─┐
+    #     ┌──┤ 3 ││ 4 ││ 6 │     │ 7 │
+    #     │  └─┬─┘└───┘└─┬─┘     └───┘
+    #     │    │         │
+    #   ┌─▼─┐┌─▼─┐     ┌─▼─┐
+    #   │ 1 ││ 2 │     │ 5 │
+    #   └───┘└───┘     └───┘
+    #
+    def depth_first_map(param, &)
+      return if param.nil?
+
+      # Postorder DFS, so we'll visit the children first.
+      if param.schema.children&.any?
+        case param.schema.children
+        in Array if param.array?
+          if param.schema.indexed?
+            param.schema.children.each_with_index { |v, i| self.class.call(param[i], schema: v, controller:, &) }
+          else
+            param.value.each { |v| self.class.call(v, schema: param.schema.children.first, controller:, &) }
+          end
+        in Hash if param.hash?
+          param.schema.children.each { |k, v| self.class.call(param[k], schema: v, controller:, &) }
+        else
+        end
+      end
+
+      # Then we visit the node.
+      yield param
+
+      param
+    end
+  end
+end

data/lib/typed_params/namespaced_set.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module TypedParams
+  ##
+  # NamespacedSet is a set of key-values that are namespaced by a class.
+  # What makes this special is that access supports class inheritance.
+  # For example, given a Parent class and a Child class that inherits
+  # from Parent, the Child namespace can access the Parent namespace
+  # as long as a Child namespace doesn't also exist, in which case
+  # it will take precedence.
+  #
+  # For example, the above, codified:
+  #
+  #   class Parent; end
+  #   class Child < Parent; end
+  #
+  #   s = NamespacedSet.new
+  #   s[Parent, :foo] = :bar
+  #
+  #   s[Parent, :foo] => :bar
+  #   s[Child, :foo] => :bar
+  #
+  #   s[Child, :baz] = :qux
+  #
+  #   s[Parent, :baz] => nil
+  #   s[Child, :baz] => :qux
+  #
+  class NamespacedSet
+    def initialize = @store = {}
+
+    def []=(namespace, key, value)
+      store.deep_merge!(namespace => { key => value })
+    end
+
+    def [](namespace, key)
+      _, data = store.find { |k, _| k == namespace } ||
+                store.find { |k, _| namespace <= k }
+
+      return nil if
+        data.nil?
+
+      data[key]
+    end
+
+    def exists?(namespace, key)
+      _, data = store.find { |k, _| k == namespace } ||
+                store.find { |k, _| namespace <= k }
+
+      return false if
+        data.nil?
+
+      data.key?(key)
+    end
+
+    private
+
+    attr_reader :store
+  end
+end