README.rst 2.6 KB
Newer Older
Nils Goroll's avatar
Nils Goroll committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
==============
varnish-objvar
==============

This bundle contains four varnish modules (vmods) implementing a next
level variable interface using the VCL object model:

* vmod_taskvar:

  `task` scoped variables as objects: Each client or backend request
  (`task`) has their own view of taskvar variables.

* vmod_topvar:

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

* vmod_globalvar:

  globally (per vcl) scoped variables as objects: All vcl subroutines
  have the same view on variables, any change comes in effect
  immediately.

* vmod_constant:

  gobally (per vcl) scoped constants as objects: All vcl subroutines
  have the same view on constants.

Full type support
-----------------

The vmods in this bundle aim to support all native VCL types, which
currently are:

* ``ACL``

* ``BACKEND``

* ``BLOB``

* ``BODY``

* ``BOOL``

* ``BYTES``

* ``DURATION``

* ``HEADER``

* ``INT``

* ``IP``

* ``PROBE``

* ``REAL``

* ``STEVEDORE``

* ``STRANDS`` implicit via ``STRING``\ -folding

* ``STRING_LIST`` implicit via ``STRING``\ -folding

* ``STRING``

* ``TIME``


SYNOPSIS
========

Variable object construction is identical for all vmods from this
bundle, shown here by example of the ``int`` type, but the other types
mentioned above are supported likewise:

::

   import constant [from "path"] ;
   import globalvar [from "path"] ;
   import taskvar [from "path"] ;
   import topvar [from "path"] ;

   vcl_init {
	new xconst_int = constant.int(5);
	new xglob_int = globalvar.int(5);
	new xtask_int = taskvar.int(5);
	new xtop_int = topvar.int(5);
   }

All vmods support methods to ``.get()`` the value and check if the
variable is ``.defined()``.

All vmods except ``vmod_constant`` support ``.set()`` and
``.undefine()`` to assign a value to a variable or unset it.

``vmod_taskvar`` and ``vmod_topvar`` also support ``.protect()`` to
make a variable read-only for the rest of its lifetime and
``.protected()`` to check for protection status.

For details see the documentation of the individual vmods.

REQUIREMENTS
============

The VMOD requires the Varnish since version 6.0.0 or the master
branch. See the project repository for versions that are compatible
with other versions of Varnish.

INSTALLATION
============

See `INSTALL.rst <INSTALL.rst>`_ in the project source repository.


COPYRIGHT
=========

::

  Copyright 2018 UPLEX Nils Goroll Systemoptimierung
  All rights reserved

  This document is licensed under the same conditions as the varnish-objvar
  project. See LICENSE for details.

  Author: Nils Goroll <nils.goroll@uplex.de>