Module varnish::vcl::convert

source ·
Expand description

Convert Rust types into their VCL_* equivalent, and back

§Type conversion

To allow for easier development the generated boilerplate will handle conversion between the lightly disguised C types used by vmod.vcc into regular Rust, and it will also do the opposite conversion when it is time to send the return value to Varnish.

The two traits IntoVCL and IntoRust take care of this, with IntoVCL being notable in that it requires a &mut crate::vcl::ws::WS to possibly store the returned value into the task request. This allows vmod writes to just return easy-to-work-with Strings and let the boilerplate handle the allocation, copy and error handling.

If one wants to handle things manually, all VCL_* types implement IntoVCL as a no-op. It can be useful to avoid extra memory allocations by the boilerplate, if that is a worry.

Here’s a table of the type correspondences:

RustdirectionVCL
f64<->VCL_REAL
i64<->VCL_INT
i64<->VCL_BYTES
bool<->VCL_BOOL
std::time::Duration<->VCL_DURATION
()<->VOID
&str<->VCL_STRING
String->VCL_STRING
Option<COWProbe><->VCL_PROBE
Option<Probe><->VCL_PROBE
Option<std::net::SockAdd>->VCL_IP

For all the other types, which are pointers, you will need to use the native types.

Note: It is possible to simply return a VCL_* type (or a Result<VCL_*, _>), in which case the boilerplate will just skip the conversion.

§Result

It’s possible for a vmod writer to return a bare value, or a Result<_, E: AsRef<str>> to potentially abort VCL processing in case the vmod hit an unrecoverable error.

If a vmod function returns Err(msg), the boilerplat will log msg, marke the current task as failed and will return a default value to the VCL. In turn, the VCL will stop its processing and will create a synthetic error object.

Traits§