sorbet-runtime 0.0.1.pre.prealpha → 0.4.4253

data/lib/types/props/constructor.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# typed: false
+
+module T::Props::Constructor
+  include T::Props::WeakConstructor
+
+  def initialize(hash={})
+    decorator = self.class.decorator
+
+    decorator.props.each do |prop, rules|
+      # It's important to explicitly compare against `true` here; the value can also be :existing or
+      # :on_load (which are truthy) but we don't want to treat those as optional in this context.
+      if T::Utils::Props.required_prop?(rules) && !decorator.has_default?(rules) && !hash.key?(prop)
+        raise ArgumentError.new("Missing required prop `#{prop}` for class `#{self.class}`")
+      end
+    end
+
+    super
+  end
+end

data/lib/types/props/custom_type.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+# typed: false
+
+module T::Props
+  module CustomType
+    include Kernel # for `is_a?`
+
+    # Returns true if the given Ruby value can be assigned to a T::Props field
+    # of this type.
+    #
+    # @param [Object] _value
+    # @return T::Boolean
+    def instance?(_value)
+      raise NotImplementedError.new('Must override in included class')
+    end
+
+    # Alias for consistent interface with T::Types::Base
+    def valid?(value)
+      instance?(value)
+    end
+
+    # Given an instance of this type, serialize that into a scalar type
+    # supported by T::Props.
+    #
+    # @param [Object] _instance
+    # @return An instance of one of T::Configuration.scalar_types
+    def serialize(_instance)
+      raise NotImplementedError.new('Must override in included class')
+    end
+
+    # Given the serialized form of your type, this returns an instance
+    # of that custom type representing that value.
+    #
+    # @param _mongo_scalar One of T::Configuration.scalar_types
+    # @return Object
+    def deserialize(_mongo_scalar)
+      raise NotImplementedError.new('Must override in included class')
+    end
+
+    def self.included(_base)
+      super
+
+      raise 'Please use "extend", not "include" to attach this module'
+    end
+
+    def self.scalar_type?(val)
+      # We don't need to check for val's included modules in
+      # T::Configuration.scalar_types, because T::Configuration.scalar_types
+      # are all classes.
+      klass = val.class
+      until klass.nil?
+        return true if T::Configuration.scalar_types.include?(klass.to_s)
+        klass = klass.superclass
+      end
+      false
+    end
+
+    # We allow custom types to serialize to Arrays, so that we can
+    # implement set-like fields that store a unique-array, but forbid
+    # hashes; Custom hash types should be implemented via an emebdded
+    # T::Struct (or a subclass like Chalk::ODM::Document) or via T.
+    def self.valid_serialization?(val, type=nil)
+      if type&.name == 'Chalk::ODM::BsonTypes::BsonObject'
+        # Special case we allow for backwards compatibility with props formerly
+        # typed as "Object" or "Hash", which contain arbitrarily-nested BSON
+        # data (e.g. parsed API request bodies). In general, we aren't pushing
+        # to convert these to Chalk::ODM::BsonTypes - we'd rather delurk them -
+        # but this lets us convert events with these types to Proto.
+        return true
+      end
+
+      case val
+      when Array
+        val.each do |v|
+          return false unless scalar_type?(v)
+        end
+
+        true
+      else
+        scalar_type?(val)
+      end
+    end
+  end
+end

data/lib/types/props/decorator.rb

@@ -0,0 +1,826 @@
+# frozen_string_literal: true
+# typed: false
+
+# NB: This is not actually a decorator. It's just named that way for consistency
+# with DocumentDecorator and ModelDecorator (which both seem to have been written
+# with an incorrect understanding of the decorator pattern). These "decorators"
+# should really just be static methods on private modules (we'd also want/need to
+# replace decorator overrides in plugins with class methods that expose the necessary
+# functionality).
+class T::Props::Decorator
+  extend T::Sig
+
+  Rules = T.type_alias(T::Hash[Symbol, T.untyped])
+  DecoratedClass = T.type_alias(T.untyped) # T.class_of(T::Props), but that produces circular reference errors in some circumstances
+  DecoratedInstance = T.type_alias(T.untyped) # Would be T::Props, but that produces circular reference errors in some circumstances
+  PropType = T.type_alias(T.any(T::Types::Base, T::Props::CustomType))
+  PropTypeOrClass = T.type_alias(T.any(PropType, Module))
+
+  class NoRulesError < StandardError; end
+
+  sig {params(klass: DecoratedClass).void}
+  def initialize(klass)
+    @class = klass
+    klass.plugins.each do |mod|
+      Private.apply_decorator_methods(mod, self)
+    end
+  end
+
+  # prop stuff
+  sig {returns(T::Hash[Symbol, Rules])}
+  def props
+    @props ||= {}.freeze
+  end
+
+  # Try to avoid using this; post-definition mutation of prop rules is
+  # surprising and hard to reason about.
+  sig {params(prop: Symbol, key: Symbol, value: T.untyped).void}
+  def mutate_prop_backdoor!(prop, key, value)
+    @props = props.merge(
+      prop => props.fetch(prop).merge(key => value).freeze
+    ).freeze
+  end
+
+  sig {returns(T::Array[Symbol])}
+  def all_props; props.keys; end
+
+  sig {params(prop: T.any(Symbol, String)).returns(Rules)}
+  def prop_rules(prop); props[prop.to_sym] || raise("No such prop: #{prop.inspect}"); end
+
+  sig {params(prop: Symbol, rules: Rules).void}
+  def add_prop_definition(prop, rules)
+    prop = prop.to_sym
+    override = rules.delete(:override)
+
+    if props.include?(prop) && !override
+      raise ArgumentError.new("Attempted to redefine prop #{prop.inspect} that's already defined without specifying :override => true: #{prop_rules(prop)}")
+    elsif !props.include?(prop) && override
+      raise ArgumentError.new("Attempted to override a prop #{prop.inspect} that doesn't already exist")
+    end
+
+    @props = @props.merge(prop => rules.freeze).freeze
+  end
+
+  sig {returns(T::Array[Symbol])}
+  def valid_props
+    %i{
+      enum
+      foreign
+      foreign_hint_only
+      ifunset
+      immutable
+      override
+      redaction
+      sensitivity
+      without_accessors
+      clobber_existing_method!
+      extra
+      optional
+      _tnilable
+    }
+  end
+
+  sig {returns(DecoratedClass)}
+  def decorated_class; @class; end
+
+  # Accessors
+
+  # For performance, don't use named params here.
+  # Passing in rules here is purely a performance optimization.
+  sig do
+    params(
+      instance: DecoratedInstance,
+      prop: T.any(String, Symbol),
+      rules: T.nilable(Rules)
+    )
+    .returns(T.untyped)
+  end
+  def get(instance, prop, rules=props[prop.to_sym])
+    # For backwards compatibility, fall back to reconstructing the accessor key
+    # (though it would probably make more sense to raise in that case).
+    instance.instance_variable_get(rules ? rules[:accessor_key] : '@' + prop.to_s) # rubocop:disable PrisonGuard/NoLurkyInstanceVariableAccess
+  end
+
+  # For performance, don't use named params here.
+  # Passing in rules here is purely a performance optimization.
+  sig do
+    params(
+      instance: DecoratedInstance,
+      prop: Symbol,
+      value: T.untyped,
+      rules: T.nilable(Rules)
+    )
+    .void
+  end
+  def set(instance, prop, value, rules=props[prop.to_sym])
+    # For backwards compatibility, fall back to reconstructing the accessor key
+    # (though it would probably make more sense to raise in that case).
+    instance.instance_variable_set(rules ? rules[:accessor_key] : '@' + prop.to_s, value) # rubocop:disable PrisonGuard/NoLurkyInstanceVariableAccess
+  end
+
+  # Use this to validate that a value will validate for a given prop. Useful for knowing whether a value can be set on a model without setting it.
+  sig {params(prop: Symbol, val: T.untyped).void}
+  def validate_prop_value(prop, val)
+    # This implements a 'public api' on document so that we don't allow callers to pass in rules
+    # Rules seem like an implementation detail so it seems good to now allow people to specify them manually.
+    check_prop_type(prop, val)
+  end
+
+  # Passing in rules here is purely a performance optimization.
+  sig {params(prop: Symbol, val: T.untyped, rules: Rules).void}
+  private def check_prop_type(prop, val, rules=prop_rules(prop))
+    type_object = rules.fetch(:type_object)
+    type = rules.fetch(:type)
+
+    # TODO: ideally we'd add `&& rules[:optional] != :existing` to this check
+    # (it makes sense to treat those props required in this context), but we'd need
+    # to be sure that doesn't break any existing code first.
+    if val.nil?
+      if !T::Props::Utils.need_nil_write_check?(rules) || (rules.key?(:default) && rules[:default].nil?)
+        return
+      end
+
+      if rules[:raise_on_nil_write]
+        raise T::Props::InvalidValueError.new("Can't set #{@class.name}.#{prop} to #{val.inspect} " \
+        "(instance of #{val.class}) - need a #{type}")
+      end
+    end
+
+    # T::Props::CustomType is not a real object based class so that we can not run real type check call.
+    # T::Props::CustomType.valid?() is only a helper function call.
+    valid =
+      if type.is_a?(T::Props::CustomType) && T::Utils::Props.optional_prop?(rules)
+        type.valid?(val)
+      else
+        type_object.valid?(val)
+      end
+    if !valid
+      raise T::Props::InvalidValueError.new("Can't set #{@class.name}.#{prop} to #{val.inspect} " \
+        "(instance of #{val.class}) - need a #{type_object}")
+    end
+  end
+
+  # For performance, don't use named params here.
+  # Passing in rules here is purely a performance optimization.
+  # Unlike the other methods that take rules, this one calls prop_rules for
+  # the default, which raises if the prop doesn't exist (this maintains
+  # preexisting behavior).
+  sig do
+    params(
+      instance: DecoratedInstance,
+      prop: Symbol,
+      val: T.untyped,
+      rules: T.nilable(Rules)
+    )
+    .void
+  end
+  def prop_set(instance, prop, val, rules=prop_rules(prop))
+    check_prop_type(prop, val, T.must(rules))
+    set(instance, prop, val, rules)
+  end
+
+  # For performance, don't use named params here.
+  # Passing in rules here is purely a performance optimization.
+  sig do
+    params(
+      instance: DecoratedInstance,
+      prop: T.any(String, Symbol),
+      rules: T.nilable(Rules)
+    )
+    .returns(T.untyped)
+  end
+  def prop_get(instance, prop, rules=props[prop.to_sym])
+    val = get(instance, prop, rules)
+
+    # NB: Do NOT change this to check `val.nil?` instead. BSON::ByteBuffer overrides `==` such
+    # that `== nil` can return true while `.nil?` returns false. Tests will break in mysterious
+    # ways. A special thanks to Ruby for enabling this type of bug.
+    #
+    # One side effect here is that _if_ a class (like BSON::ByteBuffer) defines ==
+    # in such a way that instances which are not `nil`, ie are not NilClass, nevertheless
+    # are `== nil`, then we will transparently convert such instances to `nil` on read.
+    # Yes, our code relies on this behavior (as of writing). :thisisfine:
+    if val != nil # rubocop:disable Style/NonNilCheck
+      val
+    else
+      raise NoRulesError.new if !rules
+      d = rules[:ifunset]
+      if d
+        T::Props::Utils.deep_clone_object(d)
+      else
+        nil
+      end
+    end
+  end
+
+  sig do
+    params(
+      instance: DecoratedInstance,
+      prop: Symbol,
+      foreign_class: Module,
+      rules: Rules,
+      opts: Hash
+    )
+    .returns(T.untyped)
+  end
+  def foreign_prop_get(instance, prop, foreign_class, rules=props[prop.to_sym], opts={})
+    return if !(value = prop_get(instance, prop, rules))
+    foreign_class.load(value, {}, opts)
+  end
+
+  sig do
+    params(
+      name: Symbol,
+      cls: Module,
+      rules: Rules,
+      type: PropTypeOrClass
+    )
+    .void
+  end
+  def prop_validate_definition!(name, cls, rules, type)
+    validate_prop_name(name)
+
+    if rules.key?(:pii)
+      raise ArgumentError.new("The 'pii:' option for props has been renamed " \
+        "to 'sensitivity:' (in prop #{@class.name}.#{name})")
+    end
+
+    if !(rules.keys - valid_props).empty?
+      raise ArgumentError.new("At least one invalid prop arg supplied in #{self}: #{rules.keys.inspect}")
+    end
+
+    if (array = rules[:array])
+      unless array.is_a?(Module)
+        raise ArgumentError.new("Bad class as subtype in prop #{@class.name}.#{name}: #{array.inspect}")
+      end
+    end
+
+    if !(rules[:clobber_existing_method!]) && !(rules[:without_accessors])
+      # TODO: we should really be checking all the methods on `cls`, not just Object
+      if Object.instance_methods.include?(name.to_sym)
+        raise ArgumentError.new(
+          "#{name} can't be used as a prop in #{@class} because a method with " \
+          "that name already exists (defined by #{@class.instance_method(name).owner} " \
+          "at #{@class.instance_method(name).source_location || '<unknown>'}). " \
+          "(If using this name is unavoidable, try `without_accessors: true`.)"
+        )
+      end
+    end
+
+    extra = rules[:extra]
+    if !extra.nil? && !extra.is_a?(Hash)
+      raise ArgumentError.new("Extra metadata must be a Hash in prop #{@class.name}.#{name}")
+    end
+
+    nil
+  end
+
+  private def validate_prop_name(name)
+    if name !~ /\A[A-Za-z_][A-Za-z0-9_-]*\z/
+      raise ArgumentError.new("Invalid prop name in #{@class.name}: #{name}")
+    end
+  end
+
+  # Check if this cls represents a T.nilable(type)
+  sig {params(type: PropTypeOrClass).returns(T::Boolean)}
+  private def is_nilable?(type)
+    return false if !type.is_a?(T::Types::Union)
+    type.types.any? {|t| t == T::Utils.coerce(NilClass)}
+  end
+
+  # This converts the type from a T::Type to a regular old ruby class.
+  sig {params(type: T::Types::Base).returns(Module)}
+  private def convert_type_to_class(type)
+    case type
+    when T::Types::TypedArray, T::Types::FixedArray
+      Array
+    when T::Types::TypedHash, T::Types::FixedHash
+      Hash
+    when T::Types::TypedSet
+      Set
+    when T::Types::Union
+      # The below unwraps our T.nilable types for T::Props if we can.
+      # This lets us do things like specify: const T.nilable(String), foreign: Opus::DB::Model::Merchant
+      non_nil_type = T::Utils.unwrap_nilable(type)
+      if non_nil_type
+        convert_type_to_class(non_nil_type)
+      else
+        Object
+      end
+    when T::Types::Simple
+      type.raw_type
+    else
+      # This isn't allowed unless whitelisted_for_underspecification is
+      # true, due to the check in prop_validate_definition
+      Object
+    end
+  end
+
+  sig do
+    params(
+      name: T.any(Symbol, String),
+      cls: PropTypeOrClass,
+      rules: Rules,
+    )
+    .void
+  end
+  def prop_defined(name, cls, rules={})
+    # TODO(jerry): Create similar soft assertions against false
+    if rules[:optional] == true
+      T::Configuration.hard_assert_handler(
+        'Use of `optional: true` is deprecated, please use `T.nilable(...)` instead.',
+        storytime: {
+          name: name,
+          cls_or_args: cls.to_s,
+          args: rules,
+          klass: decorated_class.name,
+        },
+      )
+    elsif rules[:optional] == false
+      T::Configuration.hard_assert_handler(
+        'Use of `optional: :false` is deprecated as it\'s the default value.',
+        storytime: {
+          name: name,
+          cls_or_args: cls.to_s,
+          args: rules,
+          klass: decorated_class.name,
+        },
+      )
+    elsif rules[:optional] == :on_load
+      T::Configuration.hard_assert_handler(
+        'Use of `optional: :on_load` is deprecated. You probably want `T.nilable(...)` with :raise_on_nil_write instead.',
+        storytime: {
+          name: name,
+          cls_or_args: cls.to_s,
+          args: rules,
+          klass: decorated_class.name,
+        },
+      )
+    elsif rules[:optional] == :existing
+      T::Configuration.hard_assert_handler(
+        'Use of `optional: :existing` is not allowed: you should use use T.nilable (http://go/optional)',
+        storytime: {
+          name: name,
+          cls_or_args: cls.to_s,
+          args: rules,
+          klass: decorated_class.name,
+        },
+      )
+    end
+
+    if T::Utils::Nilable.is_union_with_nilclass(cls)
+      # :_tnilable is introduced internally for performance purpose so that clients do not need to call
+      # T::Utils::Nilable.is_tnilable(cls) again.
+      # It is strictly internal: clients should always use T::Utils::Props.required_prop?() or
+      # T::Utils::Props.optional_prop?() for checking whether a field is required or optional.
+      rules[:_tnilable] = true
+    end
+
+    name = name.to_sym
+    type = cls
+    if !cls.is_a?(Module)
+      cls = convert_type_to_class(cls)
+    end
+    type_object = type
+    if !(type_object.singleton_class < T::Props::CustomType)
+      type_object = smart_coerce(type_object, array: rules[:array], enum: rules[:enum])
+    end
+
+    prop_validate_definition!(name, cls, rules, type_object)
+
+    # Retrive the possible underlying object with T.nilable.
+    underlying_type_object = T::Utils::Nilable.get_underlying_type_object(type_object)
+    type = T::Utils::Nilable.get_underlying_type(type)
+
+    array_subdoc_type = array_subdoc_type(underlying_type_object)
+    hash_value_subdoc_type = hash_value_subdoc_type(underlying_type_object)
+    hash_key_custom_type = hash_key_custom_type(underlying_type_object)
+
+    sensitivity_and_pii = {sensitivity: rules[:sensitivity]}
+    if defined?(Opus) && defined?(Opus::Sensitivity) && defined?(Opus::Sensitivity::Utils)
+      sensitivity_and_pii = Opus::Sensitivity::Utils.normalize_sensitivity_and_pii_annotation(sensitivity_and_pii)
+    end
+    # We check for Class so this is only applied on concrete
+    # documents/models; We allow mixins containing props to not
+    # specify their PII nature, as long as every class into which they
+    # are ultimately included does.
+    #
+    if defined?(Opus) && defined?(Opus::Sensitivity) && defined?(Opus::Sensitivity::PIIable)
+      if sensitivity_and_pii[:pii] && @class.is_a?(Class) && !@class.contains_pii?
+        raise ArgumentError.new(
+          'Cannot include a pii prop in a class that declares `contains_no_pii`'
+        )
+      end
+    end
+
+    needs_clone =
+      if cls <= Array || cls <= Hash || cls <= Set
+        shallow_clone_ok(underlying_type_object) ? :shallow : true
+      else
+        false
+      end
+
+    rules = rules.merge(
+      # TODO: The type of this element is confusing. We should refactor so that
+      # it can be always `type_object` (a PropType) or always `cls` (a Module)
+      type: type,
+      # These are precomputed for performance
+      # TODO: A lot of these are only needed by T::Props::Serializable or T::Struct
+      # and can/should be moved accordingly.
+      type_is_custom_type: cls.singleton_class < T::Props::CustomType,
+      type_is_serializable: cls < T::Props::Serializable,
+      type_is_array_of_serializable: !array_subdoc_type.nil?,
+      type_is_hash_of_serializable_values: !hash_value_subdoc_type.nil?,
+      type_is_hash_of_custom_type_keys: !hash_key_custom_type.nil?,
+      type_object: type_object,
+      type_needs_clone: needs_clone,
+      accessor_key: "@#{name}".to_sym,
+      sensitivity: sensitivity_and_pii[:sensitivity],
+      pii: sensitivity_and_pii[:pii],
+      # extra arbitrary metadata attached by the code defining this property
+      extra: rules[:extra]&.freeze,
+    )
+
+    validate_not_missing_sensitivity(name, rules)
+
+    # for backcompat
+    if type.is_a?(T::Types::TypedArray) && type.type.is_a?(T::Types::Simple)
+      rules[:array] = type.type.raw_type
+    elsif array_subdoc_type
+      rules[:array] = array_subdoc_type
+    end
+
+    if rules[:type_is_serializable]
+      rules[:serializable_subtype] = cls
+    elsif array_subdoc_type
+      rules[:serializable_subtype] = array_subdoc_type
+    elsif hash_value_subdoc_type && hash_key_custom_type
+      rules[:serializable_subtype] = {
+        keys: hash_key_custom_type,
+        values: hash_value_subdoc_type,
+      }
+    elsif hash_value_subdoc_type
+      rules[:serializable_subtype] = hash_value_subdoc_type
+    elsif hash_key_custom_type
+      rules[:serializable_subtype] = hash_key_custom_type
+    end
+
+    add_prop_definition(name, rules)
+    # NB: using `without_accessors` doesn't make much sense unless you also define some other way to
+    # get at the property (e.g., Chalk::ODM::Document exposes `get` and `set`).
+    define_getter_and_setter(name, rules) unless rules[:without_accessors]
+
+    if rules[:foreign] && rules[:foreign_hint_only]
+      raise ArgumentError.new(":foreign and :foreign_hint_only are mutually exclusive.")
+    end
+
+    handle_foreign_option(name, cls, rules, rules[:foreign]) if rules[:foreign]
+    handle_foreign_hint_only_option(cls, rules[:foreign_hint_only]) if rules[:foreign_hint_only]
+    handle_redaction_option(name, rules[:redaction]) if rules[:redaction]
+  end
+
+  sig {params(name: Symbol, rules: Rules).void}
+  private def define_getter_and_setter(name, rules)
+    if rules[:immutable]
+      @class.send(:define_method, "#{name}=") do |_x|
+        raise T::Props::ImmutableProp.new("#{self.class}##{name} cannot be modified after creation.")
+      end
+    else
+      @class.send(:define_method, "#{name}=") do |x|
+        self.class.decorator.prop_set(self, name, x, rules)
+      end
+    end
+
+    @class.send(:define_method, name) do
+      self.class.decorator.prop_get(self, name, rules)
+    end
+  end
+
+  # returns the subdoc of the array type, or nil if it's not a Document type
+  sig do
+    params(type: PropType)
+    .returns(T.nilable(Module))
+  end
+  private def array_subdoc_type(type)
+    if type.is_a?(T::Types::TypedArray)
+      el_type = T::Utils.unwrap_nilable(type.type) || type.type
+
+      if el_type.is_a?(T::Types::Simple) &&
+          (el_type.raw_type < T::Props::Serializable || el_type.raw_type.is_a?(T::Props::CustomType))
+        return el_type.raw_type
+      end
+    end
+
+    nil
+  end
+
+  # returns the subdoc of the hash value type, or nil if it's not a Document type
+  sig do
+    params(type: PropType)
+    .returns(T.nilable(Module))
+  end
+  private def hash_value_subdoc_type(type)
+    if type.is_a?(T::Types::TypedHash)
+      values_type = T::Utils.unwrap_nilable(type.values) || type.values
+
+      if values_type.is_a?(T::Types::Simple) &&
+          (values_type.raw_type < T::Props::Serializable || values_type.raw_type.is_a?(T::Props::CustomType))
+        return values_type.raw_type
+      end
+    end
+
+    nil
+  end
+
+  # returns the type of the hash key, or nil. Any CustomType could be a key, but we only expect Opus::Enum right now.
+  sig do
+    params(type: PropType)
+    .returns(T.nilable(Module))
+  end
+  private def hash_key_custom_type(type)
+    if type.is_a?(T::Types::TypedHash)
+      keys_type = T::Utils.unwrap_nilable(type.keys) || type.keys
+
+      if keys_type.is_a?(T::Types::Simple) && keys_type.raw_type.is_a?(T::Props::CustomType)
+        return keys_type.raw_type
+      end
+    end
+
+    nil
+  end
+
+  # From T::Props::Utils.deep_clone_object, plus String
+  TYPES_NOT_NEEDING_CLONE = [TrueClass, FalseClass, NilClass, Symbol, String, Numeric]
+  if defined?(Opus) && defined?(Opus::Enum)
+    TYPES_NOT_NEEDING_CLONE << Opus::Enum
+  end
+
+  sig {params(type: PropType).returns(T::Boolean)}
+  private def shallow_clone_ok(type)
+    inner_type =
+      if type.is_a?(T::Types::TypedArray)
+        type.type
+      elsif type.is_a?(T::Types::TypedSet)
+        type.type
+      elsif type.is_a?(T::Types::TypedHash)
+        type.values
+      end
+
+    inner_type.is_a?(T::Types::Simple) && TYPES_NOT_NEEDING_CLONE.any? do |cls|
+      inner_type.raw_type <= cls
+    end
+  end
+
+  sig do
+    params(type: PropTypeOrClass, array: T.untyped, enum: T.untyped)
+    .returns(T::Types::Base)
+  end
+  private def smart_coerce(type, array:, enum:)
+    # Backwards compatibility for pre-T::Types style
+    if !array.nil? && !enum.nil?
+      raise ArgumentError.new("Cannot specify both :array and :enum options")
+    elsif !array.nil?
+      if type == Set
+        T::Set[array]
+      else
+        T::Array[array]
+      end
+    elsif !enum.nil?
+      if T::Utils.unwrap_nilable(type)
+        T.nilable(T.enum(enum))
+      else
+        T.enum(enum)
+      end
+    else
+      T::Utils.coerce(type)
+    end
+  end
+
+  sig {params(prop_name: Symbol, rules: Hash).void}
+  private def validate_not_missing_sensitivity(prop_name, rules)
+    if rules[:sensitivity].nil?
+      if rules[:redaction]
+        T::Configuration.hard_assert_handler(
+          "#{@class}##{prop_name} has a 'redaction:' annotation but no " \
+          "'sensitivity:' annotation. This is probably wrong, because if a " \
+          "prop needs redaction then it is probably sensitive. Add a " \
+          "sensitivity annotation like 'sensitivity: Opus::Sensitivity::PII." \
+          "whatever', or explicitly override this check with 'sensitivity: []'."
+        )
+      end
+      # TODO(PRIVACYENG-982) Ideally we'd also check for 'password' and possibly
+      # other terms, but this interacts badly with ProtoDefinedDocument because
+      # the proto syntax currently can't declare "sensitivity: []"
+      if prop_name =~ /\bsecret\b/
+        T::Configuration.hard_assert_handler(
+          "#{@class}##{prop_name} has the word 'secret' in its name, but no " \
+          "'sensitivity:' annotation. This is probably wrong, because if a " \
+          "prop is named 'secret' then it is probably sensitive. Add a " \
+          "sensitivity annotation like 'sensitivity: Opus::Sensitivity::NonPII." \
+          "security_token', or explicitly override this check with " \
+          "'sensitivity: []'."
+        )
+      end
+    end
+  end
+
+  # Create "#{prop_name}_redacted" method
+  sig do
+    params(
+      prop_name: Symbol,
+      redaction: Chalk::Tools::RedactionUtils::RedactionDirectiveSpec,
+    )
+    .void
+  end
+  private def handle_redaction_option(prop_name, redaction)
+    redacted_method = "#{prop_name}_redacted"
+
+    @class.send(:define_method, redacted_method) do
+      value = self.public_send(prop_name)
+      Chalk::Tools::RedactionUtils.redact_with_directive(
+        value, redaction)
+    end
+  end
+
+  sig do
+    params(
+      option_sym: Symbol,
+      foreign: T.untyped,
+      valid_type_msg: String,
+    )
+    .void
+  end
+  private def validate_foreign_option(option_sym, foreign, valid_type_msg:)
+    if foreign.is_a?(Symbol) || foreign.is_a?(String)
+      raise ArgumentError.new(
+        "Using a symbol/string for `#{option_sym}` is no longer supported. Instead, use a Proc " \
+        "that returns the class, e.g., foreign: -> {Foo}"
+      )
+    end
+
+    if !foreign.is_a?(Proc) && !foreign.is_a?(Array) && !foreign.respond_to?(:load)
+      raise ArgumentError.new("The `#{option_sym}` option must be #{valid_type_msg}")
+    end
+  end
+
+  sig do
+    params(
+      prop_cls: Module,
+      foreign_hint_only: T.untyped,
+    )
+    .void
+  end
+  private def handle_foreign_hint_only_option(prop_cls, foreign_hint_only)
+    if ![String, Array].include?(prop_cls) && !(prop_cls.is_a?(T::Props::CustomType))
+      raise ArgumentError.new(
+        "`foreign_hint_only` can only be used with String or Array prop types"
+      )
+    end
+
+    validate_foreign_option(
+      :foreign_hint_only, foreign_hint_only,
+      valid_type_msg: "an individual or array of a model class, or a Proc returning such."
+    )
+  end
+
+  sig do
+    params(
+      prop_name: T.any(String, Symbol),
+      rules: Rules,
+      foreign: T.untyped,
+    )
+    .void
+  end
+  private def define_foreign_method(prop_name, rules, foreign)
+    fk_method = "#{prop_name}_"
+
+    # n.b. there's no clear reason *not* to allow additional options
+    # here, but we're baking in `allow_direct_mutation` since we
+    # *haven't* allowed additional options in the past and want to
+    # default to keeping this interface narrow.
+    @class.send(:define_method, fk_method) do |allow_direct_mutation: nil|
+      if foreign.is_a?(Proc)
+        resolved_foreign = foreign.call
+        if !resolved_foreign.respond_to?(:load)
+          raise ArgumentError.new(
+            "The `foreign` proc for `#{prop_name}` must return a model class. " \
+            "Got `#{resolved_foreign.inspect}` instead."
+          )
+        end
+        # `foreign` is part of the closure state, so this will persist to future invocations
+        # of the method, optimizing it so this only runs on the first invocation.
+        foreign = resolved_foreign
+      end
+      if allow_direct_mutation.nil?
+        opts = {}
+      else
+        opts = {allow_direct_mutation: allow_direct_mutation}
+      end
+
+      self.class.decorator.foreign_prop_get(self, prop_name, foreign, rules, opts)
+    end
+
+    force_fk_method = "#{fk_method}!"
+    @class.send(:define_method, force_fk_method) do |allow_direct_mutation: nil|
+      loaded_foreign = send(fk_method, allow_direct_mutation: allow_direct_mutation)
+      if !loaded_foreign
+        T::Configuration.hard_assert_handler(
+          'Failed to load foreign model',
+          storytime: {method: force_fk_method, class: self.class}
+        )
+      end
+      T.must(loaded_foreign)
+    end
+
+    @class.send(:define_method, "#{prop_name}_record") do |allow_direct_mutation: nil|
+      T::Configuration.soft_assert_handler(
+        "Using deprecated 'model.#{prop_name}_record' foreign key syntax. You should replace this with 'model.#{prop_name}_'",
+        notify: 'vasi'
+      )
+      send(fk_method, allow_direct_mutation: allow_direct_mutation)
+    end
+  end
+
+  sig do
+    params(
+      prop_name: Symbol,
+      prop_cls: Module,
+      rules: Rules,
+      foreign: T.untyped,
+    )
+    .void
+  end
+  private def handle_foreign_option(prop_name, prop_cls, rules, foreign)
+    validate_foreign_option(
+      :foreign, foreign, valid_type_msg: "a model class or a Proc that returns one"
+    )
+
+    if prop_cls != String
+      raise ArgumentError.new("`foreign` can only be used with a prop type of String")
+    end
+
+    if foreign.is_a?(Array)
+      # We don't support arrays with `foreign` because it's hard to both preserve ordering and
+      # keep them from being lurky performance hits by issuing a bunch of un-batched DB queries.
+      # We could potentially address that by porting over something like AmbiguousIDLoader.
+      raise ArgumentError.new(
+        "Using an array for `foreign` is no longer supported. Instead, use `foreign_hint_only` " \
+        "with an array or a Proc that returns an array, e.g., foreign_hint_only: -> {[Foo, Bar]}"
+      )
+    end
+
+    define_foreign_method(prop_name, rules, foreign)
+  end
+
+  # TODO: rename this to props_inherited
+  #
+  # This gets called when a module or class that extends T::Props gets included, extended,
+  # prepended, or inherited.
+  sig {params(child: DecoratedClass).void}
+  def model_inherited(child)
+    child.extend(T::Props::ClassMethods)
+    child.plugins.concat(decorated_class.plugins)
+
+    decorated_class.plugins.each do |mod|
+      # NB: apply_class_methods must not be an instance method on the decorator itself,
+      # otherwise we'd have to call child.decorator here, which would create the decorator
+      # before any `decorator_class` override has a chance to take effect (see the comment below).
+      Private.apply_class_methods(mod, child)
+    end
+
+    props.each do |name, rules|
+      copied_rules = rules.dup
+      # NB: Calling `child.decorator` here is a timb bomb that's going to give someone a really bad
+      # time. Any class that defines props and also overrides the `decorator_class` method is going
+      # to reach this line before its override take effect, turning it into a no-op.
+      child.decorator.add_prop_definition(name, copied_rules)
+    end
+  end
+
+  sig {params(mod: Module).void}
+  def plugin(mod)
+    decorated_class.plugins << mod
+    Private.apply_class_methods(mod, decorated_class)
+    Private.apply_decorator_methods(mod, self)
+  end
+
+  module Private
+    # These need to be non-instance methods so we can use them without prematurely creating the
+    # child decorator in `model_inherited` (see comments there for details).
+    def self.apply_class_methods(plugin, target)
+      if plugin.const_defined?('ClassMethods')
+        # FIXME: This will break preloading, selective test execution, etc if `mod::ClassMethods`
+        # is ever defined in a separate file from `mod`.
+        target.extend(plugin::ClassMethods) # rubocop:disable PrisonGuard/NoDynamicConstAccess
+      end
+    end
+
+    def self.apply_decorator_methods(plugin, target)
+      if plugin.const_defined?('DecoratorMethods')
+        # FIXME: This will break preloading, selective test execution, etc if `mod::DecoratorMethods`
+        # is ever defined in a separate file from `mod`.
+        target.extend(plugin::DecoratorMethods) # rubocop:disable PrisonGuard/NoDynamicConstAccess
+      end
+    end
+  end
+end