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:

.
├── Cargo.lock       # This code is a cdylib, so you should lock and track dependencies
├── Cargo.toml       # Add varnish as a dependency here
├── README.md        # This file can be auto-generated/updated by the Varnish macro
├── src
│   └── lib.rs       # Your main code that uses  #[vmod(docs = "README.md")]
└── tests
    └── test01.vtc   # Your VTC tests, executed with  run_vtc_tests!("tests/*.vtc") in lib.rs

§Cargo.toml

[dependencies]
varnish = "0.2.0"

§src/lib.rs

// Run all matching tests as part of `cargo test` using varnishtest utility. Fails if no tests are found.
// Due to some limitations, make sure to run `cargo build` before `cargo test`
varnish::run_vtc_tests!("tests/*.vtc");

/// A VMOD must have one module tagged with `#[varnish::vmod]`.  All public functions in this module
/// will be exported as Varnish VMOD functions.  The name of the module will be the name of the VMOD.
/// Use `#[varnish::vmod(docs = "README.md")]` to auto-generate a `README.md` file from the doc comments.
#[varnish::vmod]
mod hello_world {
    /// This function becomes available in VCL as `hello_world.is_even`
    pub fn is_even(n: i64) -> bool {
        n % 2 == 0
    }
}

§tests/test01.vtc

This test will check that the is_even function works as expected. Make sure to run cargo build before cargo test.

server s1 {
    rxreq
    expect req.http.even == "true"
    txresp
} -start

varnish v1 -vcl+backend {
    import hello_world from "${vmod}";

    sub vcl_recv {
        set req.http.even = hello_world.is_even(8);
    }
} -start

client c1 {
    txreq
    rxresp
    expect resp.status == 200

Modules§

Macros§

Attribute Macros§

  • Handle the #[vmod] attribute. This attribute can only be applied to a module. Inside the module, it handles the following items: