From db1c825bedd9e82a292c6d43da3c29c3ba4ef827 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sun, 15 Oct 2023 09:33:41 -0400 Subject: [PATCH 1/2] templates: Clarify `include` args docs --- modules/caddyhttp/templates/templates.go | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/caddyhttp/templates/templates.go b/modules/caddyhttp/templates/templates.go index 65359d9e9aa..9f3b9245868 100644 --- a/modules/caddyhttp/templates/templates.go +++ b/modules/caddyhttp/templates/templates.go @@ -125,12 +125,13 @@ func init() { // // Includes the contents of another file, rendering it in-place. // Optionally can pass key-value pairs as arguments to be accessed -// by the included file. Note that the contents are NOT escaped, -// so you should only include trusted template files. +// by the included file. Use [`.Args N`](#args) to access the N-th +// argument, 0-indexed. Note that the contents are NOT escaped, so +// you should only include trusted template files. // // ``` // {{include "path/to/file.html"}} // no arguments -// {{include "path/to/file.html" "arg1" 2 "value 3"}} // with arguments +// {{include "path/to/file.html" "arg0" 1 "value 2"}} // with arguments // ``` // // ##### `readFile` From f89f4043a4d2e5576d1afabb595bf73d3398c759 Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sun, 15 Oct 2023 09:57:04 -0400 Subject: [PATCH 2/2] More docs cleanup, add `.ClientIP` --- modules/caddyhttp/templates/templates.go | 46 ++++++++++++++--------- modules/caddyhttp/templates/tplcontext.go | 14 ++++++- 2 files changed, 42 insertions(+), 18 deletions(-) diff --git a/modules/caddyhttp/templates/templates.go b/modules/caddyhttp/templates/templates.go index 9f3b9245868..4da02b580ca 100644 --- a/modules/caddyhttp/templates/templates.go +++ b/modules/caddyhttp/templates/templates.go @@ -46,7 +46,8 @@ func init() { // // ##### `.Args` // -// A slice of arguments passed to this page/context, for example as the result of a `include`. +// A slice of arguments passed to this page/context, for example +// as the result of a [`include`](#include). // // ``` // {{index .Args 0}} // first argument @@ -103,8 +104,8 @@ func init() { // Reads and returns the contents of another file, and parses it // as a template, adding any template definitions to the template // stack. If there are no definitions, the filepath will be the -// definition name. Any {{ define }} blocks will be accessible by -// {{ template }} or {{ block }}. Imports must happen before the +// definition name. Any `{{ define }}` blocks will be accessible by +// `{{ template }}` or `{{ block }}`. Imports must happen before the // template or block action is called. Note that the contents are // NOT escaped, so you should only import trusted template files. // @@ -146,7 +147,8 @@ func init() { // // ##### `listFiles` // -// Returns a list of the files in the given directory, which is relative to the template context's file root. +// Returns a list of the files in the given directory, which is relative +// to the template context's file root. // // ``` // {{listFiles "/mydir"}} @@ -166,12 +168,21 @@ func init() { // // ##### `.RemoteIP` // -// Returns the client's IP address. +// Returns the connection's IP address. // // ``` // {{.RemoteIP}} // ``` // +// ##### `.ClientIP` +// +// Returns the real client's IP address, if `trusted_proxies` was configured, +// otherwise returns the connection's IP address. +// +// ``` +// {{.ClientIP}} +// ``` +// // ##### `.Req` // // Accesses the current HTTP request, which has various fields, including: @@ -187,7 +198,8 @@ func init() { // // ##### `.OriginalReq` // -// Like .Req, except it accesses the original HTTP request before rewrites or other internal modifications. +// Like [`.Req`](#req), except it accesses the original HTTP +// request before rewrites or other internal modifications. // // ##### `.RespHeader.Add` // @@ -223,11 +235,13 @@ func init() { // // ##### `splitFrontMatter` // -// 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: +// 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: // // **TOML** front matter starts and ends with `+++`: // -// ``` +// ```toml // +++ // template = "blog" // title = "Blog Homepage" @@ -237,7 +251,7 @@ func init() { // // **YAML** is surrounded by `---`: // -// ``` +// ```yaml // --- // template: blog // title: Blog Homepage @@ -247,14 +261,12 @@ func init() { // // **JSON** is simply `{` and `}`: // -// ``` -// -// { -// "template": "blog", -// "title": "Blog Homepage", -// "sitename": "A Caddy site" -// } -// +// ```json +// { +// "template": "blog", +// "title": "Blog Homepage", +// "sitename": "A Caddy site" +// } // ``` // // The resulting front matter will be made available like so: diff --git a/modules/caddyhttp/templates/tplcontext.go b/modules/caddyhttp/templates/tplcontext.go index a7d53148208..63e645d37f8 100644 --- a/modules/caddyhttp/templates/tplcontext.go +++ b/modules/caddyhttp/templates/tplcontext.go @@ -265,7 +265,7 @@ func (c TemplateContext) Cookie(name string) string { return "" } -// RemoteIP gets the IP address of the client making the request. +// RemoteIP gets the IP address of the connection's remote IP. func (c TemplateContext) RemoteIP() string { ip, _, err := net.SplitHostPort(c.Req.RemoteAddr) if err != nil { @@ -274,6 +274,18 @@ func (c TemplateContext) RemoteIP() string { return ip } +// ClientIP gets the IP address of the real client making the request +// if the request is trusted (see trusted_proxies), otherwise returns +// the connection's remote IP. +func (c TemplateContext) ClientIP() string { + address := caddyhttp.GetVar(c.Req.Context(), caddyhttp.ClientIPVarKey).(string) + clientIP, _, err := net.SplitHostPort(address) + if err != nil { + clientIP = address // no port + } + return clientIP +} + // Host returns the hostname portion of the Host header // from the HTTP request. func (c TemplateContext) Host() (string, error) {