123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233 |
- // Copyright 2011 The Go Authors. All rights reserved.
- // Use of this source code is governed by a BSD-style
- // license that can be found in the LICENSE file.
- package template
- import (
- "fmt"
- "text/template/parse"
- )
- // Error describes a problem encountered during template Escaping.
- type Error struct {
- // ErrorCode describes the kind of error.
- ErrorCode ErrorCode
- // Node is the node that caused the problem, if known.
- // If not nil, it overrides Name and Line.
- Node parse.Node
- // Name is the name of the template in which the error was encountered.
- Name string
- // Line is the line number of the error in the template source or 0.
- Line int
- // Description is a human-readable description of the problem.
- Description string
- }
- // ErrorCode is a code for a kind of error.
- type ErrorCode int
- // We define codes for each error that manifests while escaping templates, but
- // escaped templates may also fail at runtime.
- //
- // Output: "ZgotmplZ"
- // Example:
- // <img src="{{.X}}">
- // where {{.X}} evaluates to `javascript:...`
- // Discussion:
- // "ZgotmplZ" is a special value that indicates that unsafe content reached a
- // CSS or URL context at runtime. The output of the example will be
- // <img src="#ZgotmplZ">
- // If the data comes from a trusted source, use content types to exempt it
- // from filtering: URL(`javascript:...`).
- const (
- // OK indicates the lack of an error.
- OK ErrorCode = iota
- // ErrAmbigContext: "... appears in an ambiguous context within a URL"
- // Example:
- // <a href="
- // {{if .C}}
- // /path/
- // {{else}}
- // /search?q=
- // {{end}}
- // {{.X}}
- // ">
- // Discussion:
- // {{.X}} is in an ambiguous URL context since, depending on {{.C}},
- // it may be either a URL suffix or a query parameter.
- // Moving {{.X}} into the condition removes the ambiguity:
- // <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}">
- ErrAmbigContext
- // ErrBadHTML: "expected space, attr name, or end of tag, but got ...",
- // "... in unquoted attr", "... in attribute name"
- // Example:
- // <a href = /search?q=foo>
- // <href=foo>
- // <form na<e=...>
- // <option selected<
- // Discussion:
- // This is often due to a typo in an HTML element, but some runes
- // are banned in tag names, attribute names, and unquoted attribute
- // values because they can tickle parser ambiguities.
- // Quoting all attributes is the best policy.
- ErrBadHTML
- // ErrBranchEnd: "{{if}} branches end in different contexts"
- // Example:
- // {{if .C}}<a href="{{end}}{{.X}}
- // Discussion:
- // Package html/template statically examines each path through an
- // {{if}}, {{range}}, or {{with}} to escape any following pipelines.
- // The example is ambiguous since {{.X}} might be an HTML text node,
- // or a URL prefix in an HTML attribute. The context of {{.X}} is
- // used to figure out how to escape it, but that context depends on
- // the run-time value of {{.C}} which is not statically known.
- //
- // The problem is usually something like missing quotes or angle
- // brackets, or can be avoided by refactoring to put the two contexts
- // into different branches of an if, range or with. If the problem
- // is in a {{range}} over a collection that should never be empty,
- // adding a dummy {{else}} can help.
- ErrBranchEnd
- // ErrEndContext: "... ends in a non-text context: ..."
- // Examples:
- // <div
- // <div title="no close quote>
- // <script>f()
- // Discussion:
- // Executed templates should produce a DocumentFragment of HTML.
- // Templates that end without closing tags will trigger this error.
- // Templates that should not be used in an HTML context or that
- // produce incomplete Fragments should not be executed directly.
- //
- // {{define "main"}} <script>{{template "helper"}}</script> {{end}}
- // {{define "helper"}} document.write(' <div title=" ') {{end}}
- //
- // "helper" does not produce a valid document fragment, so should
- // not be Executed directly.
- ErrEndContext
- // ErrNoSuchTemplate: "no such template ..."
- // Examples:
- // {{define "main"}}<div {{template "attrs"}}>{{end}}
- // {{define "attrs"}}href="{{.URL}}"{{end}}
- // Discussion:
- // Package html/template looks through template calls to compute the
- // context.
- // Here the {{.URL}} in "attrs" must be treated as a URL when called
- // from "main", but you will get this error if "attrs" is not defined
- // when "main" is parsed.
- ErrNoSuchTemplate
- // ErrOutputContext: "cannot compute output context for template ..."
- // Examples:
- // {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
- // Discussion:
- // A recursive template does not end in the same context in which it
- // starts, and a reliable output context cannot be computed.
- // Look for typos in the named template.
- // If the template should not be called in the named start context,
- // look for calls to that template in unexpected contexts.
- // Maybe refactor recursive templates to not be recursive.
- ErrOutputContext
- // ErrPartialCharset: "unfinished JS regexp charset in ..."
- // Example:
- // <script>var pattern = /foo[{{.Chars}}]/</script>
- // Discussion:
- // Package html/template does not support interpolation into regular
- // expression literal character sets.
- ErrPartialCharset
- // ErrPartialEscape: "unfinished escape sequence in ..."
- // Example:
- // <script>alert("\{{.X}}")</script>
- // Discussion:
- // Package html/template does not support actions following a
- // backslash.
- // This is usually an error and there are better solutions; for
- // example
- // <script>alert("{{.X}}")</script>
- // should work, and if {{.X}} is a partial escape sequence such as
- // "xA0", mark the whole sequence as safe content: JSStr(`\xA0`)
- ErrPartialEscape
- // ErrRangeLoopReentry: "on range loop re-entry: ..."
- // Example:
- // <script>var x = [{{range .}}'{{.}},{{end}}]</script>
- // Discussion:
- // If an iteration through a range would cause it to end in a
- // different context than an earlier pass, there is no single context.
- // In the example, there is missing a quote, so it is not clear
- // whether {{.}} is meant to be inside a JS string or in a JS value
- // context. The second iteration would produce something like
- //
- // <script>var x = ['firstValue,'secondValue]</script>
- ErrRangeLoopReentry
- // ErrSlashAmbig: '/' could start a division or regexp.
- // Example:
- // <script>
- // {{if .C}}var x = 1{{end}}
- // /-{{.N}}/i.test(x) ? doThis : doThat();
- // </script>
- // Discussion:
- // The example above could produce `var x = 1/-2/i.test(s)...`
- // in which the first '/' is a mathematical division operator or it
- // could produce `/-2/i.test(s)` in which the first '/' starts a
- // regexp literal.
- // Look for missing semicolons inside branches, and maybe add
- // parentheses to make it clear which interpretation you intend.
- ErrSlashAmbig
- // ErrPredefinedEscaper: "predefined escaper ... disallowed in template"
- // Example:
- // <div class={{. | html}}>Hello<div>
- // Discussion:
- // Package html/template already contextually escapes all pipelines to
- // produce HTML output safe against code injection. Manually escaping
- // pipeline output using the predefined escapers "html" or "urlquery" is
- // unnecessary, and may affect the correctness or safety of the escaped
- // pipeline output in Go 1.8 and earlier.
- //
- // In most cases, such as the given example, this error can be resolved by
- // simply removing the predefined escaper from the pipeline and letting the
- // contextual autoescaper handle the escaping of the pipeline. In other
- // instances, where the predefined escaper occurs in the middle of a
- // pipeline where subsequent commands expect escaped input, e.g.
- // {{.X | html | makeALink}}
- // where makeALink does
- // return `<a href="`+input+`">link</a>`
- // consider refactoring the surrounding template to make use of the
- // contextual autoescaper, i.e.
- // <a href="{{.X}}">link</a>
- //
- // To ease migration to Go 1.9 and beyond, "html" and "urlquery" will
- // continue to be allowed as the last command in a pipeline. However, if the
- // pipeline occurs in an unquoted attribute value context, "html" is
- // disallowed. Avoid using "html" and "urlquery" entirely in new templates.
- ErrPredefinedEscaper
- )
- func (e *Error) Error() string {
- switch {
- case e.Node != nil:
- loc, _ := (*parse.Tree)(nil).ErrorContext(e.Node)
- return fmt.Sprintf("html/template:%s: %s", loc, e.Description)
- case e.Line != 0:
- return fmt.Sprintf("html/template:%s:%d: %s", e.Name, e.Line, e.Description)
- case e.Name != "":
- return fmt.Sprintf("html/template:%s: %s", e.Name, e.Description)
- }
- return "html/template: " + e.Description
- }
- // errorf creates an error given a format string f and args.
- // The template Name still needs to be supplied.
- func errorf(k ErrorCode, node parse.Node, line int, f string, args ...interface{}) *Error {
- return &Error{k, node, "", line, fmt.Sprintf(f, args...)}
- }
|