rapitapir 0.1.1 → 2.0.0

data/examples/serverless/spec/spec_helper.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require 'rack/test'
+require 'json'
+
+RSpec.configure do |config|
+  config.include Rack::Test::Methods
+  
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.disable_monkey_patching!
+  config.warnings = true
+
+  if config.files_to_run.one?
+    config.default_formatter = "doc"
+  end
+
+  config.profile_examples = 10
+  config.order = :random
+  Kernel.srand config.seed
+end
+
+# Helper methods for testing serverless functions
+module ServerlessTestHelpers
+  def parse_json_response
+    JSON.parse(last_response.body)
+  end
+
+  def expect_json_response(expected_keys = [])
+    expect(last_response.content_type).to include('application/json')
+    response_body = parse_json_response
+    expected_keys.each do |key|
+      expect(response_body).to have_key(key.to_s)
+    end
+    response_body
+  end
+
+  def mock_aws_context(request_id: 'test-request-123')
+    OpenStruct.new(
+      aws_request_id: request_id,
+      function_name: 'test-function',
+      function_version: '$LATEST',
+      memory_limit_in_mb: '512'
+    )
+  end
+
+  def mock_gcp_request(method: 'GET', path: '/', body: nil, headers: {})
+    request = double('request')
+    allow(request).to receive(:request_method).and_return(method)
+    allow(request).to receive(:path).and_return(path)
+    allow(request).to receive(:query_string).and_return('')
+    allow(request).to receive(:body).and_return(StringIO.new(body || ''))
+    allow(request).to receive(:content_type).and_return(headers['Content-Type'])
+    allow(request).to receive(:headers).and_return(headers)
+    allow(request).to receive(:host).and_return('localhost')
+    allow(request).to receive(:port).and_return(8080)
+    request
+  end
+
+  def mock_azure_context(invocation_id: 'test-invocation-123')
+    {
+      invocation_id: invocation_id,
+      function_name: 'test-function',
+      function_directory: '/tmp'
+    }
+  end
+
+  def mock_vercel_request(method: 'GET', url: 'https://localhost/', body: nil, headers: {})
+    request = double('request')
+    allow(request).to receive(:method).and_return(method)
+    allow(request).to receive(:url).and_return(url)
+    allow(request).to receive(:body).and_return(body)
+    allow(request).to receive(:headers).and_return(headers)
+    request
+  end
+end
+
+RSpec.configure do |config|
+  config.include ServerlessTestHelpers
+end

data/examples/serverless/vercel.json

@@ -0,0 +1,31 @@
+{
+  "version": 2,
+  "name": "rapitapir-vercel-api",
+  "builds": [
+    {
+      "src": "vercel_example.rb",
+      "use": "@vercel/ruby"
+    }
+  ],
+  "routes": [
+    {
+      "src": "/api/(.*)",
+      "dest": "/vercel_example.rb"
+    },
+    {
+      "src": "/(.*)",
+      "dest": "/vercel_example.rb"
+    }
+  ],
+  "env": {
+    "RACK_ENV": "production",
+    "RAPITAPIR_ENV": "serverless"
+  },
+  "regions": ["all"],
+  "functions": {
+    "vercel_example.rb": {
+      "memory": 512,
+      "maxDuration": 30
+    }
+  }
+}

data/examples/serverless/vercel_example.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require 'rapitapir'
+require 'json'
+
+# Vercel serverless function for SinatraRapiTapir
+# This example shows how to deploy a RapiTapir API on Vercel
+class BookAPIVercel < SinatraRapiTapir
+  # Configure for Vercel serverless
+  rapitapir do
+    info(
+      title: 'Serverless Book API - Vercel',
+      description: 'A book management API deployed on Vercel Edge Functions',
+      version: '1.0.0'
+    )
+    
+    # Vercel optimized configuration
+    configure do
+      set :environment, :production
+      set :logging, true
+      set :dump_errors, false
+      set :raise_errors, true
+      
+      # Vercel-specific optimizations
+      set :sessions, false
+      set :static, false
+      set :show_exceptions, false
+    end
+    
+    development_defaults!
+  end
+
+  # Book schema optimized for edge computing
+  BOOK_SCHEMA = T.hash({
+    "id" => T.string,
+    "title" => T.string(min_length: 1, max_length: 255),
+    "author" => T.string(min_length: 1, max_length: 255),
+    "isbn" => T.optional(T.string(pattern: /^\d{10}(\d{3})?$/)),
+    "published_year" => T.optional(T.integer(minimum: 1000, maximum: 3000)),
+    "available" => T.boolean,
+    "tags" => T.optional(T.array(T.string)),
+    "rating" => T.optional(T.float(minimum: 0, maximum: 5)),
+    "created_at" => T.datetime,
+    "updated_at" => T.datetime
+  })
+
+  # In-memory storage for demo (use Vercel KV or external DB in production)
+  @@books = [
+    {
+      id: "vercel_book_1",
+      title: "Serverless Ruby at the Edge",
+      author: "Edge Developer",
+      isbn: "9781111111111",
+      published_year: 2024,
+      available: true,
+      tags: ["ruby", "serverless", "edge"],
+      rating: 4.8,
+      created_at: Time.now - 86400,
+      updated_at: Time.now - 86400
+    },
+    {
+      id: "vercel_book_2",
+      title: "Building APIs with RapiTapir",
+      author: "API Expert",
+      isbn: "9782222222222",
+      published_year: 2024,
+      available: true,
+      tags: ["api", "ruby", "rapitapir"],
+      rating: 4.9,
+      created_at: Time.now - 43200,
+      updated_at: Time.now - 43200
+    }
+  ]
+
+  # Health check with Vercel-specific info
+  endpoint(
+    GET('/health')
+      .summary('Health check for Vercel function')
+      .description('Returns health status with Vercel deployment info')
+      .tags('Health', 'Vercel')
+      .ok(T.hash({
+        "status" => T.string,
+        "timestamp" => T.datetime,
+        "vercel_info" => T.hash({
+          "region" => T.optional(T.string),
+          "deployment_id" => T.optional(T.string),
+          "environment" => T.optional(T.string),
+          "branch" => T.optional(T.string),
+          "commit_sha" => T.optional(T.string)
+        }),
+        "performance" => T.hash({
+          "cold_start" => T.boolean,
+          "edge_location" => T.optional(T.string)
+        })
+      }))
+      .build
+  ) do
+    {
+      status: 'healthy',
+      timestamp: Time.now,
+      vercel_info: {
+        region: ENV['VERCEL_REGION'],
+        deployment_id: ENV['VERCEL_DEPLOYMENT_ID'],
+        environment: ENV['VERCEL_ENV'],
+        branch: ENV['VERCEL_GIT_COMMIT_REF'],
+        commit_sha: ENV['VERCEL_GIT_COMMIT_SHA']
+      },
+      performance: {
+        cold_start: Thread.current[:cold_start] || false,
+        edge_location: ENV['VERCEL_REGION']
+      }
+    }
+  end
+
+  # Fast book listing for edge performance
+  endpoint(
+    GET('/books')
+      .summary('List books (edge optimized)')
+      .description('Fast book listing optimized for edge deployment')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 50)), description: 'Limit results')
+      .query(:tag, T.optional(T.string), description: 'Filter by tag')
+      .query(:min_rating, T.optional(T.float(minimum: 0, maximum: 5)), description: 'Minimum rating')
+      .tags('Books')
+      .ok(T.hash({
+        "books" => T.array(BOOK_SCHEMA),
+        "total" => T.integer,
+        "edge_cached" => T.boolean,
+        "response_time_ms" => T.float
+      }))
+      .build
+  ) do |inputs|
+    start_time = Time.now
+    books = @@books.dup
+    
+    # Apply tag filter
+    books = books.select { |book| book[:tags]&.include?(inputs[:tag]) } if inputs[:tag]
+    
+    # Apply rating filter
+    books = books.select { |book| (book[:rating] || 0) >= inputs[:min_rating] } if inputs[:min_rating]
+    
+    # Apply limit
+    limit = inputs[:limit] || 20
+    books = books.first(limit)
+    
+    response_time = ((Time.now - start_time) * 1000).round(2)
+    
+    {
+      books: books,
+      total: books.length,
+      edge_cached: false, # Could be true if using Vercel Edge Config
+      response_time_ms: response_time
+    }
+  end
+
+  # Get book with edge caching headers
+  endpoint(
+    GET('/books/:id')
+      .path_param(:id, T.string, description: 'Book ID')
+      .summary('Get book by ID (edge cached)')
+      .description('Retrieve a book with aggressive edge caching')
+      .tags('Books')
+      .ok(BOOK_SCHEMA)
+      .error_response(404, T.hash({ "error" => T.string, "book_id" => T.string }))
+      .build
+  ) do |inputs|
+    book = @@books.find { |b| b[:id] == inputs[:id] }
+    
+    if book
+      # Set cache headers for Vercel edge caching
+      cache_control 'public, max-age=300, s-maxage=3600' # 5min browser, 1hr edge
+      headers 'X-Vercel-Cache' => 'MISS' # Would be set by Vercel
+      
+      book
+    else
+      halt 404, { error: 'Book not found', book_id: inputs[:id] }.to_json
+    end
+  end
+
+  # Fast book creation
+  endpoint(
+    POST('/books')
+      .summary('Create book (edge optimized)')
+      .description('Quickly create a new book with edge processing')
+      .body(T.hash({
+        "title" => T.string(min_length: 1, max_length: 255),
+        "author" => T.string(min_length: 1, max_length: 255),
+        "isbn" => T.optional(T.string(pattern: /^\d{10}(\d{3})?$/)),
+        "published_year" => T.optional(T.integer(minimum: 1000, maximum: 3000)),
+        "available" => T.optional(T.boolean),
+        "tags" => T.optional(T.array(T.string)),
+        "rating" => T.optional(T.float(minimum: 0, maximum: 5))
+      }))
+      .tags('Books')
+      .ok(BOOK_SCHEMA)
+      .error_response(400, T.hash({ "error" => T.string }))
+      .build
+  ) do |inputs|
+    book_data = inputs[:body]
+    
+    # Generate edge-optimized ID
+    new_id = "vercel_#{Time.now.to_i}_#{rand(1000)}"
+    
+    new_book = {
+      id: new_id,
+      title: book_data[:title] || book_data['title'],
+      author: book_data[:author] || book_data['author'],
+      isbn: book_data[:isbn] || book_data['isbn'],
+      published_year: book_data[:published_year] || book_data['published_year'],
+      available: book_data.key?(:available) ? book_data[:available] : (book_data.key?('available') ? book_data['available'] : true),
+      tags: book_data[:tags] || book_data['tags'] || [],
+      rating: book_data[:rating] || book_data['rating'],
+      created_at: Time.now,
+      updated_at: Time.now
+    }
+    
+    @@books << new_book
+    
+    # Set location header
+    headers 'Location' => "/books/#{new_id}"
+    
+    status 201
+    new_book
+  end
+
+  # Vercel-specific analytics endpoint
+  endpoint(
+    GET('/vercel/analytics')
+      .summary('Vercel deployment analytics')
+      .description('Get Vercel-specific deployment and performance data')
+      .tags('Vercel', 'Analytics')
+      .ok(T.hash({
+        "deployment" => T.hash({
+          "id" => T.optional(T.string),
+          "url" => T.optional(T.string),
+          "environment" => T.optional(T.string),
+          "created_at" => T.optional(T.datetime)
+        }),
+        "git_info" => T.hash({
+          "branch" => T.optional(T.string),
+          "commit_sha" => T.optional(T.string),
+          "commit_message" => T.optional(T.string),
+          "repo_url" => T.optional(T.string)
+        }),
+        "edge_performance" => T.hash({
+          "region" => T.optional(T.string),
+          "cold_starts" => T.integer,
+          "avg_response_time" => T.float
+        })
+      }))
+      .build
+  ) do
+    {
+      deployment: {
+        id: ENV['VERCEL_DEPLOYMENT_ID'],
+        url: ENV['VERCEL_URL'],
+        environment: ENV['VERCEL_ENV'],
+        created_at: ENV['VERCEL_DEPLOYMENT_ID'] ? Time.now : nil # Mock timestamp
+      },
+      git_info: {
+        branch: ENV['VERCEL_GIT_COMMIT_REF'],
+        commit_sha: ENV['VERCEL_GIT_COMMIT_SHA'],
+        commit_message: ENV['VERCEL_GIT_COMMIT_MESSAGE'],
+        repo_url: ENV['VERCEL_GIT_REPO_SLUG'] ? "https://github.com/#{ENV['VERCEL_GIT_REPO_SLUG']}" : nil
+      },
+      edge_performance: {
+        region: ENV['VERCEL_REGION'],
+        cold_starts: 0, # Mock data
+        avg_response_time: 45.2 # Mock data
+      }
+    }
+  end
+
+  # Search with edge optimization
+  endpoint(
+    GET('/books/search')
+      .query(:q, T.string(min_length: 1), description: 'Search query')
+      .query(:fuzzy, T.optional(T.boolean), description: 'Enable fuzzy search')
+      .summary('Search books (edge optimized)')
+      .description('Fast search optimized for edge computing')
+      .tags('Books', 'Search')
+      .ok(T.hash({
+        "results" => T.array(BOOK_SCHEMA),
+        "query" => T.string,
+        "fuzzy_enabled" => T.boolean,
+        "search_time_ms" => T.float,
+        "edge_region" => T.optional(T.string)
+      }))
+      .build
+  ) do |inputs|
+    start_time = Time.now
+    query = inputs[:q].downcase
+    fuzzy = inputs[:fuzzy] || false
+    
+    results = @@books.select do |book|
+      # Simple text search (could be enhanced with fuzzy matching)
+      [book[:title], book[:author], book[:tags]&.join(' ')].compact.any? do |field|
+        if fuzzy
+          # Simple fuzzy matching (could use more sophisticated algorithms)
+          field.downcase.include?(query) || 
+          query.chars.all? { |c| field.downcase.include?(c) }
+        else
+          field.downcase.include?(query)
+        end
+      end
+    end
+    
+    search_time = ((Time.now - start_time) * 1000).round(2)
+    
+    # Set edge cache headers
+    cache_control 'public, max-age=60, s-maxage=300' # 1min browser, 5min edge
+    
+    {
+      results: results,
+      query: inputs[:q],
+      fuzzy_enabled: fuzzy,
+      search_time_ms: search_time,
+      edge_region: ENV['VERCEL_REGION']
+    }
+  end
+end
+
+# Vercel handler function
+def handler(request:, response:)
+  # Mark as cold start on first execution
+  Thread.current[:cold_start] = !defined?(@@vercel_app_initialized)
+  
+  # Initialize app (cached after first execution)  
+  @@vercel_app ||= BookAPIVercel.new
+  @@vercel_app_initialized = true
+  
+  # Convert Vercel request to Rack environment
+  rack_env = build_rack_env_from_vercel(request)
+  
+  # Process request
+  status, headers, body = @@vercel_app.call(rack_env)
+  
+  # Convert response for Vercel
+  body_content = ''
+  body.each { |part| body_content += part }
+  
+  # Set Vercel response
+  response.status = status
+  headers.each { |key, value| response[key] = value }
+  response.write(body_content)
+  
+rescue => e
+  # Error handling for Vercel
+  response.status = 500
+  response['Content-Type'] = 'application/json'
+  response.write({
+    error: 'Internal server error',
+    message: e.message,
+    timestamp: Time.now.iso8601,
+    region: ENV['VERCEL_REGION']
+  }.to_json)
+ensure
+  Thread.current[:cold_start] = nil
+end
+
+# Convert Vercel request to Rack environment
+def build_rack_env_from_vercel(request)
+  method = request.method
+  url = request.url
+  uri = URI.parse(url)
+  
+  # Get request body
+  body = request.body || ''
+  
+  rack_env = {
+    'REQUEST_METHOD' => method,
+    'PATH_INFO' => uri.path,
+    'QUERY_STRING' => uri.query || '',
+    'CONTENT_TYPE' => request.headers['content-type'],
+    'CONTENT_LENGTH' => body.bytesize.to_s,
+    'rack.input' => StringIO.new(body),
+    'rack.errors' => $stderr,
+    'rack.version' => [1, 3],
+    'rack.url_scheme' => uri.scheme || 'https',
+    'rack.multithread' => false,
+    'rack.multiprocess' => true,
+    'rack.run_once' => true,
+    'SERVER_NAME' => uri.host,
+    'SERVER_PORT' => (uri.port || 443).to_s,
+    'HTTP_HOST' => uri.host
+  }
+  
+  # Add HTTP headers
+  request.headers.each do |key, value|
+    key = key.upcase.gsub('-', '_')
+    key = "HTTP_#{key}" unless %w[CONTENT_TYPE CONTENT_LENGTH].include?(key)
+    rack_env[key] = value
+  end
+  
+  # Add Vercel-specific headers
+  rack_env['HTTP_X_VERCEL_DEPLOYMENT_ID'] = ENV['VERCEL_DEPLOYMENT_ID']
+  rack_env['HTTP_X_VERCEL_REGION'] = ENV['VERCEL_REGION']
+  
+  rack_env
+end
+
+# For local development
+if __FILE__ == $0
+  BookAPIVercel.run!
+end

data/examples/strict_validation_examples.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RapiTapir Strict Validation Examples
+#
+# This file demonstrates the strict validation behavior in RapiTapir v2.0
+# By default, hash schemas now reject unexpected fields for better security.
+
+require_relative '../lib/rapitapir'
+
+puts "🔒 RapiTapir v2.0 - Strict Validation by Default"
+puts "=" * 55
+
+# Define strict schema (default behavior)
+STRICT_USER_SCHEMA = RapiTapir::Types.hash({
+  'name' => RapiTapir::Types.string,
+  'email' => RapiTapir::Types.email,
+  'age' => RapiTapir::Types.integer
+})
+
+# Define open schema (allows additional properties)
+OPEN_USER_SCHEMA = RapiTapir::Types.open_hash({
+  'name' => RapiTapir::Types.string,
+  'email' => RapiTapir::Types.email,
+  'age' => RapiTapir::Types.integer
+})
+
+def test_validation(title, data, schema)
+  puts "\n#{title}"
+  puts "-" * 40
+  puts "📥 Input: #{data.inspect}"
+  
+  begin
+    result = schema.coerce(data)
+    puts "✅ Success: #{result.inspect}"
+  rescue RapiTapir::Types::CoercionError => e
+    puts "❌ Error: #{e.message}"
+    if e.reason =~ /Unexpected fields/
+      puts "🔒 Security: Rejecting unexpected data"
+    end
+  end
+end
+
+# Test data with extra field
+test_data_with_extra = {
+  'name' => 'John Doe',
+  'email' => 'john@example.com',
+  'age' => 25,
+  'extra_field' => 'unexpected_value',
+  'another_field' => 42
+}
+
+# Test data without extra fields
+test_data_clean = {
+  'name' => 'Jane Smith',
+  'email' => 'jane@example.com',
+  'age' => 30
+}
+
+puts "\n📋 1. STRICT VALIDATION (Default Behavior)"
+puts "   🔒 Rejects unexpected fields for security"
+
+test_validation(
+  "1️⃣  Strict Schema with Extra Fields",
+  test_data_with_extra,
+  STRICT_USER_SCHEMA
+)
+
+test_validation(
+  "2️⃣  Strict Schema with Clean Data",
+  test_data_clean,
+  STRICT_USER_SCHEMA
+)
+
+puts "\n📋 2. OPEN VALIDATION (Explicit opt-in)"
+puts "   🌐 Allows additional properties when needed"
+
+test_validation(
+  "3️⃣  Open Schema with Extra Fields",
+  test_data_with_extra,
+  OPEN_USER_SCHEMA
+)
+
+test_validation(
+  "4️⃣  Open Schema with Clean Data",
+  test_data_clean,
+  OPEN_USER_SCHEMA
+)
+
+puts "\n🎉 Strict Validation Benefits:"
+puts "   ✅ Enhanced security by rejecting unexpected data"
+puts "   ✅ Clear error messages showing allowed fields"
+puts "   ✅ Prevents data leakage and injection attacks"
+puts "   ✅ Enforces API contract compliance"
+puts "   ✅ Explicit opt-in for flexible schemas when needed"
+
+puts "\n💡 Usage Guidelines:"
+puts "   • Use RapiTapir::Types.hash() for strict validation (default)"
+puts "   • Use RapiTapir::Types.open_hash() when you need flexibility"
+puts "   • Most production APIs should use strict validation"
+puts "   • Consider open validation only for specific use cases like:"
+puts "     - Webhook payloads with variable structures"
+puts "     - Configuration objects with user-defined fields"
+puts "     - Migration endpoints that need backward compatibility"