Fastly VCL developer tool
This is a VCL parser, but dedicated to Fastly's VCL (version 2.x), so we don't care about the latest Varnish (7.x or later) syntax. The Varnish may have additional syntax, builtin function, predefined variables, but this tool may not parse correctly.
Additionally, Fastly provides its special builtin function, predefined variables. It's not compatible with Varnish. But this tool is optimized for them, we could parse and lint/execute their declarations.
Fastly is a really fantastic CDN, but sometimes we have problems with deployment operations. On deploy custom VCL to the Fastly, VCLs are validated when activating a new service version. Typically our deployment flow using custom VCLs is following:
- Clone active service and create new version
- Delete existing custom VCLs
- Upload new VCL files to the Fastly
- Activate new device version <= Validate VCLs on the Fastly cloud
Above flows take a time, and then if we have some mistakes on VCL e.g. missing semicolon X(, the deployment will fail. Additionally, unnecessary service versions will be created by our trivial issue.
To solve them, we made a Fastly dedicated tool to develop custom VCLs locally.
Download binary from releases page according to your platform and place it under the $PATH, or you can install via Homebrew:
$ brew install falcoYou can compile this project by yourself with go install github.com/ysugimoto/falco/cmd/falco@latest.
Command help displays following:
falco -h
=========================================================
____ __
/ __/______ / /_____ ____
/ /_ / __ // // __// __ \
/ __// /_/ // // /__ / /_/ /
/_/ \____//_/ \___/ \____/ Fastly VCL developer tool
=========================================================
Usage:
falco [subcommand] [flags] [main vcl file]
Subcommands:
lint : Run lint (default)
terraform : Run lint from terraform planned JSON
stats : Analyze VCL statistics
simulate : Run simulator server with provided VCLs
test : Run local testing for provided VCLs
console : Run terminal console
fmt : Run formatter for provided VCLs
See subcommands help with:
falco [subcommand] -h
Common Flags:
-I, --include_path : Add include path
-h, --help : Show this help
-r, --remote : Connect with Fastly API
-V, --version : Display build version
-v : Output lint warnings (verbose)
-vv : Output all lint results (very verbose)
-json : Output results as JSON (very verbose)
Simple linting example:
falco -I . -vv /path/to/vcl/main.vclfalco provides some useful features for developing Fastly VCL.
The main feature, parse and run lint your VCL locally, and report problems.
falco bundles many linter rules that come from the author's operation experience, Fastly recommends,
that you improve your VCL more robustly by passing the linter.
See linter documentation in detail.
Format provided VCL by our recommended styles. Currently we have a few options to control formatting style like biomejs. Through the formatter, your VCL codes have unified format even multiple people are maintaining VCL.
See formatter documentation in detail.
falco has self-implemented interpreter for running VCL program locally.
You can simulate how your VCL behaves through the simulator.
In addition to local simulator, falco also provided VCL debugger.
You can debug your VCL step-by-step with dumping variables.
See simulator documentation in detail.
You can run unit testing through the falco runtime.
The unit testing file also can be written in VCL, and run test for each subroutine that you want individually.
See testing documentation in detail.
Falco supports simple terminal console to evaluate line input. You can confirm behavior without actual VCL file.
See console documentation in detail.
falco supports to run features for terraform planned result of Fastly Provider.
See terraform.md in detail.
To integrate falco into your GitHub Actions pipeline, e.g. for linting:
- name: Lint VCL
uses: ain/falco-github-action@v1
with:
subcommand: lint
options: "-v -I test/vcl/includes"
target: test/vcl/file_to_be_linted.vcl
See ain/falco-github-action for documentation.
falco plans to transpile Fastly VCL to the other programming language that works on the Compute@Edge, keep you posted when there is any progress.
- Fork this repository
- Customize / Fix problem
- Send PR :-)
- Or feel free to create issues for us. We'll look into it
MIT License
Logo created by @studiomohawk