active_typed_params 0.1.0

data/lib/active_typed_params/inference.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module ActiveTypedParams
+  # Declares parameters from an ActiveInteraction's filters or a model's
+  # columns, so the expected values are written once.
+  module Inference
+    ID_BYTES = [4, 8].freeze
+
+  module_function
+
+    # Filters whose values arrive in requests. Records and plain objects are
+    # passed by the controller, so they are skipped, as is a filter declared
+    # with `from_params: false`; an object filter whose class an enum adapter
+    # handles becomes an enum.
+    #
+    # Every input is optional and accepts null, at any depth, because the
+    # interaction reports a missing or null input as a form error and fills in
+    # the default for a null one; rejecting either here would preempt that. For
+    # the same reason a string the interaction validates the length of is not
+    # capped, and a date or time the filter parses itself stays a string.
+    def from_filter(filter, interaction = nil)
+      return if filter.options[:from_params] == false
+
+      declaration = from_custom_filter(filter) || from_builtin_filter(filter, interaction)
+      declaration&.optional(allow_nil: true)
+    end
+
+    def from_builtin_filter(filter, interaction)
+      case filter.class.slug
+      when :string, :symbol then uncapped(Declaration.build(:string), interaction, filter.name)
+      when :integer, :float, :decimal, :boolean, :file then Declaration.build(filter.class.slug)
+      when :date, :time then Declaration.build(filter.options.key?(:format) ? :string : filter.class.slug)
+      when :date_time then Declaration.build(:string)
+      when :hash then from_hash_filter(filter)
+      when :array then from_array_filter(filter)
+      when :object then from_object_filter(filter)
+      end
+    end
+
+    def from_custom_filter(filter)
+      ActiveTypedParams.config.filter_inferrers.lazy.map { |inferrer| inferrer.call(filter) }.find(&:itself)
+    end
+
+    def from_hash_filter(filter)
+      children = filter.filters.filter_map { |name, child| [name, from_filter(child)] if from_filter(child) }
+      options = filter.options.fetch(:strip, true) ? {} : {open: true}
+      Declaration.build(:hash, children:, options:)
+    end
+
+    def from_array_filter(filter)
+      item_filter = filter.filters[:"0"]
+      item = item_filter ? from_filter(item_filter) : Declaration.build(:any).optional(allow_nil: true)
+      Declaration.build(:array, item:) if item
+    end
+
+    def from_object_filter(filter)
+      klass = Object.const_get(filter.options.fetch(:class, filter.name).to_s.camelize)
+      Declaration.build(:enum, source: klass) if EnumAdapter.lookup(klass)
+    end
+
+    # Presence follows the schema. Nullability follows the column, unless the
+    # model validates presence and so reports a null itself; likewise a
+    # string the model validates the length of is not capped here.
+    def from_attribute(model, name)
+      name = name.to_s
+      attribute = model.respond_to?(:attribute_aliases) ? model.attribute_aliases.fetch(name, name) : name
+      attachment = from_attachment(model, attribute)
+      return attachment if attachment
+      return from_attribute_container(model, attribute) unless model.respond_to?(:columns_hash)
+
+      column = model.columns_hash[attribute] || raise(SchemaError, "#{model} has no column #{name.inspect}")
+      declaration = from_attribute_type(model, attribute) || from_column(model, attribute, column)
+      uncapped(declaration, model, attribute).merge_options(allow_nil: column.null || validates?(model, attribute, :presence))
+    end
+
+    # StoreModel and ActiveModel::Attributes classes declare types but no columns.
+    def from_attribute_container(model, name)
+      type = model.attribute_types[name] || raise(SchemaError, "#{model} has no attribute #{name.inspect}")
+      uncapped(from_type(type), model, name).merge_options(allow_nil: true)
+    end
+
+    def from_attachment(model, name)
+      reflection = model.reflect_on_attachment(name) if model.respond_to?(:reflect_on_attachment)
+      return if reflection.nil?
+
+      if reflection.macro == :has_many_attached
+        Declaration.build(:array, item: Declaration.build(:string), options: {invalid: :drop, allow_nil: true})
+      else
+        Declaration.direct_upload(allow_nil: true)
+      end
+    end
+
+    def from_attribute_type(model, name)
+      type = model.attribute_types[name]
+      return Declaration.build(:any) if defined?(ActiveRecord::Type::Serialized) && type.is_a?(ActiveRecord::Type::Serialized)
+
+      type && from_type(type, custom_only: true)
+    end
+
+    def from_type(type, custom_only: false)
+      custom = ActiveTypedParams.config.type_inferrers.lazy.map { |inferrer| inferrer.call(type) }.find(&:itself) || from_store_model(type)
+      return custom if custom || custom_only
+
+      case type.type
+      when :string then Declaration.build(:string)
+      when :text then Declaration.build(:string, options: text_options)
+      when :integer, :float, :decimal, :boolean, :date then Declaration.build(type.type)
+      when :datetime, :time then Declaration.build(:time)
+      else Declaration.build(:any)
+      end
+    end
+
+    # A StoreModel attribute is a hash of its model's attributes, or an array
+    # of them. StoreModel keeps the model class private.
+    def from_store_model(type)
+      return unless defined?(StoreModel::Types::One)
+
+      case type
+      when StoreModel::Types::One then store_model_hash(type.instance_variable_get(:@model_klass))
+      when StoreModel::Types::Many then Declaration.build(:array, item: store_model_hash(type.instance_variable_get(:@model_klass)))
+      end
+    end
+
+    def store_model_hash(model)
+      children = model.attribute_types.map { |name, type| [name, from_type(type).optional(allow_nil: true)] }
+      Declaration.build(:hash, children:)
+    end
+
+    def from_column(model, name, column)
+      element = from_scalar_column(model, name, column)
+      (column.respond_to?(:array) && column.array) ? Declaration.build(:array, item: element) : element
+    end
+
+    def from_scalar_column(model, name, column)
+      enum = model.defined_enums[name] if model.respond_to?(:defined_enums)
+      return Declaration.build(:string, options: {in: enum.keys}) if enum
+
+      case column.type
+      when :string then Declaration.build(:string, options: {max_length: column.limit}.compact)
+      when :text then Declaration.build(:string, options: text_options)
+      when :enum then Declaration.build(:string)
+      when :integer
+        if name.end_with?("_id")
+          Declaration.build(:id, options: {bytes: ID_BYTES.include?(column.limit) ? column.limit : 8})
+        else
+          Declaration.build(:integer)
+        end
+      when :decimal, :float, :boolean, :date then Declaration.build(column.type)
+      when :datetime, :timestamp, :timestamptz, :time then Declaration.build(:time)
+      when :json, :jsonb then Declaration.build(:any)
+      else raise SchemaError, "cannot infer a parameter type for the #{column.type.inspect} column #{name.inspect}"
+      end
+    end
+
+    def text_options
+      {max_length: ActiveTypedParams.config.text_max_length}
+    end
+
+    # A length validator on an array counts its items, so only a string is left
+    # for the owner to cap.
+    def uncapped(declaration, owner, name)
+      return declaration unless declaration.type == :string && validates?(owner, name, :length)
+
+      declaration.merge_options(text_options)
+    end
+
+    # The cap the model's attribute of the same name would get, or none when
+    # the model has no such attribute or no parameter type for it.
+    def model_cap(model, name)
+      from_attribute(model, name).options.slice(:max_length)
+    rescue SchemaError
+      {}
+    end
+
+    def validates?(owner, name, kind)
+      owner.respond_to?(:validators_on) && owner.validators_on(name.to_sym).any? { |validator| validator.kind == kind }
+    end
+
+    # `key: {option: value}` pairs add options to an inferred key, such as a
+    # condition or a presence flip, while its type still comes from the
+    # source; options named like a child of an inferred hash adjust that
+    # child. Unlike in `param`, a Hash here never declares nested keys:
+    # `key: type`, such as `key: hash(...)`, replaces the inferred type in place.
+    module BuilderMethods
+      # `model:` names the record the inputs are saved to, so string inputs take
+      # the caps of its columns of the same name.
+      def inputs_from(interaction, only: nil, except: nil, model: nil, **overrides)
+        filters = interaction.filters
+        available = filters.keys - ActiveTypedParams.config.ignored_filters.map(&:to_sym)
+        names = only ? restrict(available, only, "only") : available
+        names -= restrict(filters.keys, except, "except") if except
+        named = (Array(only).map(&:to_sym) | overrides.keys.map(&:to_sym))
+        names = filters.keys & (names | restrict(available, overrides.keys, "inputs_from"))
+        names.each do |name|
+          declaration = Inference.from_filter(filters[name], interaction)
+          raise SchemaError, "#{interaction}'s #{name.inspect} input cannot come from a request" if declaration.nil? && named.include?(name)
+
+          if model && declaration&.type == :string && !declaration.options.key?(:max_length)
+            declaration = declaration.merge_options(Inference.model_cap(model, name))
+          end
+
+          apply_declaration(name, override(declaration, overrides[name])) if declaration
+        end
+      end
+
+      # Infers the attribute named by the key it is given to, as in
+      # `address: attribute_from(User)`.
+      def attribute_from(model)
+        described(Declaration.build(:attribute, source: model))
+      end
+
+      # Lists the attributes of a model; a StoreModel or ActiveModel class
+      # without names declares every attribute but those in `except:`.
+      def attributes_from(model, *names, except: nil, **overrides)
+        if names.empty? && !model.respond_to?(:columns_hash)
+          names = model.attribute_types.keys.map(&:to_sym)
+          names -= restrict(names, except, "except") if except
+        elsif except
+          raise SchemaError, "attributes_from #{model} takes except: only without names, for a StoreModel or ActiveModel class"
+        end
+        names |= overrides.keys
+        raise SchemaError, "attributes_from #{model} needs at least one attribute" if names.empty?
+
+        names.each { |name| apply_declaration(name, override(Inference.from_attribute(model, name), overrides[name])) }
+      end
+
+    private
+
+      def restrict(names, subset, option)
+        subset = Array(subset).map(&:to_sym)
+        unknown = subset - names
+        raise SchemaError, "#{option}: names filters that do not exist: #{unknown.inspect}" if unknown.any?
+
+        names & subset
+      end
+
+      def override(declaration, options)
+        return declaration if options.nil?
+        unless options.is_a?(Hash)
+          consume(options)
+          return Declaration.from_literal(options)
+        end
+
+        declaration, options = override_children(declaration, options)
+        required = presence_option(options)
+        declaration = declaration.with(required:, options: declaration.options.except(:allow_nil)) unless required.nil?
+        declaration.merge_options(options.except(*Builder::PRESENCE_OPTIONS))
+      end
+
+      def override_children(declaration, options)
+        return [declaration, options] unless declaration.type == :hash && declaration.children&.any?
+
+        child_names = declaration.children.map { |name, _| name.to_sym }
+        nested, options = options.partition { |key, _| child_names.include?(key.to_sym) }.map(&:to_h)
+        return [declaration, options] if nested.empty?
+
+        children = declaration.children.map { |name, child| [name, nested.key?(name.to_sym) ? override(child, nested[name.to_sym]) : child] }
+        [declaration.with(children:), options]
+      end
+    end
+  end
+
+  Builder.include Inference::BuilderMethods
+end

data/lib/active_typed_params/inline.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActiveTypedParams
+  # Each distinct declaration compiles once per process, keyed by the literal
+  # itself. A proc would be a new object on every request and grow the cache
+  # without bound, so a declaration holding one is rejected before it is cached.
+  class Inline
+    def self.reject_procs(nodes, label)
+      nodes.each do |node|
+        if [node.in, node.default, node.condition&.last].any?(Proc)
+          raise SchemaError, "#{label} cannot hold a proc at #{node.key.inspect}; declare a schema instead"
+        end
+
+        reject_procs(node.children, label) if node.children
+        reject_procs([node.item], label) if node.item
+      end
+    end
+
+    def initialize(context)
+      @context = context
+    end
+
+    def require(*names, **pairs)
+      run(true, names, pairs)
+    end
+
+    def optional(*names, **pairs)
+      run(false, names, pairs)
+    end
+
+    # The keys that were sent, as a Hash even for one key, so an update does
+    # not clear an attribute the request left out.
+    def slice(*names, **pairs)
+      run(false, names, pairs, unwrap: false)
+    end
+
+    # Type helpers describe a value for `require`, `optional` and `slice`, as
+    # in `typed_params.optional(ids: typed_params.array(:id))`. They run on
+    # every request, before the cache lookup, so they build the declaration
+    # directly; its options are validated when the schema is first built.
+    LITERAL_TYPES.each do |type|
+      define_method(type) { |**options| describe(type, options) }
+    end
+
+    def text(**options)
+      describe(:string, Inference.text_options.merge(options))
+    end
+
+    def enum(source, **options)
+      describe(:enum, options, source:)
+    end
+
+    def array(item, **options)
+      describe(:array, options, item: Declaration.from_literal(item))
+    end
+
+    def map(value, **options)
+      describe(:map, options, item: Declaration.from_literal(value))
+    end
+
+    def hash(*fields, **options)
+      options, pairs = options.partition { |key, _| Builder::OPTIONS[:hash].include?(key) }.map(&:to_h)
+      list = pairs.empty? ? fields : [*fields, pairs]
+      describe(:hash, options, children: list.empty? && options[:open] ? [] : Declaration.from_list(list).children)
+    end
+
+  private
+
+    attr_reader :context
+
+    def describe(type, options, **parts)
+      required = options.key?(:optional) ? !options[:optional] : options[:required]
+      Declaration.build(type, required:, options: options.except(*Builder::PRESENCE_OPTIONS), **parts)
+    end
+
+    def run(required, names, pairs, unwrap: true)
+      schema = ActiveTypedParams.inline_schema([required, names, pairs]) { build(required, names, pairs) }
+      request = context.request if context.respond_to?(:request, true)
+      result = schema.call(context, context.params, request)
+      (unwrap && schema.nodes.size == 1) ? result[schema.nodes.first.result_key] : result
+    end
+
+    def build(required, names, pairs)
+      builder = Builder.new
+      required ? builder.required(*names, **pairs) : builder.optional(*names, **pairs)
+      label = "typed_params.#{required ? "require" : "optional"}"
+      nodes = builder.nodes
+      raise SchemaError, "#{label} declares no keys" if nodes.empty?
+
+      Inline.reject_procs(nodes, label)
+      Schema.new(name: :inline, nodes:, module_name: "Inline__#{Digest::SHA256.hexdigest(nodes.inspect)[0, 12]}")
+    end
+  end
+end

data/lib/active_typed_params/node.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActiveTypedParams
+  # Marks a node without a `default:`, so that `default: nil` stays distinct.
+  NO_DEFAULT = Object.new.freeze
+
+  TYPES = %i[string integer id decimal float boolean date time enum file hash array map any one_of].freeze
+  SCALAR_TYPES = (TYPES - %i[hash array map any one_of]).freeze
+  # The JSON type a `one_of` picks each alternative by.
+  JSON_TYPES = {
+    string: :string, date: :string, time: :string, enum: :string,
+    integer: :number, id: :number, decimal: :number, float: :number,
+    boolean: :boolean, array: :array, hash: :object, map: :object
+  }.freeze
+  LITERAL_TYPES = (SCALAR_TYPES - [:enum] + [:any]).freeze
+  # `text` is a string without the default cap, for free text of any length.
+  LITERAL_NAMES = (LITERAL_TYPES + [:text, :direct_upload]).freeze
+
+  Node = Data.define(
+    :key, :type, :required, :allow_nil, :allow_blank, :default, :in, :max_length,
+    :condition, :as, :json, :open, :bytes, :enum_map, :invalid, :children, :item, :map_key
+  ) do
+    def self.build(key:, type:, required:, **options)
+      new(
+        key: key&.to_s,
+        type:,
+        required:,
+        allow_nil: options.fetch(:allow_nil, false),
+        allow_blank: options.fetch(:allow_blank, false),
+        default: options.fetch(:default, NO_DEFAULT),
+        in: options.fetch(:in, nil),
+        max_length: options.fetch(:max_length, nil),
+        condition: options.fetch(:condition, nil),
+        as: options.fetch(:as, nil),
+        json: options.fetch(:json, false),
+        open: options.fetch(:open, false),
+        bytes: options.fetch(:bytes, nil),
+        enum_map: options.fetch(:enum_map, nil),
+        invalid: options.fetch(:invalid, :raise),
+        children: options.fetch(:children, nil),
+        item: options.fetch(:item, nil),
+        map_key: options.fetch(:map_key, nil),
+      )
+    end
+
+    def default?
+      !default.equal?(NO_DEFAULT)
+    end
+
+    def result_key
+      (as || key).to_sym
+    end
+
+    def hash?
+      type == :hash
+    end
+
+    def array?
+      type == :array
+    end
+
+    def map?
+      type == :map
+    end
+
+    def child_keys
+      children.map(&:key)
+    end
+  end
+end

data/lib/active_typed_params/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveTypedParams
+  # Makes `typed_params` available in every controller, compiles every schema
+  # at boot when eager loading, and starts over when code reloads.
+  class Railtie < Rails::Railtie
+    initializer "active_typed_params.controller" do
+      ActiveSupport.on_load(:action_controller) { include ActiveTypedParams::Controller }
+    end
+
+    initializer "active_typed_params.reloader" do |app|
+      app.reloader.before_class_unload { ActiveTypedParams.unload! }
+    end
+
+    config.after_initialize do |app|
+      ActiveTypedParams.compile_all! if app.config.eager_load
+    end
+  end
+end

data/lib/active_typed_params/runtime.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module ActiveTypedParams
+  # Helpers the compiled methods call. Each one is either a type conversion
+  # (returning nil when the value is invalid) or a boundary with the host
+  # framework.
+  module Runtime
+    INTEGER = /\A-?\d+\z/
+    DECIMAL = /\A-?\d+(?:\.\d+)?\z/
+    FLOAT = /\A-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\z/
+    DATE = /\A\d{4}-\d{2}-\d{2}\z/
+    TIME = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/
+    BOOLEANS = {"true" => true, "false" => false, "1" => true, "0" => false}.freeze
+    FRAMEWORK_KEYS = Set.new(%w[controller action format authenticity_token _method utf8 commit]).freeze
+
+  module_function
+
+    # The string-keyed hash behind ActionController::Parameters. Reading that
+    # internal (here, in `unwrap_hash` and in `plain`) avoids the deep copy
+    # `to_unsafe_h` makes; `spec/active_typed_params/runtime_spec.rb` pins it.
+    def raw(params)
+      case params
+      when ActionController::Parameters then params.instance_variable_get(:@parameters)
+      when ActiveSupport::HashWithIndifferentAccess then params
+      when Hash then ActiveSupport::HashWithIndifferentAccess.new(params)
+      else raise ArgumentError, "expected a Hash or ActionController::Parameters, got #{params.class}"
+      end
+    end
+
+    # What a `source:` returns: a hash, or nil or an empty string for none.
+    def source_hash(value)
+      return ActiveSupport::HashWithIndifferentAccess.new if value.nil? || value == ""
+
+      Runtime.raw(unwrap_hash(value) || fail(:invalid_type, [], :hash))
+    end
+
+    def unwrap_hash(value)
+      case value
+      when Hash then value
+      when ActionController::Parameters then value.instance_variable_get(:@parameters)
+      end
+    end
+
+    def fail(code, path, type = nil)
+      raise InvalidParameter.for(code, path, type)
+    end
+
+    def integer(value)
+      Integer(value, 10) if value.is_a?(String) && INTEGER.match?(value)
+    end
+
+    def decimal(value)
+      case value
+      when Integer then BigDecimal(value)
+      when BigDecimal then value
+      when Float then BigDecimal(value, Float::DIG) if value.finite?
+      when String then BigDecimal(value) if DECIMAL.match?(value)
+      end
+    end
+
+    def float(value)
+      parsed = case value
+      when Float then value
+      when Integer then value.to_f
+      when String then Float(value) if FLOAT.match?(value)
+      end
+      parsed if parsed&.finite?
+    end
+
+    def boolean(value)
+      if value == true || value == false
+        value
+      elsif value.is_a?(String)
+        BOOLEANS[value]
+      end
+    end
+
+    def date(value)
+      return unless value.is_a?(String) && DATE.match?(value)
+
+      Date.iso8601(value)
+    rescue Date::Error
+      nil
+    end
+
+    # A date alone is rejected, since Time.zone would read it as midnight in
+    # the server's zone rather than in the zone the client meant.
+    def time(value)
+      return unless value.is_a?(String) && TIME.match?(value)
+
+      if Time.respond_to?(:zone) && Time.zone
+        Time.zone.iso8601(value)
+      else
+        Time.iso8601(value)
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    def file?(value)
+      ActiveTypedParams.config.file_classes.any? { |klass| value.is_a?(klass) }
+    end
+
+    def parse_json(value, path, type)
+      JSON.parse(value)
+    rescue JSON::ParserError
+      fail(:invalid_type, path, type)
+    end
+
+    # Keys are symbols at every level, like the keys a schema declares.
+    def plain(value)
+      case value
+      when Hash then value.each_with_object({}) { |(key, child), result| result[key.to_sym] = plain(child) }
+      when Array then value.map { |child| plain(child) }
+      when ActionController::Parameters then plain(value.instance_variable_get(:@parameters))
+      else value
+      end
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |child| deep_freeze(child) }.freeze
+      when Array then value.each { |child| deep_freeze(child) }.freeze
+      else value.freeze
+      end
+    end
+
+    def allowed?(allowed, value)
+      allowed.is_a?(Range) ? allowed.cover?(value) : allowed.include?(value)
+    end
+
+    # Undeclared keys are reported with `unknown: :report`, or rejected with
+    # `unknown: :reject`. Route and framework keys are never unknown at the
+    # root, and neither is the copy ParamsWrapper makes of a JSON body.
+    def check_unknown(hash, declared, mode, path, context, request)
+      unknown = nil
+      path_parameters = request&.path_parameters
+      wrapped = wrapped_keys(hash, declared, context) if request
+      hash.each_key do |key|
+        next if declared.include?(key)
+        next if request && (FRAMEWORK_KEYS.include?(key) || path_parameters&.key?(key.to_sym) || wrapped&.include?(key))
+
+        fail(:unknown, [*path, key]) if mode == :reject
+        (unknown ||= []) << [*path, key].join(".")
+      end
+      report_unknown(unknown, context) if unknown
+    end
+
+    # The wrapper key, plus the root keys it copied when the schema reads the
+    # wrapped hash instead of the root.
+    def wrapped_keys(hash, declared, context)
+      return unless context.respond_to?(:_wrapper_key, true)
+
+      wrapper = context.send(:_wrapper_key)&.to_s
+      return if wrapper.nil?
+
+      wrapped = unwrap_hash(hash[wrapper]) if declared.include?(wrapper)
+      wrapped ? [wrapper, *wrapped.keys] : [wrapper]
+    end
+
+    def report_unknown(keys, context)
+      ActiveSupport::Notifications.instrument("unknown_parameters.typed_params", keys:, **context_payload(context))
+    end
+
+    def report_invalid(error, context)
+      ActiveSupport::Notifications.instrument(
+        "invalid_parameters.typed_params",
+        path: error.path.join("."), code: error.code, **context_payload(context),
+      )
+    end
+
+    def context_payload(context)
+      return {} if context.nil? || context.instance_of?(Object)
+
+      {
+        controller: context.class.name,
+        action: (context.action_name if context.respond_to?(:action_name)),
+        request: (context.request if context.respond_to?(:request, true)),
+      }
+    end
+  end
+end