rapitapir 0.1.0

data/lib/rapitapir/server/sinatra_integration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'enhanced_rack_adapter'
+
+module RapiTapir
+  module Server
+    # Sinatra integration for enhanced endpoints
+    module SinatraIntegration
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.class_eval do
+          @rapitapir_adapter = EnhancedRackAdapter.new
+        end
+      end
+
+      # Class methods for Sinatra integration
+      #
+      # Provides methods to define RapiTapir endpoints and generate documentation
+      # within Sinatra applications.
+      module ClassMethods
+        def rapitapir_adapter
+          @rapitapir_adapter ||= EnhancedRackAdapter.new
+        end
+
+        # Mount an endpoint in Sinatra
+        def mount_endpoint(endpoint, &handler)
+          rapitapir_adapter.mount(endpoint, &handler)
+
+          # Register the route with Sinatra
+          method_name = endpoint.method.to_s.downcase
+          path_pattern = convert_path_to_sinatra(endpoint.path)
+
+          send(method_name, path_pattern) do
+            # Delegate to RapiTapir adapter
+            rapitapir_adapter.call(env)
+          end
+        end
+
+        # Use middleware with RapiTapir
+        def rapitapir_use(middleware_class, ...)
+          rapitapir_adapter.use(middleware_class, ...)
+        end
+
+        # Register error handlers
+        def rapitapir_error(error_class, &handler)
+          rapitapir_adapter.on_error(error_class, &handler)
+        end
+
+        # Generate OpenAPI spec for all mounted endpoints
+        def to_openapi_spec(info = {})
+          spec = build_base_openapi_spec(info)
+          add_endpoints_to_spec(spec)
+          spec
+        end
+
+        private
+
+        def build_base_openapi_spec(info)
+          {
+            openapi: '3.0.3',
+            info: build_openapi_info(info),
+            paths: {}
+          }
+        end
+
+        def build_openapi_info(info)
+          {
+            title: info[:title] || 'API',
+            version: info[:version] || '1.0.0',
+            description: info[:description]
+          }.compact
+        end
+
+        def add_endpoints_to_spec(spec)
+          rapitapir_adapter.endpoints.each do |endpoint_data|
+            endpoint = endpoint_data[:endpoint]
+            path = endpoint.path
+            method = endpoint.method.to_s.downcase
+
+            spec[:paths][path] ||= {}
+            spec[:paths][path][method] = endpoint.to_openapi_spec
+          end
+        end
+
+        def convert_path_to_sinatra(path)
+          # Convert RapiTapir path format to Sinatra path format
+          # e.g., "/users/{id}" -> "/users/:id"
+          path.gsub(/\{([^}]+)\}/, ':\1')
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/sinatra/configuration.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Sinatra
+    # Configuration class for RapiTapir Sinatra integration
+    # Follows Single Responsibility Principle - manages configuration only
+    class Configuration
+      attr_accessor :docs_path, :openapi_path, :health_check_enabled, :health_check_path
+      attr_reader :api_info, :servers, :public_paths, :auth_schemes
+
+      def initialize
+        @api_info = {
+          title: 'API Documentation',
+          description: 'Generated with RapiTapir',
+          version: '1.0.0'
+        }
+        @servers = []
+        @public_paths = []
+        @auth_schemes = {}
+        @docs_path = '/docs'
+        @openapi_path = '/openapi.json'
+        @health_check_enabled = false
+        @health_check_path = '/health'
+      end
+
+      # API Information configuration
+      def info(title: nil, description: nil, version: nil, **options)
+        @api_info[:title] = title if title
+        @api_info[:description] = description if description
+        @api_info[:version] = version if version
+        @api_info.merge!(options)
+      end
+
+      # Server configuration
+      def server(url:, description: nil)
+        @servers << { url: url, description: description }.compact
+      end
+
+      # Add paths that don't require authentication
+      def add_public_paths(*paths)
+        @public_paths.concat(paths.flatten.map(&:to_s))
+      end
+
+      # Authentication scheme management
+      def add_auth_scheme(name, scheme)
+        @auth_schemes[name] = scheme
+      end
+
+      def get_auth_scheme(name)
+        @auth_schemes[name]
+      end
+
+      # Check if documentation is enabled
+      def docs_enabled?
+        !@docs_path.nil?
+      end
+
+      # Environment-specific configurations
+      def development_defaults!
+        # Enable health check endpoint
+        enable_health_check
+        # Enable docs by default in development
+        enable_docs unless @docs_path.nil? && @openapi_path.nil?
+        # Add health check to public paths (no auth required)
+        add_public_paths(@health_check_path)
+        puts '📝 Applied development defaults for RapiTapir (includes health check at /health)'
+      end
+
+      def production_defaults!
+        # Basic production settings
+        puts '🔒 Applied production defaults for RapiTapir'
+      end
+
+      # Health check configuration
+      def enable_health_check(path: '/health')
+        @health_check_enabled = true
+        @health_check_path = path
+      end
+
+      def health_check_enabled?
+        @health_check_enabled
+      end
+
+      # Documentation configuration
+      def enable_docs(path: '/docs', openapi_path: '/openapi.json')
+        @docs_path = path
+        @openapi_path = openapi_path
+      end
+    end
+  end
+end

data/lib/rapitapir/sinatra/extension.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require_relative '../server/sinatra_adapter'
+require_relative '../auth'
+require_relative '../openapi/schema_generator'
+require_relative 'configuration'
+require_relative 'resource_builder'
+require_relative 'swagger_ui_generator'
+require_relative 'oauth2_helpers'
+require_relative '../dsl/http_verbs'
+
+module RapiTapir
+  module Sinatra
+    # Main Sinatra Extension for RapiTapir integration
+    # Provides a seamless, ergonomic experience for building enterprise-grade APIs
+    module Extension
+      # Extension registration hook
+      def self.registered(app)
+        app.helpers Helpers
+        app.extend ClassMethods
+        app.extend DSL::HTTPVerbs # Automatically include enhanced HTTP verb DSL
+        app.extend OAuth2Helpers # Include OAuth2 authentication helpers
+        app.set :rapitapir_config, Configuration.new
+        app.set :rapitapir_endpoints, []
+        app.set :rapitapir_adapter, nil
+      end
+
+      # Class methods added to the Sinatra application
+      module ClassMethods
+        # Configure RapiTapir integration
+        def rapitapir(&block)
+          config = settings.rapitapir_config
+          config.instance_eval(&block) if block_given?
+          setup_rapitapir_integration
+        end
+
+        # Register an endpoint with automatic route creation
+        def endpoint(definition, &handler)
+          endpoint_obj = case definition
+                         when RapiTapir::Core::Endpoint, RapiTapir::Core::EnhancedEndpoint
+                           definition
+                         when Proc
+                           definition.call
+                         else
+                           raise ArgumentError, 'Invalid endpoint definition'
+                         end
+
+          # Store the endpoint
+          settings.rapitapir_endpoints << { endpoint: endpoint_obj, handler: handler }
+
+          # Register with adapter if available
+          settings.rapitapir_adapter&.register_endpoint(endpoint_obj, handler)
+
+          endpoint_obj
+        end
+
+        # DSL for common endpoint patterns
+        def api_resource(path, schema:, **options, &block)
+          ResourceBuilder.new(self, path, schema, **options).instance_eval(&block)
+        end
+
+        # Authentication configuration
+        def auth_scheme(name, type, **config)
+          settings.rapitapir_config.add_auth_scheme(name, type, **config)
+        end
+
+        # Middleware configuration
+        def use_rapitapir_middleware(*middleware_types)
+          middleware_types.each { |type| settings.rapitapir_config.enable_middleware(type) }
+        end
+
+        # OpenAPI documentation endpoints
+        def enable_docs(path: '/docs', openapi_path: '/openapi.json')
+          settings.rapitapir_config.docs_path = path
+          settings.rapitapir_config.openapi_path = openapi_path
+        end
+
+        private
+
+        def setup_rapitapir_integration
+          return if settings.rapitapir_adapter
+
+          config = settings.rapitapir_config
+
+          # Create and configure adapter
+          adapter = RapiTapir::Server::SinatraAdapter.new(self)
+          set :rapitapir_adapter, adapter
+
+          # Register existing endpoints
+          settings.rapitapir_endpoints.each do |ep_data|
+            adapter.register_endpoint(ep_data[:endpoint], ep_data[:handler])
+          end
+
+          # Setup documentation endpoints
+          setup_documentation_endpoints(config) if config.docs_enabled?
+
+          # Setup health check endpoint automatically
+          setup_health_check_endpoint(config) if config.health_check_enabled?
+        end
+
+        def setup_documentation_endpoints(config)
+          openapi_path = config.openapi_path
+          docs_path = config.docs_path
+
+          # OpenAPI spec endpoint
+          get openapi_path do
+            content_type :json
+            JSON.pretty_generate(generate_openapi_spec)
+          end
+
+          # Swagger UI endpoint
+          get docs_path do
+            generate_swagger_ui(openapi_path, config.api_info)
+          end
+        end
+
+        def setup_health_check_endpoint(config)
+          health_path = config.health_check_path
+          health_endpoint = build_health_check_endpoint(health_path)
+          health_handler = build_health_check_handler(config)
+
+          # Register the health check endpoint
+          settings.rapitapir_endpoints << { endpoint: health_endpoint, handler: health_handler }
+
+          # Register with adapter
+          settings.rapitapir_adapter&.register_endpoint(health_endpoint, health_handler)
+        end
+
+        def build_health_check_endpoint(health_path)
+          RapiTapir.get(health_path)
+                   .summary('Health check')
+                   .description('Returns the health status of the API')
+                   .tags('Health')
+                   .ok(build_health_check_schema)
+                   .build
+        end
+
+        def build_health_check_schema
+          RapiTapir::Types.hash({
+                                  'status' => RapiTapir::Types.string,
+                                  'timestamp' => RapiTapir::Types.string,
+                                  'version' => RapiTapir::Types.optional(RapiTapir::Types.string)
+                                })
+        end
+
+        def build_health_check_handler(config)
+          proc do |_inputs|
+            {
+              status: 'healthy',
+              timestamp: Time.now.iso8601,
+              version: config.api_info[:version]
+            }
+          end
+        end
+      end
+
+      # Instance methods added to the Sinatra application
+      module Helpers
+        # Generate OpenAPI specification from registered endpoints
+        def generate_openapi_spec
+          config = settings.rapitapir_config
+          endpoints = settings.rapitapir_endpoints.map { |ep| ep[:endpoint] }
+
+          generator = RapiTapir::OpenAPI::SchemaGenerator.new(
+            endpoints: endpoints,
+            info: config.api_info,
+            servers: config.servers
+          )
+
+          generator.generate
+        end
+
+        # Generate Swagger UI HTML
+        def generate_swagger_ui(openapi_path, api_info)
+          SwaggerUIGenerator.new(openapi_path, api_info).generate
+        end
+
+        # Authentication helpers
+        def current_user
+          @current_user
+        end
+
+        def authenticated?
+          !current_user.nil?
+        end
+
+        def scope?(scope)
+          return false unless authenticated?
+
+          user_scopes = current_user.is_a?(Hash) ? current_user[:scopes] || [] : []
+          user_scopes.include?(scope.to_s)
+        end
+        alias has_scope? scope?
+
+        def require_authentication!
+          halt 401, { error: 'Authentication required' }.to_json unless authenticated?
+        end
+
+        def require_scope!(scope)
+          require_authentication!
+          halt 403, { error: "#{scope.capitalize} permission required" }.to_json unless has_scope?(scope)
+        end
+
+        private
+
+        # Simple placeholder for future security scheme building
+        def build_security_schemes(_config)
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/sinatra/oauth2_helpers.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative '../auth/oauth2'
+
+module RapiTapir
+  module Sinatra
+    # OAuth2 integration helpers for Sinatra applications
+    # Provides convenient methods to secure endpoints with OAuth2/Auth0
+    module OAuth2Helpers
+      # Configure Auth0 OAuth2 authentication
+      def auth0_oauth2(scheme_name = :oauth2_auth0, domain:, audience:, **options)
+        auth_scheme = RapiTapir::Auth::OAuth2::Auth0Scheme.new(scheme_name, {
+          domain: domain,
+          audience: audience,
+          **options
+        })
+        
+        # Store the auth scheme for use in endpoint protection
+        settings.rapitapir_config.add_auth_scheme(scheme_name, auth_scheme)
+        
+        # Add authentication helper methods
+        helpers do
+          include OAuth2HelperMethods
+        end
+        
+        auth_scheme
+      end
+
+      # Configure generic OAuth2 authentication with token introspection
+      def oauth2_introspection(scheme_name = :oauth2, introspection_endpoint:, client_id:, client_secret:, **options)
+        auth_scheme = RapiTapir::Auth::OAuth2::GenericScheme.new(scheme_name, {
+          introspection_endpoint: introspection_endpoint,
+          client_id: client_id,
+          client_secret: client_secret,
+          **options
+        })
+        
+        settings.rapitapir_config.add_auth_scheme(scheme_name, auth_scheme)
+        
+        helpers do
+          include OAuth2HelperMethods
+        end
+        
+        auth_scheme
+      end
+
+      # Protect specific routes with OAuth2 authentication
+      def protect_with_oauth2(*paths, scopes: [], scheme: :oauth2_auth0)
+        paths.each do |path|
+          before path do
+            authorize_oauth2!(required_scopes: scopes, scheme: scheme)
+          end
+        end
+      end
+
+      # Protect all routes with OAuth2 authentication
+      def protect_all_routes_with_oauth2(scopes: [], scheme: :oauth2_auth0, except: [])
+        before do
+          # Skip protection for excluded paths
+          next if except.any? { |pattern| request.path_info.match?(pattern) }
+          
+          authorize_oauth2!(required_scopes: scopes, scheme: scheme)
+        end
+      end
+    end
+
+    # Helper methods available in route handlers
+    module OAuth2HelperMethods
+      # Authenticate and authorize with OAuth2
+      def authorize_oauth2!(required_scopes: [], scheme: :oauth2_auth0)
+        auth_scheme = settings.rapitapir_config.auth_schemes[scheme]
+        
+        unless auth_scheme
+          halt 500, { error: 'OAuth2 authentication not configured' }.to_json
+        end
+
+        begin
+          context = auth_scheme.authenticate(request)
+          
+          unless context
+            challenge = auth_scheme.challenge
+            headers 'WWW-Authenticate' => challenge
+            halt 401, { 
+              error: 'unauthorized',
+              error_description: 'Access token required' 
+            }.to_json
+          end
+
+          # Store context for use in route handlers
+          request.env['rapitapir.auth.context'] = context
+
+          # Check required scopes if specified
+          if required_scopes.any?
+            missing_scopes = required_scopes - context.scopes
+            
+            if missing_scopes.any?
+              halt 403, {
+                error: 'insufficient_scope',
+                error_description: "Missing required scopes: #{missing_scopes.join(', ')}"
+              }.to_json
+            end
+          end
+
+          context
+        rescue RapiTapir::Auth::InvalidTokenError => e
+          challenge = auth_scheme.challenge
+          headers 'WWW-Authenticate' => challenge
+          halt 401, {
+            error: 'invalid_token',
+            error_description: e.message
+          }.to_json
+        rescue RapiTapir::Auth::AuthenticationError => e
+          halt 500, {
+            error: 'authentication_failed',
+            error_description: e.message
+          }.to_json
+        end
+      end
+
+      # Get current authentication context
+      def current_auth_context
+        request.env['rapitapir.auth.context']
+      end
+
+      # Get current authenticated user
+      def current_user
+        current_auth_context&.user
+      end
+
+      # Check if user is authenticated
+      def authenticated?
+        !current_auth_context.nil?
+      end
+
+      # Check if user has specific scope
+      def has_scope?(scope)
+        return false unless current_auth_context
+        
+        current_auth_context.scopes.include?(scope.to_s)
+      end
+
+      # Check if user has all required scopes
+      def has_scopes?(*scopes)
+        return false unless current_auth_context
+        
+        scopes.all? { |scope| has_scope?(scope) }
+      end
+
+      # Check if user has any of the specified scopes
+      def has_any_scope?(*scopes)
+        return false unless current_auth_context
+        
+        scopes.any? { |scope| has_scope?(scope) }
+      end
+
+      # Require specific scopes for the current request
+      def require_scopes!(*scopes)
+        missing_scopes = scopes.reject { |scope| has_scope?(scope) }
+        
+        if missing_scopes.any?
+          halt 403, {
+            error: 'insufficient_scope',
+            error_description: "Missing required scopes: #{missing_scopes.join(', ')}"
+          }.to_json
+        end
+      end
+
+      # Extract token from Authorization header
+      def extract_bearer_token
+        auth_header = request.env['HTTP_AUTHORIZATION']
+        return nil unless auth_header
+
+        match = auth_header.match(/\ABearer\s+(.+)\z/i)
+        match ? match[1] : nil
+      end
+
+      # Validate token directly (useful for custom logic)
+      def validate_oauth2_token(token, scheme: :oauth2_auth0)
+        auth_scheme = settings.rapitapir_config.auth_schemes[scheme]
+        return nil unless auth_scheme
+
+        begin
+          auth_scheme.authenticate(
+            OpenStruct.new(env: { 'HTTP_AUTHORIZATION' => "Bearer #{token}" })
+          )
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    # DSL extensions for endpoint definitions with OAuth2
+    module OAuth2EndpointExtensions
+      # Add OAuth2 authentication to an endpoint
+      def with_oauth2_auth(scopes: [], scheme: :oauth2_auth0, description: nil)
+        auth_scheme_obj = case scheme
+                          when Symbol
+                            # Will be resolved at runtime
+                            OpenStruct.new(name: scheme, scopes: scopes)
+                          else
+                            scheme
+                          end
+
+        security_in(auth_scheme_obj).tap do |endpoint|
+          # Add to endpoint metadata for OpenAPI generation
+          endpoint.metadata[:security] ||= []
+          endpoint.metadata[:security] << {
+            scheme: scheme,
+            scopes: scopes,
+            description: description || "OAuth2 authentication with scopes: #{scopes.join(', ')}"
+          }
+        end
+      end
+
+      # Add Auth0 OAuth2 authentication to an endpoint
+      def with_auth0(scopes: [], description: nil)
+        with_oauth2_auth(scopes: scopes, scheme: :oauth2_auth0, description: description)
+      end
+
+      # Add scope requirement to an endpoint
+      def require_scopes(*scopes)
+        with_oauth2_auth(scopes: scopes.flatten)
+      end
+    end
+  end
+end
+
+# Extend the Sinatra extension with OAuth2 helpers if it exists
+if defined?(RapiTapir::Sinatra::Extension)
+  RapiTapir::Sinatra::Extension::ClassMethods.include(RapiTapir::Sinatra::OAuth2Helpers)
+end
+
+# Extend endpoint building with OAuth2 methods
+if defined?(RapiTapir::DSL::FluentEndpointBuilder)
+  RapiTapir::DSL::FluentEndpointBuilder.include(RapiTapir::Sinatra::OAuth2EndpointExtensions)
+end