Crate varnish

source ·
Expand description

§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 at least varnish-rs (this crate), and maybe varnish-sys if you use Varnish internals directly.

[build-dependencies]
varnish = "0.0.19"

[dependencies]
varnish = "0.0.19"

§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.

# we need a comment at the top, possibly describing the license
$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
  • vsc
    Access Varnish statistics

Macros§

  • boilerplate
    Convenience macro to include the generate boilerplate code.
  • vtc
    Automate VTC testing

Functions§