In Notifuse, our users write their own templates: the Liquid in their emails, their display conditions and their blog themes all comes from them. So I looked at the Liquid engines available in Go, and found that none of them was safe with templates written by someone else, and few of them rendered Liquid the way Shopify does. We had to build our own. That's liquidgo, an open-source Liquid engine written in Go, and we want it to be the best Liquid library in the world, in any language.

That's a big claim. Today liquidgo renders the same output as Shopify Liquid on 94.2% of our test templates, and every other one is a difference we chose and wrote down. It's the fastest Liquid engine in Go, 7 times faster than Shopify's own, and it's safe with templates written by your users.

Our standards

We hold liquidgo to three standards.

The first is output. Liquid is Shopify's language, and people write it the way it works in Shopify, so an engine that only "mostly" follows Shopify Liquid renders the wrong text in someone's email. We compare liquidgo with Shopify's Ruby gem byte for byte, and every difference we keep is written down with its reason.

The second is speed. Liquid runs once per recipient, on every campaign and every transactional email, and it shouldn't be the reason a send is slow.

The third is safety, and it's the one most engines skip. When your customers write the templates, anyone with an account can hand the engine a template written to break it. A template should never be able to crash the process, run forever, eat all the memory or read your data.

Why we built it

We ran every Liquid library we could use from Go on the same templates, and gave each of them templates written to cause harm: a billion iterations, a string doubled 40 times, a billion bytes of output, and 100,000 nested blocks.

The one that came closest to Shopify has no limits at all: each of those four templates runs it out of time or memory. It also compares a number from your Go data as a string, so {% if product.discount > 0 %} fails with an error. Most of the others stopped only one of the four, and the best of them stopped three. On the output side, the best one matched Shopify on 87.3% of our templates, and the others between 33.5% and 78.9%, with whole tags missing: no {% liquid %}, no cycle, no tablerow, no whitespace control.

liquidgo is a port of the Ruby gem, file by file, so that every new Shopify release can be carried over line by line. Today it ports Shopify Liquid 5.14.0, the latest release.

Same output

Shopify Liquid 5.14.0 is pinned in our CI, and every pull request checks liquidgo against it:

  • 513 cases taken from Shopify's own Ruby tests, replayed in lax, strict and strict2 mode, with Ruby numbers and with numbers decoded from JSON.

  • A differential corpus of 293 templates, each rendered in lax and strict mode by the Ruby gem on every pull request. liquidgo must give the same output, or the difference must be listed with its reason.

  • Malformed templates included: a bracket that never closes, a stray quote in a filter argument, a number with two dots. They render the way Shopify renders them.

No difference is left to fix today. Each one that remains is a choice we made on purpose, or a Ruby object that has no equivalent in Go.

Where it differs

A few behaviours differ on purpose, because Go applications pass data decoded from JSON and render text that people read:

  • An empty string is false in a condition, so {% if contact.first_name %} skips an empty name. In Ruby, only nil and false are false.

  • JSON numbers arrive in Go as floats, so liquidgo writes a whole number without its decimal: {{ 2.0 }} renders 2, where Ruby renders 2.0.

  • A filter error writes nothing in the output, where Ruby writes a "Liquid error" message that would land in someone's inbox. The error is still returned to your code.

  • Each render starts from its own data. What one render assigns never reaches the next one, so a value assigned for one recipient can't leak into another recipient's email.

  • A Go struct exposes nothing unless you declare what a template may read. Ruby raises an error for an object without to_liquid; liquidgo writes nothing, and reads nothing by reflection.

All of them are listed in docs/differences-from-shopify.md. Any difference that isn't on that list is a bug, and we want to hear about it.

7× faster

We render the same newsletter template, a loop over 50 products with conditions and filters, on GitHub's Linux arm64 runner. liquidgo renders it in 53 µs. The next Go engine takes 54 µs, and the others between 76 µs and 317 µs. Shopify Liquid 5.14 on Ruby 3.3 with YJIT takes 368 µs, 6.9 times as long.

A template is parsed once and rendered from any number of goroutines at the same time, and renders share the parse of a partial.

Untrusted templates

We designed liquidgo for a template written to hurt you, so you can put it behind a template editor that your customers use:

  • Limits on the bytes written, the work done and the bytes assigned stop a loop or a string that grows without end, filters included, and the deadline of your context.Context stops a render that runs too long.

  • Blocks, lookups and partials nested too deep are refused before they can exhaust the stack.

  • Nothing is read by reflection: a template sees maps, lists, numbers, strings and the keys you declare, never the fields or methods of your Go values.

  • Renders are isolated from each other, and the file system for partials never reads outside its folder.

  • A panic never reaches your program. It comes back as an error, with its stack.

On the four hostile templates, liquidgo stops every one of them, as Shopify Liquid 5.14 does. Every safety rule has its own tests, and every pull request runs a fuzzer and the race detector. Before each release, we remove each of the library's 40 safety checks one at a time, and a test must fail every time.

Comparison

We ran every Liquid library we could use from Go on the same 963 templates: the cases of Shopify's test suite and our differential corpus, each compared with the output of Shopify Liquid 5.14.0.

  • liquidgo: 94.2% identical, no template it cannot render, all 4 hostile templates stopped, 53 µs.

  • tobi/liquid-go: 87.3% identical and the closest on Shopify's tests alone, but none of the hostile templates stopped, and 317 µs.

  • nchapman/go-liquid: 78.9% identical, 72 templates it cannot render, 3 hostile templates stopped, 88 µs.

  • go-liquid/liquid: 64.2% identical, 195 templates it cannot render, 1 hostile template stopped, 76 µs.

  • osteele/liquid: 52.1% identical, 337 templates it cannot render, 1 hostile template stopped, 304 µs.

  • acstech/liquid: 33.5% identical, 489 templates it cannot render, 1 hostile template stopped, 54 µs.

Our differential corpus was written while we built liquidgo, so it favours us; on Shopify's tests alone, tobi/liquid-go matches 357 of 360 and liquidgo 356. The full method, the library versions and the commands to reproduce the comparison are in docs/library-comparison.md. If you maintain one of these libraries and think we measured it unfairly, open an issue and we'll run it again.

What's missing

A Go map keeps no order, so a hash with several keys is written and looped over in the order of its keys, where Ruby keeps the order they were added. And the resource limits are off by default, as in Ruby: turn them on when your users write the templates.

Try it

The code is on GitHub and the docs are on pkg.go.dev. Run it on your own templates, especially the ugly ones. When liquidgo and Shopify Liquid disagree, open an issue with the template that shows it, and we'll fix it.

Getting started

go get github.com/Notifuse/liquidgo/v5
import (
    "context"

    "github.com/Notifuse/liquidgo/v5/liquid"
    "github.com/Notifuse/liquidgo/v5/liquid/tags"
)

env, err := liquid.NewEnvironment(liquid.EnvironmentConfig{Tags: tags.Standard()})
tmpl, err := liquid.ParseTemplate("Hello {{ name | capitalize }}!",
    &liquid.TemplateOptions{Environment: env})
res, err := tmpl.Render(context.Background(), map[string]interface{}{"name": "ann"})
// res.Output == "Hello Ann!"

liquidgo is MIT-licensed and written in pure Go. Its only dependency is gopkg.in/yaml.v3, for the translations of its error messages.