synthra 0.1.0

data/docs/WEBHOOK_SIMULATOR.md

@@ -0,0 +1,579 @@
+# Webhook Simulation
+
+FakeDataDSL's Webhook Simulator lets you **send realistic webhook payloads** to your application, simulating events from external services like Stripe, GitHub, Twilio, and more.
+
+## Quick Start
+
+```ruby
+# Configure the simulator
+FakeDataDSL::WebhookSimulator.configure do |config|
+  config.endpoint = "http://localhost:3000/webhooks"
+  config.secret = "whsec_your_webhook_secret"
+end
+
+# Send a webhook
+FakeDataDSL::WebhookSimulator.send(
+  "stripe.payment_intent.succeeded",
+  schema: "StripePaymentIntent"
+)
+```
+
+## Basic Usage
+
+### Simple Webhook
+
+```ruby
+# Send webhook with generated data
+FakeDataDSL::WebhookSimulator.send(
+  "user.created",
+  schema: "User"
+)
+
+# With custom payload overrides
+FakeDataDSL::WebhookSimulator.send(
+  "order.completed",
+  schema: "Order",
+  data: { status: "completed", total: 99.99 }
+)
+```
+
+### With Delay
+
+```ruby
+# Simulate network latency
+FakeDataDSL::WebhookSimulator.send(
+  "payment.failed",
+  schema: "PaymentEvent",
+  delay: 2.seconds
+)
+```
+
+### Batch Webhooks
+
+```ruby
+# Send multiple webhooks in sequence
+FakeDataDSL::WebhookSimulator.send_batch([
+  { event: "order.created", schema: "Order" },
+  { event: "payment.processing", schema: "Payment", delay: 1.second },
+  { event: "payment.succeeded", schema: "Payment", delay: 2.seconds },
+  { event: "order.completed", schema: "Order", delay: 3.seconds }
+])
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+FakeDataDSL::WebhookSimulator.configure do |config|
+  # Target endpoint
+  config.endpoint = "http://localhost:3000/webhooks"
+  
+  # Webhook secret for signatures
+  config.secret = ENV["WEBHOOK_SECRET"]
+  
+  # Default headers
+  config.headers = {
+    "Content-Type" => "application/json",
+    "User-Agent" => "FakeDataDSL-WebhookSimulator/1.0"
+  }
+  
+  # Timeout settings
+  config.timeout = 30
+  config.open_timeout = 5
+  
+  # Retry settings
+  config.max_retries = 3
+  config.retry_delay = 1.second
+  
+  # Logging
+  config.logger = Rails.logger
+  config.log_level = :info
+end
+```
+
+### Per-Request Configuration
+
+```ruby
+FakeDataDSL::WebhookSimulator.send(
+  "event.name",
+  schema: "Schema",
+  config: {
+    endpoint: "http://different-endpoint.com/hooks",
+    secret: "different_secret",
+    timeout: 60
+  }
+)
+```
+
+## Webhook Signatures
+
+### Automatic Signing
+
+Webhooks are automatically signed based on the provider type:
+
+```ruby
+# Stripe-style signature (HMAC-SHA256)
+FakeDataDSL::WebhookSimulator.send(
+  "payment_intent.succeeded",
+  schema: "StripePayment",
+  signature_type: :stripe
+)
+# Adds: Stripe-Signature: t=1234567890,v1=abc123...
+
+# GitHub-style signature
+FakeDataDSL::WebhookSimulator.send(
+  "push",
+  schema: "GitHubPush",
+  signature_type: :github
+)
+# Adds: X-Hub-Signature-256: sha256=abc123...
+
+# Custom signature
+FakeDataDSL::WebhookSimulator.send(
+  "custom.event",
+  schema: "Custom",
+  signature: ->(payload, secret) {
+    OpenSSL::HMAC.hexdigest("SHA512", secret, payload)
+  },
+  signature_header: "X-Custom-Signature"
+)
+```
+
+### Supported Signature Types
+
+| Provider | Type | Header |
+|----------|------|--------|
+| Stripe | `:stripe` | `Stripe-Signature` |
+| GitHub | `:github` | `X-Hub-Signature-256` |
+| Twilio | `:twilio` | `X-Twilio-Signature` |
+| Shopify | `:shopify` | `X-Shopify-Hmac-SHA256` |
+| Custom | `:custom` | Configurable |
+
+## Provider Presets
+
+### Stripe
+
+```ruby
+FakeDataDSL::WebhookSimulator.stripe(
+  "payment_intent.succeeded",
+  data: {
+    amount: 2000,
+    currency: "usd",
+    customer: "cus_123"
+  }
+)
+
+# Uses built-in Stripe event schemas
+# Automatically formats as Stripe webhook structure:
+# {
+#   "id": "evt_...",
+#   "object": "event",
+#   "type": "payment_intent.succeeded",
+#   "data": { "object": { ... } }
+# }
+```
+
+### GitHub
+
+```ruby
+FakeDataDSL::WebhookSimulator.github(
+  "push",
+  repository: "owner/repo",
+  data: {
+    ref: "refs/heads/main",
+    commits: [{ message: "Update README" }]
+  }
+)
+```
+
+### Twilio
+
+```ruby
+FakeDataDSL::WebhookSimulator.twilio(
+  "message.received",
+  data: {
+    from: "+15551234567",
+    body: "Hello, world!"
+  }
+)
+```
+
+### Custom Provider
+
+```ruby
+FakeDataDSL::WebhookSimulator.register_provider(:my_service) do |config|
+  config.base_url = "https://my-service.com"
+  config.signature_type = :hmac_sha256
+  config.signature_header = "X-MyService-Signature"
+  config.event_wrapper = ->(event, data) {
+    {
+      event_type: event,
+      timestamp: Time.current.iso8601,
+      payload: data
+    }
+  }
+end
+
+# Use registered provider
+FakeDataDSL::WebhookSimulator.my_service(
+  "user.updated",
+  schema: "User"
+)
+```
+
+## Event Sequences
+
+### Define Sequences
+
+```ruby
+# Define a sequence of related events
+FakeDataDSL::WebhookSimulator.define_sequence(:checkout_flow) do
+  # Step 1: Cart created
+  step "cart.created", schema: "Cart"
+  
+  # Step 2: Payment initiated (after 1 second)
+  step "payment.initiated", schema: "Payment", delay: 1.second
+  
+  # Step 3: Payment succeeded (after 2 more seconds)
+  step "payment.succeeded", schema: "Payment", delay: 2.seconds
+  
+  # Step 4: Order created
+  step "order.created", schema: "Order", delay: 500.milliseconds
+  
+  # Step 5: Email sent
+  step "notification.sent", schema: "Notification", delay: 1.second
+end
+```
+
+### Run Sequences
+
+```ruby
+# Run the sequence
+FakeDataDSL::WebhookSimulator.run_sequence(:checkout_flow)
+
+# Run with shared context (data passed between steps)
+FakeDataDSL::WebhookSimulator.run_sequence(:checkout_flow,
+  context: { user_id: "user_123", amount: 99.99 }
+)
+
+# Run with callbacks
+FakeDataDSL::WebhookSimulator.run_sequence(:checkout_flow) do |step, response|
+  puts "Step #{step.name}: #{response.status}"
+end
+```
+
+### Conditional Steps
+
+```ruby
+FakeDataDSL::WebhookSimulator.define_sequence(:payment_flow) do
+  step "payment.initiated", schema: "Payment"
+  
+  # Branch based on previous response
+  branch do |context|
+    if context[:payment_method] == "card"
+      step "payment.card.processing", schema: "CardPayment"
+    else
+      step "payment.bank.processing", schema: "BankPayment"
+    end
+  end
+  
+  step "payment.completed", schema: "Payment"
+end
+```
+
+## Testing Integration
+
+### RSpec Helpers
+
+```ruby
+# spec/rails_helper.rb
+require 'fake_data_dsl/webhook_simulator/rspec'
+
+RSpec.configure do |config|
+  config.include FakeDataDSL::WebhookSimulator::RSpecHelpers
+end
+```
+
+```ruby
+# spec/webhooks/stripe_spec.rb
+RSpec.describe "Stripe Webhooks", type: :request do
+  it "handles payment_intent.succeeded" do
+    simulate_webhook "stripe.payment_intent.succeeded",
+      schema: "StripePayment",
+      data: { amount: 5000 }
+    
+    expect(response).to have_http_status(:ok)
+    expect(Payment.last.amount).to eq(50.00)
+  end
+  
+  it "handles the full checkout sequence" do
+    simulate_webhook_sequence :checkout_flow
+    
+    expect(Order.count).to eq(1)
+    expect(Order.last.status).to eq("completed")
+  end
+end
+```
+
+### Minitest Helpers
+
+```ruby
+# test/test_helper.rb
+require 'fake_data_dsl/webhook_simulator/minitest'
+
+class ActiveSupport::TestCase
+  include FakeDataDSL::WebhookSimulator::MinitestHelpers
+end
+```
+
+```ruby
+# test/integration/webhooks_test.rb
+class WebhooksTest < ActionDispatch::IntegrationTest
+  test "handles stripe webhook" do
+    simulate_webhook "stripe.payment_intent.succeeded",
+      schema: "StripePayment"
+    
+    assert_response :success
+  end
+end
+```
+
+## Error Simulation
+
+### Simulate Failures
+
+```ruby
+# Simulate webhook delivery failure
+FakeDataDSL::WebhookSimulator.send(
+  "event.name",
+  schema: "Schema",
+  simulate_failure: true  # Returns 500 error simulation
+)
+
+# Simulate timeout
+FakeDataDSL::WebhookSimulator.send(
+  "event.name",
+  schema: "Schema",
+  simulate_timeout: true
+)
+
+# Simulate partial failure (intermittent)
+FakeDataDSL::WebhookSimulator.send(
+  "event.name",
+  schema: "Schema",
+  failure_rate: 0.3  # 30% chance of failure
+)
+```
+
+### Retry Testing
+
+```ruby
+# Test retry behavior
+FakeDataDSL::WebhookSimulator.send(
+  "event.name",
+  schema: "Schema",
+  fail_first_n: 2  # Fail first 2 attempts, succeed on 3rd
+)
+```
+
+## Recording and Replay
+
+### Record Webhooks
+
+```ruby
+# Record all webhooks sent
+FakeDataDSL::WebhookSimulator.start_recording
+
+# ... send webhooks ...
+
+# Stop and save
+recordings = FakeDataDSL::WebhookSimulator.stop_recording
+recordings.save_to("spec/fixtures/webhooks/checkout_flow.json")
+```
+
+### Replay Recordings
+
+```ruby
+# Replay recorded webhooks
+FakeDataDSL::WebhookSimulator.replay("spec/fixtures/webhooks/checkout_flow.json")
+
+# With timing
+FakeDataDSL::WebhookSimulator.replay("recordings.json",
+  preserve_timing: true  # Replay with original delays
+)
+```
+
+## CLI Commands
+
+```bash
+# Send single webhook
+fake_data_dsl webhook send user.created \
+  --schema User \
+  --endpoint http://localhost:3000/webhooks \
+  --secret whsec_xxx
+
+# Send with data override
+fake_data_dsl webhook send payment.succeeded \
+  --schema Payment \
+  --data '{"amount": 9999}' \
+  --endpoint http://localhost:3000/webhooks
+
+# Run sequence
+fake_data_dsl webhook sequence checkout_flow \
+  --endpoint http://localhost:3000/webhooks
+
+# Record mode
+fake_data_dsl webhook record \
+  --output recordings/session.json \
+  --duration 60  # Record for 60 seconds
+
+# Replay recordings
+fake_data_dsl webhook replay recordings/session.json \
+  --endpoint http://localhost:3000/webhooks
+```
+
+## API Reference
+
+### WebhookSimulator.send
+
+```ruby
+FakeDataDSL::WebhookSimulator.send(event_name, options = {})
+```
+
+**Parameters:**
+- `event_name` - Event type string (e.g., "user.created")
+- `options[:schema]` - Schema name for payload generation
+- `options[:data]` - Override data
+- `options[:delay]` - Delay before sending
+- `options[:endpoint]` - Override endpoint
+- `options[:secret]` - Override secret
+- `options[:signature_type]` - Signature type
+- `options[:headers]` - Additional headers
+- `options[:config]` - Full config override
+
+**Returns:** `WebhookResponse` object
+
+### WebhookSimulator.send_batch
+
+```ruby
+FakeDataDSL::WebhookSimulator.send_batch(webhooks)
+```
+
+**Parameters:**
+- `webhooks` - Array of webhook configurations
+
+**Returns:** Array of `WebhookResponse` objects
+
+### WebhookSimulator.define_sequence
+
+```ruby
+FakeDataDSL::WebhookSimulator.define_sequence(name, &block)
+```
+
+**Parameters:**
+- `name` - Sequence name
+- `block` - Sequence definition block
+
+### WebhookSimulator.run_sequence
+
+```ruby
+FakeDataDSL::WebhookSimulator.run_sequence(name, options = {}, &callback)
+```
+
+**Parameters:**
+- `name` - Sequence name
+- `options[:context]` - Shared context data
+- `callback` - Optional callback for each step
+
+**Returns:** Array of `WebhookResponse` objects
+
+## Best Practices
+
+### 1. Use Consistent Secrets
+
+```ruby
+# config/environments/test.rb
+ENV["WEBHOOK_SECRET"] = "test_webhook_secret"
+
+# spec/rails_helper.rb
+FakeDataDSL::WebhookSimulator.configure do |config|
+  config.secret = ENV["WEBHOOK_SECRET"]
+end
+```
+
+### 2. Test Error Handling
+
+```ruby
+it "handles webhook failures gracefully" do
+  simulate_webhook "payment.failed",
+    schema: "FailedPayment",
+    data: { error_code: "card_declined" }
+  
+  expect(response).to have_http_status(:ok)
+  expect(Payment.last.status).to eq("failed")
+  expect(User.last).to have_received_email(:payment_failed)
+end
+```
+
+### 3. Use Sequences for Complex Flows
+
+```ruby
+# Better than individual webhook tests
+simulate_webhook_sequence :full_order_lifecycle
+
+# Instead of:
+simulate_webhook "order.created"
+simulate_webhook "payment.succeeded"
+simulate_webhook "order.shipped"
+simulate_webhook "order.delivered"
+```
+
+### 4. Record Production Webhooks for Testing
+
+```ruby
+# In development, record real webhooks
+# Then replay in tests for realistic scenarios
+```
+
+## Troubleshooting
+
+### Signature Verification Failing
+
+```ruby
+# Make sure secrets match
+FakeDataDSL::WebhookSimulator.configure do |config|
+  config.secret = ENV["WEBHOOK_SECRET"]  # Same as your app uses
+end
+
+# Debug signature
+response = FakeDataDSL::WebhookSimulator.send(...)
+puts response.request_headers["Stripe-Signature"]
+```
+
+### Timeout Issues
+
+```ruby
+# Increase timeout
+FakeDataDSL::WebhookSimulator.configure do |config|
+  config.timeout = 60
+  config.open_timeout = 10
+end
+```
+
+### Endpoint Not Reachable
+
+```ruby
+# Make sure your server is running
+# In tests, use request specs not system specs
+RSpec.describe "Webhooks", type: :request do
+  # This runs against the test server
+end
+```
+
+## See Also
+
+- [Mock Server](MOCK_SERVER.md)
+- [API Server](API_SERVER.md)
+- [Scenarios](SCENARIOS.md)
+- [Testing Best Practices](best_practices.md)