dojo.md 0.1.0 → 0.2.1

package/courses/api-error-handling/scenarios/level-2/rfc-7807-problem-details.yaml

@@ -0,0 +1,178 @@
+name: "RFC 7807 Problem Details Standard"
+level: 2
+difficulty: intermediate
+description: "Implement standardized error responses using RFC 7807 Problem Details format"
+
+context: |
+  Migrate your API error responses to the RFC 7807 standard. This standardized format
+  improves interoperability across tools and clients. Implement problem details with
+  type URI, title, status, detail, and instance fields.
+
+scenario:
+  state:
+    bank_accounts:
+      "acc_001": { balance: 5000, account_holder: "John Doe" }
+      "acc_002": { balance: 100, account_holder: "Jane Smith" }
+
+  endpoint: "POST /api/v1/accounts/{accountId}/transfer"
+
+  test_cases:
+    - name: "successful_transfer"
+      request:
+        path: "/api/v1/accounts/acc_001/transfer"
+        body:
+          to_account: "acc_002"
+          amount: 100
+      expected_status: 200
+      expected_response:
+        transaction_id: "txn_123"
+        status: "completed"
+
+    - name: "insufficient_funds_rfc7807"
+      request:
+        path: "/api/v1/accounts/acc_002/transfer"
+        body:
+          to_account: "acc_001"
+          amount: 500
+      expected_status: 422
+      expected_response:
+        type: "https://api.example.com/errors/insufficient-funds"
+        title: "Insufficient Funds"
+        status: 422
+        detail: "Account acc_002 has balance of 100 but requires 500 for this transfer"
+        instance: "/api/v1/accounts/acc_002/transfer"
+        balance: 100
+        required_amount: 500
+
+    - name: "account_not_found_rfc7807"
+      request:
+        path: "/api/v1/accounts/acc_999/transfer"
+        body:
+          to_account: "acc_001"
+          amount: 100
+      expected_status: 404
+      expected_response:
+        type: "https://api.example.com/errors/account-not-found"
+        title: "Account Not Found"
+        status: 404
+        detail: "The account acc_999 does not exist in the system"
+        instance: "/api/v1/accounts/acc_999/transfer"
+
+    - name: "invalid_amount_validation"
+      request:
+        path: "/api/v1/accounts/acc_001/transfer"
+        body:
+          to_account: "acc_002"
+          amount: -50
+      expected_status: 400
+      expected_response:
+        type: "https://api.example.com/errors/validation-error"
+        title: "Validation Error"
+        status: 400
+        detail: "The request body contains invalid values"
+        instance: "/api/v1/accounts/acc_001/transfer"
+        validation_errors:
+          - field: "amount"
+            message: "Amount must be positive"
+            rejected_value: -50
+
+    - name: "self_transfer_error"
+      request:
+        path: "/api/v1/accounts/acc_001/transfer"
+        body:
+          to_account: "acc_001"
+          amount: 100
+      expected_status: 409
+      expected_response:
+        type: "https://api.example.com/errors/invalid-operation"
+        title: "Invalid Operation"
+        status: 409
+        detail: "Cannot transfer funds to the same account"
+        instance: "/api/v1/accounts/acc_001/transfer"
+
+assertions:
+  - type: "api_called"
+    description: "type field contains URI identifying problem"
+    test: "error response includes type field with URI"
+
+  - type: "api_called"
+    description: "title field is human-readable problem type"
+    test: "title field is constant for same error type"
+
+  - type: "api_called"
+    description: "status field echoes HTTP status code"
+    test: "status field matches HTTP response status"
+
+  - type: "api_called"
+    description: "detail field explains specific instance"
+    test: "detail contains instance-specific information"
+
+  - type: "api_called"
+    description: "instance field identifies affected resource"
+    test: "instance field contains request path"
+
+  - type: "api_called"
+    description: "Extensions included for domain-specific details"
+    test: "error response includes custom fields as extensions"
+
+  - type: "outcome"
+    description: "RFC 7807 enables standard error tooling"
+    test: "error responses conform to standard specification"
+
+learning_objectives:
+  - "Understand RFC 7807 Problem Details specification"
+  - "Map problem types to type URIs"
+  - "Distinguish between title (constant) and detail (instance-specific)"
+  - "Include appropriate HTTP status codes in problem details"
+  - "Extend RFC 7807 with domain-specific fields"
+  - "Communicate problem details to generic HTTP clients"
+
+rfc7807_fields:
+  "type": "URI identifying problem type (required, should dereference to documentation)"
+  "title": "Short human-readable summary of problem type (required, same for same type)"
+  "status": "HTTP status code (optional, but recommended)"
+  "detail": "Human-readable explanation of specific problem instance (optional, instance-specific)"
+  "instance": "URI identifying specific problem occurrence (optional, usually request path)"
+
+example_error_responses: |
+  Example 1: Insufficient Funds
+  {
+    "type": "https://api.example.com/errors/insufficient-funds",
+    "title": "Insufficient Funds",
+    "status": 422,
+    "detail": "Account acc_002 has balance of 100 but requires 500 for this transfer",
+    "instance": "/api/v1/accounts/acc_002/transfer",
+    "balance": 100,
+    "required_amount": 500
+  }
+
+  Example 2: Validation Error
+  {
+    "type": "https://api.example.com/errors/validation-error",
+    "title": "Validation Error",
+    "status": 400,
+    "detail": "The request body contains invalid values",
+    "instance": "/api/v1/accounts/acc_001/transfer",
+    "validation_errors": [
+      {
+        "field": "amount",
+        "message": "Amount must be positive",
+        "rejected_value": -50
+      }
+    ]
+  }
+
+advantages:
+  - "Standard format recognized by HTTP tools and libraries"
+  - "Generic clients can handle errors without API-specific code"
+  - "Clear semantics: type vs title vs detail"
+  - "Extensibility through custom fields"
+  - "Easier debugging and error tracking"
+  - "Better integration with API gateways and monitoring"
+
+content_type:
+  "application/problem+json": "Standard MIME type for RFC 7807 responses"
+
+references:
+  - "https://datatracker.ietf.org/doc/html/rfc7807"
+  - "https://datatracker.ietf.org/doc/html/rfc9457 (RFC 9457 - Problem Details for HTTP APIs)"

package/courses/api-error-handling/scenarios/level-2/webhook-error-handling.yaml

@@ -0,0 +1,211 @@
+name: "Webhook Error Handling and Retry Logic"
+level: 2
+difficulty: intermediate
+description: "Implement webhook delivery with exponential backoff retry strategy and dead letter queues"
+
+context: |
+  Build a webhook delivery system for payment events. Handle failed deliveries with
+  exponential backoff, respect HTTP error codes (don't retry 4xx), and move permanently
+  failed webhooks to dead letter queue for inspection.
+
+scenario:
+  state:
+    webhooks:
+      "wh_payment_complete":
+        url: "https://customer-1.example.com/webhooks/payments"
+        status: "active"
+        retry_count: 0
+        last_attempt: null
+    events:
+      "evt_001": { type: "payment.completed", customer_id: "cust_1", status: "pending" }
+      "evt_002": { type: "payment.completed", customer_id: "cust_2", status: "pending" }
+    webhook_endpoints:
+      "https://customer-1.example.com/webhooks/payments":
+        response_status: 500
+        consecutive_failures: 0
+      "https://customer-2.example.com/webhooks/payments":
+        response_status: 404
+        consecutive_failures: 0
+
+  endpoint: "Internal: Webhook Delivery System"
+
+  test_cases:
+    - name: "successful_webhook_delivery"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_status: 200
+      expected_result: "delivered"
+      expected_retry_count: 0
+
+    - name: "temporary_failure_retry"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_status: 503
+      retry_strategy: "exponential_backoff"
+      expected_retries:
+        - attempt: 1
+          delay: 1
+          endpoint_status: 503
+        - attempt: 2
+          delay: 5
+          endpoint_status: 503
+        - attempt: 3
+          delay: 30
+          endpoint_status: 200
+          result: "delivered"
+
+    - name: "timeout_is_retriable"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_behavior: "timeout"
+      endpoint_timeout_ms: 35000
+      expected_retries:
+        - attempt: 1
+          delay: 1
+          result: "timeout"
+        - attempt: 2
+          delay: 5
+          result: "timeout"
+        - attempt: 3
+          delay: 30
+          endpoint_status: 200
+          result: "delivered"
+
+    - name: "404_not_found_not_retried"
+      event: "evt_001"
+      webhook_url: "https://nonexistent.example.com/webhooks/payments"
+      endpoint_status: 404
+      expected_retries: 0
+      expected_result: "dead_letter_queue"
+      expected_reason: "endpoint_not_found"
+
+    - name: "401_unauthorized_not_retried"
+      event: "evt_001"
+      webhook_url: "https://customer-2.example.com/webhooks/payments"
+      endpoint_status: 401
+      expected_retries: 0
+      expected_result: "dead_letter_queue"
+      expected_reason: "authorization_failed"
+
+    - name: "400_bad_request_not_retried"
+      event: "evt_001"
+      webhook_url: "https://customer-3.example.com/webhooks/payments"
+      endpoint_status: 400
+      expected_retries: 0
+      expected_result: "dead_letter_queue"
+      expected_reason: "malformed_request"
+
+    - name: "max_retries_exceeded"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_status: 502
+      max_retries: 5
+      expected_retries:
+        - attempt: 1
+          delay: 1
+          endpoint_status: 502
+        - attempt: 2
+          delay: 5
+          endpoint_status: 502
+        - attempt: 3
+          delay: 30
+          endpoint_status: 502
+        - attempt: 4
+          delay: 120
+          endpoint_status: 502
+        - attempt: 5
+          delay: 300
+          endpoint_status: 502
+      expected_result: "dead_letter_queue"
+      expected_reason: "max_retries_exceeded"
+
+    - name: "jitter_prevents_thundering_herd"
+      events_count: 100
+      all_failing: true
+      retry_schedule: "exponential_with_jitter"
+      expected_behavior: "retry_attempts_spread_across_time"
+
+    - name: "idempotency_prevents_duplicates"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      attempt_1_result: "timeout"
+      attempt_1_delivered: true
+      attempt_2_result: 200
+      expected_behavior: "idempotent_delivery (delivered once)"
+
+assertions:
+  - type: "api_called"
+    description: "Webhook called with event payload"
+    test: "webhook POST includes event data"
+
+  - type: "api_called"
+    description: "5xx errors are retried"
+    test: "502/503 errors trigger retry"
+
+  - type: "api_called"
+    description: "4xx errors are not retried"
+    test: "404/401/400 moved to dead letter queue"
+
+  - type: "outcome"
+    description: "Exponential backoff used"
+    test: "retry delays follow: 1s, 5s, 30s, 120s, 300s"
+
+  - type: "api_called"
+    description: "Jitter added to prevent thundering herd"
+    test: "retry_schedule uses jitter"
+
+  - type: "api_called"
+    description: "Dead letter queue stores permanently failed"
+    test: "max_retries_exceeded moves to DLQ"
+
+  - type: "outcome"
+    description: "Idempotent delivery"
+    test: "webhook called once despite retries"
+
+learning_objectives:
+  - "Understand transient vs permanent webhook failures"
+  - "Implement exponential backoff retry strategy"
+  - "Distinguish retriable (5xx) vs non-retriable (4xx) errors"
+  - "Add jitter to prevent synchronized retries"
+  - "Implement dead letter queue for manual inspection"
+  - "Track retry attempts and timing"
+  - "Handle webhook idempotency"
+
+retry_strategy:
+  "retriable_status_codes": [408, 429, 500, 502, 503, 504]
+  "non_retriable_status_codes": [400, 401, 403, 404, 405, 410]
+  "transient_failures": ["timeout", "connection_reset", "dns_failure"]
+  "backoff_pattern": "exponential: 1s, 5s, 30s, 120s, 300s"
+  "max_attempts": 5
+  "jitter": "random 0-10% of delay"
+
+headers:
+  "X-Webhook-ID": "Unique webhook endpoint identifier"
+  "X-Event-ID": "Unique event identifier for idempotency"
+  "X-Delivery-Attempt": "Attempt number (1, 2, 3, ...)"
+  "X-Webhook-Signature": "HMAC signature for verification"
+
+dead_letter_queue:
+  "storage": "Separate database table or queue"
+  "retention": "30 days minimum for inspection"
+  "alerting": "Alert ops team after 10 DLQ entries"
+  "manual_retry": "Allow manual redelivery from UI"
+
+monitoring:
+  "metrics":
+    - "delivery_success_rate"
+    - "delivery_latency_p50/p95/p99"
+    - "retry_count_distribution"
+    - "dlq_entries_rate"
+  "alerts":
+    - "delivery_success_rate < 95%"
+    - "dlq_entries > 100 in 1 hour"
+
+common_mistakes:
+  - "Retrying 404 Not Found (never succeeds)"
+  - "No exponential backoff (overwhelming server)"
+  - "No jitter (thundering herd effect)"
+  - "Unbounded retries (never gives up)"
+  - "Not idempotent (duplicate deliveries)"
+  - "No dead letter queue (lost events)"
+  - "Not respecting Retry-After header"

package/courses/api-error-handling/scenarios/level-3/distributed-tracing-errors.yaml

@@ -0,0 +1,275 @@
+name: "Distributed Tracing and Error Correlation"
+level: 3
+difficulty: advanced
+description: "Track errors across multiple services using correlation IDs and distributed tracing"
+
+context: |
+  Build a microservice system where a single user request flows through Order Service
+  → Payment Service → Shipping Service. Implement distributed tracing with correlation
+  IDs to track errors across all services and perform root cause analysis.
+
+scenario:
+  state:
+    services:
+      order_service:
+        url: "http://order-api:3000"
+        status: "healthy"
+      payment_service:
+        url: "http://payment-api:3001"
+        status: "healthy"
+      shipping_service:
+        url: "http://shipping-api:3002"
+        status: "healthy"
+    orders:
+      "ord_001": { customer_id: "cust_1", total: 100, status: "pending" }
+
+  endpoint: "POST /api/v1/orders"
+
+  test_cases:
+    - name: "successful_order_with_trace"
+      request:
+        path: "/api/v1/orders"
+        body: { customer_id: "cust_1", items: ["item_1"] }
+        headers:
+          X-Correlation-ID: "trace_123"
+      service_calls:
+        - service: "order_service"
+          action: "create_order"
+          status: 201
+          trace_id: "trace_123"
+          span_id: "span_order_1"
+          duration_ms: 50
+        - service: "payment_service"
+          action: "charge_card"
+          status: 200
+          trace_id: "trace_123"
+          parent_span: "span_order_1"
+          span_id: "span_payment_1"
+          duration_ms: 200
+        - service: "shipping_service"
+          action: "create_shipment"
+          status: 201
+          trace_id: "trace_123"
+          parent_span: "span_order_1"
+          span_id: "span_shipping_1"
+          duration_ms: 100
+      expected_response:
+        status: 201
+        order_id: "ord_002"
+      expected_trace:
+        spans:
+          - span_order_1: "50ms"
+          - span_payment_1: "200ms"
+          - span_shipping_1: "100ms"
+        total_time: "350ms"
+
+    - name: "payment_service_timeout_traced"
+      request:
+        path: "/api/v1/orders"
+        body: { customer_id: "cust_1", items: ["item_1"] }
+        headers:
+          X-Correlation-ID: "trace_456"
+      service_calls:
+        - service: "order_service"
+          action: "create_order"
+          status: 201
+          trace_id: "trace_456"
+          span_id: "span_order_2"
+          duration_ms: 50
+        - service: "payment_service"
+          action: "charge_card"
+          status: 504
+          error: "gateway_timeout"
+          trace_id: "trace_456"
+          parent_span: "span_order_2"
+          span_id: "span_payment_2"
+          duration_ms: 30000
+          error_details:
+            message: "Payment processing took too long"
+            timeout_ms: 30000
+      expected_response:
+        status: 502
+        error:
+          code: "PAYMENT_SERVICE_UNAVAILABLE"
+      correlation_id: "trace_456"
+      distributed_trace:
+        spans:
+          - name: "POST /orders"
+            service: "order_service"
+            span_id: "span_order_2"
+            status: "error"
+          - name: "POST /charges"
+            service: "payment_service"
+            parent_span: "span_order_2"
+            span_id: "span_payment_2"
+            status: "error"
+            error_type: "timeout"
+
+    - name: "cascading_failure_visible_in_trace"
+      request:
+        path: "/api/v1/orders"
+        body: { customer_id: "cust_1", items: ["item_1"] }
+        headers:
+          X-Correlation-ID: "trace_789"
+      service_calls:
+        - service: "order_service"
+          action: "create_order"
+          status: 201
+          trace_id: "trace_789"
+          span_id: "span_order_3"
+        - service: "payment_service"
+          action: "charge_card"
+          status: 500
+          trace_id: "trace_789"
+          parent_span: "span_order_3"
+          span_id: "span_payment_3"
+          error: "database_connection_failed"
+        - service: "shipping_service"
+          action: "create_shipment"
+          status: 500
+          trace_id: "trace_789"
+          parent_span: "span_order_3"
+          span_id: "span_shipping_3"
+          error: "order_not_confirmed"
+      expected_response:
+        status: 502
+      distributed_trace:
+        critical_path: "trace_789 → order_service fails payment → shipping can't proceed"
+        error_summary: "Payment service database unavailable, causing cascade"
+
+    - name: "error_context_preserved_across_services"
+      request:
+        path: "/api/v1/orders"
+        headers:
+          X-Correlation-ID: "trace_101"
+          X-Request-ID: "req_101"
+          X-User-ID: "user_123"
+      propagated_headers:
+        - service: "order_service"
+          headers: { X-Correlation-ID: "trace_101", X-Request-ID: "req_101", X-User-ID: "user_123" }
+        - service: "payment_service"
+          headers: { X-Correlation-ID: "trace_101", X-Request-ID: "req_101", X-User-ID: "user_123" }
+        - service: "shipping_service"
+          headers: { X-Correlation-ID: "trace_101", X-Request-ID: "req_101", X-User-ID: "user_123" }
+      expected_behavior: "all services log with same correlation ID"
+
+    - name: "root_cause_analysis_via_trace"
+      incident:
+        symptom: "Orders taking 30+ seconds"
+        correlation_ids: ["trace_111", "trace_112", "trace_113"]
+      analysis:
+        - step: "1. Review distributed trace"
+          finding: "All traces show: order_service 50ms, payment_service 25000ms, shipping_service 5000ms"
+        - step: "2. Identify critical path"
+          finding: "Payment service is bottleneck"
+        - step: "3. Check payment service logs"
+          finding: "SELECT * FROM charges WHERE status='processing' returns 10000 rows"
+        - step: "4. Check metrics"
+          finding: "Database CPU at 95%, pending queries at 10000"
+        - step: "5. Root cause"
+          finding: "Payment processing queries missing index, causing full table scans"
+        - step: "6. Solution"
+          action: "Add index on charges(status, created_at)"
+
+    - name: "trace_context_loss_error"
+      request:
+        path: "/api/v1/orders"
+        headers:
+          X-Correlation-ID: "trace_202"
+      service_calls:
+        - service: "order_service"
+          trace_id: "trace_202"
+          passes_header: true
+        - service: "payment_service"
+          trace_id: "trace_202"
+          passes_header: false  # Bug: forgot to propagate
+          implicit_trace: "span_payment_lost"
+      expected_problem: "Payment service error not correlated with order trace"
+      solution: "Add middleware to always propagate X-Correlation-ID"
+
+assertions:
+  - type: "api_called"
+    description: "Correlation ID propagated to all services"
+    test: "X-Correlation-ID passed through service chain"
+
+  - type: "api_called"
+    description: "Trace IDs captured in logs"
+    test: "all log entries include trace_id"
+
+  - type: "outcome"
+    description: "Error path visible in distributed trace"
+    test: "trace shows which service failed and why"
+
+  - type: "api_called"
+    description: "Timing data collected per service"
+    test: "trace includes duration for each span"
+
+  - type: "outcome"
+    description: "Root cause identifiable from trace"
+    test: "cascading_failure_visible_in_trace shows error progression"
+
+learning_objectives:
+  - "Understand importance of correlation IDs in microservices"
+  - "Implement trace ID propagation across service calls"
+  - "Collect span timing for performance analysis"
+  - "Correlate logs across multiple services"
+  - "Identify root cause from distributed traces"
+  - "Detect cascading failures in real-time"
+  - "Perform effective post-mortem analysis"
+
+correlation_headers:
+  "X-Correlation-ID": "Unique ID for entire request"
+  "X-Request-ID": "Specific request identifier"
+  "X-Trace-ID": "OpenTelemetry trace ID"
+  "X-Span-ID": "OpenTelemetry span ID"
+  "X-Parent-Span-ID": "Parent span for nesting"
+
+trace_structure:
+  "trace_id": "abc123def456"
+  "spans":
+    - "span_id": "span_order_1"
+      "operation": "create_order"
+      "service": "order_service"
+      "start_time": "2024-01-01T10:00:00.000Z"
+      "duration_ms": 50
+      "status": "OK"
+      "child_spans": ["span_payment_1", "span_shipping_1"]
+    - "span_id": "span_payment_1"
+      "operation": "charge_card"
+      "service": "payment_service"
+      "start_time": "2024-01-01T10:00:00.050Z"
+      "duration_ms": 200
+      "status": "OK"
+      "parent_span": "span_order_1"
+
+tools:
+  "OpenTelemetry": "Standard instrumentation library"
+  "Jaeger": "Distributed tracing backend"
+  "Zipkin": "Alternative tracing system"
+  "Datadog APM": "Commercial observability"
+  "AWS X-Ray": "AWS distributed tracing"
+  "Google Cloud Trace": "GCP tracing"
+
+common_mistakes:
+  - "Not propagating correlation ID to called services"
+  - "No trace ID in error messages"
+  - "Losing context in async operations"
+  - "Not collecting timing data"
+  - "Insufficient log detail for debugging"
+  - "No central trace storage"
+  - "Can't query traces by error type"
+
+post_mortem_example: |
+  Timeline:
+  10:00:00 - Order received (trace_abc)
+  10:00:00 - Order created in order_service (50ms)
+  10:00:00 - Payment service called
+  10:00:25 - Payment timeout after 25 seconds
+  10:00:25 - Shipping service never called
+  10:00:25 - 502 Bad Gateway returned
+
+  Trace shows: Payment service database locked
+  Root cause: Concurrent deployment and query
+  Fix: Add connection pooling, query timeout
+
+  Prevention: Monitor query latency in traces

package/courses/aws-lambda-debugging/course.yaml

@@ -0,0 +1,11 @@
+id: aws-lambda-debugging
+name: "AWS Lambda Function Debugging"
+description: >
+  Master AWS Lambda function debugging from basic invocation errors to
+  enterprise serverless platform operations. Learn to diagnose cold starts,
+  timeout issues, permission failures, memory problems, event source mapping
+  errors, layer conflicts, VPC connectivity, Step Functions orchestration,
+  and production serverless operations at scale.
+levels: 5
+scenarios_per_level: 10
+tags: [development, AWS, Lambda, serverless, debugging, cloud, FaaS, event-driven]