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§
- Run all VTC tests using
varnishtest
utility.
Attribute Macros§
- Handle the
#[vmod]
attribute. This attribute can only be applied to a module. Inside the module, it handles the following items: