rapitapir 0.1.0

data/examples/working_simple_example.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# RapiTapir Sinatra Working Example
+# Using the original SinatraAdapter approach that we know works
+
+require_relative '../lib/rapitapir'
+
+# Check for Sinatra availability
+begin
+  require 'sinatra/base'
+  require_relative '../lib/rapitapir/server/sinatra_adapter'
+  require_relative '../lib/rapitapir/openapi/schema_generator'
+  require_relative '../lib/rapitapir/sinatra/swagger_ui_generator'
+  SINATRA_AVAILABLE = true
+rescue LoadError
+  SINATRA_AVAILABLE = false
+  puts '⚠️  Sinatra not available. Install with: gem install sinatra'
+  puts '🔄 Running in demo mode instead...'
+end
+
+# Simple in-memory data store
+class BookStore
+  @@books = [
+    { id: 1, title: 'The Ruby Programming Language', author: 'Matz', isbn: '978-0596516178', published: true },
+    { id: 2, title: 'Metaprogramming Ruby', author: 'Paolo Perrotta', isbn: '978-1934356470', published: true }
+  ]
+  @@next_id = 3
+
+  def self.all
+    @@books
+  end
+
+  def self.find(id)
+    @@books.find { |book| book[:id] == id.to_i }
+  end
+
+  def self.create(attrs)
+    book = attrs.merge(id: @@next_id)
+    @@next_id += 1
+    @@books << book
+    book
+  end
+
+  def self.published
+    @@books.select { |book| book[:published] }
+  end
+end
+
+# Define the book schema
+BOOK_SCHEMA = RapiTapir::Types.hash({
+                                      'id' => RapiTapir::Types.integer,
+                                      'title' => RapiTapir::Types.string,
+                                      'author' => RapiTapir::Types.string,
+                                      'isbn' => RapiTapir::Types.string,
+                                      'published' => RapiTapir::Types.boolean
+                                    })
+
+# Working Bookstore API using direct SinatraAdapter
+if SINATRA_AVAILABLE
+  class WorkingBookstoreAPI < Sinatra::Base
+    configure do
+      # Create the RapiTapir adapter
+      set :rapitapir, RapiTapir::Server::SinatraAdapter.new(self)
+    end
+
+    # OpenAPI JSON endpoint - clean and simple
+    get '/openapi.json' do
+      content_type :json
+      endpoints = settings.rapitapir.endpoints.map { |ep_data| ep_data[:endpoint] }
+
+      generator = RapiTapir::OpenAPI::SchemaGenerator.new(
+        endpoints: endpoints,
+        info: {
+          title: 'Working Bookstore API',
+          description: 'A simple bookstore API built with RapiTapir and Sinatra',
+          version: '1.0.0'
+        },
+        servers: [{ url: 'http://localhost:4567', description: 'Development server' }]
+      )
+
+      generator.to_json
+    end
+
+    # Swagger UI documentation endpoint - clean and simple
+    get '/docs' do
+      content_type :html
+      api_info = {
+        title: 'Working Bookstore API',
+        description: 'A simple bookstore API built with RapiTapir and Sinatra'
+      }
+
+      RapiTapir::Sinatra::SwaggerUIGenerator.new('/openapi.json', api_info).generate
+    end
+
+    # Health endpoint
+    health_endpoint = RapiTapir.get('/health')
+                               .summary('Health check')
+                               .ok(RapiTapir::Types.hash({ 'status' => RapiTapir::Types.string }))
+                               .build
+
+    settings.rapitapir.register_endpoint(health_endpoint) do |_inputs|
+      { status: 'healthy' }
+    end
+
+    # List books endpoint
+    list_books_endpoint = RapiTapir.get('/books')
+                                   .summary('List all books')
+                                   .ok(RapiTapir::Types.array(BOOK_SCHEMA))
+                                   .build
+
+    settings.rapitapir.register_endpoint(list_books_endpoint) do |_inputs|
+      BookStore.all
+    end
+
+    # Get book by ID endpoint
+    get_book_endpoint = RapiTapir.get('/books/:id')
+                                 .summary('Get book by ID')
+                                 .path_param(:id, RapiTapir::Types.integer, description: 'Book ID')
+                                 .ok(BOOK_SCHEMA)
+                                 .build
+
+    settings.rapitapir.register_endpoint(get_book_endpoint) do |inputs|
+      book = BookStore.find(inputs[:id])
+      halt 404, { error: 'Book not found' }.to_json unless book
+      book
+    end
+
+    # Create book endpoint
+    create_book_endpoint = RapiTapir.post('/books')
+                                    .summary('Create new book')
+                                    .json_body(BOOK_SCHEMA)
+                                    .created(BOOK_SCHEMA)
+                                    .build
+
+    settings.rapitapir.register_endpoint(create_book_endpoint) do |inputs|
+      BookStore.create(inputs[:body].transform_keys(&:to_sym))
+    end
+
+    # Published books endpoint
+    published_books_endpoint = RapiTapir.get('/books/published')
+                                        .summary('Get published books only')
+                                        .ok(RapiTapir::Types.array(BOOK_SCHEMA))
+                                        .build
+
+    settings.rapitapir.register_endpoint(published_books_endpoint) do |_inputs|
+      BookStore.published
+    end
+
+    configure :development do
+      puts "\n📚 Working Bookstore API"
+      puts '🌐 Health: http://localhost:4567/health'
+      puts '📖 Books: http://localhost:4567/books'
+      puts '📋 Published: http://localhost:4567/books/published'
+      puts '📚 Documentation: http://localhost:4567/docs'
+      puts '📋 OpenAPI: http://localhost:4567/openapi.json'
+      puts "\n✅ Using direct SinatraAdapter integration"
+      puts '📖 Full OpenAPI 3.0 documentation auto-generated!'
+    end
+  end
+
+  WorkingBookstoreAPI.run! if __FILE__ == $PROGRAM_NAME
+else
+  # Demo mode when Sinatra is not available
+  puts "\n📚 Working Bookstore API - Demo Mode"
+  puts '=' * 45
+
+  puts "\n✅ Successfully loaded:"
+  puts '   • RapiTapir core'
+  puts '   • Type system'
+  puts '   • Book schema and store'
+
+  puts "\n📊 This API provides:"
+  puts '   GET    /health           - Health check'
+  puts '   GET    /books            - List all books'
+  puts '   GET    /books/:id        - Get book by ID'
+  puts '   POST   /books            - Create new book'
+  puts '   GET    /books/published  - Published books only'
+
+  puts "\n🔧 Direct SinatraAdapter integration:"
+  puts '   • Uses settings.rapitapir.register_endpoint()'
+  puts '   • Standard RapiTapir endpoint definitions'
+  puts '   • No complex extension magic'
+  puts '   • Just works!'
+
+  puts "\n💡 To run the actual server:"
+  puts '   gem install sinatra'
+  puts "   ruby #{__FILE__}"
+
+  puts "\n📖 Sample usage with curl:"
+  puts '   curl http://localhost:4567/books'
+  puts '   curl http://localhost:4567/books/1'
+  puts '   curl -X POST http://localhost:4567/books \\'
+  puts "        -H 'Content-Type: application/json' \\"
+  puts "        -d '{\"title\":\"New Book\",\"author\":\"Author\",\"isbn\":\"123\",\"published\":true}'"
+end

data/lib/rapitapir/auth/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Auth
+    # Configuration class for authentication and security settings
+    #
+    # Provides centralized configuration for authentication schemes, OAuth2,
+    # session management, rate limiting, and CORS settings.
+    #
+    # @example Configure authentication
+    #   RapiTapir::Auth.configure do |config|
+    #     config.jwt_secret = 'your-secret-key'
+    #     config.oauth2.client_id = 'your-client-id'
+    #     config.rate_limiting.requests_per_minute = 100
+    #   end
+    class Configuration
+      attr_accessor :default_realm, :jwt_secret, :jwt_algorithm
+      attr_reader :oauth2, :session, :rate_limiting, :cors
+
+      def initialize
+        @default_realm = 'RapiTapir API'
+        @jwt_secret = nil
+        @jwt_algorithm = 'HS256'
+        @oauth2 = OAuth2Config.new
+        @session = SessionConfig.new
+        @rate_limiting = RateLimitingConfig.new
+        @cors = CorsConfig.new
+      end
+
+      # OAuth2 configuration settings
+      #
+      # Provides configuration for OAuth2 authentication flow including
+      # authorization URLs, token endpoints, and client credentials.
+      class OAuth2Config
+        attr_accessor :authorization_url, :token_url, :refresh_url, :scopes, :client_id, :client_secret
+
+        def initialize
+          @authorization_url = nil
+          @token_url = nil
+          @refresh_url = nil
+          @client_id = nil
+          @client_secret = nil
+          @scopes = {}
+        end
+
+        def add_scope(name, description)
+          @scopes[name.to_s] = description
+        end
+      end
+
+      # Session management configuration
+      #
+      # Provides settings for session-based authentication including
+      # session keys, security settings, and cookie configuration.
+      class SessionConfig
+        attr_accessor :enabled, :key, :secret, :domain, :path, :secure, :http_only, :same_site
+
+        def initialize
+          @enabled = false
+          @key = '_rapitapir_session'
+          @secret = nil
+          @domain = nil
+          @path = '/'
+          @secure = false
+          @http_only = true
+          @same_site = 'Lax'
+        end
+      end
+
+      # Rate limiting configuration
+      #
+      # Provides settings for rate limiting including request limits per time period,
+      # burst limits, and client identification methods.
+      class RateLimitingConfig
+        attr_accessor :enabled, :requests_per_minute, :requests_per_hour,
+                      :requests_per_day, :burst_limit, :identifier
+
+        def initialize
+          @enabled = false
+          @requests_per_minute = 60
+          @requests_per_hour = 1000
+          @requests_per_day = 10_000
+          @burst_limit = 10
+          @identifier = :ip_address
+        end
+
+        def enable(requests_per_minute: 60, requests_per_hour: 1000,
+                   requests_per_day: 10_000, burst_limit: 10, identifier: :ip_address)
+          @enabled = true
+          @requests_per_minute = requests_per_minute
+          @requests_per_hour = requests_per_hour
+          @requests_per_day = requests_per_day
+          @burst_limit = burst_limit
+          @identifier = identifier
+        end
+      end
+
+      # CORS (Cross-Origin Resource Sharing) configuration
+      #
+      # Provides settings for CORS headers including allowed origins, methods,
+      # headers, and credentials handling.
+      class CorsConfig
+        attr_accessor :enabled, :allowed_origins, :allowed_methods, :allowed_headers,
+                      :exposed_headers, :allow_credentials, :max_age, :preflight_continue
+
+        def initialize
+          @enabled = false
+          @allowed_origins = ['*']
+          @allowed_methods = %w[GET POST PUT PATCH DELETE OPTIONS HEAD]
+          @allowed_headers = %w[Content-Type Authorization Accept X-Requested-With]
+          @exposed_headers = []
+          @allow_credentials = false
+          @max_age = 86_400 # 24 hours
+          @preflight_continue = false
+        end
+
+        def enable(allowed_origins: ['*'], allowed_methods: nil, allowed_headers: nil,
+                   allow_credentials: false, max_age: 86_400)
+          @enabled = true
+          @allowed_origins = allowed_origins
+          @allowed_methods = allowed_methods if allowed_methods
+          @allowed_headers = allowed_headers if allowed_headers
+          @allow_credentials = allow_credentials
+          @max_age = max_age
+        end
+      end
+    end
+  end
+end

data/lib/rapitapir/auth/context.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Auth
+    # Authentication context containing user information and authorization data
+    #
+    # Represents the authenticated state of a request, including user details,
+    # granted scopes, authentication tokens, and session information.
+    #
+    # @example Create a context
+    #   context = RapiTapir::Auth::Context.new(
+    #     user: { id: 123, name: 'John' },
+    #     scopes: ['read', 'write'],
+    #     token: 'bearer-token-123'
+    #   )
+    #
+    # @example Check permissions
+    #   context.authenticated?        # => true
+    #   context.has_scope?('read')    # => true
+    class Context
+      attr_reader :user, :scopes, :token, :session, :metadata
+
+      def initialize(user: nil, scopes: [], token: nil, session: {}, metadata: {})
+        @user = user
+        @scopes = Array(scopes)
+        @token = token
+        @session = session || {}
+        @metadata = metadata || {}
+      end
+
+      def authenticated?
+        !@user.nil?
+      end
+
+      def scope?(scope)
+        @scopes.include?(scope.to_s)
+      end
+      alias has_scope? scope?
+
+      def any_scope?(*scopes)
+        scopes.any? { |scope| scope?(scope) }
+      end
+      alias has_any_scope? any_scope?
+
+      def all_scopes?(*scopes)
+        scopes.all? { |scope| scope?(scope) }
+      end
+      alias has_all_scopes? all_scopes?
+
+      def user_id
+        return nil unless @user
+
+        case @user
+        when Hash
+          @user[:id] || @user['id']
+        when Numeric, String
+          @user
+        else
+          @user.respond_to?(:id) ? @user.id : @user.to_s
+        end
+      end
+
+      def add_scope(scope)
+        @scopes << scope.to_s unless scope?(scope)
+      end
+
+      def remove_scope(scope)
+        @scopes.delete(scope.to_s)
+      end
+
+      def merge(other_context)
+        Context.new(
+          user: other_context.user || @user,
+          scopes: (@scopes + other_context.scopes).uniq,
+          token: other_context.token || @token,
+          session: @session.merge(other_context.session),
+          metadata: @metadata.merge(other_context.metadata)
+        )
+      end
+
+      def to_hash
+        {
+          user: @user,
+          scopes: @scopes,
+          token: @token,
+          session: @session,
+          metadata: @metadata,
+          authenticated: authenticated?,
+          user_id: user_id
+        }
+      end
+
+      def inspect
+        "#<RapiTapir::Auth::Context user_id=#{user_id.inspect} " \
+          "scopes=#{@scopes.inspect} authenticated=#{authenticated?}>"
+      end
+    end
+
+    # Thread-local context storage
+    class ContextStore
+      def self.current
+        Thread.current[:rapitapir_auth_context]
+      end
+
+      def self.current=(context)
+        Thread.current[:rapitapir_auth_context] = context
+      end
+
+      def self.with_context(context)
+        old_context = current
+        self.current = context
+        yield
+      ensure
+        self.current = old_context
+      end
+
+      def self.clear
+        Thread.current[:rapitapir_auth_context] = nil
+      end
+    end
+  end
+end

data/lib/rapitapir/auth/errors.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Auth
+    # Base authentication error for all authentication-related exceptions
+    # This is the parent class for all authentication errors in RapiTapir
+    class AuthenticationError < StandardError
+      attr_reader :status, :error_code, :error_description
+
+      def initialize(message, status: 401, error_code: 'authentication_failed', error_description: nil)
+        super(message)
+        @status = status
+        @error_code = error_code
+        @error_description = error_description || message
+      end
+
+      def to_hash
+        {
+          error: @error_code,
+          error_description: @error_description,
+          status: @status
+        }
+      end
+    end
+
+    # Authorization error for insufficient permissions
+    # Raised when a user lacks required permissions to access a resource
+    class AuthorizationError < AuthenticationError
+      def initialize(message, error_code: 'insufficient_scope', error_description: nil)
+        super(message, status: 403, error_code: error_code, error_description: error_description)
+      end
+    end
+
+    # Error for invalid or expired authentication tokens
+    # Raised when a provided token is malformed, expired, or otherwise invalid
+    class InvalidTokenError < AuthenticationError
+      def initialize(message = 'Invalid or expired token', error_code: 'invalid_token')
+        super
+      end
+    end
+
+    # Error for missing authentication tokens
+    # Raised when authentication is required but no token was provided
+    class MissingTokenError < AuthenticationError
+      def initialize(message = 'Authentication token required', error_code: 'missing_token')
+        super
+      end
+    end
+
+    # Error for invalid user credentials
+    # Raised when provided username/password credentials are incorrect
+    class InvalidCredentialsError < AuthenticationError
+      def initialize(message = 'Invalid credentials', error_code: 'invalid_credentials')
+        super
+      end
+    end
+
+    # Error for exceeded rate limits
+    # Raised when a client exceeds the configured rate limit for requests
+    class RateLimitExceededError < AuthenticationError
+      attr_reader :retry_after, :limit, :remaining, :reset_time
+
+      def initialize(message = 'Rate limit exceeded', retry_after: nil, limit: nil, remaining: 0, reset_time: nil)
+        super(message, status: 429, error_code: 'rate_limit_exceeded')
+        @retry_after = retry_after
+        @limit = limit
+        @remaining = remaining
+        @reset_time = reset_time
+      end
+
+      def to_hash
+        super.merge({
+          retry_after: @retry_after,
+          limit: @limit,
+          remaining: @remaining,
+          reset_time: @reset_time&.to_i
+        }.compact)
+      end
+    end
+
+    # Error for insufficient OAuth scopes
+    # Raised when a token lacks the required scopes for an operation
+    class ScopeError < AuthorizationError
+      attr_reader :required_scopes, :provided_scopes
+
+      def initialize(required_scopes, provided_scopes = [])
+        @required_scopes = Array(required_scopes)
+        @provided_scopes = Array(provided_scopes)
+
+        message = "Insufficient scope. Required: #{@required_scopes.join(', ')}"
+        message += ". Provided: #{@provided_scopes.join(', ')}" unless @provided_scopes.empty?
+
+        super(message, error_code: 'insufficient_scope')
+      end
+
+      def to_hash
+        super.merge({
+                      required_scopes: @required_scopes,
+                      provided_scopes: @provided_scopes
+                    })
+      end
+    end
+  end
+end