fastly-fiddle

Files (7)

• SKILL.md
• robots.json · examples/
• api.md · references/
• falco-vs-fiddle.md · references/
• spec-shape.md · references/
• test-dsl.md · references/
• run-fiddle.sh · scripts/

SKILL.md (first lines)

# Fastly Fiddle — Real-Edge VCL Testing

## Trigger and scope

Trigger on: Fastly Fiddle, fiddle.fastly.dev URLs, the Fiddle HTTP API, CI testing of VCL services, real-edge VCL tests, shareable VCL reproductions, `clientFetch.*`/`events.*`/`originFetches.*` test expressions, `.test.js` / Mocha specs that target fiddles, SSE `updateResult` / `waitingForSync` events, remote VCL linting via Fiddle, or validating real Fastly behavior (geo, WAF, ESI, clustering, shielding) that local tools cannot simulate.

Do NOT use for: local VCL unit testing (use `falco`), fast TDD loops (Fiddle has a 10-20s edge-sync floor per publish), Fastly Compute/Wasm testing (use `viceroy` or `fastlike`), production service deployment (use `fastly-cli`), or anything requiring authenticated Fastly API access — Fiddle does not use your Fastly API key.

Fastly Fiddle is a web-based sandbox at <https://fiddle.fastly.dev> that compiles and runs VCL on real Fastly edge nodes. Because it uses the production VCL compiler and real POPs, it's the only way outside a real service to test VCL features that depend on edge infrastructure — geolocation data, WAF, ESI, clustering, shielding, rate limiting, real TLS, and real cache behavior.

**Official UI**: <https://fiddle.fastly.dev>
**Demo CI runner**: <https://github.com/fastly/demo-fiddle-ci>
**API base**: `https://fiddle.fastly.dev` (undocumented but stable; no auth required for public fiddles)

## Prerequisites and public uploads

The helper requires Bash, `curl` 7.76 or newer, `jq`, and network access to `fiddle.fastly.dev`.
If a tool is missing, name it and provide installation guidance before running the helper.

Creating or updating a fiddle uploads its VCL, origins, request headers, request bodies, and tests to a public service, including with `--lint-only`.
Only publish when the user has authorized a public Fiddle upload or shareable reproduction.
For a request limited to local testing, use Falco and keep the spec local.
Never include credentials or private project data in a fiddle.

Set `FIDDLE_SKILL_DIR` to the absolute directory containing this `SKILL.md`, using the installed skill location supplied by the client:

```bash
FIDDLE_SKILL_DIR=/absolute/path/to/fastly-fiddle
```

This is a variable you assign, not a client-provided environment variable.
Keep the user's project as the working directory so inputs such as `fiddle.json` and `spec.json` remain project-relative.
Bundled scripts and examples use `FIDDLE_SKILL_DIR` instead.

## When Fiddle, when Falco

| Need                                                  | Use                                |
| ----------------------------------------------------- | ---------------------------------- |
| Fast local iteration (< 1s), watch mode, offline      | `falco test`                       |
| Real Fastly VCL compiler and semantics                | Fiddle                             |
| Real `client.geo.*`, WAF, ESI, rate limiting, shield  | Fiddle                             |
| Shareable URL for bug repros and support tickets      | Fiddle                             |
| CI against real edge nodes                            | Fiddle                             |
| Structured lint with line/col (no execution required) | Either                             |
| Fastly Compute (WASM)                                 | Neither — use `viceroy`/`fastlike` |

Common workflow: iterate locally with `falco test` for speed, then push edge cases to Fiddle when you need real Fastly behavior or a shareable link. See [falco-vs-fiddle.md](references/falco-vs-fiddle.md) for full trade-offs.

## Workflow: deliverable first, then the cheapest check that answers your question

Two rules keep you out of the slow path, which is what wastes time and gets
agents killed by a wall-clock limit:

1. **If your job is to produce a spec file, write it to disk first**, before
   any network call. The file is the deliverable — it must exist even if a
   later publish stalls on a cold edge-sync. Don't build the spec only inside
   a `curl --data` argument and lose it when the call blocks.

2. **Match the check to the question.** "Does this VCL compile / is the spec
   shape accepted?" is answered by a _single_ `POST /fiddle` reading `valid` —
   ~1-3s, no execution, no edge-sync wait (see gotcha #5). You only need the
   full publish → execute → SSE round trip when you must observe _runtime_
   assertion results (actual `clientFetch`/`originFetches`/`events` values),
   and that pays the 10-120s edge-sync floor per publish. **Executing is the
   exception, not the default** — reach for it deliberately, and always bound
   your wait; never block indefinitely on the stream.

### Lint-only (the common case): compile check, no execution

```bash
bash "$FIDDLE_SKILL_DIR/scripts/run-fiddle.sh" --lint-only fiddle.json
# {fiddle_id, url, valid, lintStatus}. Exit 0 = compiles, 2 = lint error
# (details on stderr). No /execute, no SSE, no edge-sync wait.
```

The raw equivalent is one call — POST and read `valid`:

```bash
UA='fiddle-skill-example/1.0'
curl -sS --max-time 30 -X POST https://fiddle.fastly.dev/fiddle \
  -H 'Content-Type: application/json' -H "User-Agent: $UA" \
  --data @fiddle.json | jq '{valid, lintStatus}'   # valid==true ⇒ it compiles
```

### Full round trip (only when you need runtime results)

When you genuinely need to see assertions pass/fail on the edge, the bundled
helper handles publish → execute → SSE → completion-detection in one call,
with a bounded `--max-wait` (default 180s per attempt) so it can't hang:

```bash
bash "$FIDDLE_SKILL_DIR/scripts/run-fiddle.sh" "$FIDDLE_SKILL_DIR/examples/robots.json"
# Prints fiddle URL, then pass/fail JSON per assertion (including body_preview
# and status by default). Exits non-zero on failure. Pass --no-bodies for
# compact output.

# Iterate against an already-published fiddle without paying edge-sync again:
bash "$FIDDLE_SKILL_DIR/scripts/run-fiddle.sh" --id <fiddle-id>           # re-execute (warmest, ~2s)
bash "$FIDDLE_SKILL_DIR/scripts/run-fiddle.sh" --id <fiddle-id> spec.json # PUT then execute
```

The equivalent raw-curl flow, for reference or when the helper isn't available:

```bash
UA='fiddle-skill-example/1.0'

# 1. Create. Capture the ID and the validity flag.
RESP=$(curl -sS -X POST https://fiddle.fastly.dev/fiddle \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H "User-Agent: $UA" \
  --data '{
    "origins": ["https://http-me.fastly.dev"],
    "vcl": {
      "init": "# Synthetic robots.txt response\n# via error restart pattern",
      "recv": "if (req.url.path == \"/robots.txt\") {\n  error 601;\n}",
      "error": "if (obj.status == 601) {\n  set obj.status = 200;\n  synthetic {\"User-agent: BadBot\"};\n  return(deliver);\n}"
    },
    "requests": [
      { "path": "/robots.txt",

From fastly/fastly-agent-toolkit, MIT.

More from fastly/fastly-agent-toolkit