JSON module for Varnish VCL
C Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
m4
src Minor fix Oct 16, 2013
.gitignore
.syntastic_c_config
.travis.yml
LICENSE Initial commit Oct 9, 2013
Makefile.am
README.md
TODO
autogen.sh
configure.ac

README.md

Build Status

Introduction

libvmod-json is a varnish vcl module for creating JSON strings

Usage

libvmod-json makes available a series of functions used to create a json structure stored internally, and a dump function to convert that internal structore to a string.

Key Paths

libvmod-json introduces a concept called a key path which is used to refer to structures inside of the json state. A key path is a string which specifies a path to a leaf node in your expected json tree. Interior nodes are created automatically.

The root of the internal json state is always a single json object, accessible by the empty string. Therefore all key paths always start with object access.

Key Path Operations

Key paths are composed of zero or more operations concatenated together. They are of the following form:

Operation String Description
object access .<identifier> Access the field named <identifier> of the object
array access [<index>] Access the array element <index> of the array
array append [<] Append to the array
array prepend [>] Prepend to the array

For array access operations, arrays automatically grow to their indexed size and are filled with null.

Negative indexes are allowed, and access from the end of the array.

Example Key Paths and Their Equivalent JSON

  • .foo: {"foo": ...}
  • .foo.bar: {"foo": {"bar": ...}}
  • .foo[1]: {"foo": [null, ...]}
  • .foo[<][1]: {"foo": [[null, ...]]}
  • .foo[<][1].baz.foobaz[3]: {"foo": [[null, {"baz": {"foobaz": [null, null, null, ...]}}]]}

Scoping

There are two scopes for the internal json structure:

  • local scope: the internal json structure will be reset on every request
  • global scope: the internal structure will be shared among all requests

Functions

For now, refer to vmod_json.vcc

Errors

If an error occurrs, all calls into the json library the session wherein the error occurred will be ignored until error_clear is called.

Future Work

Currently, libvmod-json only supports generating json strings. It can in the future support parsing json strings, at which point it would also be a superset of the functionality of libvmod-var

The way local variables are implemented will need to be rewritten for varnish 4