Documentation
¶
Overview ¶
Package htmlinject provides utilities to pre-process HTML templates and inject additional parts into them before parsing.
Index ¶
- Constants
- Variables
- func LoadFiles(tpl *template.Template, lcfg LoadConfig, filenames ...template.TrustedSource) (*template.Template, error)
- func LoadGlob(tpl *template.Template, lcfg LoadConfig, pattern template.TrustedSource) (*template.Template, error)
- func LoadGlobEmbed(tpl *template.Template, lcfg LoadConfig, pattern template.TrustedSource, ...) (*template.Template, error)
- func LoadTrustedTemplate(tpl *template.Template, lcfg LoadConfig, src template.TrustedTemplate) (*template.Template, error)
- func Transform(src io.Reader, cfg ...TransformConfig) (string, error)
- type LoadConfig
- type Rule
- type TransformConfig
Examples ¶
Constants ¶
const CSPNoncesDefaultFuncName = "CSPNonce"
CSPNoncesDefaultFuncName is the default func name for the func that generates CSP nonces.
const XSRFTokensDefaultFuncName = `XSRFToken`
XSRFTokensDefaultFuncName is the default func name for the func that generates XSRF tokens.
Variables ¶
var CSPNoncesDefault = CSPNonces(`nonce="{{` + CSPNoncesDefaultFuncName + `}}"`)
CSPNoncesDefault is the default config for CSP Nonces. The rewritten template expects the CSPNonce Func to be available in the template to provide nonces.
var XSRFTokensDefault = XSRFTokens(`<input type="hidden" name="xsrf-token" value="{{` + XSRFTokensDefaultFuncName + `}}">`)
XSRFTokensDefault is the default config to add hidden inputs to forms to provide an anti-XSRF token. The rewritten template expects the XSRFToken Func to be available in the template to provide tokens and sets the name for the sent value to be "xsrf-token".
Functions ¶
func LoadFiles ¶
func LoadFiles(tpl *template.Template, lcfg LoadConfig, filenames ...template.TrustedSource) (*template.Template, error)
LoadFiles matches the behavior of safehtml.ParseFiles but runs a transformation on every loaded template.
func LoadGlob ¶
func LoadGlob(tpl *template.Template, lcfg LoadConfig, pattern template.TrustedSource) (*template.Template, error)
LoadGlob matches the behavior of safehtml.ParseGlob but runs a transformation on every loaded template.
func LoadGlobEmbed ¶
func LoadGlobEmbed(tpl *template.Template, lcfg LoadConfig, pattern template.TrustedSource, fsys embed.FS) (*template.Template, error)
LoadGlobEmbed is like LoadGlob but works on an embedded filesystem.
func LoadTrustedTemplate ¶
func LoadTrustedTemplate(tpl *template.Template, lcfg LoadConfig, src template.TrustedTemplate) (*template.Template, error)
LoadTrustedTemplate processes the given TrustedTemplate with the specified default configurations and adds it to the given template. If the given template is nil a new one is created.
func Transform ¶
func Transform(src io.Reader, cfg ...TransformConfig) (string, error)
Transform rewrites the given template according to the given configs. If the passed io.Rewriter has a `Size() int64` method it will be used to pre-allocate buffers.
Example ¶
const in = `
<html>
<head>
<link rel=preload as="script" src="gopher.js">
</head>
<body>
{{.Content}}
<script type="application/javascript">alert("script")</script>
<form>
First name:<br>
<input type="text" name="firstname"><br>
Last name:<br>
<input type="text" name="lastname">
</form>
</body>
</html>
`
got, err := Transform(strings.NewReader(in), CSPNoncesDefault, XSRFTokensDefault)
if err != nil {
// handle error
panic(err)
}
template.Must(template.New("example transform").Funcs(map[string]interface{}{
"XSRFToken": func() string { return "XSRFToken-secret" },
"CSPNonce": func() string { return "CSPNonce-secret" },
}).Parse(got)).Execute(os.Stdout, map[string]string{"Content": "This is some content"})
Output: <html> <head> <link nonce="CSPNonce-secret" rel=preload as="script" src="gopher.js"> </head> <body> This is some content <script nonce="CSPNonce-secret" type="application/javascript">alert("script")</script> <form><input type="hidden" name="xsrf-token" value="XSRFToken-secret"> First name:<br> <input type="text" name="firstname"><br> Last name:<br> <input type="text" name="lastname"> </form> </body> </html>
Types ¶
type LoadConfig ¶
type LoadConfig struct {
// DisableCSP disables CSP autononcing
DisableCSP bool
// DisableXSRF disables XSRF token injection
DisableXSRF bool
}
LoadConfig is a configuration to use with loaders when processing a template.
type Rule ¶
type Rule struct {
// Name is used for debug purposes in case rewriting fails.
Name string
// OnTag is the tag to be used to trigger the rule.
OnTag string
// WithAttributes is a filter applied on tags to decide whether to run the Rule:
// only tags with the given attributes key:value will be matched.
WithAttributes map[string]string
// AddAttributes is a list of strings to add to the HTML as attributes.
// All the given strings will be appended verbatim after the matched tag so they
// should be prefixed with a space.
AddAttributes []string
// AddNodes is a list of nodes to append immediately after the opening tag that matched.
// This means that for elements that have a matching closing tag the added node will be
// a child node, for self-closing tags it will be a sibling.
AddNodes []string
}
Rule is a directive to instruct Transform on how to rewrite the given template.
type TransformConfig ¶
type TransformConfig []Rule
TransformConfig is a slice of Rules that are somehow related to each other.
func CSPNonces ¶
func CSPNonces(nonceAttr string) TransformConfig
CSPNonces constructs a Config to add CSP nonces to a template. The given nonce attribute will be automatically prefixed with the required empty space.
func XSRFTokens ¶
func XSRFTokens(inputTag string) TransformConfig
XSRFTokens constructs a Config to add the given string as a child node to forms.
Source Files