Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

templates: Clarify include args docs, add .ClientIP #5898

Merged
merged 2 commits into from
Oct 16, 2023
Merged

templates: Clarify include args docs, add .ClientIP #5898

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db1c825
templates: Clarify `include` args docs
francislavoie Oct 15, 2023
f89f404
More docs cleanup, add `.ClientIP`
francislavoie Oct 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 33 additions & 20 deletions modules/caddyhttp/templates/templates.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
//
Expand All @@ -125,12 +126,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`
Expand All @@ -145,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"}}
Expand All @@ -165,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:
Expand All @@ -186,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`
//
Expand Down Expand Up @@ -222,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"
Expand All @@ -236,7 +251,7 @@ func init() {
//
// **YAML** is surrounded by `---`:
//
// ```
// ```yaml
// ---
// template: blog
// title: Blog Homepage
Expand All @@ -246,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"
// }
// ```
Comment on lines +264 to 270
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really stupid, but if we have any kind of indentation between { } the lint-on-save in VSCode will reformat it as how it was before, making it look stupid after markdown parsing. So for now the only solution I could find is to remove any JSON indentation 😭

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh! Haha, yeah you're right. I don't know a workaround. That's OK.

//
// The resulting front matter will be made available like so:
Expand Down
14 changes: 13 additions & 1 deletion modules/caddyhttp/templates/tplcontext.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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) {
Expand Down
Loading