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§
- Access Varnish statistics
Macros§
- Convenience macro to include the generate boilerplate code.
- Automate VTC testing
Functions§
- Process the
vmod.vcc
file into the boilerplate code