src/html/template/error.go

   1 // Copyright 2011 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 package template
   6
   7 import (
   8         "fmt"
   9         "text/template/parse"
  10 )
  11
  12 // Error describes a problem encountered during template Escaping.
  13 type Error struct {
  14         // ErrorCode describes the kind of error.
  15         ErrorCode ErrorCode
  16         // Node is the node that caused the problem, if known.
  17         // If not nil, it overrides Name and Line.
  18         Node parse.Node
  19         // Name is the name of the template in which the error was encountered.
  20         Name string
  21         // Line is the line number of the error in the template source or 0.
  22         Line int
  23         // Description is a human-readable description of the problem.
  24         Description string
  25 }
  26
  27 // ErrorCode is a code for a kind of error.
  28 type ErrorCode int
  29
  30 // We define codes for each error that manifests while escaping templates, but
  31 // escaped templates may also fail at runtime.
  32 //
  33 // Output: "ZgotmplZ"
  34 // Example:
  35 //
  36 //      <img src="{{.X}}">
  37 //      where {{.X}} evaluates to `javascript:...`
  38 //
  39 // Discussion:
  40 //
  41 //      "ZgotmplZ" is a special value that indicates that unsafe content reached a
  42 //      CSS or URL context at runtime. The output of the example will be
  43 //        <img src="#ZgotmplZ">
  44 //      If the data comes from a trusted source, use content types to exempt it
  45 //      from filtering: URL(`javascript:...`).
  46 const (
  47         // OK indicates the lack of an error.
  48         OK ErrorCode = iota
  49
  50         // ErrAmbigContext: "... appears in an ambiguous context within a URL"
  51         // Example:
  52         //   <a href="
  53         //      {{if .C}}
  54         //        /path/
  55         //      {{else}}
  56         //        /search?q=
  57         //      {{end}}
  58         //      {{.X}}
  59         //   ">
  60         // Discussion:
  61         //   {{.X}} is in an ambiguous URL context since, depending on {{.C}},
  62         //  it may be either a URL suffix or a query parameter.
  63         //   Moving {{.X}} into the condition removes the ambiguity:
  64         //   <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}">
  65         ErrAmbigContext
  66
  67         // ErrBadHTML: "expected space, attr name, or end of tag, but got ...",
  68         //   "... in unquoted attr", "... in attribute name"
  69         // Example:
  70         //   <a href = /search?q=foo>
  71         //   <href=foo>
  72         //   <form na<e=...>
  73         //   <option selected<
  74         // Discussion:
  75         //   This is often due to a typo in an HTML element, but some runes
  76         //   are banned in tag names, attribute names, and unquoted attribute
  77         //   values because they can tickle parser ambiguities.
  78         //   Quoting all attributes is the best policy.
  79         ErrBadHTML
  80
  81         // ErrBranchEnd: "{{if}} branches end in different contexts"
  82         // Example:
  83         //   {{if .C}}<a href="{{end}}{{.X}}
  84         // Discussion:
  85         //   Package html/template statically examines each path through an
  86         //   {{if}}, {{range}}, or {{with}} to escape any following pipelines.
  87         //   The example is ambiguous since {{.X}} might be an HTML text node,
  88         //   or a URL prefix in an HTML attribute. The context of {{.X}} is
  89         //   used to figure out how to escape it, but that context depends on
  90         //   the run-time value of {{.C}} which is not statically known.
  91         //
  92         //   The problem is usually something like missing quotes or angle
  93         //   brackets, or can be avoided by refactoring to put the two contexts
  94         //   into different branches of an if, range or with. If the problem
  95         //   is in a {{range}} over a collection that should never be empty,
  96         //   adding a dummy {{else}} can help.
  97         ErrBranchEnd
  98
  99         // ErrEndContext: "... ends in a non-text context: ..."
 100         // Examples:
 101         //   <div
 102         //   <div title="no close quote>
 103         //   <script>f()
 104         // Discussion:
 105         //   Executed templates should produce a DocumentFragment of HTML.
 106         //   Templates that end without closing tags will trigger this error.
 107         //   Templates that should not be used in an HTML context or that
 108         //   produce incomplete Fragments should not be executed directly.
 109         //
 110         //   {{define "main"}} <script>{{template "helper"}}</script> {{end}}
 111         //   {{define "helper"}} document.write(' <div title=" ') {{end}}
 112         //
 113         //   "helper" does not produce a valid document fragment, so should
 114         //   not be Executed directly.
 115         ErrEndContext
 116
 117         // ErrNoSuchTemplate: "no such template ..."
 118         // Examples:
 119         //   {{define "main"}}<div {{template "attrs"}}>{{end}}
 120         //   {{define "attrs"}}href="{{.URL}}"{{end}}
 121         // Discussion:
 122         //   Package html/template looks through template calls to compute the
 123         //   context.
 124         //   Here the {{.URL}} in "attrs" must be treated as a URL when called
 125         //   from "main", but you will get this error if "attrs" is not defined
 126         //   when "main" is parsed.
 127         ErrNoSuchTemplate
 128
 129         // ErrOutputContext: "cannot compute output context for template ..."
 130         // Examples:
 131         //   {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
 132         // Discussion:
 133         //   A recursive template does not end in the same context in which it
 134         //   starts, and a reliable output context cannot be computed.
 135         //   Look for typos in the named template.
 136         //   If the template should not be called in the named start context,
 137         //   look for calls to that template in unexpected contexts.
 138         //   Maybe refactor recursive templates to not be recursive.
 139         ErrOutputContext
 140
 141         // ErrPartialCharset: "unfinished JS regexp charset in ..."
 142         // Example:
 143         //     <script>var pattern = /foo[{{.Chars}}]/</script>
 144         // Discussion:
 145         //   Package html/template does not support interpolation into regular
 146         //   expression literal character sets.
 147         ErrPartialCharset
 148
 149         // ErrPartialEscape: "unfinished escape sequence in ..."
 150         // Example:
 151         //   <script>alert("\{{.X}}")</script>
 152         // Discussion:
 153         //   Package html/template does not support actions following a
 154         //   backslash.
 155         //   This is usually an error and there are better solutions; for
 156         //   example
 157         //     <script>alert("{{.X}}")</script>
 158         //   should work, and if {{.X}} is a partial escape sequence such as
 159         //   "xA0", mark the whole sequence as safe content: JSStr(`\xA0`)
 160         ErrPartialEscape
 161
 162         // ErrRangeLoopReentry: "on range loop re-entry: ..."
 163         // Example:
 164         //   <script>var x = [{{range .}}'{{.}},{{end}}]</script>
 165         // Discussion:
 166         //   If an iteration through a range would cause it to end in a
 167         //   different context than an earlier pass, there is no single context.
 168         //   In the example, there is missing a quote, so it is not clear
 169         //   whether {{.}} is meant to be inside a JS string or in a JS value
 170         //   context. The second iteration would produce something like
 171         //
 172         //     <script>var x = ['firstValue,'secondValue]</script>
 173         ErrRangeLoopReentry
 174
 175         // ErrSlashAmbig: '/' could start a division or regexp.
 176         // Example:
 177         //   <script>
 178         //     {{if .C}}var x = 1{{end}}
 179         //     /-{{.N}}/i.test(x) ? doThis : doThat();
 180         //   </script>
 181         // Discussion:
 182         //   The example above could produce `var x = 1/-2/i.test(s)...`
 183         //   in which the first '/' is a mathematical division operator or it
 184         //   could produce `/-2/i.test(s)` in which the first '/' starts a
 185         //   regexp literal.
 186         //   Look for missing semicolons inside branches, and maybe add
 187         //   parentheses to make it clear which interpretation you intend.
 188         ErrSlashAmbig
 189
 190         // ErrPredefinedEscaper: "predefined escaper ... disallowed in template"
 191         // Example:
 192         //   <div class={{. | html}}>Hello<div>
 193         // Discussion:
 194         //   Package html/template already contextually escapes all pipelines to
 195         //   produce HTML output safe against code injection. Manually escaping
 196         //   pipeline output using the predefined escapers "html" or "urlquery" is
 197         //   unnecessary, and may affect the correctness or safety of the escaped
 198         //   pipeline output in Go 1.8 and earlier.
 199         //
 200         //   In most cases, such as the given example, this error can be resolved by
 201         //   simply removing the predefined escaper from the pipeline and letting the
 202         //   contextual autoescaper handle the escaping of the pipeline. In other
 203         //   instances, where the predefined escaper occurs in the middle of a
 204         //   pipeline where subsequent commands expect escaped input, e.g.
 205         //     {{.X | html | makeALink}}
 206         //   where makeALink does
 207         //     return `<a href="`+input+`">link</a>`
 208         //   consider refactoring the surrounding template to make use of the
 209         //   contextual autoescaper, i.e.
 210         //     <a href="{{.X}}">link</a>
 211         //
 212         //   To ease migration to Go 1.9 and beyond, "html" and "urlquery" will
 213         //   continue to be allowed as the last command in a pipeline. However, if the
 214         //   pipeline occurs in an unquoted attribute value context, "html" is
 215         //   disallowed. Avoid using "html" and "urlquery" entirely in new templates.
 216         ErrPredefinedEscaper
 217
 218         // ErrJSTemplate: "... appears in a JS template literal"
 219         // Example:
 220         //     <script>var tmpl = `{{.Interp}}`</script>
 221         // Discussion:
 222         //   Package html/template does not support actions inside of JS template
 223         //   literals.
 224         //
 225         // Deprecated: ErrJSTemplate is no longer returned when an action is present
 226         // in a JS template literal. Actions inside of JS template literals are now
 227         // escaped as expected.
 228         ErrJSTemplate
 229 )
 230
 231 func (e *Error) Error() string {
 232         switch {
 233         case e.Node != nil:
 234                 loc, _ := (*parse.Tree)(nil).ErrorContext(e.Node)
 235                 return fmt.Sprintf("html/template:%s: %s", loc, e.Description)
 236         case e.Line != 0:
 237                 return fmt.Sprintf("html/template:%s:%d: %s", e.Name, e.Line, e.Description)
 238         case e.Name != "":
 239                 return fmt.Sprintf("html/template:%s: %s", e.Name, e.Description)
 240         }
 241         return "html/template: " + e.Description
 242 }
 243
 244 // errorf creates an error given a format string f and args.
 245 // The template Name still needs to be supplied.
 246 func errorf(k ErrorCode, node parse.Node, line int, f string, args ...any) *Error {
 247         return &Error{k, node, "", line, fmt.Sprintf(f, args...)}
 248 }