Spoofy

Your staging environment is a ghost town. Spoofy fixes that.

Point it at an OpenAPI spec. It generates continuous, production-shaped traffic
so your dashboards have signal and your alert thresholds can be tuned
against something other than a flat line.

The problem

You built a Grafana dashboard for staging. It's empty. You wrote an alert rule. You can't tell if it works without deliberately breaking something, so you click around by hand until a graph twitches.

Load testing tools don't help here. k6 and Vegeta answer "can it handle 10k RPS", a question you ask occasionally. Spoofy answers "does this environment look alive", which is a condition you want permanently true.

spoofy run --url https://staging.acme.com --rate 20/s --shape diurnal

It runs until you stop it.

Quickstart

go install github.com/ashdaily/spoofy/cmd/spoofy@latest

With an openapi.yaml in the current directory:

spoofy run --url http://localhost:8080

Spoofy discovers the spec, exercises every read endpoint, and serves its own metrics at :9090/metrics.

spoofy run --url http://localhost:8080 --dry-run

GET /pets/{petId}

curl -i -X GET \
  -H "Accept: application/json" \
  -H "User-Agent: spoofy" \
  "http://localhost:8080/pets/6f1a9c2e-0b3d-4f8a-91c7-2d5e8a4b0f13"

See it work

git clone https://github.com/ashdaily/spoofy && cd spoofy
docker compose up

Then open http://localhost:3000. A demo API, Spoofy, Prometheus, and Grafana with the dashboard already loaded. Nothing to configure.

The demo API has varied latency, one slow endpoint, and a 2% error rate, so the dashboard has something on it. A target that always returns 200 in 1ms does not teach you anything about your monitoring.

How it works

flowchart LR
    SPEC["OpenAPI spec<br/>file or URL"] --> OPS["Operations"]
    OPS --> SEL{"Filter"}
    SEL -->|"reads, by default"| PICK["Weighted pick"]
    SEL -.->|"writes, opt in"| PICK

    SHAPE["Traffic shape<br/>constant · diurnal<br/>ramp · spike"] --> PACE["Rate limiter"]
    PACE --> PICK

    PICK --> GEN["Build request<br/>params · body · auth"]
    GEN --> SEND["Send"]
    SEND --> TGT[("Your API")]
    SEND --> MET["Prometheus<br/>/metrics"]
    SEND --> TUI["Live view"]

    classDef input fill:#dbeafe,stroke:#2563eb,color:#0f172a
    classDef target fill:#f3e8ff,stroke:#9333ea,color:#0f172a
    classDef output fill:#dcfce7,stroke:#16a34a,color:#0f172a

    class SPEC,SHAPE input
    class TGT target
    class MET,TUI output

Values come from the spec before they come from a random number generator:

example → examples → default → const → enum → format → pattern → type

Syntactically valid nonsense produces an environment full of 400s, where the dashboards look busy and prove nothing. Spec examples are real values written by someone who knows the API, so they take precedence. pattern gets a small regex engine, since the fields specs constrain that way (SKUs, account numbers, postcodes) are the ones where a random string is rejected outright.

Traffic shapes

rate is always the average. Changing shape redistributes traffic without changing the total, so you can try shapes without recalculating anything.

traffic:
  rate: 20/s
  shape: diurnal

diurnal is aligned to wall-clock time of day rather than process start, so restarting at 3pm resumes at afternoon levels instead of putting a cliff in the graph that reads as an incident.

Each shape takes a few parameters of its own. See traffic in the configuration reference below.

Configuration

Spoofy runs entirely from flags. A config file is optional, and useful once you want endpoint weights, auth, or settings you'd rather commit than retype.

spoofy init            # writes spoofy.yaml
spoofy run             # picks it up automatically

Flags override the file, so you can keep a committed baseline and vary one thing on the command line.

A complete file

Every key Spoofy understands, in one place. Only target and spec are required; the rest are shown at their defaults.

target: https://staging.acme.com
spec: ./openapi.yaml

traffic:
  rate: 10/s
  shape: constant
  concurrency: 10
  timeout: 10s

  # diurnal only
  amplitude: 0.6
  period: 24h

  # ramp only
  from: 5/s
  to: 50/s
  over: 30m

  # spike only
  spike_every: 30m
  spike_for: 2m
  spike_rate: 100/s

endpoints:
  - match: /admin/*
    skip: true
  - match: /orders
    weight: 5

auth:
  bearer: ${API_TOKEN}
  basic:
    user: ${API_USER}
    pass: ${API_PASS}
  headers:
    X-Tenant: acme

safety:
  allow_writes: false
  allow_prod: false
  max_rate: 200/s

metrics:
  addr: ":9090"
  disabled: false

Value formats

Unknown keys are rejected at startup rather than ignored, so a typo fails immediately instead of quietly changing nothing.

Reference

Top level

traffic

endpoints

A list of rules matched against templated paths such as /orders/{id}. Rules are checked in order and the first match wins, like a routing table.

auth

Applied to every generated request. Explicit headers are set last, so they win over anything else.

safety

metrics

Examples

target: http://localhost:8080
spec: ./openapi.yaml

target: https://staging.acme.com/v1
spec: https://staging.acme.com/v1/openapi.json

traffic:
  rate: 25/s
  shape: diurnal
  amplitude: 0.7          # quiet nights, busy afternoons
  concurrency: 16

endpoints:
  - match: /health
    skip: true
  - match: /admin/*
    skip: true
  - match: /products
    weight: 10
  - match: /products/{id}
    weight: 4
  - match: /cart
    weight: 2

auth:
  bearer: ${STAGING_TOKEN}

target: http://localhost:8080
spec: ./openapi.yaml

traffic:
  rate: 5/s
  shape: spike
  spike_every: 10m
  spike_for: 90s
  spike_rate: 150/s
  concurrency: 32

safety:
  max_rate: 200/s         # spike_rate is checked against this

target: http://localhost:8080
spec: ./openapi.yaml

traffic:
  shape: ramp
  from: 5/s
  to: 120/s
  over: 30m
  concurrency: 64

safety:
  max_rate: 200/s

target: http://localhost:8080
spec: ./openapi.yaml

traffic:
  rate: 8/s
  shape: constant

endpoints:
  - match: /admin/*
    skip: true
  - match: /*/purge
    skip: true
  - match: /users/{id}      # no DELETE against real user records
    skip: true
  - match: /orders
    weight: 3

safety:
  allow_writes: true

target: https://gateway.internal/api
spec: ./specs/orders-v2.yaml

traffic:
  rate: 1200/m            # same as 20/s, written the way the team says it
  shape: diurnal

auth:
  headers:
    X-Api-Key: ${GATEWAY_KEY}
    X-Tenant-Id: ${TENANT_ID}
    X-Trace-Sampling: always

metrics:
  addr: ":9464"           # matches the OTel collector convention here

Flags

--url, -u             target base URL
--spec, -s            OpenAPI spec: path or URL (default: discovered)
--config, -c          config file (default: spoofy.yaml if present)
--rate, -r            average rate: 20/s, 1200/m, 72000/h
--shape               constant | diurnal | ramp | spike
--concurrency         requests in flight at once
--timeout             per-request timeout
--duration            stop after this long (default: run forever)
--only / --skip       path globs; * spans /
--allow-writes        exercise POST/PUT/PATCH/DELETE
--allow-prod          permit a production-looking hostname
--dry-run             print requests as curl, send nothing
--seed                reproducible runs
--auth-bearer         bearer token
--auth-basic          user:pass
--header              extra header, repeatable
--metrics-addr        Prometheus listen address (default :9090)
--startup-timeout     how long to wait for a remote spec

Safety

Spoofy runs unattended for weeks, so a bad default costs a month rather than one run. These defaults refuse rather than surprise.

Spoofy also states what it is not doing, so a filtered-down run cannot pass for a healthy one:

endpoints 5 of 8, skipped 3 writes (use --allow-writes)

Metrics

Served at :9090/metrics, plus /healthz for probes.

path is always the templated form (/pets/{petId}), never the concrete URL. Labelling on concrete URLs adds a time series per id and takes Prometheus down within a day.

Compare what Spoofy sent against what your app reports receiving. A gap between the two is a real finding: dropped requests, broken instrumentation, or a misconfigured scrape. It makes Spoofy a way to check your observability stack rather than just populate it.

Deploying

docker run --rm ghcr.io/ashdaily/spoofy:latest run \
  --spec http://api:8080/openapi.json \
  --url http://api:8080 \
  --rate 20/s --shape diurnal

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spoofy
spec:
  replicas: 1
  selector:
    matchLabels: { app: spoofy }
  template:
    metadata:
      labels: { app: spoofy }
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9090"
    spec:
      containers:
        - name: spoofy
          image: ghcr.io/ashdaily/spoofy:latest
          args:
            - run
            - --spec=http://my-api/openapi.json
            - --url=http://my-api
            - --rate=20/s
            - --shape=diurnal
          ports:
            - { name: metrics, containerPort: 9090 }
          livenessProbe:
            httpGet: { path: /healthz, port: 9090 }
          resources:
            requests: { cpu: 50m, memory: 32Mi }
            limits:   { cpu: 500m, memory: 128Mi }

What Spoofy is not

Worth knowing before you adopt it.

• Not a load tester. Built for realism at a modest rate, not throughput records. Use k6 or Vegeta for "can it handle 10k RPS".
• It cannot manufacture 5xx. Spoofy is a client. It can reliably drive volume, latency, 4xx rates, and traffic mix. Genuine server errors need your app's own fault injection or a service mesh fault filter.
• It does not assert correctness. It reports what happened; it does not decide whether your API is right. See the roadmap.
• OpenAPI 3.x only. Swagger 2.0 is not supported yet.

Roadmap

• Stateful scenarios. POST /login → token → POST /orders → id → GET /orders/{id}. Without this, generated traffic against resource endpoints is largely 404s. This is the big one.
• Alert exercising. Drive traffic until a named Prometheus alert fires, assert it fired, stop, assert it resolved.
• Response validation as a metric, surfacing spec violations without turning Spoofy into a test runner.
• gRPC and GraphQL.

Contributing

make test      # unit + integration, race detector on
make lint      # gofmt + go vet
make run       # against the bundled demo API
make demo      # the full compose stack

Issues and PRs welcome. If you're adding a traffic shape, it needs a test that drives it with an injected clock, so a 24-hour cycle is verifiable in microseconds rather than 24 hours.

License

Apache-2.0. See LICENSE.