Skip to content

Latest commit

 

History

History
176 lines (119 loc) · 6.16 KB

README.md

File metadata and controls

176 lines (119 loc) · 6.16 KB
Raw

Fastly VCL developer tool

Go Reference Build

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:

  1. Clone active service and create new version
  2. Delete existing custom VCLs
  3. Upload new VCL files to the Fastly
  4. 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