fsdk-2237-ruby-e2e 0.1.0

data/lib/petstore/internal/types/enum.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      # Module for defining enums
+      module Enum
+        include Type
+
+        # @api private
+        #
+        # @return [Array<Object>]
+        def values
+          @values ||= constants.map { |c| const_get(c) }
+        end
+
+        # @api private
+        def finalize!
+          values
+        end
+
+        # @api private
+        def strict?
+          @strict ||= false
+        end
+
+        # @api private
+        def strict!
+          @strict = true
+        end
+
+        def coerce(value, strict: strict?)
+          coerced_value = Utils.coerce(Symbol, value)
+
+          return coerced_value if values.include?(coerced_value)
+
+          raise Errors::TypeError, "`#{value}` not in enum #{self}" if strict
+
+          value
+        end
+
+        # Parse JSON string and coerce to the enum value
+        #
+        # @param str [String] JSON string to parse
+        # @return [String] The enum value
+        def load(str)
+          coerce(::JSON.parse(str))
+        end
+
+        def inspect
+          "#{name}[#{values.join(', ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/petstore/internal/types/hash.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      class Hash
+        include Type
+
+        attr_reader :key_type, :value_type
+
+        class << self
+          def [](key_type, value_type)
+            new(key_type, value_type)
+          end
+        end
+
+        def initialize(key_type, value_type)
+          @key_type = key_type
+          @value_type = value_type
+        end
+
+        def coerce(value, strict: strict?)
+          unless value.is_a?(::Hash)
+            raise Errors::TypeError, 'not hash' if strict
+
+            return value
+          end
+
+          value.to_h do |k, v|
+            [Utils.coerce(key_type, k, strict: strict), Utils.coerce(value_type, v, strict: strict)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petstore/internal/types/model/field.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      class Model
+        # Definition of a field on a model
+        class Field
+          SENSITIVE_FIELD_NAMES = %i[
+            password secret token api_key apikey access_token refresh_token
+            client_secret client_id credential bearer authorization
+          ].freeze
+
+          attr_reader :name, :type, :optional, :nullable, :api_name, :value, :default
+
+          def initialize(name:, type:, optional: false, nullable: false, api_name: nil, value: nil, default: nil)
+            @name = name.to_sym
+            @type = type
+            @optional = optional
+            @nullable = nullable
+            @api_name = api_name || name.to_s
+            @value = value
+            @default = default
+          end
+
+          def literal?
+            !value.nil?
+          end
+
+          def sensitive?
+            SENSITIVE_FIELD_NAMES.include?(@name) ||
+              SENSITIVE_FIELD_NAMES.any? { |sensitive| @name.to_s.include?(sensitive.to_s) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petstore/internal/types/model.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      # @abstract
+      #
+      # An abstract model that all data objects will inherit from
+      class Model
+        include Type
+
+        class << self
+          # The defined fields for this model
+          #
+          # @api private
+          #
+          # @return [Hash<Symbol, Field>]
+          def fields
+            @fields ||= if self < ::Petstore::Internal::Types::Model
+                          superclass.fields.dup
+                        else
+                          {}
+                        end
+          end
+
+          # Any extra fields that have been created from instantiation
+          #
+          # @api private
+          #
+          # @return [Hash<Symbol, Field>]
+          def extra_fields
+            @extra_fields ||= {}
+          end
+
+          # Define a new field on this model
+          #
+          # @param name [Symbol] The name of the field
+          # @param type [Class] Type of the field
+          # @option optional [Boolean] If it is an optional field
+          # @option nullable [Boolean] If it is a nullable field
+          # @option api_name [Symbol, String] Name in the API of this field. When serializing/deserializing, will use
+          #   this field name
+          # @return [void]
+          def field(name, type, optional: false, nullable: false, api_name: nil, default: nil)
+            add_field_definition(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
+                                 default: default)
+
+            define_accessor(name)
+            define_setter(name)
+          end
+
+          # Define a new literal for this model
+          #
+          # @param name [Symbol]
+          # @param value [Object]
+          # @option api_name [Symbol, String]
+          # @return [void]
+          def literal(name, value, api_name: nil)
+            add_field_definition(name: name, type: value.class, optional: false, nullable: false, api_name: api_name,
+                                 value: value)
+
+            define_accessor(name)
+          end
+
+          # Adds a new field definition into the class's extra fields registry
+          #
+          # @api private
+          #
+          # @param name [Symbol]
+          # @param type [Class]
+          # @option required [Boolean]
+          # @option optional [Boolean]
+          # @return [void]
+          def add_extra_field_definition(name:, type:)
+            return if extra_fields.key?(name.to_sym)
+
+            extra_fields[name.to_sym] = Field.new(name: name, type: type, optional: true, nullable: false)
+
+            define_accessor(name)
+            define_setter(name)
+          end
+
+          def coerce(value, strict: (respond_to?(:strict?) ? strict? : false))
+            return value if value.is_a?(self)
+
+            return value unless value.is_a?(::Hash)
+
+            new(value)
+          end
+
+          def load(str)
+            coerce(::JSON.parse(str, symbolize_names: true))
+          end
+
+          def ===(instance)
+            instance.class.ancestors.include?(self)
+          end
+
+          private
+
+          # Adds a new field definition into the class's fields registry
+          #
+          # @api private
+          #
+          # @param name [Symbol]
+          # @param type [Class]
+          # @option optional [Boolean]
+          # @return [void]
+          def add_field_definition(name:, type:, optional:, nullable:, api_name:, default: nil, value: nil)
+            fields[name.to_sym] =
+              Field.new(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
+                        value: value, default: default)
+          end
+
+          # @api private
+          def define_accessor(name)
+            method_name = name.to_sym
+
+            define_method(method_name) do
+              @data[name]
+            end
+          end
+
+          # @api private
+          def define_setter(name)
+            method_name = :"#{name}="
+
+            define_method(method_name) do |val|
+              @data[name] = val
+            end
+          end
+        end
+
+        # Creates a new instance of this model
+        # TODO: Should all this logic be in `#coerce` instead?
+        #
+        # @param values [Hash]
+        # @option strict [Boolean]
+        # @return [self]
+        def initialize(values = {})
+          @data = {}
+
+          values = Utils.symbolize_keys(values.dup)
+
+          self.class.fields.each do |field_name, field|
+            # Presence, not truthiness: `values[key]` cannot tell "absent" from "explicitly nil",
+            # and `to_h` needs that distinction — an explicit null is "delete this field" to a
+            # `merge-patch` endpoint, while an absent one must stay absent.
+            provided_key = [field.api_name.to_sym, field.api_name, field_name].find { |key| values.key?(key) }
+            value = provided_key.nil? ? nil : values.delete(provided_key)
+
+            # Presence again, not truthiness: `value || default` replaced an explicitly-passed
+            # `false` with the literal/default, `false` being falsy in Ruby. An explicit nil now
+            # wins over the default too — asking for null is not asking for the default.
+            field_value = if !provided_key.nil?
+                            value
+                          elsif field.literal?
+                            field.value
+                          elsif field.default
+                            field.default
+                          end
+
+            # An optional field the caller never mentioned is left OUT of `@data` rather than
+            # materialized as an explicit nil, which `to_h` would have serialized as `null`.
+            next if provided_key.nil? && field_value.nil? && field.optional
+
+            @data[field_name] = Utils.coerce(field.type, field_value)
+          end
+
+          # Any remaining values in the input become extra fields
+          values.each do |name, value|
+            self.class.add_extra_field_definition(name: name, type: value.class)
+
+            @data[name.to_sym] = value
+          end
+        end
+
+        def to_h
+          result = self.class.fields.merge(self.class.extra_fields).each_with_object({}) do |(name, field), acc|
+            # Keyed on PRESENCE first, then on nullability:
+            #   absent                     -> omitted, for the reason `initialize` gives above
+            #   explicit nil, nullable     -> `null`; that is exactly what the caller asked for
+            #   explicit nil, NOT nullable -> omitted; the declared schema forbids null
+
+            value = @data[name]
+
+            next if field.optional && !@data.key?(name)
+            next if value.nil? && field.optional && !field.nullable
+
+            acc[field.api_name] = serialize_value(value)
+          end
+
+          # Inject union discriminant if this instance was coerced from a discriminated union
+          # and the discriminant key is not already present in the result
+          discriminant_key = instance_variable_get(:@_fern_union_discriminant_key)
+          discriminant_value = instance_variable_get(:@_fern_union_discriminant_value)
+          result[discriminant_key] = discriminant_value if discriminant_key && discriminant_value && !result.key?(discriminant_key)
+
+          result
+        end
+
+        def ==(other)
+          self.class == other.class && to_h == other.to_h
+        end
+
+        # @return [String]
+        def inspect
+          attrs = @data.map do |name, value|
+            field = self.class.fields[name] || self.class.extra_fields[name]
+            display_value = field&.sensitive? ? '[REDACTED]' : value.inspect
+            "#{name}=#{display_value}"
+          end
+
+          "#<#{self.class.name}:0x#{object_id&.to_s(16)} #{attrs.join(' ')}>"
+        end
+
+        private
+
+        # `::Hash#to_h` returns itself rather than recursing, so a model nested inside a
+        # dictionary-typed field's VALUES (not just a direct model field) needs an explicit
+        # recursive walk here rather than the bare `value.to_h` this used to do. `Symbol` is
+        # handled the same way: enum members are coerced to `Symbol` on the way in
+        # (`Internal::Types::Enum#coerce`) so they round-trip through `==`/`Set` lookups, but the
+        # wire shape is always the original string value.
+        def serialize_value(value)
+          case value
+          when ::Symbol
+            value.to_s
+          when ::Array
+            value.map { |item| serialize_value(item) }
+          when ::Hash
+            value.transform_values { |item| serialize_value(item) }
+          else
+            # `respond_to?(:to_h)`, not `is_a?(Model)`: a free-form/`any`-typed field can hold
+            # whatever a caller constructs it with, not only this SDK's own model classes --
+            # `Struct`, `OpenStruct`, `Data`, and similar objects respond to `#to_h` too, and
+            # narrowing to `Model` would silently fall through to `#to_s` in `JSON.generate` for
+            # any of them. `Model#to_h` itself routes back through this same method for every
+            # field, so a nested `Model` value still serializes correctly through this branch.
+            !value.nil? && value.respond_to?(:to_h) ? value.to_h : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petstore/internal/types/type.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      # @abstract
+      module Type
+        include ::Petstore::Internal::JSON::Serializable
+
+        # Coerces a value to this type
+        #
+        # @param value [unknown]
+        # @option strict [Boolean] If we should strictly coerce this value
+        def coerce(value, strict: strict?)
+          raise NotImplementedError
+        end
+
+        # Returns if strictness is on for this type, defaults to `false`
+        #
+        # @return [Boolean]
+        def strict?
+          @strict ||= false
+        end
+
+        # Enable strictness by default for this type
+        #
+        # @return [void]
+        def strict!
+          @strict = true
+          self
+        end
+      end
+    end
+  end
+end

data/lib/petstore/internal/types/union.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      # Define a union between two types
+      module Union
+        include ::Petstore::Internal::Types::Type
+
+        def members
+          @members ||= []
+        end
+
+        # Add a member to this union
+        #
+        # @param type [Object]
+        # @option key [Symbol, String]
+        # @return [void]
+        def member(type, key: nil)
+          members.push([key, Utils.wrap_type(type)])
+          self
+        end
+
+        def type_member?(type)
+          members.any? { |_key, type_fn| type == type_fn.call }
+        end
+
+        # Set the discriminant for this union
+        #
+        # @param key [Symbol, String]
+        # @return [void]
+        def discriminant(key)
+          @discriminant = key
+        end
+
+        def coerce(value, strict: strict?)
+          type = resolve_member(value)
+
+          unless type
+            return value unless strict
+
+            if discriminated?
+              raise Errors::TypeError,
+                    "value of type `#{value.class}` not member of union #{self}"
+            end
+
+            raise Errors::TypeError, "could not resolve to member of union #{self}"
+          end
+
+          coerced = Utils.coerce(type, value, strict: strict)
+
+          # For discriminated unions, store the discriminant info on the coerced instance
+          # so it can be injected back during serialization (to_h)
+          if discriminated? && value.is_a?(::Hash) && coerced.is_a?(Model)
+            discriminant_value = value.fetch(@discriminant, nil) || value.fetch(@discriminant.to_s, nil)
+            if discriminant_value
+              coerced.instance_variable_set(:@_fern_union_discriminant_key, @discriminant.to_s)
+              coerced.instance_variable_set(:@_fern_union_discriminant_value, discriminant_value)
+            end
+          end
+
+          coerced
+        end
+
+        # Parse JSON string and coerce to the correct union member type
+        #
+        # @param str [String] JSON string to parse
+        # @return [Object] Coerced value matching a union member
+        def load(str)
+          coerce(::JSON.parse(str, symbolize_names: true))
+        end
+
+        # FSDK-1660: like +load+, but RAISES when the value matches no member instead of handing
+        # the raw parsed value back.
+        #
+        # +load+ returns the value untouched in that case, because +coerce+ only raises under
+        # strictness and +strict?+ defaults to false. That is correct for a REQUEST body, where the
+        # caller's value is theirs to send. It is wrong for a DECLARED SUCCESS RESPONSE: the
+        # method's return type is this union, so a bare ::Hash violates it, and the caller found
+        # out through a +NoMethodError+ from +result.field+ a long way from the real cause.
+        #
+        # Only member RESOLUTION is enforced here. The matched member is coerced exactly as +load+
+        # coerces it — non-strict — so nothing that used to deserialize stops deserializing; the
+        # only bodies that change behaviour are the ones that produced no typed value at all.
+        #
+        # Note a generated union module defines its OWN +self.load+, which shadows the one above;
+        # this method is unshadowed and is deliberately self-contained rather than delegating, so
+        # it does not depend on which +load+ wins.
+        #
+        # @param str [String] JSON string to parse
+        # @return [Object] Coerced value matching a union member
+        # @raise [Errors::TypeError] If the value matches no member of this union.
+        def load!(str)
+          value = ::JSON.parse(str, symbolize_names: true)
+          unless resolve_member(value)
+            raise Errors::TypeError,
+                  "response body could not be resolved to a member of union #{self}"
+          end
+
+          coerce(value)
+        end
+
+        private
+
+        # @api private
+        def discriminated?
+          !@discriminant.nil?
+        end
+
+        # Check if value matches a type, handling type wrapper instances
+        # (Internal::Types::Hash and Internal::Types::Array instances)
+        #
+        # @param value [Object]
+        # @param member_type [Object]
+        # @return [Boolean]
+        def type_matches?(value, member_type)
+          case member_type
+          when ::Petstore::Internal::Types::Hash
+            value.is_a?(::Hash)
+          when ::Petstore::Internal::Types::Array
+            value.is_a?(::Array)
+          when Class, Module
+            value.is_a?(member_type)
+          else
+            false
+          end
+        end
+
+        # Resolves the type of a value to be one of the members
+        #
+        # @param value [Object]
+        # @return [Class]
+        def resolve_member(value)
+          if discriminated? && value.is_a?(::Hash)
+            # Try both symbol and string keys for the discriminant
+            discriminant_value = value.fetch(@discriminant, nil) || value.fetch(@discriminant.to_s, nil)
+
+            return if discriminant_value.nil?
+
+            # Convert to string for consistent comparison
+            discriminant_str = discriminant_value.to_s
+
+            # First try exact match
+            members_hash = members.to_h
+            result = members_hash[discriminant_str]&.call
+            return result if result
+
+            # Try case-insensitive match as fallback
+            discriminant_lower = discriminant_str.downcase
+            matching_keys = members_hash.keys.select { |k| k.to_s.downcase == discriminant_lower }
+
+            # Only use case-insensitive match if exactly one key matches (avoid ambiguity)
+            return members_hash[matching_keys.first]&.call if matching_keys.length == 1
+
+            nil
+          else
+            # First try exact type matching
+            result = members.find do |_key, mem|
+              member_type = Utils.unwrap_type(mem)
+              type_matches?(value, member_type)
+            end&.last&.call
+
+            return result if result
+
+            # For Hash values, try to coerce into Model member types
+            if value.is_a?(::Hash)
+              members.find do |_key, mem|
+                member_type = Utils.unwrap_type(mem)
+                # Check if member_type is a Model class
+                next unless member_type.is_a?(Class) && member_type <= Model
+
+                # Try to coerce the hash into this model type with strict mode
+                begin
+                  candidate = Utils.coerce(member_type, value, strict: true)
+
+                  # Validate that all required (non-optional) fields are present
+                  # This ensures undiscriminated unions properly distinguish between member types
+                  member_type.fields.each do |field_name, field|
+                    raise Errors::TypeError, "Required field `#{field_name}` missing for union member #{member_type.name}" if candidate.instance_variable_get(:@data)[field_name].nil? && !field.optional
+                  end
+
+                  true
+                rescue Errors::TypeError
+                  false
+                end
+              end&.last&.call
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/petstore/internal/types/unknown.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Petstore
+  module Internal
+    module Types
+      module Unknown
+        include ::Petstore::Internal::Types::Type
+
+        def coerce(value)
+          value
+        end
+      end
+    end
+  end
+end