fastlike

Files (8)

• SKILL.md
• abi.md · references/
• backends.md · references/
• build.md · references/
• config.md · references/
• profiling.md · references/
• test.md · references/
• understanding-compute-from-source.md · references/

SKILL.md (first lines)

## Trigger and scope

Trigger on: Fastly Compute, Compute@Edge, WASM on Fastly, fastlike, XQD ABI, Compute request lifecycle, 508 loop detection, backend subrequests, body streaming, profiling a local Compute app, embedding a Fastly Compute runtime in Go code, or any question about how Compute platform primitives work internally (caching, KV stores, edge rate limiting, ACLs, geolocation, secret stores, config stores, dictionaries, logging, dynamic backends, request collapsing, async I/O).

Do NOT use for: Fastly VCL (use falco), Fastly CLI/API (use fastly-cli or fastly), Viceroy, CDN comparison, WAF, Terraform, cache purging via API, or Fastly logging/stats configuration.

# Fastlike — Local Compute Runtime & Reference

Fastlike is a Go implementation of the Fastly Compute ABI. It runs compiled WebAssembly programs locally, implementing the same 249+ host functions that Fastly's production Compute platform provides: backends, dictionaries, KV stores, caching, geolocation, rate limiting, ACLs, secret stores, and more.

Equally important, **the fastlike source code is the most complete programmatic specification of how Fastly Compute works** — its ABI implementations document every platform primitive, request lifecycle detail, and data structure as executable code.

**Fastlike documentation**: https://github.com/avidal/fastlike

## Source Code as Compute Reference

When you have access to the fastlike source code locally (default: `~/src/fastlike`), use these paths to answer specific Compute questions:

| Question                                                    | Read This File                                       | Why                                                             |
| ----------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
| "How does the request lifecycle work?"                      | `instance.go`, `xqd_http_downstream.go`              | Per-request setup, execution, downstream handling               |
| "What ABI functions exist for X?"                           | `xqd_*.go` files                                     | Each file implements a group of related ABI functions           |
| "How do backend subrequests work?"                          | `xqd_backend.go`, `backend.go`                       | Request sending, dynamic backends, timeouts                     |
| "How does caching work?"                                    | `xqd_cache.go`, `xqd_http_cache.go`, `cache.go`      | Cache operations, Vary, surrogate keys, request collapsing      |
| "How does KV store work?"                                   | `xqd_kv_store.go`, `kv_store.go`                     | CRUD operations, pagination, generation-based concurrency       |
| "How does rate limiting work?"                              | `xqd_erl.go`, `erl.go`                               | Rate counters, penalty boxes, threshold checks                  |
| "How do ACLs work?"                                         | `xqd_acl.go`, `acl.go`                               | CIDR-based IP filtering, most-specific match                    |
| "What configuration options exist?"                         | `options.go`                                         | Every `With*` functional option for the runtime                 |
| "What error codes can operations return?"                   | `constants.go`                                       | All XQD status codes and error types                            |
| "How does the profiler work / what does a trace look like?" | `profile.go`, `profile_json.go`, `docs/profiling.md` | Trace data model, JSON wire format, deep-mode metrics, encoders |

For a comprehensive guide, see [understanding-compute-from-source.md](references/understanding-compute-from-source.md).

## Install from Source

Requires Go 1.24+.

```bash
# Clone and build
git clone https://github.com/avidal/fastlike.git ~/src/fastlike
cd ~/src/fastlike
make build        # Creates bin/fastlike

# Or install to GOPATH/bin
make install

# Or install directly
go install fastlike.dev/cmd/fastlike@latest
```

## Quick Start

The `bin/fastlike` examples use a source build.
Use its absolute path from your project directory, or `fastlike` for an installed binary.

```bash
# Minimal: WASM + single backend. The wasm path is positional.
bin/fastlike -backend localhost:8000 app.wasm
```

Flags can appear on either side of the wasm path.

On macOS, avoid binding to port 5000 — the AirTunes/AirPlay Receiver listens there by default and will steal the connection. Pick another port (e.g. `-bind localhost:8000`) or disable the AirPlay Receiver in System Settings.

## Fastlike vs Viceroy

| Feature        | Fastlike                     | Viceroy                                   |
| -------------- | ---------------------------- | ----------------------------------------- |
| Language       | Go                           | Rust                                      |
| Geolocation    | Custom JSON file (`-geo`)    | Built-in defaults                         |
| Hot reload     | SIGHUP (`-reload`)           | Restart required                          |
| Install        | `go install` or `make build` | `cargo install` or `fastly compute serve` |
| Local backends | `-backend name=host:port`    | `[local_server.backends]` in fastly.toml  |

**When to use Fastlike**: Non-Rust Compute apps, want custom geo data, need hot reload, debugging.
**When to use Viceroy**: Rust Compute apps with cargo-nextest, Component Model projects, using `fastly compute serve`.

## Common Configurations

**With named backends:**

```bash
bin/fastlike \
  -backend api=api.example.com:8080 \
  -backend cache=redis:6379 \
  -backend localhost:8000 \
  app.wasm
```

**Development mode with hot-reload:**

```bash
bin/fastlike -backend localhost:8000 -reload -v 2 app.wasm
```

Send `SIGHUP` to reload the WASM without restarting.

**With the built-in profiler:**

```bash
bin/fastlike -backend localhost:8000 -profile-ui localhost:6060 app.wasm
```

Open `http://localhost:6060/` for the trace index. Each request lands as `/r/{id}` (HTML) or `/r/{id}.json` (canonical native JSON; also `.chrome.json`, `.firefox.json`, `.pprof`). Add `-profile deep` for body byte / cache outcome / header / wasm heap metrics. Non-loopback `-profile-ui` requires `-profile-auth TOKEN` (or explicit `-profile-insecure-ui`). See [profiling.md](references/profiling.md).

**Full configuration:**

```bash
bin/fastlike \
  -bind 0.0.0.0:5000 \
  -backend localhost:8000 \
  -dictionary config=./config.json \
  -kv store=./data.json \
  -config-store settings=./settings.json \
  -secret-store secrets=./secrets.json \
  -acl blocklist=./acl.json \
  -logger output=./logs.txt \
  -geo ./geodata.json \
  -compliance-region us-eu \

From fastly/fastly-agent-toolkit, MIT.

More from fastly/fastly-agent-toolkit