rapitapir 0.1.0

data/lib/rapitapir/core/endpoint.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Core
+    # Core endpoint definition representing an HTTP API endpoint
+    #
+    # Encapsulates the definition of an HTTP endpoint including its method, path,
+    # input parameters, output formats, error responses, and metadata.
+    #
+    # @example Create an endpoint
+    #   endpoint = RapiTapir::Core::Endpoint.new(
+    #     method: :get,
+    #     path: '/users/{id}',
+    #     inputs: [path_param(:id, :integer)],
+    #     outputs: [json_output(user_schema)]
+    #   )
+    class Endpoint
+      HTTP_METHODS = %i[get post put patch delete options head].freeze
+
+      attr_reader :method, :path, :inputs, :outputs, :errors, :metadata
+
+      def initialize(**options)
+        @method = options[:method]
+        @path = options[:path]
+        @inputs = (options[:inputs] || []).freeze
+        @outputs = (options[:outputs] || []).freeze
+        @errors = (options[:errors] || []).freeze
+        @metadata = (options[:metadata] || {}).freeze
+      end
+
+      HTTP_METHODS.each do |http_method|
+        define_singleton_method(http_method) do |path = nil|
+          new(method: http_method, path: path)
+        end
+      end
+
+      def in(input)
+        validate_input!(input)
+        copy_with(inputs: inputs + [input])
+      end
+
+      def out(output)
+        validate_output!(output)
+        copy_with(outputs: outputs + [output])
+      end
+
+      def error_out(code, output, **options)
+        validate_status_code!(code)
+        validate_output!(output)
+        error_entry = { code: code, output: output }.merge(options)
+        copy_with(errors: errors + [error_entry])
+      end
+
+      def with_metadata(**meta)
+        copy_with(metadata: metadata.merge(meta))
+      end
+
+      def description(text)
+        with_metadata(description: text)
+      end
+
+      def summary(text)
+        with_metadata(summary: text)
+      end
+
+      def tag(name)
+        with_metadata(tag: name)
+      end
+
+      def deprecated(*args, **kwargs)
+        # Support both deprecated(true/false) and deprecated(flag: true/false)
+        flag_value = if args.length.positive?
+                       args.first
+                     else
+                       kwargs.fetch(:flag, true)
+                     end
+        with_metadata(deprecated: flag_value)
+      end
+
+      # Validate input/output types for a given input/output hash
+      # Raises validation errors if invalid, returns true if valid
+      def validate!(input_hash = {}, output_hash = {}) # rubocop:disable Naming/PredicateMethod
+        validate_inputs!(input_hash)
+        validate_outputs!(output_hash) unless output_hash.empty?
+        true
+      end
+
+      def to_h
+        {
+          method: method,
+          path: path,
+          inputs: inputs.map(&:to_h),
+          outputs: outputs.map(&:to_h),
+          errors: errors,
+          metadata: metadata
+        }
+      end
+
+      private
+
+      def copy_with(**changes)
+        self.class.new(
+          method: changes.fetch(:method, method),
+          path: changes.fetch(:path, path),
+          inputs: changes.fetch(:inputs, inputs),
+          outputs: changes.fetch(:outputs, outputs),
+          errors: changes.fetch(:errors, errors),
+          metadata: changes.fetch(:metadata, metadata)
+        )
+      end
+
+      def validate_input!(input)
+        return if input.respond_to?(:kind) && input.respond_to?(:name) && input.respond_to?(:type)
+
+        raise ArgumentError, 'Input must respond to :kind, :name, and :type'
+      end
+
+      def validate_output!(output)
+        return if output.respond_to?(:kind) && output.respond_to?(:type)
+
+        raise ArgumentError, 'Output must respond to :kind and :type'
+      end
+
+      def validate_status_code!(code)
+        return if code.is_a?(Integer) && code >= 100 && code <= 599
+
+        raise ArgumentError, "Invalid status code: #{code}. Must be an integer between 100-599"
+      end
+
+      def validate_inputs!(input_hash)
+        inputs.each do |input|
+          next unless input_hash.key?(input.name)
+
+          unless input.valid_type?(input_hash[input.name])
+            raise TypeError,
+                  "Invalid type for input '#{input.name}': expected #{input.type}, got #{input_hash[input.name].class}"
+          end
+        end
+      end
+
+      def validate_outputs!(output_hash)
+        outputs.each do |output|
+          if output.type.is_a?(Hash)
+            unless output.valid_type?(output_hash)
+              raise TypeError, "Invalid output hash: expected #{output.type}, got #{output_hash}"
+            end
+          else
+            output_hash.each do |k, v|
+              unless output.valid_type?(v)
+                raise TypeError, "Invalid type for output '#{k}': expected #{output.type}, got #{v.class}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/core/enhanced_endpoint.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require_relative 'endpoint'
+require_relative '../dsl/enhanced_endpoint_dsl'
+require_relative '../types'
+require_relative '../schema'
+
+module RapiTapir
+  module Core
+    # Enhanced Endpoint class that integrates with the new type system
+    class EnhancedEndpoint < Endpoint
+      attr_reader :security_schemes, :custom_validators
+
+      def initialize(**options)
+        super
+        @security_schemes = []
+        @custom_validators = []
+      end
+
+      # Type validation helpers
+      def validate_with_type(type, value)
+        return true if type.nil?
+
+        type.validate(value)
+        true
+      rescue Types::CoercionError => e
+        raise ValidationError, "Type validation failed: #{e.message}"
+      end
+
+      # Enhanced error handling with typed errors
+      def error_out(status_code, error_type_def, **options)
+        error_type = resolve_type(error_type_def)
+        error_output = DSL::EnhancedOutput.new(
+          kind: :json,
+          type: error_type,
+          options: options.merge(status_code: status_code)
+        )
+
+        error_entry = {
+          code: status_code,
+          output: error_output,
+          type: error_type
+        }.merge(options)
+
+        copy_with(errors: errors + [error_entry])
+      end
+
+      # Security integration
+      def security_in(auth_scheme)
+        copy_with(
+          inputs: inputs + [auth_scheme],
+          security_schemes: security_schemes + [auth_scheme]
+        )
+      end
+
+      # Validation integration
+      def validate_request_with(validator)
+        new_validators = custom_validators + [validator]
+        copy_with_validators(new_validators)
+      end
+
+      # Process a request with full type validation
+      def process_request(extracted_inputs)
+        run_custom_validators(extracted_inputs)
+        validate_input_values(extracted_inputs)
+        extracted_inputs
+      end
+
+      private
+
+      def run_custom_validators(extracted_inputs)
+        custom_validators.each do |validator|
+          validator.call(extracted_inputs)
+        end
+      end
+
+      def validate_input_values(extracted_inputs)
+        validation_errors = collect_input_validation_errors(extracted_inputs)
+        raise ValidationError, build_validation_error_message(validation_errors) if validation_errors.any?
+      end
+
+      def collect_input_validation_errors(extracted_inputs)
+        validation_errors = []
+
+        inputs.each do |input|
+          next unless extracted_inputs.key?(input.name)
+
+          value = extracted_inputs[input.name]
+          result = input.validate(value)
+          next if result[:valid]
+
+          add_input_errors_to_collection(validation_errors, input, result[:errors])
+        end
+
+        validation_errors
+      end
+
+      def add_input_errors_to_collection(validation_errors, input, errors)
+        errors.each do |error|
+          validation_errors << "Input '#{input.name}': #{error}"
+        end
+      end
+
+      def build_validation_error_message(validation_errors)
+        "Request validation failed:\n#{validation_errors.join("\n")}"
+      end
+
+      public
+
+      # Generate OpenAPI specification for this endpoint
+      def to_openapi_spec
+        spec = build_base_spec
+        add_parameters_to_spec(spec)
+        add_request_body_to_spec(spec)
+        add_responses_to_spec(spec)
+        add_error_responses_to_spec(spec)
+        add_security_to_spec(spec)
+        spec.compact
+      end
+
+      # Enhanced validation with detailed errors
+      def validate!
+        super
+
+        # Additional validations for enhanced features
+        validate_security_schemes!
+        validate_type_consistency!
+      end
+
+      private
+
+      def build_base_spec
+        {
+          summary: metadata[:summary],
+          description: metadata[:description],
+          tags: Array(metadata[:tags]),
+          parameters: [],
+          responses: {}
+        }
+      end
+
+      def add_parameters_to_spec(spec)
+        inputs.each do |input|
+          next if input.kind == :body
+
+          spec[:parameters] << input.to_openapi_parameter
+        end
+      end
+
+      def add_request_body_to_spec(spec)
+        body_input = inputs.find { |i| i.kind == :body }
+        return unless body_input
+
+        spec[:requestBody] = {
+          required: body_input.required?,
+          content: {
+            'application/json' => {
+              schema: body_input.type.to_json_schema
+            }
+          }
+        }
+      end
+
+      def add_responses_to_spec(spec)
+        outputs.each do |output|
+          next if output.kind == :status
+
+          status_code = find_status_code || 200
+          spec[:responses][status_code.to_s] = output.to_openapi_response
+        end
+      end
+
+      def add_error_responses_to_spec(spec)
+        errors.each do |error|
+          spec[:responses][error[:code].to_s] = error[:output].to_openapi_response
+        end
+      end
+
+      def add_security_to_spec(spec)
+        return unless security_schemes.any?
+
+        spec[:security] = security_schemes.map do |scheme|
+          map_security_scheme_to_openapi(scheme)
+        end
+      end
+
+      def map_security_scheme_to_openapi(scheme)
+        case scheme.options[:auth_type]
+        when :bearer
+          { 'bearerAuth' => [] }
+        when :api_key
+          { 'apiKeyAuth' => [] }
+        when :basic
+          { 'basicAuth' => [] }
+        else
+          {}
+        end
+      end
+
+      def copy_with_validators(new_validators)
+        new_endpoint = copy_with({})
+        new_endpoint.instance_variable_set(:@custom_validators, new_validators)
+        new_endpoint
+      end
+
+      def find_status_code
+        status_output = outputs.find { |o| o.kind == :status }
+        status_output&.type
+      end
+
+      def validate_security_schemes!
+        security_schemes.each do |scheme|
+          unless %i[bearer api_key basic].include?(scheme.options[:auth_type])
+            raise ArgumentError, "Unknown authentication type: #{scheme.options[:auth_type]}"
+          end
+        end
+      end
+
+      def validate_type_consistency!
+        inputs.each do |input|
+          unless input.type.respond_to?(:validate)
+            raise ArgumentError, "Input '#{input.name}' type does not support validation"
+          end
+        end
+
+        outputs.each do |output|
+          next if output.kind == :status
+          raise ArgumentError, 'Output type does not support validation' unless output.type.respond_to?(:validate)
+        end
+      end
+
+      class ValidationError < StandardError; end
+    end
+  end
+end

data/lib/rapitapir/core/input.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Core
+    # Input parameter definition for HTTP endpoints
+    #
+    # Represents different types of input parameters that an endpoint can accept,
+    # including query parameters, path parameters, headers, and request body.
+    #
+    # @example Query parameter
+    #   RapiTapir::Core::Input.new(kind: :query, name: :limit, type: :integer)
+    #
+    # @example Path parameter
+    #   RapiTapir::Core::Input.new(kind: :path, name: :id, type: :string)
+    class Input
+      VALID_KINDS = %i[query path header body].freeze
+      VALID_TYPES = %i[string integer float boolean date datetime].freeze
+
+      attr_reader :kind, :name, :type, :options
+
+      def initialize(kind:, name:, type:, options: {})
+        validate_kind!(kind)
+        validate_name!(name)
+        validate_type!(type)
+
+        @kind = kind
+        @name = name.to_sym
+        @type = type
+        @options = options.freeze
+      end
+
+      def required?
+        !options[:optional]
+      end
+
+      def optional?
+        !!options[:optional]
+      end
+
+      def valid_type?(value)
+        return true if value.nil? && optional?
+
+        validate_type_match(value, type)
+      end
+
+      def validate_type_match(value, target_type)
+        case target_type
+        when :string then value.is_a?(String)
+        when :integer then value.is_a?(Integer)
+        when :float then numeric_value?(value)
+        when :boolean then boolean_value?(value)
+        else
+          validate_complex_type_match(value, target_type)
+        end
+      end
+
+      def validate_complex_type_match(value, target_type)
+        case target_type
+        when :date then validate_date_type(value)
+        when :datetime then validate_datetime_type(value)
+        when Hash then validate_hash_type(value)
+        when Class then value.is_a?(target_type)
+        else true # Accept any for custom types
+        end
+      end
+
+      def numeric_value?(value)
+        value.is_a?(Float) || value.is_a?(Integer)
+      end
+
+      def boolean_value?(value)
+        [true, false].include?(value)
+      end
+
+      def validate_date_type(value)
+        value.is_a?(Date) || (value.is_a?(String) && date_string?(value))
+      end
+
+      def validate_datetime_type(value)
+        value.is_a?(DateTime) || (value.is_a?(String) && datetime_string?(value))
+      end
+
+      def coerce(value)
+        return nil if value.nil? && optional?
+
+        coerce_by_type(value, type)
+      rescue ArgumentError => e
+        raise TypeError, "Cannot coerce #{value.inspect} to #{type}: #{e.message}"
+      end
+
+      def coerce_by_type(value, target_type)
+        case target_type
+        when :string then value.to_s
+        when :integer then Integer(value)
+        when :float then Float(value)
+        when :boolean then !!value
+        when :date then coerce_to_date(value)
+        when :datetime then coerce_to_datetime(value)
+        else value
+        end
+      end
+
+      def coerce_to_date(value)
+        value.is_a?(Date) ? value : Date.parse(value.to_s)
+      end
+
+      def coerce_to_datetime(value)
+        value.is_a?(DateTime) ? value : DateTime.parse(value.to_s)
+      end
+
+      def to_h
+        {
+          kind: kind,
+          name: name,
+          type: type,
+          options: options,
+          required: required?
+        }
+      end
+
+      private
+
+      def validate_kind!(kind)
+        return if VALID_KINDS.include?(kind)
+
+        raise ArgumentError, "Invalid kind: #{kind}. Must be one of #{VALID_KINDS}"
+      end
+
+      def validate_name!(name)
+        return unless name.nil? || (name.respond_to?(:empty?) && name.empty?)
+
+        raise ArgumentError, 'Input name cannot be nil or empty'
+      end
+
+      def validate_type!(type)
+        return if VALID_TYPES.include?(type) || type.is_a?(Hash) || type.is_a?(Class)
+
+        raise ArgumentError, "Invalid type: #{type}. Must be one of #{VALID_TYPES}, a Hash, or a Class"
+      end
+
+      def validate_hash_type(value)
+        return false unless value.is_a?(Hash)
+
+        type.all? do |key, expected_type|
+          valid_hash_field_type?(value[key], expected_type)
+        end
+      end
+
+      def valid_hash_field_type?(field_value, expected_type)
+        case expected_type
+        when :string then field_value.is_a?(String)
+        when :integer then field_value.is_a?(Integer)
+        when :float then numeric_field_value?(field_value)
+        when :boolean then boolean_field_value?(field_value)
+        else true
+        end
+      end
+
+      def numeric_field_value?(field_value)
+        field_value.is_a?(Float) || field_value.is_a?(Integer)
+      end
+
+      def boolean_field_value?(field_value)
+        [true, false].include?(field_value)
+      end
+
+      def date_string?(value)
+        Date.parse(value.to_s)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      def datetime_string?(value)
+        DateTime.parse(value.to_s)
+        true
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end