Source file 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 // Examples: 83 // {{if .C}}<a href="{{end}}{{.X}} 84 // <script {{with .T}}type="{{.}}"{{end}}> 85 // Discussion: 86 // Package html/template statically examines each path through an 87 // {{if}}, {{range}}, or {{with}} to escape any following pipelines. 88 // The first example is ambiguous since {{.X}} might be an HTML text node, 89 // or a URL prefix in an HTML attribute. The context of {{.X}} is 90 // used to figure out how to escape it, but that context depends on 91 // the run-time value of {{.C}} which is not statically known. 92 // The second example is ambiguous as the script type attribute 93 // can change the type of escaping needed for the script contents. 94 // 95 // The problem is usually something like missing quotes or angle 96 // brackets, or can be avoided by refactoring to put the two contexts 97 // into different branches of an if, range or with. If the problem 98 // is in a {{range}} over a collection that should never be empty, 99 // adding a dummy {{else}} can help. 100 ErrBranchEnd 101 102 // ErrEndContext: "... ends in a non-text context: ..." 103 // Examples: 104 // <div 105 // <div title="no close quote> 106 // <script>f() 107 // Discussion: 108 // Executed templates should produce a DocumentFragment of HTML. 109 // Templates that end without closing tags will trigger this error. 110 // Templates that should not be used in an HTML context or that 111 // produce incomplete Fragments should not be executed directly. 112 // 113 // {{define "main"}} <script>{{template "helper"}}</script> {{end}} 114 // {{define "helper"}} document.write(' <div title=" ') {{end}} 115 // 116 // "helper" does not produce a valid document fragment, so should 117 // not be Executed directly. 118 ErrEndContext 119 120 // ErrNoSuchTemplate: "no such template ..." 121 // Examples: 122 // {{define "main"}}<div {{template "attrs"}}>{{end}} 123 // {{define "attrs"}}href="{{.URL}}"{{end}} 124 // Discussion: 125 // Package html/template looks through template calls to compute the 126 // context. 127 // Here the {{.URL}} in "attrs" must be treated as a URL when called 128 // from "main", but you will get this error if "attrs" is not defined 129 // when "main" is parsed. 130 ErrNoSuchTemplate 131 132 // ErrOutputContext: "cannot compute output context for template ..." 133 // Examples: 134 // {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}} 135 // Discussion: 136 // A recursive template does not end in the same context in which it 137 // starts, and a reliable output context cannot be computed. 138 // Look for typos in the named template. 139 // If the template should not be called in the named start context, 140 // look for calls to that template in unexpected contexts. 141 // Maybe refactor recursive templates to not be recursive. 142 ErrOutputContext 143 144 // ErrPartialCharset: "unfinished JS regexp charset in ..." 145 // Example: 146 // <script>var pattern = /foo[{{.Chars}}]/</script> 147 // Discussion: 148 // Package html/template does not support interpolation into regular 149 // expression literal character sets. 150 ErrPartialCharset 151 152 // ErrPartialEscape: "unfinished escape sequence in ..." 153 // Example: 154 // <script>alert("\{{.X}}")</script> 155 // Discussion: 156 // Package html/template does not support actions following a 157 // backslash. 158 // This is usually an error and there are better solutions; for 159 // example 160 // <script>alert("{{.X}}")</script> 161 // should work, and if {{.X}} is a partial escape sequence such as 162 // "xA0", mark the whole sequence as safe content: JSStr(`\xA0`) 163 ErrPartialEscape 164 165 // ErrRangeLoopReentry: "on range loop re-entry: ..." 166 // Example: 167 // <script>var x = [{{range .}}'{{.}},{{end}}]</script> 168 // Discussion: 169 // If an iteration through a range would cause it to end in a 170 // different context than an earlier pass, there is no single context. 171 // In the example, there is missing a quote, so it is not clear 172 // whether {{.}} is meant to be inside a JS string or in a JS value 173 // context. The second iteration would produce something like 174 // 175 // <script>var x = ['firstValue,'secondValue]</script> 176 ErrRangeLoopReentry 177 178 // ErrSlashAmbig: '/' could start a division or regexp. 179 // Example: 180 // <script> 181 // {{if .C}}var x = 1{{end}} 182 // /-{{.N}}/i.test(x) ? doThis : doThat(); 183 // </script> 184 // Discussion: 185 // The example above could produce `var x = 1/-2/i.test(s)...` 186 // in which the first '/' is a mathematical division operator or it 187 // could produce `/-2/i.test(s)` in which the first '/' starts a 188 // regexp literal. 189 // Look for missing semicolons inside branches, and maybe add 190 // parentheses to make it clear which interpretation you intend. 191 ErrSlashAmbig 192 193 // ErrPredefinedEscaper: "predefined escaper ... disallowed in template" 194 // Example: 195 // <div class={{. | html}}>Hello<div> 196 // Discussion: 197 // Package html/template already contextually escapes all pipelines to 198 // produce HTML output safe against code injection. Manually escaping 199 // pipeline output using the predefined escapers "html" or "urlquery" is 200 // unnecessary, and may affect the correctness or safety of the escaped 201 // pipeline output in Go 1.8 and earlier. 202 // 203 // In most cases, such as the given example, this error can be resolved by 204 // simply removing the predefined escaper from the pipeline and letting the 205 // contextual autoescaper handle the escaping of the pipeline. In other 206 // instances, where the predefined escaper occurs in the middle of a 207 // pipeline where subsequent commands expect escaped input, e.g. 208 // {{.X | html | makeALink}} 209 // where makeALink does 210 // return `<a href="`+input+`">link</a>` 211 // consider refactoring the surrounding template to make use of the 212 // contextual autoescaper, i.e. 213 // <a href="{{.X}}">link</a> 214 // 215 // To ease migration to Go 1.9 and beyond, "html" and "urlquery" will 216 // continue to be allowed as the last command in a pipeline. However, if the 217 // pipeline occurs in an unquoted attribute value context, "html" is 218 // disallowed. Avoid using "html" and "urlquery" entirely in new templates. 219 ErrPredefinedEscaper 220 221 // ErrJSTemplate: "... appears in a JS template literal" 222 // Example: 223 // <script>var tmpl = `{{.Interp}}`</script> 224 // Discussion: 225 // Package html/template does not support actions inside of JS template 226 // literals. 227 // 228 // Deprecated: ErrJSTemplate is no longer returned when an action is present 229 // in a JS template literal. Actions inside of JS template literals are now 230 // escaped as expected. 231 ErrJSTemplate 232 ) 233 234 func (e *Error) Error() string { 235 switch { 236 case e.Node != nil: 237 loc, _ := (*parse.Tree)(nil).ErrorContext(e.Node) 238 return fmt.Sprintf("html/template:%s: %s", loc, e.Description) 239 case e.Line != 0: 240 return fmt.Sprintf("html/template:%s:%d: %s", e.Name, e.Line, e.Description) 241 case e.Name != "": 242 return fmt.Sprintf("html/template:%s: %s", e.Name, e.Description) 243 } 244 return "html/template: " + e.Description 245 } 246 247 // errorf creates an error given a format string f and args. 248 // The template Name still needs to be supplied. 249 func errorf(k ErrorCode, node parse.Node, line int, f string, args ...any) *Error { 250 return &Error{k, node, "", line, fmt.Sprintf(f, args...)} 251 } 252