varnish 0.7.0

//! Safe Rust bindings for [Varnish](http://varnish-cache.org/), providing everything needed to
//! write pure-Rust VMODs. See also the
//! [examples](https://github.com/varnish-rs/varnish-rs/tree/main/examples).
//!
//! For a guide to building a VMOD — project structure, `Cargo.toml`, VTC tests — see [`vcl`].
//!
//! To read Varnish statistics from an external program, see [`MetricsReader`].

// Re-publish some varnish_sys modules
/// This module gathers the tools needed to build a vmod in `rust`.
///
/// In addition to the following primer and documentation, you can also look at the various [example vmods](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_example), each focusing on different aspects of the code.
///
/// # Building your first vmod
///
/// ## Create a new project
///
/// Start by creating a new library project:
/// ``` shell
/// cargo new --lib my_vmod
/// cd my_vmod
/// ```
///
/// The general structure of your code should look like this:
///
/// ```text
/// .
/// ├── Cargo.toml
/// └── src
///     └── lib.rs
/// ```
///
/// ## Cargo.toml
///
/// Let's add `varnish` as a dependency in `Cargo.toml`
///
/// ```toml
/// [package]
/// name = "my_vmod"
/// version = "0.1.0"
/// edition = "2024"
///
/// [dependencies]
/// varnish = "0.6.0"       # add this line
///
/// [lib]
/// crate-type = ["cdylib"] # and this line
/// ```
///
/// ## src/lib.rs
///
/// Next, we need to actually write the code. For this example, we are going to create two functions:
/// - `my_vmod.sum()` which takes two numbers and sum them
/// - `my_vmod.reverse()` which takes an optional string, and reverses it
///
/// ```rust,ignore
/// /// an example vmod
/// #[varnish::vmod(docs = "API.md")]
/// mod my_vmod {
///     /// sum two numbers
///     pub fn sum(a: i64, b: i64) -> i64 {
///         a + b
///     }
///
///     /// reverse a string, if no string is given, output a default one
///     pub fn reverse(s: Option<&str>) -> String {
///         match s {
///             Some(s) => s.chars().rev().collect(),
///             None => "no string given".into(),
///         }
///     }
/// }
///
/// #[test]
/// fn test_reverse_foo() {
///     assert_eq!(my_vmod::reverse(Some("foo")), "oof");
/// }
///
/// #[test]
/// fn test_reverse_none() {
///     assert_eq!(my_vmod::reverse(None), "no string given");
/// }
///
/// #[test]
/// fn test_sum() {
///     assert_eq!(my_vmod::sum(3, 8), 11);
/// }
/// ```
///
/// The most important bit here is the [`vmod`][macro@vmod] macro applied to the `my_vmod` module. It means that the functions inside it should be exported as vmod functions.
///
/// `varnish-rs` will automatically convert `rust` types to and from VCL ones. Wrapping a type into an [Option] makes it optional, meaning it can be ignored when calling the vmod from VCL.
///
/// Run `cargo build` to generate both the vmod file (in `./target/debug/`), and the `API.md` documentation in markdown:
///
/// ````txt
/// <!--
///
///   !!!!!!  WARNING: DO NOT EDIT THIS FILE!
///
///   This file was generated from the Varnish VMOD source code.
///   It will be automatically updated on each build.
///
/// -->
/// # Varnish Module (VMOD) `my_vmod`
///
/// an example vmod
///
/// ```vcl
/// // Place import statement at the top of your VCL file
/// // This loads vmod from a standard location
/// import my_vmod;
///
/// // Or load vmod from a specific file
/// import my_vmod from "path/to/libmy_vmod.so";
/// ```
///
/// ### Function `INT my_vmod.sum(INT a, INT b)`
///
/// sum two numbers
///
/// ### Function `STRING my_vmod.reverse([STRING s])`
///
/// reverse a string, if no string is given, output a default one
/// ````
///
/// ## VTC tests
///
/// Our `rust` code already contains unit tests, but it's good to validate that the code is properly wired and test the vmod in a full-stack tests.
///
/// For this, we use [varnishtest](https://www.varnish-software.com/developers/tutorials/testing-varnish-varnishtest/) which will start a full ephemeral Varnish server and load the VCL of our choice, before sending requests and validating the responses.
///
/// First, create a new `tests/test01.vtc` file:
///
/// ```vtc
/// varnishtest "first my_vmod test"
///
/// server s1 {
///     rxreq
///     expect req.http.reversed == "olleh"
///     txresp
/// } -start
///
/// varnish v1 -vcl+backend {
///     import my_vmod from "${vmod}";
///
///     sub vcl_recv {
///         set req.http.reversed = my_vmod.reverse("hello");
///     }
/// } -start
///
/// client c1 {
///     txreq
///     rxresp
///     expect resp.status == 200
/// } -run
/// ```
///
/// And add this line at the top of `src/lib.rs`:
/// ``` rust,no_run
/// varnish::run_vtc_tests!("tests/*.vtc");
/// ```
///
/// You can then compile the vmod, and run all the tests:
///
/// ``` txt
/// $ cargo build && cargo test
///     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s
///     Finished `test` profile [unoptimized + debuginfo] target(s) in 0.04s
///      Running unittests src/lib.rs (target/debug/deps/my_vmod-6f8d69114a407a56)
///
/// running 4 tests
/// test test_reverse_none ... ok
/// test test_reverse_foo ... ok
/// test test_sum ... ok
/// test vtc_test01 ... ok
///
/// test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 2.03s
/// ```
///
/// # Installation
///
/// The vmod file will be located in your build directory (`./target/debug/libmy_vmod.so`) by default, and you can install in the system-wide vmod directory, which you can find with `pkg-config`:
/// ```shell
/// # pkg-config --variable=vmoddir varnishapi
/// /usr/lib/varnish/vmods
/// # sudo cp ./target/debug/libmy_vmod.so /usr/lib/varnish/vmods/
/// ```
///
/// # Argument types
///
/// `varnish-rs` allows you to use native type as function arguments, and will convert them from VCL types before handling them to your code.
///
/// Here are the types you can use, and how they correspond to VCL types:
///
/// | Rust | VCL |
/// | :--: | :-:
/// | `f64`  | `VCL_REAL` |
/// | `i64`  | `VCL_INT` |
/// | `bool` | `VCL_BOOL` |
/// | `std::time::Duration` | `VCL_DURATION` |
/// | `std::time::SystemTime` | `VCL_TIME` |
/// | `&str` | `VCL_STRING` |
/// | `&[u8]` | `VCL_BLOB` |
/// | `Option<CowProbe>` | `VCL_PROBE` |
/// | `Option<Probe>` | `VCL_PROBE` |
/// | `Option<std::net::SocketAddr>` | `VCL_IP` |
/// | `Subroutine` | `VCL_SUB` |
///
/// All types can in addition be wrapped in an `Option` to make the argument optional.
///
/// **Note:** some types, like `VCL_PROBE` are nullable (they can be a `NULL` pointer in C), so `Option<Option<Probe>>` is valid, meaning your function can receive three different values:
/// - `None`: the VCL code didn't provide a `VCL_PROBE`
/// - `Some(None)`: the VCL code provided a `NULL` `VCL_PROBE`
/// - `Some(Some(probe))`: the VCL code provided a non-`NULL` `VCL_PROBE`
///
/// VCL types can also be ingested natively, at the cost of marking the function `unsafe`.
///
/// ## Context
///
/// For some operations such as logging, you may need access to the [`vcl::Ctx`] object (`vrt_ctx` in C). To do this, you can use the `ctx: &mut Ctx` which `varnish-rs` will recognize as special and handle you a `rust` proxy object.
///
/// ## Per-task shared data
///
/// Vmods routinely need to store data for the duration of a task. This can be accomplished with the `#[shared_per_task]` attribute on an argument of type `&mut Option<Box<T>>` for mutable access, or `Option<&T>` for read-only access.
///
/// All calls to the vmod functions within a same VCL task will share the same reference, with the first call pointing to `None`.
///
/// You can check [vmod_timestamp](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_timestamp) for an example:
///
/// ```rust,ignore
/// /// Returns the duration since the same function was called for the last time (in the same task).
/// /// If it's the first time it's been called, return 0.
/// pub fn timestamp(#[shared_per_task] shared: &mut Option<Box<Instant>>) -> Duration {
///     // we will need this either way
///     let now = Instant::now();
///
///     match shared {
///         None => {
///             // This is the first time we're running this function in the task's context
///             *shared = Some(Box::new(now));
///             Duration::default()
///         }
///         Some(shared) => {
///             // Update box content in-place to the new value, and get the old value
///             let old_now = mem::replace(&mut **shared, now);
///             // Since Instant implements Copy, we can continue using it and subtract the old value
///             now.duration_since(old_now)
///         }
///     }
/// }
/// ```
///
/// For relatively obvious reasons, the `#[shared_per_task]` object type must be the same across the vmod.
///
/// ## Per-VCL shared data
///
/// Similarly, some vmods need a global store, shared across all tasks. This is achieved with the `#[shared_per_vcl]` attribute which requires an `Option<&T>` type (the reference **can't** be `mut`).
///
/// Example from [vmod_event](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_event):
/// ```rust,ignore
/// /// Return the number of VCL loads stored when the event function ran.
/// pub fn loaded(#[shared_per_vcl] shared: Option<&i64>) -> i64  {
///     shared.copied().unwrap_or(0)
/// }
/// ```
///
/// If you wish to modify the value from a client or backend task, you'll need the type to be thread-safe.
///
/// ## Event function
///
/// Vmods have the ability to hook into the VCL lifetime and act when the VCL is loaded, discarded, etc. This is an opportunity to update `#[shared_per_vcl]` objects, for example, again from [vmod_event](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_event):
///
/// ```rust,ignore
/// #[event]
/// pub fn on_event(
///     ctx: &mut Ctx,
///     #[shared_per_vcl] shared: &mut Option<Box<i64>>,
///     event: Event,
/// ) -> Result<(), &'static str> {
///     // log the event, showing that it implements Debug
///     ctx.log(LogTag::Debug, format!("event: {event:?}"));
///
///     // we only care about load events, which is why we don't use `match`
///     if matches!(event, Event::Load) {
///         // increment the count in a thread-safe way
///         let last_count = super::EVENT_LOADED_COUNT.fetch_add(1, Relaxed);
///         if last_count == 1 {
///             // Demo that we can fail on the second `load` event
///             return Err("second load always fail");
///         }
///
///         // store the count, so it is accessible in the `loaded()` VCL function
///         let new_count = last_count + 1;
///         match shared {
///             None => {
///                 // This is the first time we're running this function in the VCL context
///                 *shared = Some(Box::new(new_count));
///             }
///             Some(shared) => {
///                 // Update box content in-place to the new value
///                 **shared = new_count;
///             }
///         }
///     }
///
///     Ok(())
/// }
/// ```
///
/// Note the type of the `#[shared_per_vcl]` argument here: `&mut Option<Box<i64>>`, while it was `Option<&i64>` for "regular" functions.
///
/// # Return types
///
/// Similarly, your vmod can return different types that will be translated back into VCL types before being handed back to the C code:
///
/// | Rust | VCL |
/// | :--: | :-:
/// | `()` | `VCL_VOID` |
/// | `f64`  | `VCL_REAL` |
/// | `i64`  | `VCL_INT` |
/// | `bool` | `VCL_BOOL` |
/// | `std::time::Duration` | `VCL_DURATION` |
/// | `std::time::SystemTime` | `VCL_TIME` |
/// | `&str` | `VCL_STRING` |
/// | `String` | `VCL_STRING` |
/// | `&[u8]` | `VCL_BLOB` |
/// | `Option<CowProbe>` | `VCL_PROBE` |
/// | `Option<Probe>` | `VCL_PROBE` |
/// | `Option<std::net::SocketAddr>` | `VCL_IP` |
/// | `Subroutine` | `VCL_SUB` |
///
/// You can also omit the return value entirely.
///
/// In addition, you can wrap the return value in a `Result<T, ::varnish::vcl::VclError>`, `Result<T, &'static str>` or `Result<T, String>`. Doing so and returning an `Err` will create a VCL failure that will stop the processing of the current task which is useful for unrecoverable failures.
///
/// VCL types can also be returned as-is, at the cost of marking the function `unsafe`.
///
/// # Objects
///
/// In `vcl_init{}` which runs as the VCL is loaded, vmods can create objects and define methods for them. It's an easy way to store internal data. An object is created when a constructor is called, and will live until the VCL is discarded, once no traffic requests rely on it.
///
/// See [vmod_object](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_object) for a full code example.
///
/// To expose an object, you will need to define it **outside** of the `varnish::vmod` module, and its `impl` containing only the `pub` methods **inside** of it:
///
/// ```rust,ignore
/// pub struct MyObject {
///     val: i64
/// }
///
/// #[varnish::vmod(docs = "README.md")]
/// mod object {
///     use super::MyObject;
///
///     impl MyObject {
///         pub fn new(val: i64) -> Self {
///             Self { val }
///         }
///
///         pub fn get(&self) -> i64 {
///             self.val
///         }
///     }
/// }
/// ```
///
/// Any function that returns `Self` will instantly become a constructor in the vmod. An `impl` can contain multiple constructors, and a `vmod` block can contain multiple `impl`.
///
/// # Metrics
///
/// Vmods can expose new counters to `varnishstat` (and other VSC readers) with [`Vsc`] and [`VscMetric`]. In your code, create a new struct, and tag it with `#[derive(VscMetric)]`:
///
/// ```rust,no_run
/// use std::sync::atomic::AtomicU64;
/// use varnish::VscMetric;
/// #[derive(VscMetric)]
/// #[repr(C)] // required for correct memory layout
/// pub struct VariousStats {
///     /// Some arbitrary counter
///     #[counter]
///     foo: AtomicU64,
///
///     /// Some arbitrary gauge
///     #[gauge]
///     temperature: AtomicU64,
/// }
/// ```
///
/// Three important points:
/// - the structure must also be tagged `#[repr(C)]`
/// - all fields inside it must be `AtomicU64`
/// - the code comments will be converted to metadata and exposed to the VSC readers.
///
/// You can then create, expose and modify those metrics:
///
/// ``` rust, ignore
/// let stats = Vsc::<VariousStats>::new("mystats", "default");
/// stats.foo.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
/// ```
///
/// You'll be able to see the metrics with `varnishstat`:
///
/// ```txt
/// $ varnishstat -j -f mystats.default.foo -f mystats.default.temperature
/// {
///   "version": 1,
///   "timestamp": "2026-06-11T10:42:13",
///   "counters": {
///     "mystats.default.foo": {
///       "description": "Some arbitrary counter",
///       "flag": "c",
///       "format": "i",
///       "value": 4
///     },
///     "mystats.default.temperature": {
///       "description": "Some arbitrary gauge",
///       "flag": "g",
///       "format": "i",
///       "value": 22
///     }
///   }
/// }
/// ```
///
/// See [vmod_counter](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_counters) for the full example.
///
/// # Backends and directors
///
/// See [vmod_simple_backend](https://github.com/varnish-rs/varnish-rs/tree/main/examples/vmod_simple_backend/) for a complete example of a `rust` vmod that simply send a string set at construction time.
///
/// As a C construct, [`crate::ffi::VCL_BACKEND`] can be a bit confusing to create and manipulate, notably as it
/// involves a bunch of structures with different lifetimes and quite a lot of casting. This
/// module hopes to alleviate those issues by handling the most of them and by offering a more
/// idiomatic interface centered around vmod objects.
///
/// Here's what's in the toolbox:
/// - [`vcl::Backend`]: an "actual" backend that can be used by Varnish to create an HTTP response. It
///   relies on two traits:
///   - [`vcl::VclBackend`] reports health, and generates the response headers
///   - [`vcl::VclResponse`] for the response body writer, structs implementing that trait are
///     returned by [`vcl::VclBackend::get_response`]
/// - [`vcl::NativeBackend`]: a specialization of [`vcl::Backend`], relying on the native Varnish
///   implementation providing IP and UDS backends
/// - [`vcl::NativeBackendBuilder`]: a builder to easily create a [`vcl::NativeBackend`]
/// - [`vcl::Director`]: a routing object doesn't create responses, but instead picks a [`vcl::Backend`]
///   or [`vcl::Director`] object based on the HTTP request, based on the [`vcl::VclDirector`].
/// - [`vcl::BackendRef`]: a refcounted wrapper around [`vcl::Backend`] and [`vcl::Director`], this is the primary
///   type used for arguments and returns of vmod functions.
///
///   **Important:** all these types wrap refcounted C structures that Varnish will try to free
///   when a VCL goes cold, which means you can't hold onto them forever. It's not as scary as it
///   sounds, and you can approach this in two different ways.
///
///   Use a vmod object that will own them. The object will automatically be dropped at the end of
///   the VCL lifetime, as will all its fields, and all the types above will automatically decrease
///   their refcount to the underlying C structure when this happens.
///
///   Otherwise, your vmod can implement the event function and drop the structs on a cold event.
pub use varnish_sys::vcl;

// Re-export the report_details_json macro
pub use varnish_sys::report_details_json;

#[cfg(not(feature = "ffi"))]
#[doc(hidden)]
pub mod ffi {
    // This list must match the `use_ffi_items` in generator.rs
    pub use varnish_sys::ffi::{
        vmod_data, vmod_priv, vmod_priv_methods, vrt_ctx, VMOD_ABI_Version, VclEvent, VCL_BACKEND,
        VCL_BLOB, VCL_BOOL, VCL_DURATION, VCL_INT, VCL_IP, VCL_MET_BACKEND_ERROR,
        VCL_MET_BACKEND_FETCH, VCL_MET_BACKEND_REFRESH, VCL_MET_BACKEND_RESPONSE, VCL_MET_DELIVER,
        VCL_MET_FINI, VCL_MET_HASH, VCL_MET_HIT, VCL_MET_INIT, VCL_MET_MISS, VCL_MET_PASS,
        VCL_MET_PIPE, VCL_MET_PURGE, VCL_MET_RECV, VCL_MET_SYNTH, VCL_MET_TASK_B, VCL_MET_TASK_C,
        VCL_MET_TASK_H, VCL_PROBE, VCL_REAL, VCL_STRING, VCL_SUB, VCL_TIME, VCL_VOID,
        VMOD_PRIV_METHODS_MAGIC,
    };
}

#[cfg(feature = "ffi")]
pub use varnish_sys::ffi;

pub mod varnishtest;

mod metrics_reader;
pub use metrics_reader::{Metric, MetricFormat, MetricsReader, MetricsReaderBuilder, Semantics};

mod metrics_publisher;
pub use metrics_publisher::{Vsc, VscMetric};
pub use varnish_macros::{run_vtc_tests, vmod, VscMetric};