Crate varnish

Varnish bindings

This module provides access to various Varnish facilities, notably those needed to create pure-rust vmods (check out examples here). Note that it doesn’t aim to be a 1-to-1 mirror of the C API, as Rust allows for better ergonomics than what the C code can provide (notably around strings and buffer handling).

WARNING: This crate is pre-1.0 and under active development so expect things to move around. There’s also a lot of unsafe code and a few “shortcuts” that will be cleaned later on. In short: see this as a tech-preview, and don’t run it in production.

Building a VMOD

The main idea for this crate is to make the building framework as light as possible for the vmod writer, here’s a checklist, but you can also just check the source code.

The general structure of your code should look like this:

.
├── build.rs
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│   └── lib.rs
├── tests
│   └── test01.vtc
└── vmod.vcc

Cargo.toml

You will need both varnish-rs (this crate), but also varnish-sys to build the vmod as the boilerplate code uses it.

[build-dependencies]
varnish = "0.0.4"

[dependencies]
varnish = "0.0.4"
varnish-sys = "0.0.4"

vmod.vcc

You will need a vmod.vcc alongside your Cargo.toml. This file describes your vmod’s API and how it’ll be accessible from VCL.

The good news is that the syntax is exactly the same as for a C vmod. The bad news is that we don’t support all types and niceties just yet. Check out the crate::vcl::convert page for more information.

$Module example 3 "An example vmod"

$Function BOOL is_even(INT)

build.rs

The vmod.vcc file needs to be processed into rust-code so the module is loadable by Varnish. This steps is currently done via a python script triggered by the build.rs file (also alongside Cargo.toml). The nitty-gritty details have been hidden away and you can have a fairly simple file:

fn main() {
    varnish::generate_boilerplate().unwrap();
}

src/lib.rs

Here’s the actual code that you can write to implement your API. Basically, you need to implement public functions that mirror what you described in vmod.vcc, and the first argument needs to be a reference to crate::vcl::ctx::Ctx:

varnish::boilerplate!();

use varnish::vcl::ctx::Ctx;

pub fn is_even(_: &Ctx, n: i64) -> bool {
    return n % 2 == 0;
}

The various type translations are described in detail in crate::vcl::convert.

Modules

vcl

Macros

boilerplate

Convenience macro to include the generate boilerplate code.

vtc

Automate VTC testing

Functions

generate_boilerplate

Process the vmod.vcc file into the boilerplate code