Edgestash

Description

Edgestash is a realtime templating engine built inside of Varnish Cache Plus. Edgestash allows for JSON data to be composed into a response using Mustache syntax, ex: {{variable}}. Each response can be assigned its own JSON object for truly dynamic responses. JSON can either be fetched from a backend or generated via VCL and any number of JSONs can be assigned to a template.

An Edgestash template is fetched and compiled into response optimized byte code and then stored into cache. This byte code is then executed on delivery, efficiently streaming the response to the client using a zero-parse and zero-copy algorithm. JSON is also stored into cache as a fast search index.

Edgestash currently supports the full Mustache spec plus expressions and variables.

To dynamically insert Edgestash tags into content, see XBody.

This API applies to Varnish Cache Plus 6.0 and higher.

Edgestash 4.1 API

Quick Start

VCL Example

Join a template with JSON:

vcl 4.0;

import edgestash;

backend default
{
  .host = "backend.example.com";
  .port = "80";
}

sub vcl_backend_response
{
  if (bereq.url ~ "\.json$") {
    edgestash.index_json();
  } else if (bereq.url ~ "/edgestash/.*\.txt$") {
    edgestash.parse_response();
  }
}

sub vcl_deliver
{
  # Pair /edgestash/template.txt with /edgestash/template.json
  if (req.url ~ "/edgestash/.*\.txt$" && edgestash.is_edgestash()) {
    edgestash.add_json_url(regsub(req.url, "\.txt$", ".json"));
    edgestash.execute();
  }

  if (edgestash.is_edgestash() || edgestash.is_json()) {
    set resp.http.X-edgestash = edgestash.version();
  }
}

Edgestash Examples

Filter a list and produce JSON output:

[
  {{#.}}
    "{{value}}"
    {{^$last}},{{/$last}}
  {{/}}
]

Print a list with formatting:

{{#.}}
  {{# $first}}
    <!-- Print header here -->
  {{/}}
  {{#($pos % 2f) == 0f}}
    <span class="even">
  {{/}}
  {{#($pos % 2f) != 0f}}
    <span class="odd">
  {{/}}
      {{value}}
    </span>
  {{# $last}}
    <!-- Print footer here -->
  {{/}}
{{/}}
{{^.}}
  No values found
{{/}}

Detect no JSON:

{{#$type}}
  JSON detected
  ...
{{/}}
{{^$type}}
  No JSON detected
{{/}}

Mixing Edgestash with another mustache template:

Edgestash variable 1: {{var1}}

{{=${ }=}}

Untouched: {{var}}
Edgestash variable 2: ${var2}

VMOD

parse_response

VOID edgestash.parse_response()

• Description

  Parse an Edgestash template into bytecode. Only can be used in vcl_backend_response.

• Return value

  None

index_json

VOID edgestash.index_json()

• Description

  Parse a JSON response. Optional. It enables storage of a fast JSON search index. If not invoked, JSON will be parsed on delivery, resulting in slower Edgestash assembly. Only can be used in vcl_backend_response.

• Return value

  None

add_json_url

VOID add_json_url(STRING json_url, STRING json_host, BOOL xbody)

• Description

  Include a JSON URL for Edgestash templating. Can only be used in vcl_deliver. JSON URL will execute back through VCL with one higher (+1) esi_level. Multiple JSON fetches will happen in parallel. Use index_json() on this URL to enable storage of a fast JSON search index. If this URL is JSON generated from an Edgestash template, use parse_response(). JSON will be searched and used in the order they are added, including add_json().

• Return value

  None

  • json_url

    The JSON URL to use for Edgestash templating. URL must be supplied without the scheme and host.

  • json_host

    Optional. The Host header used for the subsequent JSON request. req.http.Host will be set to this value on the sub request.

  • xbody

    Optional. If true, use the XBody JSON capture. Defaults to false.

add_json_url_csv

VOID add_json_url_csv(STRING json_urls, STRING prefix, STRING delimiter, STRING json_host, BOOL xbody)

• Description

  Parse a comma separated list of URLs and call add_json_url() for each. JSONs can be iterated using the following Edgestash syntax: {{ # . }}

• Return value

  None

  • json_urls

    Comma separated list of URLs.

  • prefix

    Optional. Prefix added to each URL.

  • delimiter

    Delimiter used to parse json_urls. Single character. Defaults to ,.

  • json_host

    Optional. The Host header used for the subsequent JSON request.

  • xbody

    Optional. If true, use the XBody JSON capture. XBody URL must be cached.

add_json

VOID add_json(STRING json)

• Description

  Include a JSON string for Edgestash templating. Only can be used in vcl_deliver. JSON will be searched and used in the order they are added, including add_json_url().

• Return value

  None

  • json

    The JSON string to use for Edgestash templating.

execute

VOID edgestash.execute(BOOL do_gzip)

• Description

  Execute an Edgestash template. Only valid for responses which have been parsed with parse_response(). Partial includes will execute back thru VCL with one higher (+1) esi_level. Can only be used in vcl_deliver.

• Return value

  None

  • do_gzip

    Gzip the response. Defaults to true.

set_delimiter

VOID edgestash.set_delimiter(STRING start, STRING end)

• Description

  Set the initial Edgestash command delimiters. Only can be used in vcl_backend_response.

• Return value

  None

  • start

    The starting Edgestash command delimiter. Default: {{

  • end

    The ending Edgestash command delimiter. Default: }}

is_edgestash

BOOL edgestash.is_edgestash()

• Description

  Checks to see if parse_response() was called on this object and was successful in generating bytecode.

• Return value

  True if Edgestash bytecode exists for this object, otherwise false.

is_json

BOOL edgestash.is_json()

• Description

  Checks to see if index_json() was called on this object and was successful in generating an index.

• Return value

  True if a json index exists for this object, otherwise false.

version

STRING edgestash.version()

• Description

  Get the Edgestash implementation version.

• Return value

  The Edgestash version.

req.esi

• Description

  Boolean. Set to false to disable templating for this request. The Edgestash template will be delivered unprocessed. Useful when the raw template needs to be fetched into another cache or framework. Defaults to true. Can be used anywhere where req is valid.

Edgestash Syntax

{{variable}}

• Description

  Variable or expression. Substitutes in the JSON value of variable. HTML is escaped, JSON is un-escaped, Ex:

  • < turns into <

  • > turns into >

  • \" turns into "

{{ & variable}}

• Description

  Unescaped variable. Substitutes in the raw JSON value of variable. {{{variable}}} syntax is NOT supported. Variable supports dotted object and array syntax. HTML is untouched, JSON is untouched. Ex:

  • < is left as <

  • > is left as >

  • \" is left as \"

{{ # section}} {{ / section}}

• Description

  A section block. Can be a variable or expression. If the value of section is not falsy, the section is executed, otherwise it is skipped. If the value is an object, it is used as context for the section. If the value is a non empty array, the section is repeated once for each element in the array and used as context (if the element is an object). If the value is a root object, all root JSON includes are iterated (ex: {{ # . }}). Falsy values:

  • [], false, null

• Notes

  Closing section can be left as {{/}}.

{{ ^ section}} {{ / section}}

• Description

  An inverted section block. If the value of section is falsy, the section is executed, otherwise it is skipped. Falsy values:

  • [], false, null

• Notes

  Closing section can be left as {{/}}.

{{ ! comment}}

• Description

  Comment, these are ignored and removed. May contain newlines.

{{ > /url}}

• Description

  Partial, these are includes. The partial is executed back thru VCL with an esi_level + 1. If the partial is a template, the current JSON context is used (assuming no JSON was explicitly set for this template).

  If a URL contains a scheme and host, the host is passed as req.http.Host when executing back thru Varnish.

  Ex:

  • {{> http://example.com/site/templates/user.es}}

{{=sd ed=}}

• Description

  Change the Edgestash command delimiter to the value of sd and ed. Custom delimiter can not contain whitespace or the equal sign.

Notes

• Preceding and trailing whitespace is allowed inside of all command syntax.
  Ex: {{ $ abc }} is equal to {{$abc}}

• If the variable is not found, the variable is substituted with an empty string, unless overridden. If there is a section context, the variable is searched for in each parent until the root is hit. If multiple JSON files are used, files are searched in added order until the variable is found.

• JSON is strictly parsed in full accordance to the official spec (json.org). Invalid JSON is equivalent to a falsy value with $type as null.

• If an Edgestash parsing error is encountered (unterminated variable, unterminated section, etc), the document is treated as plain text and templating will not happen.

Variables and Expressions

variable

• Description

  String. A JSON variable. Variables support dotted object and array syntax. Ex:

  {{ variable }} - The variable value from the current JSON context.
  {{ . }} - The current context.
  {{ [0] }} - The first element of the current array context.
  {{ name.begin }} - The begin value from the name object. If it doesn’t exist, the value name.begin.
  {{ locations[2].country }} - The country value from the 3nd element (0 based index) of the locations array.

$first

• Description

  Boolean. true if the current section context is the first element of an array, otherwise false. If the current section context is not an array or does not exist, value defaults to true.

$last

• Description

  Boolean. true if the current section context is the last element of an array, otherwise false. If the current section context is not an array or does not exist, value defaults to true.

$type

• Description

  String. The JSON type of the current context. Possible values: "object", "array", "string", "number", "true", "false", "null". If there is no JSON context, the value is equivilant to null.

$pos

• Description

  Number. If in an array context, the element position, 0 based. The first element has a value of 0 and the last element element has a value of $size - 1. If there is no JSON context, defaults to 0.

$size

• Description

  Number. The size of the current context. Only valid for objects and arrays. All other types have a size of 0.

"string"

• Description

  String. A string value to be used in an expression.

123.4f

• Description

  Number. A number value to be used in an expression. d notation is also supported. All numbers are treated as 64bit Javascript doubles.

== !=

• Description

  Boolean operator. Equality. Types must be equal for an == expression to be true.

&& || !

• Description

  Logical AND, OR and NOT operators. Returns a boolean value.

> >= < <=

• Description

  Relational operators. Do a numeric comparison in an expression.

+ - * /

• Description

  Arithmetical operators. Common numerical calculations.

%

• Description

  Modulus operator. Returns the remainder after a division.

( )

• Description

  Expression. Use parentheses to enforce logic order.

Notes

• Preceding and trailing whitespace is required around expression operators.
  Ex: {{#($pos % 2f) == 0f}} is correct. {{#($pos%2f)==0f}} is incorrect.