rapitapir 0.1.0

data/examples/authentication_example.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# Example: Authentication and Security in RapiTapir
+#
+# This example demonstrates how to use RapiTapir's Phase 2.2 Authentication & Security features,
+# including various authentication schemes, authorization middleware, and security features.
+
+require_relative '../lib/rapitapir'
+require 'ostruct'
+
+# Helper method to create simple JWT (for demonstration only)
+def create_simple_jwt(payload, secret)
+  require 'base64'
+  require 'json'
+  require 'openssl'
+
+  header = { 'alg' => 'HS256', 'typ' => 'JWT' }
+
+  encoded_header = Base64.urlsafe_encode64(JSON.generate(header)).tr('=', '')
+  encoded_payload = Base64.urlsafe_encode64(JSON.generate(payload)).tr('=', '')
+
+  signature = Base64.urlsafe_encode64(
+    OpenSSL::HMAC.digest('SHA256', secret, "#{encoded_header}.#{encoded_payload}")
+  ).tr('=', '')
+
+  "#{encoded_header}.#{encoded_payload}.#{signature}"
+end
+
+# Configure authentication globally
+RapiTapir::Auth.configure do |config|
+  config.default_realm = 'My API'
+  config.jwt_secret = 'your-secret-key'
+  config.oauth2.client_id = 'your-client-id'
+  config.oauth2.client_secret = 'your-client-secret'
+  config.rate_limiting.requests_per_minute = 100
+end
+
+# Create authentication schemes
+bearer_auth = RapiTapir::Auth.bearer_token(:bearer, {
+                                             token_validator: proc do |token|
+                                               # Validate token against your database or service
+                                               case token
+                                               when 'valid-token-123'
+                                                 {
+                                                   user: { id: 123, name: 'John Doe', email: 'john@example.com' },
+                                                   scopes: %w[read write]
+                                                 }
+                                               when 'admin-token-456'
+                                                 {
+                                                   user: { id: 456, name: 'Admin User', email: 'admin@example.com' },
+                                                   scopes: %w[read write admin]
+                                                 }
+                                               end
+                                             end
+                                           })
+
+api_key_auth = RapiTapir::Auth.api_key(:api_key, {
+                                         header_name: 'X-API-Key',
+                                         key_validator: proc do |key|
+                                           # Validate API key
+                                           case key
+                                           when 'api-key-789'
+                                             {
+                                               user: { id: 'api-user', name: 'API Client' },
+                                               scopes: ['read']
+                                             }
+                                           end
+                                         end
+                                       })
+
+jwt_auth = RapiTapir::Auth.jwt(:jwt, {
+                                 secret: 'your-jwt-secret',
+                                 algorithm: 'HS256'
+                               })
+
+# Usage examples:
+
+# 1. Test authentication manually
+puts '=== Authentication Examples ==='
+
+# Create a mock request for Bearer token
+bearer_request = Struct.new(:env, :params, :headers).new(
+  { 'HTTP_AUTHORIZATION' => 'Bearer valid-token-123' },
+  {},
+  { 'authorization' => 'Bearer valid-token-123' }
+)
+
+context = bearer_auth.authenticate(bearer_request)
+puts "Bearer auth result: #{context&.authenticated?} - User: #{context&.user}"
+
+# Create a mock request for API key
+api_key_request = Struct.new(:env, :params, :headers).new(
+  { 'HTTP_X_API_KEY' => 'api-key-789' },
+  {},
+  { 'x-api-key' => 'api-key-789' }
+)
+
+context = api_key_auth.authenticate(api_key_request)
+puts "API key auth result: #{context&.authenticated?} - User: #{context&.user}"
+
+# 2. Test JWT authentication
+puts "\n=== JWT Authentication Example ==="
+
+# Create a simple JWT token
+jwt_payload = {
+  'sub' => 'user123',
+  'name' => 'JWT User',
+  'scopes' => %w[read write],
+  'exp' => Time.now.to_i + 3600
+}
+
+jwt_token = create_simple_jwt(jwt_payload, 'your-jwt-secret')
+puts "Generated JWT: #{jwt_token[0..20]}..."
+
+jwt_request = Struct.new(:env, :params, :headers).new(
+  { 'HTTP_AUTHORIZATION' => "Bearer #{jwt_token}" },
+  {},
+  { 'authorization' => "Bearer #{jwt_token}" }
+)
+
+context = jwt_auth.authenticate(jwt_request)
+puts "JWT auth result: #{context&.authenticated?} - User: #{context&.user}"
+
+# 3. Demonstrate context store
+puts "\n=== Context Store Example ==="
+
+test_context = RapiTapir::Auth::Context.new(
+  user: { id: 999, name: 'Test User' },
+  scopes: %w[read write],
+  token: 'test-token'
+)
+
+RapiTapir::Auth::ContextStore.with_context(test_context) do
+  puts "Current user: #{RapiTapir::Auth.current_user}"
+  puts "Authenticated: #{RapiTapir::Auth.authenticated?}"
+  puts "Has 'read' scope: #{RapiTapir::Auth.has_scope?('read')}"
+  puts "Has 'admin' scope: #{RapiTapir::Auth.has_scope?('admin')}"
+end
+
+puts "Context after block: #{RapiTapir::Auth.current_context}"
+
+# 4. Test middleware functionality
+puts "\n=== Middleware Examples ==="
+
+# Test rate limiting storage
+storage = RapiTapir::Auth::Middleware::RateLimitingMiddleware::MemoryStorage.new
+storage.increment('test_key')
+storage.increment('test_key')
+puts "Rate limit count: #{storage.get('test_key')}"
+
+# Test CORS functionality
+cors_middleware = RapiTapir::Auth.cors_middleware({
+                                                    allowed_origins: ['https://example.com'],
+                                                    allowed_methods: %w[GET POST],
+                                                    allow_credentials: true
+                                                  })
+
+puts "CORS middleware created: #{cors_middleware.class}"
+
+# 5. Test authorization
+puts "\n=== Authorization Examples ==="
+
+admin_context = RapiTapir::Auth::Context.new(
+  user: { id: 123, name: 'Admin' },
+  scopes: %w[read write admin]
+)
+
+regular_context = RapiTapir::Auth::Context.new(
+  user: { id: 456, name: 'User' },
+  scopes: ['read']
+)
+
+RapiTapir::Auth::ContextStore.with_context(admin_context) do
+  puts "Admin user has admin scope: #{RapiTapir::Auth.has_scope?('admin')}"
+end
+
+RapiTapir::Auth::ContextStore.with_context(regular_context) do
+  puts "Regular user has admin scope: #{RapiTapir::Auth.has_scope?('admin')}"
+end
+
+puts "\n=== Phase 2.2 Authentication & Security System Complete ==="
+puts '✅ Bearer Token Authentication'
+puts '✅ API Key Authentication'
+puts '✅ Basic Authentication'
+puts '✅ OAuth2 Authentication'
+puts '✅ JWT Authentication'
+puts '✅ Authorization Middleware'
+puts '✅ Rate Limiting'
+puts '✅ CORS Support'
+puts '✅ Security Headers'
+puts '✅ Context Management'
+puts '✅ Comprehensive Test Suite (91 tests)'

data/examples/auto_derivation_ruby_friendly.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# This file demonstrates the improved auto-derivation capabilities that work
+# well with Ruby's dynamic nature and lack of built-in type declarations
+
+require_relative '../lib/rapitapir/types'
+
+puts "=== RapiTapir Auto-Derivation Examples ==="
+puts
+
+# 1. From Hash (most reliable for Ruby)
+puts "1. From Hash (recommended for Ruby)"
+hash_data = {
+  name: "John Doe",
+  age: 30,
+  email: "john@example.com",
+  active: true,
+  score: 95.5,
+  tags: ["developer", "ruby"],
+  metadata: { role: "senior", team: "backend" }
+}
+
+schema = RapiTapir::Types.from_hash(hash_data)
+puts "Schema from hash:"
+puts schema.field_types.inspect
+puts
+
+# 2. From Hash with filtering
+filtered_schema = RapiTapir::Types.from_hash(hash_data, except: [:metadata])
+puts "Schema with 'except' filtering:"
+puts filtered_schema.field_types.inspect
+puts
+
+# 3. From explicit types (recommended for classes)
+puts "2. From Class with Explicit Types (recommended)"
+class Person
+  attr_accessor :name, :age, :email, :active
+end
+
+# Method 1: Via types parameter
+person_schema = RapiTapir::Types.from_object(Person, types: {
+  name: :string,
+  age: :integer,
+  email: :string,
+  active: :boolean
+})
+puts "Person schema with explicit types:"
+puts person_schema.field_types.inspect
+puts
+
+# 4. From instance (less reliable but convenient)
+puts "3. From Instance (use with well-populated data)"
+person = Person.new
+person.name = "Jane Smith"
+person.age = 28
+person.email = "jane@example.com"
+person.active = true
+
+instance_schema = RapiTapir::Types.from_object(person)
+puts "Schema from instance:"
+puts instance_schema.field_types.inspect
+puts
+
+# 5. From Struct (good compromise)
+puts "4. From Struct (good Ruby pattern)"
+Point = Struct.new(:x, :y, :z) do
+  def distance_from_origin
+    Math.sqrt(x**2 + y**2 + z**2)
+  end
+end
+
+sample_point = Point.new(1.0, 2.0, 3.0)
+point_schema = RapiTapir::Types.from_object(Point, sample: sample_point)
+puts "Point schema from Struct:"
+puts point_schema.field_types.inspect
+puts
+
+# 6. DSL approach (most Ruby-like)
+puts "5. DSL Approach (Ruby-idiomatic)"
+class User
+  include RapiTapir::Types::AutoDerivation::Annotated
+  
+  attr_accessor :username, :email, :age, :admin
+  
+  rapitapir_schema do
+    field :username, :string
+    field :email, :string
+    field :age, :integer
+    field :admin, :boolean
+  end
+end
+
+user_schema = RapiTapir::Types.from_object(User)
+puts "User schema with DSL:"
+puts user_schema.field_types.inspect
+puts
+
+# 7. OpenStruct (convenient for prototyping)
+puts "6. From OpenStruct"
+require 'ostruct'
+
+config = OpenStruct.new(
+  host: "localhost",
+  port: 3000,
+  ssl: false,
+  timeout: 30.5
+)
+
+config_schema = RapiTapir::Types.from_open_struct(config)
+puts "Config schema from OpenStruct:"
+puts config_schema.field_types.inspect
+puts
+
+# 8. JSON Schema (for external APIs)
+puts "7. From JSON Schema"
+json_schema = {
+  "type" => "object",
+  "properties" => {
+    "id" => { "type" => "integer" },
+    "name" => { "type" => "string", "maxLength" => 100 },
+    "email" => { "type" => "string", "format" => "email" },
+    "created_at" => { "type" => "string", "format" => "date-time" },
+    "tags" => { 
+      "type" => "array", 
+      "items" => { "type" => "string" }
+    }
+  },
+  "required" => ["id", "name", "email"]
+}
+
+json_derived_schema = RapiTapir::Types.from_json_schema(json_schema)
+puts "Schema from JSON Schema:"
+puts json_derived_schema.field_types.inspect
+puts
+
+# 9. Demonstrate the limitations
+puts "8. Limitations and Error Handling"
+
+class EmptyClass
+end
+
+begin
+  # This should fail gracefully
+  RapiTapir::Types.from_object(EmptyClass)
+rescue ArgumentError => e
+  puts "Expected error for empty class: #{e.message}"
+end
+
+begin
+  # This should also fail
+  RapiTapir::Types.from_object(Point)  # Struct without sample
+rescue ArgumentError => e
+  puts "Expected error for Struct without sample: #{e.message}"
+end
+
+puts
+puts "=== Recommendations ==="
+puts "1. Use from_hash() for parsed JSON or config data"
+puts "2. Use explicit types parameter for Ruby classes"
+puts "3. Use DSL annotations for reusable schemas"
+puts "4. Use Structs for value objects with samples"
+puts "5. Use from_json_schema() for external API integration"
+puts "6. Avoid deriving from empty classes or nil values"

data/examples/cli/user_api_endpoints.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Add the lib directory to the load path
+lib_path = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+
+require 'rapitapir'
+
+# Include DSL to use helper methods
+include RapiTapir::DSL
+
+# Define endpoints for CLI usage
+[
+  # Get all users
+  RapiTapir.get('/users')
+           .out(json_body([{ id: :integer, name: :string, email: :string }]))
+           .summary('Get all users')
+           .description('Retrieve a list of all users'),
+
+  # Get user by ID
+  RapiTapir.get('/users/:id')
+           .in(path_param(:id, :integer))
+           .out(json_body({ id: :integer, name: :string, email: :string }))
+           .summary('Get user by ID')
+           .description('Retrieve a specific user by their ID'),
+
+  # Create new user
+  RapiTapir.post('/users')
+           .in(body({ name: :string, email: :string }))
+           .out(json_body({ id: :integer, name: :string, email: :string }))
+           .summary('Create new user')
+           .description('Create a new user with the provided information'),
+
+  # Update user
+  RapiTapir.put('/users/:id')
+           .in(path_param(:id, :integer))
+           .in(body({ name: :string, email: :string }))
+           .out(json_body({ id: :integer, name: :string, email: :string }))
+           .summary('Update user')
+           .description('Update an existing user'),
+
+  # Delete user
+  RapiTapir.delete('/users/:id')
+           .in(path_param(:id, :integer))
+           .out(json_body({ success: :boolean }))
+           .summary('Delete user')
+           .description('Delete a user by their ID'),
+
+  # Search users
+  RapiTapir.get('/users/search')
+           .in(query(:q, :string))
+           .in(query(:limit, :integer, optional: true))
+           .out(json_body([{ id: :integer, name: :string, email: :string }]))
+           .summary('Search users')
+           .description('Search for users by name or email')
+]

data/examples/client/typescript_client_example.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/rapitapir'
+
+# Include DSL to use helper methods
+include RapiTapir::DSL
+
+# Define the same User API as before
+user_api = [
+  # Get all users
+  RapiTapir.get('/users')
+           .out(json_body([{ id: :integer, name: :string, email: :string }]))
+           .summary('Get all users')
+           .description('Retrieve a list of all users'),
+
+  # Get user by ID
+  RapiTapir.get('/users/:id')
+           .in(path_param(:id, :integer))
+           .out(json_body({ id: :integer, name: :string, email: :string }))
+           .summary('Get user by ID')
+           .description('Retrieve a specific user by their ID'),
+
+  # Create new user
+  RapiTapir.post('/users')
+           .in(body({ name: :string, email: :string }))
+           .out(json_body({ id: :integer, name: :string, email: :string }))
+           .summary('Create new user')
+           .description('Create a new user with the provided information'),
+
+  # Update user
+  RapiTapir.put('/users/:id')
+           .in(path_param(:id, :integer))
+           .in(body({ name: :string, email: :string }))
+           .out(json_body({ id: :integer, name: :string, email: :string }))
+           .summary('Update user')
+           .description('Update an existing user'),
+
+  # Delete user
+  RapiTapir.delete('/users/:id')
+           .in(path_param(:id, :integer))
+           .out(json_body({ success: :boolean }))
+           .summary('Delete user')
+           .description('Delete a user by their ID'),
+
+  # Search users
+  RapiTapir.get('/users/search')
+           .in(query(:q, :string))
+           .in(query(:limit, :integer, optional: true))
+           .out(json_body([{ id: :integer, name: :string, email: :string }]))
+           .summary('Search users')
+           .description('Search for users by name or email')
+]
+
+# Generate TypeScript client
+puts 'Generating TypeScript client...'
+
+generator = RapiTapir::Client::TypescriptGenerator.new(
+  endpoints: user_api,
+  config: {
+    base_url: 'https://api.example.com',
+    client_name: 'UserApiClient',
+    package_name: '@mycompany/user-api-client',
+    version: '1.2.0'
+  }
+)
+
+# Save to file
+output_file = File.join(__dir__, 'user-api-client.ts')
+generator.save_to_file(output_file)
+
+puts "\nTypeScript client generated successfully!"
+puts "File: #{output_file}"
+puts "\nTo use the client in your TypeScript project:"
+puts '1. Copy the generated file to your project'
+puts '2. Install dependencies: npm install'
+puts '3. Import and use the client:'
+puts ''
+puts '```typescript'
+puts "import UserApiClient from './user-api-client';"
+puts ''
+puts 'const client = new UserApiClient({'
+puts "  baseUrl: 'https://api.example.com',"
+puts "  headers: { 'Authorization': 'Bearer your-token' }"
+puts '});'
+puts ''
+puts '// Get all users'
+puts 'const users = await client.getUsers();'
+puts ''
+puts '// Get user by ID'
+puts 'const user = await client.getUsersById({ id: 123 });'
+puts ''
+puts '// Create new user'
+puts 'const newUser = await client.createUsers({'
+puts "  body: { name: 'John Doe', email: 'john@example.com' }"
+puts '});'
+puts ''
+puts '// Search users'
+puts 'const searchResults = await client.getUsersSearch({'
+puts "  q: 'john',"
+puts '  limit: 10'
+puts '});'
+puts '```'

data/examples/client/user-api-client.ts

@@ -0,0 +1,193 @@
+// Generated by RapiTapir TypeScript Client Generator
+// Package: @mycompany/user-api-client
+// Version: 1.2.0
+// Base URL: https://api.example.com
+
+// Response type for all API calls
+export interface ApiResponse<T> {
+  data: T;
+  status: number;
+  headers: Record<string, string>;
+}
+
+// Error type for API errors
+export interface ApiError {
+  message: string;
+  status: number;
+  details?: any;
+}
+
+// HTTP client configuration
+export interface ClientConfig {
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+
+
+// Generated types
+export type GetusersResponse = { id: number; name: string; email: string }[];
+
+export interface GetusersbyidRequest {
+  id: number;
+}
+
+
+export type GetusersbyidResponse = { id: number; name: string; email: string };
+
+export interface CreateuserRequest {
+  body: { name: string; email: string };
+}
+
+
+export type CreateuserResponse = { id: number; name: string; email: string };
+
+export interface UpdateuserRequest {
+  id: number;
+  body: { name: string; email: string };
+}
+
+
+export type UpdateuserResponse = { id: number; name: string; email: string };
+
+export interface DeleteuserRequest {
+  id: number;
+}
+
+
+export type DeleteuserResponse = { success: boolean };
+
+export interface GetuserssearchRequest {
+  q: string;
+  limit?: number;
+}
+
+
+export type GetuserssearchResponse = { id: number; name: string; email: string }[];
+
+export class UserApiClient {
+  private baseUrl: string;
+  private headers: Record<string, string>;
+  private timeout: number;
+  
+  constructor(config: ClientConfig = {}) {
+    this.baseUrl = config.baseUrl || 'https://api.example.com';
+    this.headers = config.headers || {};
+    this.timeout = config.timeout || 10000;
+  }
+  
+  private async request<T>(
+    method: string,
+    path: string,
+    options: {
+      params?: Record<string, any>;
+      body?: any;
+      headers?: Record<string, string>;
+    } = {}
+  ): Promise<ApiResponse<T>> {
+    const url = new URL(path, this.baseUrl);
+    
+    // Add query parameters
+    if (options.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+    
+    const requestHeaders = {
+      'Content-Type': 'application/json',
+      ...this.headers,
+      ...options.headers,
+    };
+    
+    const requestInit: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+    
+    if (options.body) {
+      requestInit.body = JSON.stringify(options.body);
+    }
+    
+    try {
+      const response = await fetch(url.toString(), requestInit);
+      
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+      
+      let data: T;
+      const contentType = response.headers.get('content-type');
+      if (contentType && contentType.includes('application/json')) {
+        data = await response.json();
+      } else {
+        data = (await response.text()) as unknown as T;
+      }
+      
+      if (!response.ok) {
+        const error: ApiError = {
+          message: `HTTP ${response.status}: ${response.statusText}`,
+          status: response.status,
+          details: data,
+        };
+        throw error;
+      }
+      
+      return {
+        data,
+        status: response.status,
+        headers: responseHeaders,
+      };
+    } catch (error) {
+      if (error && typeof error === 'object' && 'status' in error) {
+        throw error; // Re-throw ApiError
+      }
+      
+      const apiError: ApiError = {
+        message: error instanceof Error ? error.message : 'Unknown error',
+        status: 0,
+        details: error,
+      };
+      throw apiError;
+    }
+  }
+  
+  async getUsers(): Promise<ApiResponse<GetusersResponse>> {
+    return this.request<GetusersResponse>('GET', '/users');
+  }
+
+  async getUsersById(request: GetusersbyidRequest): Promise<ApiResponse<GetusersbyidResponse>> {
+    return this.request<GetusersbyidResponse>('GET', `/users/${request.id}`, {
+    });
+  }
+
+  async createUser(request: CreateuserRequest): Promise<ApiResponse<CreateuserResponse>> {
+    return this.request<CreateuserResponse>('POST', '/users', {
+      body: request.body
+    });
+  }
+
+  async updateUser(request: UpdateuserRequest): Promise<ApiResponse<UpdateuserResponse>> {
+    return this.request<UpdateuserResponse>('PUT', `/users/${request.id}`, {
+      body: request.body
+    });
+  }
+
+  async deleteUser(request: DeleteuserRequest): Promise<ApiResponse<DeleteuserResponse>> {
+    return this.request<DeleteuserResponse>('DELETE', `/users/${request.id}`, {
+    });
+  }
+
+  async getUsersSearch(request: GetuserssearchRequest): Promise<ApiResponse<GetuserssearchResponse>> {
+    return this.request<GetuserssearchResponse>('GET', '/users/search', {
+      params: { q: request.q, limit: request.limit }
+    });
+  }
+}
+
+
+// Default export
+export default UserApiClient;