README
¶
Fastly VCL developer tool
Disclaimer
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.
Motivation
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.
Installation
Download binary from releases page according to your platform and place it under the $PATH, or you can install via Homebrew:
$ brew install falco
You can compile this project by yourself with go install github.com/ysugimoto/falco/cmd/falco@latest.
Usage
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.vcl
falco provides some useful features for developing Fastly VCL.
Linter
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.
Formatter
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.
Local Simulator / VCL Debugger
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.
VCL Unit Testing
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.
Console
Falco supports simple terminal console to evaluate line input. You can confirm behavior without actual VCL file.
See console documentation in detail.
Terraform Support
falco supports to run features for terraform planned result of Fastly Provider.
See terraform.md in detail.
GitHub Actions Support
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.
Transforming
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.
Contribution
- Fork this repository
- Customize / Fix problem
- Send PR :-)
- Or feel free to create issues for us. We'll look into it
License
MIT License
Contributors
Credits / Thanks
Logo created by @studiomohawk
Directories