Scenarios

Define custom response sequences for specific paths using YAML files or the /scenario API. Scenarios cycle through predefined responses to simulate complex behaviors.

How It Works

graph TD
  A[Receive Request] --> B{Match Path}
  B -->|Scenario Found| C[Get Next Response]
  B -->|No Scenario| D[Default Echo]
  C --> E[Apply Status, Body, Headers, Delay]
  E --> F[Update Cycle Index]
  F --> G[Respond]
  D --> G

YAML Scenarios

Load scenarios from a YAML file specified by ECHO_SCENARIO_FILE (default: scenarios.yaml).

Env: ECHO_SCENARIO_FILE=/path/to/scenarios.yaml
Example YAML:

- path: /api/users
  responses:
    - status: 200
      delay: 100ms
      headers:
        Content-Type: application/json
      body: '{"users": []}'
    - status: 500
      delay: 200ms
      body: '{"error": "db failure"}'

Requests to /api/users cycle through responses (200, 500).

Scenario API

Dynamically update scenarios via /scenario endpoint.

GET: Retrieve current scenarios.
POST: Update scenarios with JSON array.
Example:

curl -X POST http://localhost:8080/scenario -H "Content-Type: application/json" -d '[
  {
    "path": "/test",
    "responses": [
      {"status": 200, "body": "OK", "delay": "100ms"},
      {"status": 429, "body": "Too Many Requests"}
    ]
  }
]'
# Response: {"status": "scenarios updated"}
curl /test  # Returns 200, then 429, cycling

Notes

Scenarios override default echo behavior for matching paths.
Responses cycle in order per path.
Invalid YAML or JSON results in HTTP 400.
Metrics track via echo_requests_total.