vmod_topvar(3)

📦 version 0.0~git20260330, in ubuntu stonking

✨ NAME ✨

bestie, welcome to vmod_topvar(3) — it lives in the Library Functions Manual and it's literally the "cross-ESI (top) variables as objects for VCL" module. no cap. 💖

🌸 SYNOPSIS 🌸

okay so here's the whole shape of it, verbatim, don't skip:

import topvar [as name] [from "path"]

new xacl = topvar.acl([ACL init])

    ACL xacl.get([ACL fallback])

    VOID xacl.set(ACL)

    VOID xacl.undefine()

    BOOL xacl.defined()

    VOID xacl.protect()

    BOOL xacl.protected()

new xbackend = topvar.backend([BACKEND init])

    BACKEND xbackend.get([BACKEND fallback])

    VOID xbackend.set(BACKEND)

    VOID xbackend.undefine()

    BOOL xbackend.defined()

    VOID xbackend.protect()

    BOOL xbackend.protected()

new xblob = topvar.blob([BLOB init])

    BLOB xblob.get([BLOB fallback])

    VOID xblob.set(BLOB)

    VOID xblob.undefine()

    BOOL xblob.defined()

    VOID xblob.protect()

    BOOL xblob.protected()

new xbody = topvar.body([BODY init])

    BODY xbody.get([BODY fallback])

    VOID xbody.set(BODY)

    VOID xbody.undefine()

    BOOL xbody.defined()

    VOID xbody.protect()

    BOOL xbody.protected()

new xbool = topvar.bool([BOOL init])

    BOOL xbool.get([BOOL fallback])

    VOID xbool.set(BOOL)

    VOID xbool.undefine()

    BOOL xbool.defined()

    VOID xbool.protect()

    BOOL xbool.protected()

new xbytes = topvar.bytes([BYTES init])

    BYTES xbytes.get([BYTES fallback])

    VOID xbytes.set(BYTES)

    VOID xbytes.undefine()

    BOOL xbytes.defined()

    VOID xbytes.protect()

    BOOL xbytes.protected()

new xduration = topvar.duration([DURATION init])

    DURATION xduration.get([DURATION fallback])

    VOID xduration.set(DURATION)

    VOID xduration.undefine()

    BOOL xduration.defined()

    VOID xduration.protect()

    BOOL xduration.protected()

new xheader = topvar.header([HEADER init])

    HEADER xheader.get([HEADER fallback])

    VOID xheader.set(HEADER)

    VOID xheader.undefine()

    BOOL xheader.defined()

    VOID xheader.protect()

    BOOL xheader.protected()

new xint = topvar.int([INT init])

    INT xint.get([INT fallback])

    VOID xint.set(INT)

    VOID xint.undefine()

    BOOL xint.defined()

    VOID xint.protect()

    BOOL xint.protected()

new xip = topvar.ip([IP init])

    IP xip.get([IP fallback])

    VOID xip.set(IP)

    VOID xip.undefine()

    BOOL xip.defined()

    VOID xip.protect()

    BOOL xip.protected()

new xprobe = topvar.probe([PROBE init])

    PROBE xprobe.get([PROBE fallback])

    VOID xprobe.set(PROBE)

    VOID xprobe.undefine()

    BOOL xprobe.defined()

    VOID xprobe.protect()

    BOOL xprobe.protected()

new xreal = topvar.real([REAL init])

    REAL xreal.get([REAL fallback])

    VOID xreal.set(REAL)

    VOID xreal.undefine()

    BOOL xreal.defined()

    VOID xreal.protect()

    BOOL xreal.protected()

new xstevedore = topvar.stevedore([STEVEDORE init])

    STEVEDORE xstevedore.get([STEVEDORE fallback])

    VOID xstevedore.set(STEVEDORE)

    VOID xstevedore.undefine()

    BOOL xstevedore.defined()

    VOID xstevedore.protect()

    BOOL xstevedore.protected()

new xstring = topvar.string([STRING init])

    STRING xstring.get([STRING fallback])

    VOID xstring.set(STRING)

    VOID xstring.undefine()

    BOOL xstring.defined()

    VOID xstring.protect()

    BOOL xstring.protected()

new xtime = topvar.time([TIME init])

    TIME xtime.get([TIME fallback])

    VOID xtime.set(TIME)

    VOID xtime.undefine()

    BOOL xtime.defined()

    VOID xtime.protect()

    BOOL xtime.protected()

🦋 DESCRIPTION 🦋

okay so boom: this module turns top scoped variables into objects. every single client request — and like, all the esi include levels too (that's the "top" part, iykyk) — gets its own lil view of the topvar variables. basically each request has main character energy and its own copy of the vibes. ✨

a topvar can be constructed with a default, and that default gets used as the initial value at the beginning of each request at esi level 0. it's giving "first day of school outfit". 🎀

the value of a topvar is either the default or the last value assigned to it within any esi subrequest. and if neither a default nor a previous value was set? then the value is undefined. mystery era. 💀

you can also just straight up undefine a topvar with the .undefine() method. bye bestie. 👋

if you try to .get() an undefined value, you'll get back the .get() method's fallback argument. for most types there's a default fallback already; but if there isn't one, then using .get() on an undefined value triggers a VCL failure at runtime. not a vibe. 😭

also! topvar variables can be protected against write access, and once they are, any attempt to .set() them triggers a VCL failure at runtime. so like, locked, no take-backsies. 🔒

Example time, look at this gorgeous specimen:

import topvar;

sub vcl_init {
 new xint = topvar.int();
}

sub vcl_recv {
 if (req.esi_level == 0) {
  set req.http.def = xint.defined(); # false
  set req.http.fallback = xint.get(5); # 5
  xint.set(42);
 } else {
  set req.http.fallback = xint.get(5); #42
 }
}

sub vcl_deliver {
 set resp.http.the-answer = xint.get(); # 42
}

ngl the implementation of all these classes is auto-generated, and so is the documentation. so everything below this generic description is literally identical for every type — the only things that change are the type names and the .get() fallback. iconic, honestly. 💅

🌈 new xacl = topvar.acl([ACL init])

construct a(n) ACL topvar with the default value init, if you feel like providing it. if you don't, the variable starts out undefined. girl's a blank slate. ✨

`ACL xacl.get([ACL fallback])`

returns the value of the topvar, or the fallback argument when it's undefined. heads up though: using .get() on an undefined value without a fallback triggers a VCL error. 🚨

restricted to: client.

`VOID xacl.set(ACL)`

sets the value of the topvar.

triggers a vcl failure for protected variables. periodt.

restricted to: client.

`VOID xacl.undefine()`

undefines the topvar. poof. 🌸

restricted to: client.

`BOOL xacl.defined()`

returns whether the topvar is defined. yes/no bestie. 💖

restricted to: client.

`VOID xacl.protect()`

protects the topvar, so any future .set() calls on it trigger a vcl failure. armor on. 🛡️

restricted to: client.

`BOOL xacl.protected()`

returns whether the topvar is protected.

restricted to: client.

🌈 new xbackend = topvar.backend([BACKEND init])

construct a(n) BACKEND topvar with the default value init, if provided. no init? then it's initially undefined.

`BACKEND xbackend.get([BACKEND fallback])`

returns the value of the topvar, or the fallback argument if it's undefined. the default fallback is the None backend.

restricted to: client.

`VOID xbackend.set(BACKEND)`

sets the value of the topvar.

triggers a vcl failure for protected variables.

restricted to: client.

`VOID xbackend.undefine()`

undefines the topvar.

restricted to: client.

`BOOL xbackend.defined()`

returns whether the topvar is defined.

restricted to: client.

`VOID xbackend.protect()`

protects the topvar, so any future .set() calls on it trigger a vcl failure.

restricted to: client.

`BOOL xbackend.protected()`

returns whether the topvar is protected.

restricted to: client.

🌈 new xblob = topvar.blob([BLOB init])

construct a(n) BLOB topvar with the default value init, if provided. no init, no value — initially undefined, as always.

`BLOB xblob.get([BLOB fallback])`

returns the value of the topvar, or the fallback argument if it's undefined. the default fallback is the null blob. 🫧

restricted to: client.

`VOID xblob.set(BLOB)`

sets the value of the topvar.

triggers a vcl failure for protected variables.

restricted to: client.

`VOID xblob.undefine()`

undefines the topvar.

restricted to: client.

`BOOL xblob.defined()`

returns whether the topvar is defined.

restricted to: client.

`VOID xblob.protect()`

protects the topvar, so any future .set() calls on it trigger a vcl failure.

restricted to: client.

`BOOL xblob.protected()`

returns whether the topvar is protected.

restricted to: client.

🌈 new xbody = topvar.body([BODY init])

construct a(n) BODY topvar with the default value init, if provided. if no init value is provided, the variable will be initially undefined.

`BODY xbody.get([BODY fallback])`

returns the value of the topvar, or the fallback argument if it's undefined. using .get() on an undefined value without a fallback triggers a VCL error. 💀

restricted to: client.

`VOID xbody.set(BODY)`

sets the value of the topvar.

triggers a vcl failure for protected variables.

restricted to: client.

`VOID xbody.undefine()`

undefines the topvar.

restricted to: client.

`BOOL xbody.defined()`

returns whether the topvar is defined.

restricted to: client.

`VOID xbody.protect()`

protects the topvar, so any future .set() calls on it trigger a vcl failure.

restricted to: client.

`BOOL xbody.protected()`

returns whether the topvar is protected.

restricted to: client.

🌈 new xbool = topvar.bool([BOOL init])

construct a(n) BOOL topvar with the default value init, if provided. no init? initially undefined, you know the drill.

`BOOL xbool.get([BOOL fallback])`

returns the value of the topvar, or the fallback argument if it's undefined. the default fallback is false. simple as. 🍓

restricted to: client.

`VOID xbool.set(BOOL)`

sets the value of the topvar.

triggers a vcl failure for protected variables.

restricted to: client.

`VOID xbool.undefine()`

undefines the topvar.

restricted to: client.

`BOOL xbool.defined()`

returns whether the topvar is defined.

restricted to: client.

`VOID xbool.protect()`

protects the topvar, so any future .set() calls on it trigger a vcl failure.

restricted to: client.

`BOOL xbool.protected()`

returns whether the topvar is protected.

restricted to: client.

🌈 new xbytes = topvar.bytes([BYTES init])

construct a(n) BYTES topvar with the default value init, if provided. if no init value is provided, the variable will be initially undefined.

`BYTES xbytes.get([BYTES fallback])`

returns the value of the topvar, or the fallback argument if it's undefined. the default fallback is 0 bytes.

restricted to: client.

`VOID xbytes.set(BYTES)`

sets the value of the topvar.

triggers a vcl failure for protected variables.

restricted to: client.

`VOID xbytes.undefine()`

undefines the topvar.

restricted to: client.

`BOOL xbytes.defined()`

returns whether the topvar is defined.

restricted to: client.

…aaand we're back in the BYTES block 🌈 only three methods left, let's finish her off bestie:

BOOL xbytes.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xbytes.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. 🔒 Restricted to: client.
BOOL xbytes.protected() — returns whether the topvar is protected. Restricted to: client.

🦋 DURATION

new xduration = topvar.duration([DURATION init])

constructs a(n) DURATION topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined ✨

DURATION xduration.get([DURATION fallback]) — hands you back the value of the topvar, or the fallback argument if it's undefined. The default fallback is 0s. Restricted to: client.
VOID xduration.set(DURATION) — sets the value of the topvar. Triggers a vcl failure for protected variables 😭 Restricted to: client.
VOID xduration.undefine() — undefines the topvar. Restricted to: client.
BOOL xduration.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xduration.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xduration.protected() — returns whether the topvar is protected. Restricted to: client.

new xheader = topvar.header([HEADER init])

constructs a(n) HEADER topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 💅

HEADER xheader.get([HEADER fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. Head up tho: using .get() on an undefined value without a fallback triggers a VCL error. no chill, no default, just pain 😭 Restricted to: client.
VOID xheader.set(HEADER) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xheader.undefine() — undefines the topvar. Restricted to: client.
BOOL xheader.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xheader.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xheader.protected() — returns whether the topvar is protected. Restricted to: client.

🔢 INT

new xint = topvar.int([INT init])

constructs a(n) INT topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 🎀

INT xint.get([INT fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is 0. Restricted to: client.
VOID xint.set(INT) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xint.undefine() — undefines the topvar. Restricted to: client.
BOOL xint.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xint.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xint.protected() — returns whether the topvar is protected. Restricted to: client.

🌐 IP

new xip = topvar.ip([IP init])

constructs a(n) IP topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 🌈

IP xip.get([IP fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is IPv4 0.0.0.0. Restricted to: client.
VOID xip.set(IP) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xip.undefine() — undefines the topvar. Restricted to: client.
BOOL xip.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xip.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xip.protected() — returns whether the topvar is protected. Restricted to: client.

🩺 PROBE

new xprobe = topvar.probe([PROBE init])

constructs a(n) PROBE topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 🫶

PROBE xprobe.get([PROBE fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is no backend. Restricted to: client.
VOID xprobe.set(PROBE) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xprobe.undefine() — undefines the topvar. Restricted to: client.
BOOL xprobe.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xprobe.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xprobe.protected() — returns whether the topvar is protected. Restricted to: client.

🍓 REAL

new xreal = topvar.real([REAL init])

constructs a(n) REAL topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined ⭐

REAL xreal.get([REAL fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is 0.0. Restricted to: client.
VOID xreal.set(REAL) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xreal.undefine() — undefines the topvar. Restricted to: client.
BOOL xreal.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xreal.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xreal.protected() — returns whether the topvar is protected. Restricted to: client.

📦 STEVEDORE

new xstevedore = topvar.stevedore([STEVEDORE init])

constructs a(n) STEVEDORE topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 🧚

STEVEDORE xstevedore.get([STEVEDORE fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is the default storage. Restricted to: client.
VOID xstevedore.set(STEVEDORE) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xstevedore.undefine() — undefines the topvar. Restricted to: client.
BOOL xstevedore.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xstevedore.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xstevedore.protected() — returns whether the topvar is protected. Restricted to: client.

🎀 STRING

new xstring = topvar.string([STRING init])

constructs a(n) STRING topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 💖

STRING xstring.get([STRING fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is the empty string. Restricted to: client.
VOID xstring.set(STRING) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xstring.undefine() — undefines the topvar. Restricted to: client.
BOOL xstring.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xstring.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xstring.protected() — returns whether the topvar is protected. Restricted to: client.

⏰ TIME

new xtime = topvar.time([TIME init])

constructs a(n) TIME topvar with the default value init, if provided. If no init value is provided, the variable will be initially undefined 🕰️

TIME xtime.get([TIME fallback]) — returns the value of the topvar, or the fallback argument if it's undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT). Restricted to: client.
VOID xtime.set(TIME) — sets the value of the topvar. Triggers a vcl failure for protected variables. Restricted to: client.
VOID xtime.undefine() — undefines the topvar. Restricted to: client.
BOOL xtime.defined() — returns whether the topvar is defined. Restricted to: client.
VOID xtime.protect() — protects the topvar, so any future .set() calls on it trigger a vcl failure. Restricted to: client.
BOOL xtime.protected() — returns whether the topvar is protected. Restricted to: client.

👀 SEE ALSO

vcl(7)
vinyld(1)

📜 COPYRIGHT

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

and that's the whole page bestie 🫶 you've officially finished vmod_topvar(3) — the source/version and date are down there chillin' in the footer like always 💅 periodt ✨

📦 where this page comes from

ubuntu stonking: libvmod-objvar 0.0~git20260330-3 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

vmod_topvar(3)

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🌈 new xacl = topvar.acl([ACL init])

ACL xacl.get([ACL fallback])

VOID xacl.set(ACL)

VOID xacl.undefine()

BOOL xacl.defined()

VOID xacl.protect()

BOOL xacl.protected()

🌈 new xbackend = topvar.backend([BACKEND init])

BACKEND xbackend.get([BACKEND fallback])

VOID xbackend.set(BACKEND)

VOID xbackend.undefine()

BOOL xbackend.defined()

VOID xbackend.protect()

BOOL xbackend.protected()

🌈 new xblob = topvar.blob([BLOB init])

BLOB xblob.get([BLOB fallback])

VOID xblob.set(BLOB)

VOID xblob.undefine()

BOOL xblob.defined()

VOID xblob.protect()

BOOL xblob.protected()

🌈 new xbody = topvar.body([BODY init])

BODY xbody.get([BODY fallback])

VOID xbody.set(BODY)

VOID xbody.undefine()

BOOL xbody.defined()

VOID xbody.protect()

BOOL xbody.protected()

🌈 new xbool = topvar.bool([BOOL init])

BOOL xbool.get([BOOL fallback])

VOID xbool.set(BOOL)

VOID xbool.undefine()

BOOL xbool.defined()

VOID xbool.protect()

BOOL xbool.protected()

🌈 new xbytes = topvar.bytes([BYTES init])

BYTES xbytes.get([BYTES fallback])

VOID xbytes.set(BYTES)

VOID xbytes.undefine()

BOOL xbytes.defined()

🦋 DURATION

💌 HEADER

🔢 INT

🌐 IP

🩺 PROBE

🍓 REAL

📦 STEVEDORE

🎀 STRING

⏰ TIME

👀 SEE ALSO

📜 COPYRIGHT

`ACL xacl.get([ACL fallback])`

`VOID xacl.set(ACL)`

`VOID xacl.undefine()`

`BOOL xacl.defined()`

`VOID xacl.protect()`

`BOOL xacl.protected()`

`BACKEND xbackend.get([BACKEND fallback])`

`VOID xbackend.set(BACKEND)`

`VOID xbackend.undefine()`

`BOOL xbackend.defined()`

`VOID xbackend.protect()`

`BOOL xbackend.protected()`

`BLOB xblob.get([BLOB fallback])`

`VOID xblob.set(BLOB)`

`VOID xblob.undefine()`

`BOOL xblob.defined()`

`VOID xblob.protect()`

`BOOL xblob.protected()`

`BODY xbody.get([BODY fallback])`

`VOID xbody.set(BODY)`

`VOID xbody.undefine()`

`BOOL xbody.defined()`

`VOID xbody.protect()`

`BOOL xbody.protected()`

`BOOL xbool.get([BOOL fallback])`

`VOID xbool.set(BOOL)`

`VOID xbool.undefine()`

`BOOL xbool.defined()`

`VOID xbool.protect()`

`BOOL xbool.protected()`

`BYTES xbytes.get([BYTES fallback])`

`VOID xbytes.set(BYTES)`

`VOID xbytes.undefine()`

`BOOL xbytes.defined()`