engine

package
v0.2.23 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package engine renders a template's parts in one language with Go templates: text/template for text parts, html/template for html parts (contextual escaping), a closed function set with language-aware helpers, strict about missing data, and bounded so a template cannot exhaust the process. Shared pieces are other templates (named "_x") whose part of the same name a part includes with {{template "_x" .}}.

Index

Constants

View Source
const (
	KindText = "text"
	KindHTML = "html"
)

Kinds of a part.

View Source
const (
	MaxPartBytes   = 256 << 10
	MaxParts       = 16
	MaxDataBytes   = 1 << 20
	MaxOutputBytes = 1 << 20
	// RenderTimeout bounds one render of every part.
	RenderTimeout = 2 * time.Second
)

Limits of what the engine accepts.

View Source
const (
	MaxRangeDepth = 2
	MaxDataItems  = 10000
)

What a template may do. A Go template cannot be interrupted, so the engine refuses up front what could loop without bound:

  • {{range}} iterates only over data: a field (.items, $.a.b, $e.x), a variable holding data, never a number (Go 1.22 ranges over ints) nor a function's result; JSON numbers decode as float64, which range refuses, so data cannot smuggle an int in;
  • ranges nest at most MaxRangeDepth deep, counted through included shared pieces, and data holds at most MaxDataItems elements, so the iterations of one render stay under MaxDataItems^MaxRangeDepth;
  • parts and shared pieces define no templates of their own and shared pieces include each other without cycles, so nothing recurses.

Output (MaxOutputBytes), time (RenderTimeout) and concurrent renders (slots) are bounded at render.

Variables

View Source
var (
	ErrNoParts    = errors.New("template: no parts")
	ErrPartName   = errors.New("template: part name must be [a-z][a-z0-9_]* and unique")
	ErrPartKind   = errors.New("template: part kind must be text or html")
	ErrPartTooBig = errors.New("template: part exceeds 256 KiB")
	ErrTooMany    = errors.New("template: too many parts")
	ErrParse      = errors.New("template: parse")
	ErrRender     = errors.New("template: render")
	ErrDataTooBig = errors.New("template: data exceeds 1 MiB")
	ErrTooLong    = errors.New("output exceeds 1 MiB")
	ErrTooSlow    = errors.New("template: render exceeded 2s")
	ErrLanguage   = errors.New("template: not a language tag")
	// ErrBusy: renders that ran past their time still hold every slot;
	// retrying later can succeed.
	ErrBusy = errors.New("template: too many renders running")
)

Errors of Compile and Render; every one is final but ErrBusy.

View Source
var (
	ErrRangeSource = errors.New("range iterates only over data: a field or a variable holding one")
	ErrRangeDepth  = errors.New("ranges nest at most 2 deep")
	ErrDefine      = errors.New("define and block are not allowed: use a shared piece")
	ErrCycle       = errors.New("shared pieces include each other in a cycle")
	ErrDataItems   = errors.New("template: data holds more than 10000 elements")
)

Errors of the checks.

Functions

func Check

func Check(parts []Part) error

Check validates the parts' shape without compiling.

func CheckData added in v0.2.0

func CheckData(data map[string]any) error

CheckData bounds the elements a template can iterate over.

func DecodeData

func DecodeData(raw []byte) (map[string]any, error)

DecodeData parses the JSON object data of a render and bounds what a template can iterate over (see safety.go).

func ParseLanguage added in v0.2.0

func ParseLanguage(s string) (string, error)

ParseLanguage is the canonical BCP 47 form of a tag ("ru", "pt-BR").

Types

type Compiled

type Compiled struct {
	// contains filtered or unexported fields
}

Compiled is a template ready to render in one language.

func Compile

func Compile(parts []Part, partials []Partial, lang string) (*Compiled, error)

Compile parses every part of the template in lang with the partials it may include and checks what it may do (see safety.go). Problems come back one per failing part, joined.

func (*Compiled) Render

func (c *Compiled) Render(data map[string]any) (map[string]string, error)

Render executes every part with data; a failing part is a ProblemError. A part's output is bounded by MaxOutputBytes and the whole render by RenderTimeout.

type Part

type Part struct {
	Name   string `json:"name"`
	Kind   string `json:"kind"`
	Source string `json:"source,omitempty"`
}

Part is one output of a template in one language: its name, how it is escaped and its source.

type Partial

type Partial struct {
	Name  string
	Parts []Part
}

Partial is a shared piece in the language being compiled: a template whose parts other templates include by the template's name.

type ProblemError

type ProblemError struct {
	Part    string `json:"part"`
	Message string `json:"message"`
}

ProblemError is what a part is wrong about: for the console's editor.

func Problems

func Problems(err error) []ProblemError

Problems lists the problems an error carries (parse or render), in part order.

func (ProblemError) Error

func (p ProblemError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL