vmod_topvar(3)

Name
vmod_topvar - cross-ESI (top) variables as objects for VCL

SYNOPSIS

            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

This module implements top scoped variables as objects: Each client request including all esi include levels (top) has its own view of topvar variables.

A topvar can be constructed with a default, which is used as the initial value at the beginning of each request at esi level 0.

The value of a topvar is the either the default or the last value assigned to it within any esi subrequest. If neither a default nor previous value was set, then the value is undefined.

A topvar can also be undefined using the .undefine() method.

Attempts to .get() an undefined value will return the .get() method`s fallback argument. For most types, there is a default fallback; if there is none, using .get() on an undefined value triggers a VCL failure at runtime.

topvar variables can be protected against write access, in which case any attempt to .set() them triggers a VCL failure at runtime.

Example:

            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
            }

The implementation of the various classes of this vmod is auto-generated, and so is the documentation. Thus, the documentation following this generic description is identical for all types except for the respective type names and the .get() fallback.

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

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

  ACL xacl.get([ACL fallback])

Return the value of the topvar or the fallback argument if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

Restricted to: client.

  VOID xacl.set(ACL)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xacl.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xacl.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xacl.protect()

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

Restricted to: client.

  BOOL xacl.protected()

Return 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. If no init value is provided, the variable will be initially undefined.

  BACKEND xbackend.get([BACKEND fallback])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is the None backend.

Restricted to: client.

  VOID xbackend.set(BACKEND)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xbackend.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xbackend.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xbackend.protect()

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

Restricted to: client.

  BOOL xbackend.protected()

Return 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. If no init value is provided, the variable will be initially undefined.

  BLOB xblob.get([BLOB fallback])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is the null blob.

Restricted to: client.

  VOID xblob.set(BLOB)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xblob.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xblob.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xblob.protect()

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

Restricted to: client.

  BOOL xblob.protected()

Return 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])

Return the value of the topvar or the fallback argument if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

Restricted to: client.

  VOID xbody.set(BODY)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xbody.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xbody.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xbody.protect()

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

Restricted to: client.

  BOOL xbody.protected()

Return 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. If no init value is provided, the variable will be initially undefined.

  BOOL xbool.get([BOOL fallback])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is false

Restricted to: client.

  VOID xbool.set(BOOL)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xbool.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xbool.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xbool.protect()

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

Restricted to: client.

  BOOL xbool.protected()

Return 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is 0 bytes.

Restricted to: client.

  VOID xbytes.set(BYTES)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xbytes.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xbytes.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xbytes.protect()

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

Restricted to: client.

  BOOL xbytes.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is 0s.

Restricted to: client.

  VOID xduration.set(DURATION)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xduration.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xduration.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xduration.protect()

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

Restricted to: client.

  BOOL xduration.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.

Restricted to: client.

  VOID xheader.set(HEADER)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xheader.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xheader.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xheader.protect()

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

Restricted to: client.

  BOOL xheader.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is 0.

Restricted to: client.

  VOID xint.set(INT)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xint.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xint.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xint.protect()

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

Restricted to: client.

  BOOL xint.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is IPv4 0.0.0.0.

Restricted to: client.

  VOID xip.set(IP)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xip.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xip.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xip.protect()

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

Restricted to: client.

  BOOL xip.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is no backend.

Restricted to: client.

  VOID xprobe.set(PROBE)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xprobe.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xprobe.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xprobe.protect()

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

Restricted to: client.

  BOOL xprobe.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is 0.0.

Restricted to: client.

  VOID xreal.set(REAL)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xreal.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xreal.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xreal.protect()

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

Restricted to: client.

  BOOL xreal.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is the default storage.

Restricted to: client.

  VOID xstevedore.set(STEVEDORE)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xstevedore.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xstevedore.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xstevedore.protect()

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

Restricted to: client.

  BOOL xstevedore.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is the empty string.

Restricted to: client.

  VOID xstring.set(STRING)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xstring.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xstring.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xstring.protect()

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

Restricted to: client.

  BOOL xstring.protected()

Return whether the topvar is protected.

Restricted to: client.

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

Construct 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])

Return the value of the topvar or the fallback argument if it is undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT).

Restricted to: client.

  VOID xtime.set(TIME)

Set the value of the topvar.

Triggers a vcl failure for protected variables.

Restricted to: client.

  VOID xtime.undefine()

Undefine the topvar.

Restricted to: client.

  BOOL xtime.defined()

Return whether the topvar is defined.

Restricted to: client.

  VOID xtime.protect()

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

Restricted to: client.

  BOOL xtime.protected()

Return whether the topvar is protected.

Restricted to: client.

SEE ALSO

vcl(7),vinyld(1)

COPYRIGHT

            Copyright 2018-2022 UPLEX Nils Goroll Systemoptimierung

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

            1. Redistributions of source code must retain the above copyright
               notice, this list of conditions and the following disclaimer.

            2. 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.