Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS
Mirrored from https://github.com/Slazee/caddy.git
Synced Nov 12, 22:00 UTC
templates: Clarify `include` args docs, add `.ClientIP` (#5898)
Francis Lavoie committed
Oct 15, 2023 at 20:58 UTC
0900844c813b8d02023c514085d84e5a52df49d7
2 files changed
+46
-21
modules/caddyhttp/templates/templates.go
+33
-20
@@ -46,7 +46,8 @@ func init() {
46
//
47
// ##### `.Args`
48
//
49
-// A slice of arguments passed to this page/context, for example as the result of a `include`.
49
+// A slice of arguments passed to this page/context, for example
50
+// as the result of a [`include`](#include).
51
//
52
// ```
53
// {{index .Args 0}} // first argument
@@ -103,8 +104,8 @@ func init() {
104
// Reads and returns the contents of another file, and parses it
105
// as a template, adding any template definitions to the template
106
// stack. If there are no definitions, the filepath will be the
106
-// definition name. Any {{ define }} blocks will be accessible by
107
-// {{ template }} or {{ block }}. Imports must happen before the
107
+// definition name. Any `{{ define }}` blocks will be accessible by
108
+// `{{ template }}` or `{{ block }}`. Imports must happen before the
109
// template or block action is called. Note that the contents are
110
// NOT escaped, so you should only import trusted template files.
111
//
@@ -125,12 +126,13 @@ func init() {
126
//
127
// Includes the contents of another file, rendering it in-place.
128
// Optionally can pass key-value pairs as arguments to be accessed
128
-// by the included file. Note that the contents are NOT escaped,
129
-// so you should only include trusted template files.
129
+// by the included file. Use [`.Args N`](#args) to access the N-th
130
+// argument, 0-indexed. Note that the contents are NOT escaped, so
131
+// you should only include trusted template files.
132
//
133
// ```
134
// {{include "path/to/file.html"}} // no arguments
133
-// {{include "path/to/file.html" "arg1" 2 "value 3"}} // with arguments
135
+// {{include "path/to/file.html" "arg0" 1 "value 2"}} // with arguments
136
// ```
137
//
138
// ##### `readFile`
@@ -145,7 +147,8 @@ func init() {
147
//
148
// ##### `listFiles`
149
//
148
-// Returns a list of the files in the given directory, which is relative to the template context's file root.
150
+// Returns a list of the files in the given directory, which is relative
151
+// to the template context's file root.
152
//
153
// ```
154
// {{listFiles "/mydir"}}
@@ -165,12 +168,21 @@ func init() {
168
//
169
// ##### `.RemoteIP`
170
//
168
-// Returns the client's IP address.
171
+// Returns the connection's IP address.
172
//
173
// ```
174
// {{.RemoteIP}}
175
// ```
176
//
177
+// ##### `.ClientIP`
178
+//
179
+// Returns the real client's IP address, if `trusted_proxies` was configured,
180
+// otherwise returns the connection's IP address.
181
+//
182
+// ```
183
+// {{.ClientIP}}
184
+// ```
185
+//
186
// ##### `.Req`
187
//
188
// Accesses the current HTTP request, which has various fields, including:
@@ -186,7 +198,8 @@ func init() {
198
//
199
// ##### `.OriginalReq`
200
//
189
-// Like .Req, except it accesses the original HTTP request before rewrites or other internal modifications.
201
+// Like [`.Req`](#req), except it accesses the original HTTP
202
+// request before rewrites or other internal modifications.
203
//
204
// ##### `.RespHeader.Add`
205
//
@@ -222,11 +235,13 @@ func init() {
235
//
236
// ##### `splitFrontMatter`
237
//
225
-// Splits front matter out from the body. Front matter is metadata that appears at the very beginning of a file or string. Front matter can be in YAML, TOML, or JSON formats:
238
+// Splits front matter out from the body. Front matter is metadata that
239
+// appears at the very beginning of a file or string. Front matter can
240
+// be in YAML, TOML, or JSON formats:
241
//
242
// **TOML** front matter starts and ends with `+++`:
243
//
229
-// ```
244
+// ```toml
245
// +++
246
// template = "blog"
247
// title = "Blog Homepage"
@@ -236,7 +251,7 @@ func init() {
251
//
252
// **YAML** is surrounded by `---`:
253
//
239
-// ```
254
+// ```yaml
255
// ---
256
// template: blog
257
// title: Blog Homepage
@@ -246,14 +261,12 @@ func init() {
261
//
262
// **JSON** is simply `{` and `}`:
263
//
249
-// ```
250
-//
251
-// {
252
-// "template": "blog",
253
-// "title": "Blog Homepage",
254
-// "sitename": "A Caddy site"
255
-// }
256
-//
264
+// ```json
265
+// {
266
+// "template": "blog",
267
+// "title": "Blog Homepage",
268
+// "sitename": "A Caddy site"
269
+// }
270
// ```
271
//
272
// The resulting front matter will be made available like so:
modules/caddyhttp/templates/tplcontext.go
+13
-1
@@ -265,7 +265,7 @@ func (c TemplateContext) Cookie(name string) string {
265
return ""
266
}
267
268
-// RemoteIP gets the IP address of the client making the request.
268
+// RemoteIP gets the IP address of the connection's remote IP.
269
func (c TemplateContext) RemoteIP() string {
270
ip, _, err := net.SplitHostPort(c.Req.RemoteAddr)
271
if err != nil {
@@ -274,6 +274,18 @@ func (c TemplateContext) RemoteIP() string {
274
return ip
275
}
276
277
+// ClientIP gets the IP address of the real client making the request
278
+// if the request is trusted (see trusted_proxies), otherwise returns
279
+// the connection's remote IP.
280
+func (c TemplateContext) ClientIP() string {
281
+ address := caddyhttp.GetVar(c.Req.Context(), caddyhttp.ClientIPVarKey).(string)
282
+ clientIP, _, err := net.SplitHostPort(address)
283
+ if err != nil {
284
+ clientIP = address // no port
285
+ }
286
+ return clientIP
287
+}
288
+
289
// Host returns the hostname portion of the Host header
290
// from the HTTP request.
291
func (c TemplateContext) Host() (string, error) {