diff --git a/client/options.go b/client/options.go index 027b7fb5..f4711834 100644 --- a/client/options.go +++ b/client/options.go @@ -77,6 +77,12 @@ func WithMarkdown() PublishOption { return WithHeader("X-Markdown", "yes") } +// WithTemplate instructs the server to use a specific template for the message. If templateName is is "yes" or "1", +// the server will interpret the message and title as a template. +func WithTemplate(templateName string) PublishOption { + return WithHeader("X-Template", templateName) +} + // WithFilename sets a filename for the attachment, and/or forces the HTTP body to interpreted as an attachment func WithFilename(filename string) PublishOption { return WithHeader("X-Filename", filename) diff --git a/cmd/publish.go b/cmd/publish.go index c15761ab..f3139a63 100644 --- a/cmd/publish.go +++ b/cmd/publish.go @@ -32,6 +32,7 @@ var flagsPublish = append( &cli.StringFlag{Name: "actions", Aliases: []string{"A"}, EnvVars: []string{"NTFY_ACTIONS"}, Usage: "actions JSON array or simple definition"}, &cli.StringFlag{Name: "attach", Aliases: []string{"a"}, EnvVars: []string{"NTFY_ATTACH"}, Usage: "URL to send as an external attachment"}, &cli.BoolFlag{Name: "markdown", Aliases: []string{"md"}, EnvVars: []string{"NTFY_MARKDOWN"}, Usage: "Message is formatted as Markdown"}, + &cli.StringFlag{Name: "template", Aliases: []string{"tpl"}, EnvVars: []string{"NTFY_TEMPLATE"}, Usage: "use templates to transform JSON message body"}, &cli.StringFlag{Name: "filename", Aliases: []string{"name", "n"}, EnvVars: []string{"NTFY_FILENAME"}, Usage: "filename for the attachment"}, &cli.StringFlag{Name: "file", Aliases: []string{"f"}, EnvVars: []string{"NTFY_FILE"}, Usage: "file to upload as an attachment"}, &cli.StringFlag{Name: "email", Aliases: []string{"mail", "e"}, EnvVars: []string{"NTFY_EMAIL"}, Usage: "also send to e-mail address"}, @@ -98,6 +99,7 @@ func execPublish(c *cli.Context) error { actions := c.String("actions") attach := c.String("attach") markdown := c.Bool("markdown") + template := c.String("template") filename := c.String("filename") file := c.String("file") email := c.String("email") @@ -146,6 +148,9 @@ func execPublish(c *cli.Context) error { if markdown { options = append(options, client.WithMarkdown()) } + if template != "" { + options = append(options, client.WithTemplate(template)) + } if filename != "" { options = append(options, client.WithFilename(filename)) } diff --git a/cmd/serve.go b/cmd/serve.go index 0cbade0f..f894fe65 100644 --- a/cmd/serve.go +++ b/cmd/serve.go @@ -29,13 +29,9 @@ func init() { commands = append(commands, cmdServe) } -const ( - defaultServerConfigFile = "/etc/ntfy/server.yml" -) - var flagsServe = append( append([]cli.Flag{}, flagsDefault...), - &cli.StringFlag{Name: "config", Aliases: []string{"c"}, EnvVars: []string{"NTFY_CONFIG_FILE"}, Value: defaultServerConfigFile, Usage: "config file"}, + &cli.StringFlag{Name: "config", Aliases: []string{"c"}, EnvVars: []string{"NTFY_CONFIG_FILE"}, Value: server.DefaultConfigFile, Usage: "config file"}, altsrc.NewStringFlag(&cli.StringFlag{Name: "base-url", Aliases: []string{"base_url", "B"}, EnvVars: []string{"NTFY_BASE_URL"}, Usage: "externally visible base URL for this host (e.g. https://ntfy.sh)"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "listen-http", Aliases: []string{"listen_http", "l"}, EnvVars: []string{"NTFY_LISTEN_HTTP"}, Value: server.DefaultListenHTTP, Usage: "ip:port used as HTTP listen address"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "listen-https", Aliases: []string{"listen_https", "L"}, EnvVars: []string{"NTFY_LISTEN_HTTPS"}, Usage: "ip:port used as HTTPS listen address"}), @@ -56,7 +52,7 @@ var flagsServe = append( altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-total-size-limit", Aliases: []string{"attachment_total_size_limit", "A"}, EnvVars: []string{"NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT"}, Value: util.FormatSize(server.DefaultAttachmentTotalSizeLimit), Usage: "limit of the on-disk attachment cache"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-file-size-limit", Aliases: []string{"attachment_file_size_limit", "Y"}, EnvVars: []string{"NTFY_ATTACHMENT_FILE_SIZE_LIMIT"}, Value: util.FormatSize(server.DefaultAttachmentFileSizeLimit), Usage: "per-file attachment size limit (e.g. 300k, 2M, 100M)"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "attachment-expiry-duration", Aliases: []string{"attachment_expiry_duration", "X"}, EnvVars: []string{"NTFY_ATTACHMENT_EXPIRY_DURATION"}, Value: util.FormatDuration(server.DefaultAttachmentExpiryDuration), Usage: "duration after which uploaded attachments will be deleted (e.g. 3h, 20h)"}), - altsrc.NewStringFlag(&cli.StringFlag{Name: "template-dir", Aliases: []string{"template_dir"}, EnvVars: []string{"NTFY_TEMPLATE_DIR"}, Usage: "directory to load named message templates from"}), + altsrc.NewStringFlag(&cli.StringFlag{Name: "template-dir", Aliases: []string{"template_dir"}, EnvVars: []string{"NTFY_TEMPLATE_DIR"}, Value: server.DefaultTemplateDir, Usage: "directory to load named message templates from"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "keepalive-interval", Aliases: []string{"keepalive_interval", "k"}, EnvVars: []string{"NTFY_KEEPALIVE_INTERVAL"}, Value: util.FormatDuration(server.DefaultKeepaliveInterval), Usage: "interval of keepalive messages"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "manager-interval", Aliases: []string{"manager_interval", "m"}, EnvVars: []string{"NTFY_MANAGER_INTERVAL"}, Value: util.FormatDuration(server.DefaultManagerInterval), Usage: "interval of for message pruning and stats printing"}), altsrc.NewStringSliceFlag(&cli.StringSliceFlag{Name: "disallowed-topics", Aliases: []string{"disallowed_topics"}, EnvVars: []string{"NTFY_DISALLOWED_TOPICS"}, Usage: "topics that are not allowed to be used"}), diff --git a/cmd/user.go b/cmd/user.go index e6867b11..0ee45bc3 100644 --- a/cmd/user.go +++ b/cmd/user.go @@ -6,6 +6,7 @@ import ( "crypto/subtle" "errors" "fmt" + "heckel.io/ntfy/v2/server" "heckel.io/ntfy/v2/user" "os" "strings" @@ -25,7 +26,7 @@ func init() { var flagsUser = append( append([]cli.Flag{}, flagsDefault...), - &cli.StringFlag{Name: "config", Aliases: []string{"c"}, EnvVars: []string{"NTFY_CONFIG_FILE"}, Value: defaultServerConfigFile, DefaultText: defaultServerConfigFile, Usage: "config file"}, + &cli.StringFlag{Name: "config", Aliases: []string{"c"}, EnvVars: []string{"NTFY_CONFIG_FILE"}, Value: server.DefaultConfigFile, DefaultText: server.DefaultConfigFile, Usage: "config file"}, altsrc.NewStringFlag(&cli.StringFlag{Name: "auth-file", Aliases: []string{"auth_file", "H"}, EnvVars: []string{"NTFY_AUTH_FILE"}, Usage: "auth database file used for access control"}), altsrc.NewStringFlag(&cli.StringFlag{Name: "auth-default-access", Aliases: []string{"auth_default_access", "p"}, EnvVars: []string{"NTFY_AUTH_DEFAULT_ACCESS"}, Value: "read-write", Usage: "default permissions if no matching entries in the auth database are found"}), ) diff --git a/docs/publish.md b/docs/publish.md index 24aa443a..6410bece 100644 --- a/docs/publish.md +++ b/docs/publish.md @@ -944,27 +944,165 @@ Templating lets you **format a JSON message body into human-friendly message and [Go templates](https://pkg.go.dev/text/template) (see tutorials [here](https://blog.gopheracademy.com/advent-2017/using-go-templates/), [here](https://www.digitalocean.com/community/tutorials/how-to-use-templates-in-go), and [here](https://developer.hashicorp.com/nomad/tutorials/templates/go-template-syntax)). This is specifically useful when -**combined with webhooks** from services such as GitHub, Grafana, or other services that emit JSON webhooks. +**combined with webhooks** from services such as [GitHub](https://docs.github.com/en/webhooks/about-webhooks), +[Grafana](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/), +[Alertmanager](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config), or other services that emit JSON webhooks. Instead of using a separate bridge program to parse the webhook body into the format ntfy expects, you can include a templated message and/or a templated title which will be populated based on the fields of the webhook body (so long as the webhook body is valid JSON). -You can enable templating by setting the `X-Template` header (or its aliases `Template` or `tpl`): +You can enable templating by setting the `X-Template` header (or its aliases `Template` or `tpl`, or the query parameter `?template=...`): +* **Pre-defined template files**: Setting the `X-Template` header or query parameter to a template name (e.g. `?template=github`) + to a pre-defined template name (e.g. `github`, `grafana`, or `alertmanager`) will use the template with that name. + See [pre-defined templates](#pre-defined-templates) for more details. +* **Custom template files**: Setting the `X-Template` header or query parameter to a custom template name (e.g. `?template=myapp`) + will use a custom template file from the template directory (defaults to `/etc/ntfy/templates`, can be overridden with `template-dir`). + See [custom templates](#custom-templates) for more details. * **Inline templating**: Setting the `X-Template` header or query parameter to `yes` or `1` (e.g. `?template=yes`) - will enable inline templating, which means that the `message` and/or `title` **will be parsed as a Go template**. - See [Inline templating](#inline-templating) and [Template syntax](#template-syntax) for details on how to use Go - templates in your messages and titles. -* **Pre-defined template files**: You can also set `X-Template` header or query parameter to a template name (e.g. `?template=github`). - ntfy will then read the template from either the built-in pre-defined template files, or from the template files defined in - the `template-dir`. See [Template files](#pre-defined-templates) for more details. + will enable inline templating, which means that the `message` and/or `title` will be parsed as a Go template. + See [inline templating](#inline-templating) for more details. + +To learn the basics of Go's templating language, please see [template syntax](#template-syntax). + +### Pre-defined templates + +When `X-Template: ` (aliases: `Template: `, `Tpl: `) or `?template=` is set, ntfy will transform the +message and/or title based on one of the built-in pre-defined templates + +The following **pre-defined templates** are available: + +* `github`: Formats a subset of [GitHub webhook](https://docs.github.com/en/webhooks/about-webhooks) payloads (PRs, issues, new star, new watcher, new comment) +* `grafana`: Formats [Grafana webhook](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) payloads (firing/resolved alerts) +* `alertmanager`: Formats [Alertmanager webhook](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config) payloads (firing/resolved alerts) + +Here's an example of how to use the pre-defined `github` template: First, configure the webhook in GitHub to send a webhook to your ntfy topic, e.g. `https://ntfy.sh/mytopic?template=github`. +
+ ![GitHub webhook config](static/img/screenshot-github-webhook-config.png){ width=600 } +
GitHub webhook configuration
+
+ +After that, when GitHub publishes a JSON webhook to the topic, ntfy will transform it according to the template rules +and you'll receive notifications in the ntfy app. Here's an example for when somebody stars your repository: + +
+ ![pre-defined template](static/img/android-screenshot-template-predefined.png){ width=500 } +
Receiving a webhook, formatted using the pre-defined "github" template
+
+ +### Custom templates + +To define **your own custom templates**, place a template file in the template directory (defaults to `/etc/ntfy/templates`, can be overridden with `template-dir`) +and set the `X-Template` header or query parameter to the name of the template file (without the `.yml` extension). + +For example, if you have a template file `/etc/ntfy/templates/myapp.yml`, you can set the header `X-Template: myapp` or +the query parameter `?template=myapp` to use it. + +Template files must have the `.yml` (not: `.yaml`!) extension and must be formatted as YAML. They may contain `title` and `message` keys, +which are interpreted as Go templates. + +Here's an **example custom template**: + +=== "Custom template (/etc/ntfy/templates/myapp.yml)" + ```yaml + title: | + {{- if eq .status "firing" }} + {{- if gt .percent 90.0 }}🚨 Critical alert + {{- else }}⚠️ Alert{{- end }} + {{- else if eq .status "resolved" }} + ✅ Alert resolved + {{- end }} + message: | + Status: {{ .status }} + Type: {{ .type | upper }} ({{ .percent }}%) + Server: {{ .server }} + ``` + +Once you have the template file in place, you can send the payload to your topic using the `X-Template` +header or query parameter: + +=== "Command line (curl)" + ``` + echo '{"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}' | \ + curl -sT- "https://ntfy.example.com/mytopic?template=myapp" + ``` + +=== "ntfy CLI" + ``` + echo '{"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}' | \ + ntfy publish --template=myapp https://ntfy.example.com/mytopic + ``` + +=== "HTTP" + ``` http + POST /mytopic?template=myapp HTTP/1.1 + Host: ntfy.example.com + + { + "status": "firing", + "type": "cpu", + "server": "ntfy.sh", + "percent": 99 + } + ``` + +=== "JavaScript" + ``` javascript + fetch('https://ntfy.example.com/mytopic?template=myapp', { + method: 'POST', + body: '{"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}' + }) + ``` + +=== "Go" + ``` go + payload := `{"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}` + req, _ := http.NewRequest("POST", "https://ntfy.example.com/mytopic?template=myapp", strings.NewReader(payload)) + http.DefaultClient.Do(req) + ``` + +=== "PowerShell" + ``` powershell + $Request = @{ + Method = "POST" + Uri = "https://ntfy.example.com/mytopic?template=myapp" + Body = '{"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}' + } + Invoke-RestMethod @Request + ``` + +=== "Python" + ``` python + requests.post("https://ntfy.example.com/mytopic?template=myapp", + json={"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}) + ``` + +=== "PHP" + ``` php-inline + file_get_contents('https://ntfy.example.com/mytopic?template=myapp', false, stream_context_create([ + 'http' => [ + 'method' => 'POST', + 'header' => "Content-Type: application/json", + 'content' => '{"status":"firing","type":"cpu","server":"ntfy.sh","percent":99}' + ] + ])); + ``` + +Which will result in a notification that looks like this: + +
+ ![notification from custom JSON webhook template](static/img/android-screenshot-template-custom.png){ width=500 } +
JSON webhook, transformed using a custom template
+
### Inline templating -When `X-Template: yes` or `?template=yes` is set, you can use Go templates in the `message` and `title` fields of your -webhook payload. This is most useful if no [pre-defined template](#pre-defined-templates) exists, for templated one-off messages, -of if you do not control the ntfy server (e.g., if you're using ntfy.sh). Please consider using [template files](#pre-defined-templates) +When `X-Template: yes` (aliases: `Template: yes`, `Tpl: yes`) or `?template=yes` is set, you can use Go templates in the `message` and `title` fields of your +webhook payload. + +Inline templates are most useful for templated one-off messages, of if you do not control the ntfy server (e.g., if you're using ntfy.sh). +Consider using [pre-defined templates](#pre-defined-templates) or [custom templates](#custom-templates) instead, if you control the ntfy server, as templates are much easier to maintain. Here's an **example for a Grafana alert**: @@ -1078,10 +1216,6 @@ This example uses the `message`/`m` and `title`/`t` query parameters, but obviou `Message`/`Title` headers. It will send a notification with a title `phil-pc: A severe error has occurred` and a message `Error message: Disk has run out of space`. -### Pre-defined templates - -XXXXXXXXXXXXxx - ### Template syntax ntfy uses [Go templates](https://pkg.go.dev/text/template) for its templates, which is arguably one of the most powerful, yet also one of the worst templating languages out there. @@ -1101,23 +1235,23 @@ message templating and for transforming the data provided through the JSON paylo Below are the functions that are available to use inside your message/title templates. -* [String Functions](./sprig/strings.md): `trim`, `trunc`, `substr`, `plural`, etc. - * [String List Functions](./sprig/string_slice.md): `splitList`, `sortAlpha`, etc. -* [Integer Math Functions](./sprig/math.md): `add`, `max`, `mul`, etc. - * [Integer List Functions](./sprig/integer_slice.md): `until`, `untilStep` -* [Date Functions](./sprig/date.md): `now`, `date`, etc. -* [Defaults Functions](./sprig/defaults.md): `default`, `empty`, `coalesce`, `fromJSON`, `toJSON`, `toPrettyJSON`, `toRawJSON`, `ternary` -* [Encoding Functions](./sprig/encoding.md): `b64enc`, `b64dec`, etc. -* [Lists and List Functions](./sprig/lists.md): `list`, `first`, `uniq`, etc. -* [Dictionaries and Dict Functions](./sprig/dicts.md): `get`, `set`, `dict`, `hasKey`, `pluck`, `dig`, etc. -* [Type Conversion Functions](./sprig/conversion.md): `atoi`, `int64`, `toString`, etc. -* [Path and Filepath Functions](./sprig/paths.md): `base`, `dir`, `ext`, `clean`, `isAbs`, `osBase`, `osDir`, `osExt`, `osClean`, `osIsAbs` -* [Flow Control Functions]( ./sprig/flow_control.md): `fail` +* [String Functions](publish/template-functions.md#string-functions): `trim`, `trunc`, `substr`, `plural`, etc. +* [String List Functions](publish/template-functions.md#string-list-functions): `splitList`, `sortAlpha`, etc. +* [Integer Math Functions](publish/template-functions.md#integer-math-functions): `add`, `max`, `mul`, etc. +* [Integer List Functions](publish/template-functions.md#integer-list-functions): `until`, `untilStep` +* [Date Functions](publish/template-functions.md#date-functions): `now`, `date`, etc. +* [Defaults Functions](publish/template-functions.md#default-functions): `default`, `empty`, `coalesce`, `fromJSON`, `toJSON`, `toPrettyJSON`, `toRawJSON`, `ternary` +* [Encoding Functions](publish/template-functions.md#encoding-functions): `b64enc`, `b64dec`, etc. +* [Lists and List Functions](publish/template-functions.md#lists-and-list-functions): `list`, `first`, `uniq`, etc. +* [Dictionaries and Dict Functions](publish/template-functions.md#dictionaries-and-dict-functions): `get`, `set`, `dict`, `hasKey`, `pluck`, `dig`, etc. +* [Type Conversion Functions](publish/template-functions.md#type-conversion-functions): `atoi`, `int64`, `toString`, etc. +* [Path and Filepath Functions](publish/template-functions.md#path-and-filepath-functions): `base`, `dir`, `ext`, `clean`, `isAbs`, `osBase`, `osDir`, `osExt`, `osClean`, `osIsAbs` +* [Flow Control Functions](publish/template-functions.md#flow-control-functions): `fail` * Advanced Functions - * [UUID Functions](./sprig/uuid.md): `uuidv4` - * [Reflection](./sprig/reflection.md): `typeOf`, `kindIs`, `typeIsLike`, etc. - * [Cryptographic and Security Functions](./sprig/crypto.md): `sha256sum`, etc. - * [URL](./sprig/url.md): `urlParse`, `urlJoin` + * [UUID Functions](publish/template-functions.md#uuid-functions): `uuidv4` + * [Reflection](publish/template-functions.md#reflection-functions): `typeOf`, `kindIs`, `typeIsLike`, etc. + * [Cryptographic and Security Functions](publish/template-functions.md#cryptographic-and-security-functions): `sha256sum`, etc. + * [URL](publish/template-functions.md#url-functions): `urlParse`, `urlJoin` ## Publish as JSON diff --git a/docs/template-functions.md b/docs/publish/template-functions.md similarity index 59% rename from docs/template-functions.md rename to docs/publish/template-functions.md index 7c9593e6..238bddd9 100644 --- a/docs/template-functions.md +++ b/docs/publish/template-functions.md @@ -1,4 +1,8 @@ -# Template functions +# Template Functions + +These template functions may be used in the [message template](../publish.md#message-templating) feature of ntfy. Please refer to the examples in the documentation for how to use them. + +The original set of template functions is based on the [Sprig library](https://masterminds.github.io/sprig/). This documentation page is a (slightly modified) copy of their docs. **Thank you to the Sprig developers for their work!** 🙏 ## Table of Contents @@ -23,106 +27,89 @@ Sprig has a number of string manipulation functions. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
trimThe `trim` function removes space from either side of a string: +### trim + +The `trim` function removes space from either side of a string: ``` trim " hello " ``` The above produces `hello` -
trimAllRemove given characters from the front or back of a string: +### trimAll + +Remove given characters from the front or back of a string: ``` trimAll "$" "$5.00" ``` The above returns `5.00` (as a string). -
trimSuffixTrim just the suffix from a string: +### trimSuffix + +Trim just the suffix from a string: ``` trimSuffix "-" "hello-" ``` The above returns `hello` -
trimPrefixTrim just the prefix from a string: +### trimPrefix + +Trim just the prefix from a string: ``` trimPrefix "-" "-hello" ``` The above returns `hello` -
upperConvert the entire string to uppercase: +### upper + +Convert the entire string to uppercase: ``` upper "hello" ``` The above returns `HELLO` -
lowerConvert the entire string to lowercase: +### lower + +Convert the entire string to lowercase: ``` lower "HELLO" ``` The above returns `hello` -
titleConvert to title case: +### title + +Convert to title case: ``` title "hello world" ``` The above returns `Hello World` -
repeatRepeat a string multiple times: +### repeat + +Repeat a string multiple times: ``` repeat 3 "hello" ``` The above returns `hellohellohello` -
substrGet a substring from a string. It takes three parameters: +### substr + +Get a substring from a string. It takes three parameters: - start (int) - end (int) @@ -133,12 +120,10 @@ substr 0 5 "hello world" ``` The above returns `hello` -
truncTruncate a string (and add no suffix) +### trunc + +Truncate a string (and add no suffix) ``` trunc 5 "hello world" @@ -151,24 +136,20 @@ trunc -5 "hello world" ``` The above produces `world`. -
containsTest to see if one string is contained inside of another: +### contains + +Test to see if one string is contained inside of another: ``` contains "cat" "catch" ``` The above returns `true` because `catch` contains `cat`. -
hasPrefix and hasSuffixThe `hasPrefix` and `hasSuffix` functions test whether a string has a given +### hasPrefix and hasSuffix + +The `hasPrefix` and `hasSuffix` functions test whether a string has a given prefix or suffix: ``` @@ -176,19 +157,15 @@ hasPrefix "cat" "catch" ``` The above returns `true` because `catch` has the prefix `cat`. -
quote and squoteThese functions wrap a string in double quotes (`quote`) or single quotes +### quote and squote + +These functions wrap a string in double quotes (`quote`) or single quotes (`squote`). -
catThe `cat` function concatenates multiple strings together into one, separating +### cat + +The `cat` function concatenates multiple strings together into one, separating them with spaces: ``` @@ -196,12 +173,10 @@ cat "hello" "beautiful" "world" ``` The above produces `hello beautiful world` -
indentThe `indent` function indents every line in a given string to the specified +### indent + +The `indent` function indents every line in a given string to the specified indent width. This is useful when aligning multi-line strings: ``` @@ -209,12 +184,10 @@ indent 4 $lots_of_text ``` The above will indent every line of text by 4 space characters. -
nindentThe `nindent` function is the same as the indent function, but prepends a new +### nindent + +The `nindent` function is the same as the indent function, but prepends a new line to the beginning of the string. ``` @@ -223,12 +196,10 @@ nindent 4 $lots_of_text The above will indent every line of text by 4 space characters and add a new line to the beginning. -
replacePerform simple string replacement. +### replace + +Perform simple string replacement. It takes three arguments: @@ -241,12 +212,10 @@ It takes three arguments: ``` The above will produce `I-Am-Henry-VIII` -
pluralPluralize a string. +### plural + +Pluralize a string. ``` len $fish | plural "one anchovy" "many anchovies" @@ -266,12 +235,10 @@ NOTE: Sprig does not currently support languages with more complex pluralization rules. And `0` is considered a plural because the English language treats it as such (`zero anchovies`). The Sprig developers are working on a solution for better internationalization. -
regexMatch, mustRegexMatchReturns true if the input string contains any match of the regular expression. +### regexMatch, mustRegexMatch + +Returns true if the input string contains any match of the regular expression. ``` regexMatch "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$" "test@acme.com" @@ -281,12 +248,10 @@ The above produces `true` `regexMatch` panics if there is a problem and `mustRegexMatch` returns an error to the template engine if there is a problem. -
regexFindAll, mustRegexFindAllReturns a slice of all matches of the regular expression in the input string. +### regexFindAll, mustRegexFindAll + +Returns a slice of all matches of the regular expression in the input string. The last parameter n determines the number of substrings to return, where -1 means return all matches ``` @@ -297,12 +262,10 @@ The above produces `[2 4 6 8]` `regexFindAll` panics if there is a problem and `mustRegexFindAll` returns an error to the template engine if there is a problem. -
regexFind, mustRegexFindReturn the first (left most) match of the regular expression in the input string +### regexFind, mustRegexFind + +Return the first (left most) match of the regular expression in the input string ``` regexFind "[a-zA-Z][1-9]" "abcd1234" @@ -312,12 +275,10 @@ The above produces `d1` `regexFind` panics if there is a problem and `mustRegexFind` returns an error to the template engine if there is a problem. -
regexReplaceAll, mustRegexReplaceAllReturns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. +### regexReplaceAll, mustRegexReplaceAll + +Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. Inside string replacement, $ signs are interpreted as in Expand, so for instance $1 represents the text of the first submatch ``` @@ -328,12 +289,10 @@ The above produces `-W-xxW-` `regexReplaceAll` panics if there is a problem and `mustRegexReplaceAll` returns an error to the template engine if there is a problem. -
regexReplaceAllLiteral, mustRegexReplaceAllLiteralReturns a copy of the input string, replacing matches of the Regexp with the replacement string replacement +### regexReplaceAllLiteral, mustRegexReplaceAllLiteral + +Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement The replacement string is substituted directly, without using Expand ``` @@ -344,12 +303,10 @@ The above produces `-${1}-${1}-` `regexReplaceAllLiteral` panics if there is a problem and `mustRegexReplaceAllLiteral` returns an error to the template engine if there is a problem. -
regexSplit, mustRegexSplitSlices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. The last parameter `n` determines the number of substrings to return, where `-1` means return all matches +### regexSplit, mustRegexSplit + +Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. The last parameter `n` determines the number of substrings to return, where `-1` means return all matches ``` regexSplit "z+" "pizza" -1 @@ -359,12 +316,10 @@ The above produces `[pi a]` `regexSplit` panics if there is a problem and `mustRegexSplit` returns an error to the template engine if there is a problem. -
regexQuoteMetaReturns a string that escapes all regular expression metacharacters inside the argument text; +### regexQuoteMeta + +Returns a string that escapes all regular expression metacharacters inside the argument text; the returned string is a regular expression matching the literal text. ``` @@ -372,22 +327,20 @@ regexQuoteMeta "1.2.3" ``` The above produces `1\.2\.3` -
-The [Conversion Functions](conversion.md) contain functions for converting strings. The [String List Functions](string_slice.md) contains +### See Also... + +The [Conversion Functions](#type-conversion-functions) contain functions for converting strings. The [String List Functions](#string-list-functions) contains functions for working with an array of strings. ## String List Functions -These function operate on or generate slices of strings. In Go, a slice is a +These functions operate on or generate slices of strings. In Go, a slice is a growable array. In Sprig, it's a special case of a `list`. - - - - - - - - - - - - - - - - - -
joinJoin a list of strings into a single string, with the given separator. +### join + +Join a list of strings into a single string, with the given separator. ``` list "hello" "world" | join "_" @@ -402,12 +355,10 @@ list 1 2 3 | join "+" ``` The above will produce `1+2+3` -
splitList and splitSplit a string into a list of strings: +### splitList and split + +Split a string into a list of strings: ``` splitList "$" "foo$bar$baz" @@ -429,12 +380,10 @@ $a._0 ``` The above produces `foo` -
splitn`splitn` function splits a string into a `dict` with `n` keys. It is designed to make +### splitn + +`splitn` function splits a string into a `dict` with `n` keys. It is designed to make it easy to use template dot notation for accessing members: ``` @@ -448,132 +397,99 @@ $a._0 ``` The above produces `foo` -
sortAlphaThe `sortAlpha` function sorts a list of strings into alphabetical (lexicographical) +### sortAlpha + +The `sortAlpha` function sorts a list of strings into alphabetical (lexicographical) order. It does _not_ sort in place, but returns a sorted copy of the list, in keeping with the immutability of lists. -
## Integer Math Functions The following math functions operate on `int64` values. - - - - - - - - - +### add1 - - - - +To increment by 1, use `add1` - - - - +### sub - - - - +To subtract, use `sub` - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
addSum numbers with `add`. Accepts two or more inputs. +### add + +Sum numbers with `add`. Accepts two or more inputs. ``` add 1 2 3 ``` -
add1To increment by 1, use `add1` -
subTo subtract, use `sub` -
divPerform integer division with `div` -
modModulo with `mod` -
mulMultiply with `mul`. Accepts two or more inputs. +### div + +Perform integer division with `div` + +### mod + +Modulo with `mod` + +### mul + +Multiply with `mul`. Accepts two or more inputs. ``` mul 1 2 3 ``` -
maxReturn the largest of a series of integers: +### max + +Return the largest of a series of integers: This will return `3`: ``` max 1 2 3 ``` -
minReturn the smallest of a series of integers. +### min + +Return the smallest of a series of integers. `min 1 2 3` will return `1` -
floorReturns the greatest float value less than or equal to input value +### floor + +Returns the greatest float value less than or equal to input value `floor 123.9999` will return `123.0` -
ceilReturns the greatest float value greater than or equal to input value +### ceil + +Returns the greatest float value greater than or equal to input value `ceil 123.001` will return `124.0` -
roundReturns a float value with the remainder rounded to the given number to digits after the decimal point. +### round + +Returns a float value with the remainder rounded to the given number to digits after the decimal point. `round 123.555555 3` will return `123.556` -
randIntReturns a random integer value from min (inclusive) to max (exclusive). +### randInt +Returns a random integer value from min (inclusive) to max (exclusive). ``` randInt 12 30 ``` The above will produce a random number in the range [12,30]. -
## Integer List Functions - - - - - - - - - - - - - -
untilThe `until` function builds a range of integers. +### until + +The `until` function builds a range of integers. ``` until 5 @@ -582,12 +498,10 @@ until 5 The above generates the list `[0, 1, 2, 3, 4]`. This is useful for looping with `range $i, $e := until 5`. -
untilStepLike `until`, `untilStep` generates a list of counting integers. But it allows +### untilStep + +Like `until`, `untilStep` generates a list of counting integers. But it allows you to define a start, stop, and step: ``` @@ -596,12 +510,10 @@ untilStep 3 6 2 The above will produce `[3 5]` by starting with 3, and adding 2 until it is equal or greater than 6. This is similar to Python's `range` function. -
seqWorks like the bash `seq` command. +### seq + +Works like the bash `seq` command. * 1 parameter (end) - will generate all counting integers between 1 and `end` inclusive. * 2 parameters (start, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by 1. * 3 parameters (start, step, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by `step`. @@ -614,22 +526,16 @@ seq 2 -2 => 2 1 0 -1 -2 seq 0 2 10 => 0 2 4 6 8 10 seq 0 -2 -5 => 0 -2 -4 ``` -
## Date Functions - - - - - +### now - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
nowThe current date/time. Use this in conjunction with other date functions. -
agoThe `ago` function returns duration from time.Now in seconds resolution. +The current date/time. Use this in conjunction with other date functions. + +### ago + +The `ago` function returns duration from time.Now in seconds resolution. ``` ago .CreatedAt @@ -640,12 +546,10 @@ returns in `time.Duration` String() format ``` 2h34m7s ``` -
dateThe `date` function formats a date. +### date + +The `date` function formats a date. Format the date to YEAR-MONTH-DAY: @@ -663,34 +567,28 @@ Mon Jan 2 15:04:05 MST 2006 Write it in the format you want. Above, `2006-01-02` is the same date, but in the format we want. -
dateInZoneSame as `date`, but with a timezone. +### dateInZone + +Same as `date`, but with a timezone. ``` dateInZone "2006-01-02" (now) "UTC" ``` -
durationFormats a given amount of seconds as a `time.Duration`. +### duration + +Formats a given amount of seconds as a `time.Duration`. This returns 1m35s ``` duration "95" ``` -
durationRoundRounds a given duration to the most significant unit. Strings and `time.Duration` +### durationRound + +Rounds a given duration to the most significant unit. Strings and `time.Duration` gets parsed as a duration, while a `time.Time` is calculated as the duration since. This return 2h @@ -704,22 +602,18 @@ This returns 3mo ``` durationRound "2400h10m5s" ``` -
unixEpochReturns the seconds since the unix epoch for a `time.Time`. +### unixEpoch + +Returns the seconds since the unix epoch for a `time.Time`. ``` now | unixEpoch ``` -
dateModify, mustDateModifyThe `dateModify` takes a modification and a date and returns the timestamp. +### dateModify, mustDateModify + +The `dateModify` takes a modification and a date and returns the timestamp. Subtract an hour and thirty minutes from the current time: @@ -728,33 +622,27 @@ now | date_modify "-1.5h" ``` If the modification format is wrong `dateModify` will return the date unmodified. `mustDateModify` will return an error otherwise. -
htmlDateThe `htmlDate` function formats a date for inserting into an HTML date picker +### htmlDate + +The `htmlDate` function formats a date for inserting into an HTML date picker input field. ``` now | htmlDate ``` -
htmlDateInZoneSame as htmlDate, but with a timezone. +### htmlDateInZone + +Same as htmlDate, but with a timezone. ``` htmlDateInZone (now) "UTC" ``` -
toDate, mustToDate`toDate` converts a string to a date. The first argument is the date layout and +### toDate, mustToDate + +`toDate` converts a string to a date. The first argument is the date layout and the second the date string. If the string can't be convert it returns the zero value. `mustToDate` will return an error in case the string cannot be converted. @@ -765,18 +653,14 @@ This is useful when you want to convert a string date to another format ``` toDate "2006-01-02" "2017-12-31" | date "02/01/2006" ``` -
## Default Functions Sprig provides tools for setting default values for templates. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
defaultTo set a simple default value, use `default`: +### default + +To set a simple default value, use `default`: ``` default "foo" .Bar @@ -796,12 +680,10 @@ The definition of "empty" depends on type: For structs, there is no definition of empty, so a struct will never return the default. -
emptyThe `empty` function returns `true` if the given value is considered empty, and +### empty + +The `empty` function returns `true` if the given value is considered empty, and `false` otherwise. The empty values are listed in the `default` section. ``` @@ -810,12 +692,10 @@ empty .Foo Note that in Go template conditionals, emptiness is calculated for you. Thus, you rarely need `if empty .Foo`. Instead, just use `if .Foo`. -
coalesceThe `coalesce` function takes a list of values and returns the first non-empty +### coalesce + +The `coalesce` function takes a list of values and returns the first non-empty one. ``` @@ -833,12 +713,10 @@ coalesce .name .parent.name "Matt" The above will first check to see if `.name` is empty. If it is not, it will return that value. If it _is_ empty, `coalesce` will evaluate `.parent.name` for emptiness. Finally, if both `.name` and `.parent.name` are empty, it will return `Matt`. -
allThe `all` function takes a list of values and returns true if all values are non-empty. +### all + +The `all` function takes a list of values and returns true if all values are non-empty. ``` all 0 1 2 @@ -853,12 +731,10 @@ all (eq .Request.TLS.Version 0x0304) (.Request.ProtoAtLeast 2 0) (eq .Request.Me ``` The above will check http.Request is POST with tls 1.3 and http/2. -
anyThe `any` function takes a list of values and returns true if any value is non-empty. +### any + +The `any` function takes a list of values and returns true if any value is non-empty. ``` any 0 1 2 @@ -873,23 +749,19 @@ any (eq .Request.Method "GET") (eq .Request.Method "POST") (eq .Request.Method " ``` The above will check http.Request method is one of GET/POST/OPTIONS. -
fromJSON, mustFromJSON`fromJSON` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string. +### fromJSON, mustFromJSON + +`fromJSON` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string. `mustFromJSON` will return an error in case the JSON is invalid. ``` fromJSON "{\"foo\": 55}" ``` -
toJSON, mustToJSONThe `toJSON` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string. +### toJSON, mustToJSON + +The `toJSON` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string. `mustToJSON` will return an error in case the item cannot be encoded in JSON. ``` @@ -897,40 +769,34 @@ toJSON .Item ``` The above returns JSON string representation of `.Item`. -
toPrettyJSON, mustToPrettyJSONThe `toPrettyJSON` function encodes an item into a pretty (indented) JSON string. +### toPrettyJSON, mustToPrettyJSON + +The `toPrettyJSON` function encodes an item into a pretty (indented) JSON string. ``` toPrettyJSON .Item ``` The above returns indented JSON string representation of `.Item`. -
toRawJSON, mustToRawJSONThe `toRawJSON` function encodes an item into JSON string with HTML characters unescaped. +### toRawJSON, mustToRawJSON + +The `toRawJSON` function encodes an item into JSON string with HTML characters unescaped. ``` toRawJSON .Item ``` The above returns unescaped JSON string representation of `.Item`. -
ternaryThe `ternary` function takes two values, and a test value. If the test value is +### ternary + +The `ternary` function takes two values, and a test value. If the test value is true, the first value will be returned. If the test value is empty, the second value will be returned. This is similar to the c ternary operator. -### true test value +#### true test value ``` ternary "foo" "bar" true @@ -944,7 +810,7 @@ true | ternary "foo" "bar" The above returns `"foo"`. -### false test value +#### false test value ``` ternary "foo" "bar" false @@ -957,27 +823,13 @@ false | ternary "foo" "bar" ``` The above returns `"bar"`. -
## Encoding Functions Sprig has the following encoding and decoding functions: - - - - - - - - - - -
b64enc/b64decEncode or decode with Base64 -
b32enc/b32decEncode or decode with Base32 -
+- `b64enc`/`b64dec`: Encode or decode with Base64 +- `b32enc`/`b32dec`: Encode or decode with Base32 ## Lists and List Functions @@ -993,54 +845,45 @@ $myList := list 1 2 3 4 5 The above creates a list of `[1 2 3 4 5]`. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
first, mustFirstTo get the head item on a list, use `first`. +### first, mustFirst + +To get the head item on a list, use `first`. `first $myList` returns `1` `first` panics if there is a problem while `mustFirst` returns an error to the template engine if there is a problem. -
rest, mustRestTo get the tail of the list (everything but the first item), use `rest`. +### rest, mustRest + +To get the tail of the list (everything but the first item), use `rest`. `rest $myList` returns `[2 3 4 5]` `rest` panics if there is a problem while `mustRest` returns an error to the template engine if there is a problem. -
last, mustLastTo get the last item on a list, use `last`: +### last, mustLast + +To get the last item on a list, use `last`: `last $myList` returns `5`. This is roughly analogous to reversing a list and then calling `first`. `last` panics if there is a problem while `mustLast` returns an error to the template engine if there is a problem. -
initial, mustInitialThis compliments `last` by returning all _but_ the last element. +### initial, mustInitial + +This compliments `last` by returning all _but_ the last element. `initial $myList` returns `[1 2 3 4]`. `initial` panics if there is a problem while `mustInitial` returns an error to the template engine if there is a problem. -
append, mustAppendAppend a new item to an existing list, creating a new list. +### append, mustAppend + +Append a new item to an existing list, creating a new list. ``` $new = append $myList 6 @@ -1050,12 +893,10 @@ The above would set `$new` to `[1 2 3 4 5 6]`. `$myList` would remain unaltered. `append` panics if there is a problem while `mustAppend` returns an error to the template engine if there is a problem. -
prepend, mustPrependPush an element onto the front of a list, creating a new list. +### prepend, mustPrepend + +Push an element onto the front of a list, creating a new list. ``` prepend $myList 0 @@ -1065,24 +906,20 @@ The above would produce `[0 1 2 3 4 5]`. `$myList` would remain unaltered. `prepend` panics if there is a problem while `mustPrepend` returns an error to the template engine if there is a problem. -
concatConcatenate arbitrary number of lists into one. +### concat + +Concatenate arbitrary number of lists into one. ``` concat $myList ( list 6 7 ) ( list 8 ) ``` The above would produce `[1 2 3 4 5 6 7 8]`. `$myList` would remain unaltered. -
reverse, mustReverseProduce a new list with the reversed elements of the given list. +### reverse, mustReverse + +Produce a new list with the reversed elements of the given list. ``` reverse $myList @@ -1092,12 +929,10 @@ The above would generate the list `[5 4 3 2 1]`. `reverse` panics if there is a problem while `mustReverse` returns an error to the template engine if there is a problem. -
uniq, mustUniqGenerate a list with all of the duplicates removed. +### uniq, mustUniq + +Generate a list with all of the duplicates removed. ``` list 1 1 1 2 | uniq @@ -1107,12 +942,10 @@ The above would produce `[1 2]` `uniq` panics if there is a problem while `mustUniq` returns an error to the template engine if there is a problem. -
without, mustWithoutThe `without` function filters items out of a list. +### without, mustWithout + +The `without` function filters items out of a list. ``` without $myList 3 @@ -1130,12 +963,10 @@ That would produce `[2 4]` `without` panics if there is a problem while `mustWithout` returns an error to the template engine if there is a problem. -
has, mustHasTest to see if a list has a particular element. +### has, mustHas + +Test to see if a list has a particular element. ``` has 4 $myList @@ -1145,12 +976,10 @@ The above would return `true`, while `has "hello" $myList` would return false. `has` panics if there is a problem while `mustHas` returns an error to the template engine if there is a problem. -
compact, mustCompactAccepts a list and removes entries with empty values. +### compact, mustCompact + +Accepts a list and removes entries with empty values. ``` $list := list 1 "a" "foo" "" @@ -1161,12 +990,10 @@ $copy := compact $list `compact` panics if there is a problem and `mustCompact` returns an error to the template engine if there is a problem. -
slice, mustSliceTo get partial elements of a list, use `slice list [n] [m]`. It is +### slice, mustSlice + +To get partial elements of a list, use `slice list [n] [m]`. It is equivalent of `list[n:m]`. - `slice $myList` returns `[1 2 3 4 5]`. It is same as `myList[:]`. @@ -1176,26 +1003,21 @@ equivalent of `list[n:m]`. `slice` panics if there is a problem while `mustSlice` returns an error to the template engine if there is a problem. -
chunkTo split a list into chunks of given size, use `chunk size list`. This is useful for pagination. +### chunk + +To split a list into chunks of given size, use `chunk size list`. This is useful for pagination. ``` chunk 3 (list 1 2 3 4 5 6 7 8) ``` This produces list of lists `[ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 ] ]`. -
### A Note on List Internals -A list is implemented in Go as a `[]interface{}`. For Go developers embedding -Sprig, you may pass `[]interface{}` items into your template context and be +A list is implemented in Go as a `[]any`. For Go developers embedding +Sprig, you may pass `[]any` items into your template context and be able to use all of the `list` functions on those items. ## Dictionaries and Dict Functions @@ -1209,10 +1031,9 @@ type, even another `dict` or `list`. Unlike `list`s, `dict`s are not immutable. The `set` and `unset` functions will modify the contents of a dictionary. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
dictCreating dictionaries is done by calling the `dict` function and passing it a +### dict + +Creating dictionaries is done by calling the `dict` function and passing it a list of pairs. The following creates a dictionary with three items: @@ -1220,12 +1041,10 @@ The following creates a dictionary with three items: ``` $myDict := dict "name1" "value1" "name2" "value2" "name3" "value 3" ``` -
getGiven a map and a key, get the value from the map. +### get + +Given a map and a key, get the value from the map. ``` get $myDict "name1" @@ -1235,12 +1054,10 @@ The above returns `"value1"` Note that if the key is not found, this operation will simply return `""`. No error will be generated. -
setUse `set` to add a new key/value pair to a dictionary. +### set + +Use `set` to add a new key/value pair to a dictionary. ``` $_ := set $myDict "name4" "value4" @@ -1248,12 +1065,10 @@ $_ := set $myDict "name4" "value4" Note that `set` _returns the dictionary_ (a requirement of Go template functions), so you may need to trap the value as done above with the `$_` assignment. -
unsetGiven a map and a key, delete the key from the map. +### unset + +Given a map and a key, delete the key from the map. ``` $_ := unset $myDict "name4" @@ -1263,24 +1078,20 @@ As with `set`, this returns the dictionary. Note that if the key is not found, this operation will simply return. No error will be generated. -
hasKeyThe `hasKey` function returns `true` if the given dict contains the given key. +### hasKey + +The `hasKey` function returns `true` if the given dict contains the given key. ``` hasKey $myDict "name1" ``` If the key is not found, this returns `false`. -
pluckThe `pluck` function makes it possible to give one key and multiple maps, and +### pluck + +The `pluck` function makes it possible to give one key and multiple maps, and get a list of all of the matches: ``` @@ -1298,12 +1109,10 @@ inserted. A common idiom in Sprig templates is to uses `pluck... | first` to get the first matching key out of a collection of dictionaries. -
digThe `dig` function traverses a nested set of dicts, selecting keys from a list +### dig + +The `dig` function traverses a nested set of dicts, selecting keys from a list of values. It returns a default value if any of the keys are not found at the associated dict. @@ -1331,12 +1140,10 @@ especially since Go's template package's `and` doesn't shortcut. For instance `a.maybeNil.iNeedThis`, and panic if `a` lacks a `maybeNil` field.) `dig` accepts its dict argument last in order to support pipelining. -
keysThe `keys` function will return a `list` of all of the keys in one or more `dict` +### keys + +The `keys` function will return a `list` of all of the keys in one or more `dict` types. Since a dictionary is _unordered_, the keys will not be in a predictable order. They can be sorted with `sortAlpha`. @@ -1350,12 +1157,10 @@ function along with `sortAlpha` to get a unqiue, sorted list of keys. ``` keys $myDict $myOtherDict | uniq | sortAlpha ``` -
pickThe `pick` function selects just the given keys out of a dictionary, creating a +### pick + +The `pick` function selects just the given keys out of a dictionary, creating a new `dict`. ``` @@ -1363,12 +1168,10 @@ $new := pick $myDict "name1" "name2" ``` The above returns `{name1: value1, name2: value2}` -
omitThe `omit` function is similar to `pick`, except it returns a new `dict` with all +### omit + +The `omit` function is similar to `pick`, except it returns a new `dict` with all the keys that _do not_ match the given keys. ``` @@ -1376,12 +1179,10 @@ $new := omit $myDict "name1" "name3" ``` The above returns `{name2: value2}` -
valuesThe `values` function is similar to `keys`, except it returns a new `list` with +### values + +The `values` function is similar to `keys`, except it returns a new `list` with all the values of the source `dict` (only one dictionary is supported). ``` @@ -1391,62 +1192,44 @@ $vals := values $myDict The above returns `list["value1", "value2", "value 3"]`. Note that the `values` function gives no guarantees about the result ordering- if you care about this, then use `sortAlpha`. -
## Type Conversion Functions The following type conversion functions are provided by Sprig: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
atoiConvert a string to an integer. -
float64Convert to a `float64`. -
intConvert to an `int` at the system's width. -
int64Convert to an `int64`. -
toDecimalConvert a unix octal to a `int64`. -
toStringConvert to a string. -
toStringsConvert a list, slice, or array to a list of strings. -
+- `atoi`: Convert a string to an integer. +- `float64`: Convert to a `float64`. +- `int`: Convert to an `int` at the system's width. +- `int64`: Convert to an `int64`. +- `toDecimal`: Convert a unix octal to a `int64`. +- `toString`: Convert to a string. +- `toStrings`: Convert a list, slice, or array to a list of strings. Only `atoi` requires that the input be a specific type. The others will attempt to convert from any type to the destination type. For example, `int64` can convert floats to ints, and it can also convert strings to ints. +### toStrings + +Given a list-like collection, produce a slice of strings. + +``` +list 1 2 3 | toStrings +``` + +The above converts `1` to `"1"`, `2` to `"2"`, and so on, and then returns +them as a list. + +### toDecimal + +Given a unix octal permission, produce a decimal. + +``` +"0777" | toDecimal +``` + +The above converts `0777` to `511` and returns the value as an int64. + ## Path and Filepath Functions While Sprig does not grant access to the filesystem, it does provide functions @@ -1466,56 +1249,44 @@ Examples: [URIs](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier): `https://example.com/some/content/`, `ftp://example.com/file/`. - - - - - - - - - - - - - - - - - - - - - -
baseReturn the last element of a path. +#### base + +Return the last element of a path. ``` base "foo/bar/baz" ``` The above prints "baz". -
dirReturn the directory, stripping the last part of the path. So `dir "foo/bar/baz"` +#### dir + +Return the directory, stripping the last part of the path. So `dir "foo/bar/baz"` returns `foo/bar`. -
cleanClean up a path. +#### clean + +Clean up a path. ``` clean "foo/bar/../baz" ``` The above resolves the `..` and returns `foo/baz`. -
extReturn the file extension. +#### ext + +Return the file extension. ``` ext "foo.bar" ``` The above returns `.bar`. -
isAbsTo check whether a path is absolute, use `isAbs`. -
+#### isAbs + +To check whether a path is absolute, use `isAbs`. ### Filepaths @@ -1531,10 +1302,9 @@ Examples: the filesystem path is separated by the backslash character (`\`): `C:\Users\Username\`, `C:\Program Files\Application\`; - - - - - - - - - - - - - - - - - - - - - -
osBaseReturn the last element of a filepath. +#### osBase + +Return the last element of a filepath. ``` osBase "/foo/bar/baz" @@ -1542,20 +1312,16 @@ osBase "C:\\foo\\bar\\baz" ``` The above prints "baz" on Linux and Windows, respectively. -
osDirReturn the directory, stripping the last part of the path. So `osDir "/foo/bar/baz"` +#### osDir + +Return the directory, stripping the last part of the path. So `osDir "/foo/bar/baz"` returns `/foo/bar` on Linux, and `osDir "C:\\foo\\bar\\baz"` returns `C:\\foo\\bar` on Windows. -
osCleanClean up a path. +#### osClean + +Clean up a path. ``` osClean "/foo/bar/../baz" @@ -1563,12 +1329,10 @@ osClean "C:\\foo\\bar\\..\\baz" ``` The above resolves the `..` and returns `foo/baz` on Linux and `C:\\foo\\baz` on Windows. -
osExtReturn the file extension. +#### osExt + +Return the file extension. ``` osExt "/foo.bar" @@ -1576,48 +1340,32 @@ osExt "C:\\foo.bar" ``` The above returns `.bar` on Linux and Windows, respectively. -
osIsAbsTo check whether a file path is absolute, use `osIsAbs`. -
+#### osIsAbs + +To check whether a file path is absolute, use `osIsAbs`. ## Flow Control Functions - - - - - -
failUnconditionally returns an empty `string` and an `error` with the specified +### fail + +Unconditionally returns an empty `string` and an `error` with the specified text. This is useful in scenarios where other conditionals have determined that template rendering should fail. ``` fail "Please accept the end user license agreement" ``` -
## UUID Functions Sprig can generate UUID v4 universally unique IDs. - - - - - -
uuidv4 ``` uuidv4 ``` The above returns a new UUID of the v4 (randomly generated) type. -
## Reflection Functions @@ -1632,63 +1380,35 @@ Sprig provides a set of functions for each. ### Kind Functions - - - - - - - - - - -
kindOfReturns the kind of an object. +There are two Kind functions: `kindOf` returns the kind of an object. ``` kindOf "hello" ``` -The above would return `string`. -
kindIsFor simple tests (like in `if` blocks), the `kindIs` function will let you verify that a value is a particular kind: +The above would return `string`. For simple tests (like in `if` blocks), the +`kindIs` function will let you verify that a value is a particular kind: ``` kindIs "int" 123 ``` The above will return `true` -
### Type Functions Types are slightly harder to work with, so there are three different functions: - - - - - - - - - - - - - - - -
typeOfReturns the underlying type of a value: `typeOf $foo` -
typeIsLike `kindIs`, but for types: `typeIs "*io.Buffer" $myVal` -
typeIsLikeWorks as `typeIs`, except that it also dereferences pointers. -
+- `typeOf` returns the underlying type of a value: `typeOf $foo` +- `typeIs` is like `kindIs`, but for types: `typeIs "*io.Buffer" $myVal` +- `typeIsLike` works as `typeIs`, except that it also dereferences pointers. **Note:** None of these can test whether or not something implements a given interface, since doing so would require compiling the interface in ahead of time. - - - - - -
deepEqualReturns true if two values are ["deeply equal"](https://golang.org/pkg/reflect/#DeepEqual) +### deepEqual + +`deepEqual` returns true if two values are ["deeply equal"](https://golang.org/pkg/reflect/#DeepEqual) Works for non-primitive types as well (compared to the built-in `eq`). @@ -1697,28 +1417,22 @@ deepEqual (list 1 2 3) (list 1 2 3) ``` The above will return `true` -
## Cryptographic and Security Functions Sprig provides a couple of advanced cryptographic functions. - - - - - - - - - - - - - - - - - -
sha1sumThe `sha1sum` function receives a string, and computes it's SHA1 digest. +### sha1sum + +The `sha1sum` function receives a string, and computes it's SHA1 digest. ``` sha1sum "Hello world!" ``` -
sha256sumThe `sha256sum` function receives a string, and computes it's SHA256 digest. +### sha256sum + +The `sha256sum` function receives a string, and computes it's SHA256 digest. ``` sha256sum "Hello world!" @@ -1726,12 +1440,10 @@ sha256sum "Hello world!" The above will compute the SHA 256 sum in an "ASCII armored" format that is safe to print. -
sha512sumThe `sha512sum` function receives a string, and computes it's SHA512 digest. +### sha512sum + +The `sha512sum` function receives a string, and computes it's SHA512 digest. ``` sha512sum "Hello world!" @@ -1739,26 +1451,19 @@ sha512sum "Hello world!" The above will compute the SHA 512 sum in an "ASCII armored" format that is safe to print. -
adler32sumThe `adler32sum` function receives a string, and computes its Adler-32 checksum. +### adler32sum + +The `adler32sum` function receives a string, and computes its Adler-32 checksum. ``` adler32sum "Hello world!" ``` -
## URL Functions - - - - - - - - - -
urlParseParses string for URL and produces dict with URL parts +### urlParse +Parses string for URL and produces dict with URL parts ``` urlParse "http://admin:secret@server.com:8080/api?list=false#anchor" @@ -1776,12 +1481,9 @@ userinfo: 'admin:secret' ``` For more info, check https://golang.org/pkg/net/url/#URL -
urlJoinJoins map (produced by `urlParse`) to produce URL string +### urlJoin +Joins map (produced by `urlParse`) to produce URL string ``` urlJoin (dict "fragment" "fragment" "host" "host:80" "path" "/path" "query" "query" "scheme" "http") @@ -1791,6 +1493,3 @@ The above returns the following string: ``` proto://host:80/path?query#fragment ``` -
diff --git a/docs/sprig.md b/docs/sprig.md deleted file mode 100644 index be4e6c9c..00000000 --- a/docs/sprig.md +++ /dev/null @@ -1,24 +0,0 @@ -# Template Functions - -ntfy includes a (reduced) version of [Sprig](https://github.com/Masterminds/sprig) to add functions that can be used -when you are using the [message template](publish.md#message-templating) feature. - -Below are the functions that are available to use inside your message/title templates. - -* [String Functions](./sprig/strings.md): `trim`, `trunc`, `substr`, `plural`, etc. - * [String List Functions](./sprig/string_slice.md): `splitList`, `sortAlpha`, etc. -* [Integer Math Functions](./sprig/math.md): `add`, `max`, `mul`, etc. - * [Integer List Functions](./sprig/integer_slice.md): `until`, `untilStep` -* [Date Functions](./sprig/date.md): `now`, `date`, etc. -* [Defaults Functions](./sprig/defaults.md): `default`, `empty`, `coalesce`, `fromJSON`, `toJSON`, `toPrettyJSON`, `toRawJSON`, `ternary` -* [Encoding Functions](./sprig/encoding.md): `b64enc`, `b64dec`, etc. -* [Lists and List Functions](./sprig/lists.md): `list`, `first`, `uniq`, etc. -* [Dictionaries and Dict Functions](./sprig/dicts.md): `get`, `set`, `dict`, `hasKey`, `pluck`, `dig`, etc. -* [Type Conversion Functions](./sprig/conversion.md): `atoi`, `int64`, `toString`, etc. -* [Path and Filepath Functions](./sprig/paths.md): `base`, `dir`, `ext`, `clean`, `isAbs`, `osBase`, `osDir`, `osExt`, `osClean`, `osIsAbs` -* [Flow Control Functions](./sprig/flow_control.md): `fail` -* Advanced Functions - * [UUID Functions](./sprig/uuid.md): `uuidv4` - * [Reflection](./sprig/reflection.md): `typeOf`, `kindIs`, `typeIsLike`, etc. - * [Cryptographic and Security Functions](./sprig/crypto.md): `sha256sum`, etc. - * [URL](./sprig/url.md): `urlParse`, `urlJoin` diff --git a/docs/sprig/conversion.md b/docs/sprig/conversion.md deleted file mode 100644 index af952682..00000000 --- a/docs/sprig/conversion.md +++ /dev/null @@ -1,36 +0,0 @@ -# Type Conversion Functions - -The following type conversion functions are provided by Sprig: - -- `atoi`: Convert a string to an integer. -- `float64`: Convert to a `float64`. -- `int`: Convert to an `int` at the system's width. -- `int64`: Convert to an `int64`. -- `toDecimal`: Convert a unix octal to a `int64`. -- `toString`: Convert to a string. -- `toStrings`: Convert a list, slice, or array to a list of strings. - -Only `atoi` requires that the input be a specific type. The others will attempt -to convert from any type to the destination type. For example, `int64` can convert -floats to ints, and it can also convert strings to ints. - -## toStrings - -Given a list-like collection, produce a slice of strings. - -``` -list 1 2 3 | toStrings -``` - -The above converts `1` to `"1"`, `2` to `"2"`, and so on, and then returns -them as a list. - -## toDecimal - -Given a unix octal permission, produce a decimal. - -``` -"0777" | toDecimal -``` - -The above converts `0777` to `511` and returns the value as an int64. diff --git a/docs/sprig/crypto.md b/docs/sprig/crypto.md deleted file mode 100644 index c66a269d..00000000 --- a/docs/sprig/crypto.md +++ /dev/null @@ -1,41 +0,0 @@ -# Cryptographic and Security Functions - -Sprig provides a couple of advanced cryptographic functions. - -## sha1sum - -The `sha1sum` function receives a string, and computes it's SHA1 digest. - -``` -sha1sum "Hello world!" -``` - -## sha256sum - -The `sha256sum` function receives a string, and computes it's SHA256 digest. - -``` -sha256sum "Hello world!" -``` - -The above will compute the SHA 256 sum in an "ASCII armored" format that is -safe to print. - -## sha512sum - -The `sha512sum` function receives a string, and computes it's SHA512 digest. - -``` -sha512sum "Hello world!" -``` - -The above will compute the SHA 512 sum in an "ASCII armored" format that is -safe to print. - -## adler32sum - -The `adler32sum` function receives a string, and computes its Adler-32 checksum. - -``` -adler32sum "Hello world!" -``` diff --git a/docs/sprig/date.md b/docs/sprig/date.md deleted file mode 100644 index 7410c08d..00000000 --- a/docs/sprig/date.md +++ /dev/null @@ -1,126 +0,0 @@ -# Date Functions - -## now - -The current date/time. Use this in conjunction with other date functions. - -## ago - -The `ago` function returns duration from time.Now in seconds resolution. - -``` -ago .CreatedAt -``` - -returns in `time.Duration` String() format - -``` -2h34m7s -``` - -## date - -The `date` function formats a date. - -Format the date to YEAR-MONTH-DAY: - -``` -now | date "2006-01-02" -``` - -Date formatting in Go is a [little bit different](https://pauladamsmith.com/blog/2011/05/go_time.html). - -In short, take this as the base date: - -``` -Mon Jan 2 15:04:05 MST 2006 -``` - -Write it in the format you want. Above, `2006-01-02` is the same date, but -in the format we want. - -## dateInZone - -Same as `date`, but with a timezone. - -``` -dateInZone "2006-01-02" (now) "UTC" -``` - -## duration - -Formats a given amount of seconds as a `time.Duration`. - -This returns 1m35s - -``` -duration "95" -``` - -## durationRound - -Rounds a given duration to the most significant unit. Strings and `time.Duration` -gets parsed as a duration, while a `time.Time` is calculated as the duration since. - -This return 2h - -``` -durationRound "2h10m5s" -``` - -This returns 3mo - -``` -durationRound "2400h10m5s" -``` - -## unixEpoch - -Returns the seconds since the unix epoch for a `time.Time`. - -``` -now | unixEpoch -``` - -## dateModify, mustDateModify - -The `dateModify` takes a modification and a date and returns the timestamp. - -Subtract an hour and thirty minutes from the current time: - -``` -now | date_modify "-1.5h" -``` - -If the modification format is wrong `dateModify` will return the date unmodified. `mustDateModify` will return an error otherwise. - -## htmlDate - -The `htmlDate` function formats a date for inserting into an HTML date picker -input field. - -``` -now | htmlDate -``` - -## htmlDateInZone - -Same as htmlDate, but with a timezone. - -``` -htmlDateInZone (now) "UTC" -``` - -## toDate, mustToDate - -`toDate` converts a string to a date. The first argument is the date layout and -the second the date string. If the string can't be convert it returns the zero -value. -`mustToDate` will return an error in case the string cannot be converted. - -This is useful when you want to convert a string date to another format -(using pipe). The example below converts "2017-12-31" to "31/12/2017". - -``` -toDate "2006-01-02" "2017-12-31" | date "02/01/2006" -``` diff --git a/docs/sprig/defaults.md b/docs/sprig/defaults.md deleted file mode 100644 index b8af1455..00000000 --- a/docs/sprig/defaults.md +++ /dev/null @@ -1,169 +0,0 @@ -# Default Functions - -Sprig provides tools for setting default values for templates. - -## default - -To set a simple default value, use `default`: - -``` -default "foo" .Bar -``` - -In the above, if `.Bar` evaluates to a non-empty value, it will be used. But if -it is empty, `foo` will be returned instead. - -The definition of "empty" depends on type: - -- Numeric: 0 -- String: "" -- Lists: `[]` -- Dicts: `{}` -- Boolean: `false` -- And always `nil` (aka null) - -For structs, there is no definition of empty, so a struct will never return the -default. - -## empty - -The `empty` function returns `true` if the given value is considered empty, and -`false` otherwise. The empty values are listed in the `default` section. - -``` -empty .Foo -``` - -Note that in Go template conditionals, emptiness is calculated for you. Thus, -you rarely need `if empty .Foo`. Instead, just use `if .Foo`. - -## coalesce - -The `coalesce` function takes a list of values and returns the first non-empty -one. - -``` -coalesce 0 1 2 -``` - -The above returns `1`. - -This function is useful for scanning through multiple variables or values: - -``` -coalesce .name .parent.name "Matt" -``` - -The above will first check to see if `.name` is empty. If it is not, it will return -that value. If it _is_ empty, `coalesce` will evaluate `.parent.name` for emptiness. -Finally, if both `.name` and `.parent.name` are empty, it will return `Matt`. - -## all - -The `all` function takes a list of values and returns true if all values are non-empty. - -``` -all 0 1 2 -``` - -The above returns `false`. - -This function is useful for evaluating multiple conditions of variables or values: - -``` -all (eq .Request.TLS.Version 0x0304) (.Request.ProtoAtLeast 2 0) (eq .Request.Method "POST") -``` - -The above will check http.Request is POST with tls 1.3 and http/2. - -## any - -The `any` function takes a list of values and returns true if any value is non-empty. - -``` -any 0 1 2 -``` - -The above returns `true`. - -This function is useful for evaluating multiple conditions of variables or values: - -``` -any (eq .Request.Method "GET") (eq .Request.Method "POST") (eq .Request.Method "OPTIONS") -``` - -The above will check http.Request method is one of GET/POST/OPTIONS. - -## fromJSON, mustFromJSON - -`fromJSON` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string. -`mustFromJSON` will return an error in case the JSON is invalid. - -``` -fromJSON "{\"foo\": 55}" -``` - -## toJSON, mustToJSON - -The `toJSON` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string. -`mustToJSON` will return an error in case the item cannot be encoded in JSON. - -``` -toJSON .Item -``` - -The above returns JSON string representation of `.Item`. - -## toPrettyJSON, mustToPrettyJSON - -The `toPrettyJSON` function encodes an item into a pretty (indented) JSON string. - -``` -toPrettyJSON .Item -``` - -The above returns indented JSON string representation of `.Item`. - -## toRawJSON, mustToRawJSON - -The `toRawJSON` function encodes an item into JSON string with HTML characters unescaped. - -``` -toRawJSON .Item -``` - -The above returns unescaped JSON string representation of `.Item`. - -## ternary - -The `ternary` function takes two values, and a test value. If the test value is -true, the first value will be returned. If the test value is empty, the second -value will be returned. This is similar to the c ternary operator. - -### true test value - -``` -ternary "foo" "bar" true -``` - -or - -``` -true | ternary "foo" "bar" -``` - -The above returns `"foo"`. - -### false test value - -``` -ternary "foo" "bar" false -``` - -or - -``` -false | ternary "foo" "bar" -``` - -The above returns `"bar"`. diff --git a/docs/sprig/dicts.md b/docs/sprig/dicts.md deleted file mode 100644 index 5a4490d5..00000000 --- a/docs/sprig/dicts.md +++ /dev/null @@ -1,172 +0,0 @@ -# Dictionaries and Dict Functions - -Sprig provides a key/value storage type called a `dict` (short for "dictionary", -as in Python). A `dict` is an _unorder_ type. - -The key to a dictionary **must be a string**. However, the value can be any -type, even another `dict` or `list`. - -Unlike `list`s, `dict`s are not immutable. The `set` and `unset` functions will -modify the contents of a dictionary. - -## dict - -Creating dictionaries is done by calling the `dict` function and passing it a -list of pairs. - -The following creates a dictionary with three items: - -``` -$myDict := dict "name1" "value1" "name2" "value2" "name3" "value 3" -``` - -## get - -Given a map and a key, get the value from the map. - -``` -get $myDict "name1" -``` - -The above returns `"value1"` - -Note that if the key is not found, this operation will simply return `""`. No error -will be generated. - -## set - -Use `set` to add a new key/value pair to a dictionary. - -``` -$_ := set $myDict "name4" "value4" -``` - -Note that `set` _returns the dictionary_ (a requirement of Go template functions), -so you may need to trap the value as done above with the `$_` assignment. - -## unset - -Given a map and a key, delete the key from the map. - -``` -$_ := unset $myDict "name4" -``` - -As with `set`, this returns the dictionary. - -Note that if the key is not found, this operation will simply return. No error -will be generated. - -## hasKey - -The `hasKey` function returns `true` if the given dict contains the given key. - -``` -hasKey $myDict "name1" -``` - -If the key is not found, this returns `false`. - -## pluck - -The `pluck` function makes it possible to give one key and multiple maps, and -get a list of all of the matches: - -``` -pluck "name1" $myDict $myOtherDict -``` - -The above will return a `list` containing every found value (`[value1 otherValue1]`). - -If the give key is _not found_ in a map, that map will not have an item in the -list (and the length of the returned list will be less than the number of dicts -in the call to `pluck`. - -If the key is _found_ but the value is an empty value, that value will be -inserted. - -A common idiom in Sprig templates is to uses `pluck... | first` to get the first -matching key out of a collection of dictionaries. - -## dig - -The `dig` function traverses a nested set of dicts, selecting keys from a list -of values. It returns a default value if any of the keys are not found at the -associated dict. - -``` -dig "user" "role" "humanName" "guest" $dict -``` - -Given a dict structured like -``` -{ - user: { - role: { - humanName: "curator" - } - } -} -``` - -the above would return `"curator"`. If the dict lacked even a `user` field, -the result would be `"guest"`. - -Dig can be very useful in cases where you'd like to avoid guard clauses, -especially since Go's template package's `and` doesn't shortcut. For instance -`and a.maybeNil a.maybeNil.iNeedThis` will always evaluate -`a.maybeNil.iNeedThis`, and panic if `a` lacks a `maybeNil` field.) - -`dig` accepts its dict argument last in order to support pipelining. - -## keys - -The `keys` function will return a `list` of all of the keys in one or more `dict` -types. Since a dictionary is _unordered_, the keys will not be in a predictable order. -They can be sorted with `sortAlpha`. - -``` -keys $myDict | sortAlpha -``` - -When supplying multiple dictionaries, the keys will be concatenated. Use the `uniq` -function along with `sortAlpha` to get a unqiue, sorted list of keys. - -``` -keys $myDict $myOtherDict | uniq | sortAlpha -``` - -## pick - -The `pick` function selects just the given keys out of a dictionary, creating a -new `dict`. - -``` -$new := pick $myDict "name1" "name2" -``` - -The above returns `{name1: value1, name2: value2}` - -## omit - -The `omit` function is similar to `pick`, except it returns a new `dict` with all -the keys that _do not_ match the given keys. - -``` -$new := omit $myDict "name1" "name3" -``` - -The above returns `{name2: value2}` - -## values - -The `values` function is similar to `keys`, except it returns a new `list` with -all the values of the source `dict` (only one dictionary is supported). - -``` -$vals := values $myDict -``` - -The above returns `list["value1", "value2", "value 3"]`. Note that the `values` -function gives no guarantees about the result ordering- if you care about this, -then use `sortAlpha`. diff --git a/docs/sprig/encoding.md b/docs/sprig/encoding.md deleted file mode 100644 index 1c7a36f8..00000000 --- a/docs/sprig/encoding.md +++ /dev/null @@ -1,6 +0,0 @@ -# Encoding Functions - -Sprig has the following encoding and decoding functions: - -- `b64enc`/`b64dec`: Encode or decode with Base64 -- `b32enc`/`b32dec`: Encode or decode with Base32 diff --git a/docs/sprig/flow_control.md b/docs/sprig/flow_control.md deleted file mode 100644 index 6414640a..00000000 --- a/docs/sprig/flow_control.md +++ /dev/null @@ -1,11 +0,0 @@ -# Flow Control Functions - -## fail - -Unconditionally returns an empty `string` and an `error` with the specified -text. This is useful in scenarios where other conditionals have determined that -template rendering should fail. - -``` -fail "Please accept the end user license agreement" -``` diff --git a/docs/sprig/integer_slice.md b/docs/sprig/integer_slice.md deleted file mode 100644 index ab4bef6d..00000000 --- a/docs/sprig/integer_slice.md +++ /dev/null @@ -1,41 +0,0 @@ -# Integer List Functions - -## until - -The `until` function builds a range of integers. - -``` -until 5 -``` - -The above generates the list `[0, 1, 2, 3, 4]`. - -This is useful for looping with `range $i, $e := until 5`. - -## untilStep - -Like `until`, `untilStep` generates a list of counting integers. But it allows -you to define a start, stop, and step: - -``` -untilStep 3 6 2 -``` - -The above will produce `[3 5]` by starting with 3, and adding 2 until it is equal -or greater than 6. This is similar to Python's `range` function. - -## seq - -Works like the bash `seq` command. -* 1 parameter (end) - will generate all counting integers between 1 and `end` inclusive. -* 2 parameters (start, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by 1. -* 3 parameters (start, step, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by `step`. - -``` -seq 5 => 1 2 3 4 5 -seq -3 => 1 0 -1 -2 -3 -seq 0 2 => 0 1 2 -seq 2 -2 => 2 1 0 -1 -2 -seq 0 2 10 => 0 2 4 6 8 10 -seq 0 -2 -5 => 0 -2 -4 -``` diff --git a/docs/sprig/lists.md b/docs/sprig/lists.md deleted file mode 100644 index ed8c52b3..00000000 --- a/docs/sprig/lists.md +++ /dev/null @@ -1,188 +0,0 @@ -# Lists and List Functions - -Sprig provides a simple `list` type that can contain arbitrary sequential lists -of data. This is similar to arrays or slices, but lists are designed to be used -as immutable data types. - -Create a list of integers: - -``` -$myList := list 1 2 3 4 5 -``` - -The above creates a list of `[1 2 3 4 5]`. - -## first, mustFirst - -To get the head item on a list, use `first`. - -`first $myList` returns `1` - -`first` panics if there is a problem while `mustFirst` returns an error to the -template engine if there is a problem. - -## rest, mustRest - -To get the tail of the list (everything but the first item), use `rest`. - -`rest $myList` returns `[2 3 4 5]` - -`rest` panics if there is a problem while `mustRest` returns an error to the -template engine if there is a problem. - -## last, mustLast - -To get the last item on a list, use `last`: - -`last $myList` returns `5`. This is roughly analogous to reversing a list and -then calling `first`. - -`last` panics if there is a problem while `mustLast` returns an error to the -template engine if there is a problem. - -## initial, mustInitial - -This compliments `last` by returning all _but_ the last element. -`initial $myList` returns `[1 2 3 4]`. - -`initial` panics if there is a problem while `mustInitial` returns an error to the -template engine if there is a problem. - -## append, mustAppend - -Append a new item to an existing list, creating a new list. - -``` -$new = append $myList 6 -``` - -The above would set `$new` to `[1 2 3 4 5 6]`. `$myList` would remain unaltered. - -`append` panics if there is a problem while `mustAppend` returns an error to the -template engine if there is a problem. - -## prepend, mustPrepend - -Push an element onto the front of a list, creating a new list. - -``` -prepend $myList 0 -``` - -The above would produce `[0 1 2 3 4 5]`. `$myList` would remain unaltered. - -`prepend` panics if there is a problem while `mustPrepend` returns an error to the -template engine if there is a problem. - -## concat - -Concatenate arbitrary number of lists into one. - -``` -concat $myList ( list 6 7 ) ( list 8 ) -``` - -The above would produce `[1 2 3 4 5 6 7 8]`. `$myList` would remain unaltered. - -## reverse, mustReverse - -Produce a new list with the reversed elements of the given list. - -``` -reverse $myList -``` - -The above would generate the list `[5 4 3 2 1]`. - -`reverse` panics if there is a problem while `mustReverse` returns an error to the -template engine if there is a problem. - -## uniq, mustUniq - -Generate a list with all of the duplicates removed. - -``` -list 1 1 1 2 | uniq -``` - -The above would produce `[1 2]` - -`uniq` panics if there is a problem while `mustUniq` returns an error to the -template engine if there is a problem. - -## without, mustWithout - -The `without` function filters items out of a list. - -``` -without $myList 3 -``` - -The above would produce `[1 2 4 5]` - -Without can take more than one filter: - -``` -without $myList 1 3 5 -``` - -That would produce `[2 4]` - -`without` panics if there is a problem while `mustWithout` returns an error to the -template engine if there is a problem. - -## has, mustHas - -Test to see if a list has a particular element. - -``` -has 4 $myList -``` - -The above would return `true`, while `has "hello" $myList` would return false. - -`has` panics if there is a problem while `mustHas` returns an error to the -template engine if there is a problem. - -## compact, mustCompact - -Accepts a list and removes entries with empty values. - -``` -$list := list 1 "a" "foo" "" -$copy := compact $list -``` - -`compact` will return a new list with the empty (i.e., "") item removed. - -`compact` panics if there is a problem and `mustCompact` returns an error to the -template engine if there is a problem. - -## slice, mustSlice - -To get partial elements of a list, use `slice list [n] [m]`. It is -equivalent of `list[n:m]`. - -- `slice $myList` returns `[1 2 3 4 5]`. It is same as `myList[:]`. -- `slice $myList 3` returns `[4 5]`. It is same as `myList[3:]`. -- `slice $myList 1 3` returns `[2 3]`. It is same as `myList[1:3]`. -- `slice $myList 0 3` returns `[1 2 3]`. It is same as `myList[:3]`. - -`slice` panics if there is a problem while `mustSlice` returns an error to the -template engine if there is a problem. - -## chunk - -To split a list into chunks of given size, use `chunk size list`. This is useful for pagination. - -``` -chunk 3 (list 1 2 3 4 5 6 7 8) -``` - -This produces list of lists `[ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 ] ]`. - -## A Note on List Internals - -A list is implemented in Go as a `[]interface{}`. For Go developers embedding -Sprig, you may pass `[]interface{}` items into your template context and be -able to use all of the `list` functions on those items. diff --git a/docs/sprig/math.md b/docs/sprig/math.md deleted file mode 100644 index b08d0a2f..00000000 --- a/docs/sprig/math.md +++ /dev/null @@ -1,78 +0,0 @@ -# Integer Math Functions - -The following math functions operate on `int64` values. - -## add - -Sum numbers with `add`. Accepts two or more inputs. - -``` -add 1 2 3 -``` - -## add1 - -To increment by 1, use `add1` - -## sub - -To subtract, use `sub` - -## div - -Perform integer division with `div` - -## mod - -Modulo with `mod` - -## mul - -Multiply with `mul`. Accepts two or more inputs. - -``` -mul 1 2 3 -``` - -## max - -Return the largest of a series of integers: - -This will return `3`: - -``` -max 1 2 3 -``` - -## min - -Return the smallest of a series of integers. - -`min 1 2 3` will return `1` - -## floor - -Returns the greatest float value less than or equal to input value - -`floor 123.9999` will return `123.0` - -## ceil - -Returns the greatest float value greater than or equal to input value - -`ceil 123.001` will return `124.0` - -## round - -Returns a float value with the remainder rounded to the given number to digits after the decimal point. - -`round 123.555555 3` will return `123.556` - -## randInt -Returns a random integer value from min (inclusive) to max (exclusive). - -``` -randInt 12 30 -``` - -The above will produce a random number in the range [12,30]. diff --git a/docs/sprig/paths.md b/docs/sprig/paths.md deleted file mode 100644 index f847e357..00000000 --- a/docs/sprig/paths.md +++ /dev/null @@ -1,114 +0,0 @@ -# Path and Filepath Functions - -While Sprig does not grant access to the filesystem, it does provide functions -for working with strings that follow file path conventions. - -## Paths - -Paths separated by the slash character (`/`), processed by the `path` package. - -Examples: - -* The [Linux](https://en.wikipedia.org/wiki/Linux) and - [MacOS](https://en.wikipedia.org/wiki/MacOS) - [filesystems](https://en.wikipedia.org/wiki/File_system): - `/home/user/file`, `/etc/config`; -* The path component of - [URIs](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier): - `https://example.com/some/content/`, `ftp://example.com/file/`. - -### base - -Return the last element of a path. - -``` -base "foo/bar/baz" -``` - -The above prints "baz". - -### dir - -Return the directory, stripping the last part of the path. So `dir "foo/bar/baz"` -returns `foo/bar`. - -### clean - -Clean up a path. - -``` -clean "foo/bar/../baz" -``` - -The above resolves the `..` and returns `foo/baz`. - -### ext - -Return the file extension. - -``` -ext "foo.bar" -``` - -The above returns `.bar`. - -### isAbs - -To check whether a path is absolute, use `isAbs`. - -## Filepaths - -Paths separated by the `os.PathSeparator` variable, processed by the `path/filepath` package. - -These are the recommended functions to use when parsing paths of local filesystems, usually when dealing with local files, directories, etc. - -Examples: - -* Running on Linux or MacOS the filesystem path is separated by the slash character (`/`): - `/home/user/file`, `/etc/config`; -* Running on [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) - the filesystem path is separated by the backslash character (`\`): - `C:\Users\Username\`, `C:\Program Files\Application\`; - -### osBase - -Return the last element of a filepath. - -``` -osBase "/foo/bar/baz" -osBase "C:\\foo\\bar\\baz" -``` - -The above prints "baz" on Linux and Windows, respectively. - -### osDir - -Return the directory, stripping the last part of the path. So `osDir "/foo/bar/baz"` -returns `/foo/bar` on Linux, and `osDir "C:\\foo\\bar\\baz"` -returns `C:\\foo\\bar` on Windows. - -### osClean - -Clean up a path. - -``` -osClean "/foo/bar/../baz" -osClean "C:\\foo\\bar\\..\\baz" -``` - -The above resolves the `..` and returns `foo/baz` on Linux and `C:\\foo\\baz` on Windows. - -### osExt - -Return the file extension. - -``` -osExt "/foo.bar" -osExt "C:\\foo.bar" -``` - -The above returns `.bar` on Linux and Windows, respectively. - -### osIsAbs - -To check whether a file path is absolute, use `osIsAbs`. diff --git a/docs/sprig/reflection.md b/docs/sprig/reflection.md deleted file mode 100644 index 51e167aa..00000000 --- a/docs/sprig/reflection.md +++ /dev/null @@ -1,50 +0,0 @@ -# Reflection Functions - -Sprig provides rudimentary reflection tools. These help advanced template -developers understand the underlying Go type information for a particular value. - -Go has several primitive _kinds_, like `string`, `slice`, `int64`, and `bool`. - -Go has an open _type_ system that allows developers to create their own types. - -Sprig provides a set of functions for each. - -## Kind Functions - -There are two Kind functions: `kindOf` returns the kind of an object. - -``` -kindOf "hello" -``` - -The above would return `string`. For simple tests (like in `if` blocks), the -`kindIs` function will let you verify that a value is a particular kind: - -``` -kindIs "int" 123 -``` - -The above will return `true` - -## Type Functions - -Types are slightly harder to work with, so there are three different functions: - -- `typeOf` returns the underlying type of a value: `typeOf $foo` -- `typeIs` is like `kindIs`, but for types: `typeIs "*io.Buffer" $myVal` -- `typeIsLike` works as `typeIs`, except that it also dereferences pointers. - -**Note:** None of these can test whether or not something implements a given -interface, since doing so would require compiling the interface in ahead of time. - -## deepEqual - -`deepEqual` returns true if two values are ["deeply equal"](https://golang.org/pkg/reflect/#DeepEqual) - -Works for non-primitive types as well (compared to the built-in `eq`). - -``` -deepEqual (list 1 2 3) (list 1 2 3) -``` - -The above will return `true` diff --git a/docs/sprig/string_slice.md b/docs/sprig/string_slice.md deleted file mode 100644 index 96c0c83b..00000000 --- a/docs/sprig/string_slice.md +++ /dev/null @@ -1,72 +0,0 @@ -# String List Functions - -These function operate on or generate slices of strings. In Go, a slice is a -growable array. In Sprig, it's a special case of a `list`. - -## join - -Join a list of strings into a single string, with the given separator. - -``` -list "hello" "world" | join "_" -``` - -The above will produce `hello_world` - -`join` will try to convert non-strings to a string value: - -``` -list 1 2 3 | join "+" -``` - -The above will produce `1+2+3` - -## splitList and split - -Split a string into a list of strings: - -``` -splitList "$" "foo$bar$baz" -``` - -The above will return `[foo bar baz]` - -The older `split` function splits a string into a `dict`. It is designed to make -it easy to use template dot notation for accessing members: - -``` -$a := split "$" "foo$bar$baz" -``` - -The above produces a map with index keys. `{_0: foo, _1: bar, _2: baz}` - -``` -$a._0 -``` - -The above produces `foo` - -## splitn - -`splitn` function splits a string into a `dict` with `n` keys. It is designed to make -it easy to use template dot notation for accessing members: - -``` -$a := splitn "$" 2 "foo$bar$baz" -``` - -The above produces a map with index keys. `{_0: foo, _1: bar$baz}` - -``` -$a._0 -``` - -The above produces `foo` - -## sortAlpha - -The `sortAlpha` function sorts a list of strings into alphabetical (lexicographical) -order. - -It does _not_ sort in place, but returns a sorted copy of the list, in keeping -with the immutability of lists. diff --git a/docs/sprig/strings.md b/docs/sprig/strings.md deleted file mode 100644 index 784392f1..00000000 --- a/docs/sprig/strings.md +++ /dev/null @@ -1,309 +0,0 @@ -# String Functions - -Sprig has a number of string manipulation functions. - -## trim - -The `trim` function removes space from either side of a string: - -``` -trim " hello " -``` - -The above produces `hello` - -## trimAll - -Remove given characters from the front or back of a string: - -``` -trimAll "$" "$5.00" -``` - -The above returns `5.00` (as a string). - -## trimSuffix - -Trim just the suffix from a string: - -``` -trimSuffix "-" "hello-" -``` - -The above returns `hello` - -## trimPrefix - -Trim just the prefix from a string: - -``` -trimPrefix "-" "-hello" -``` - -The above returns `hello` - -## upper - -Convert the entire string to uppercase: - -``` -upper "hello" -``` - -The above returns `HELLO` - -## lower - -Convert the entire string to lowercase: - -``` -lower "HELLO" -``` - -The above returns `hello` - -## title - -Convert to title case: - -``` -title "hello world" -``` - -The above returns `Hello World` - -## repeat - -Repeat a string multiple times: - -``` -repeat 3 "hello" -``` - -The above returns `hellohellohello` - -## substr - -Get a substring from a string. It takes three parameters: - -- start (int) -- end (int) -- string (string) - -``` -substr 0 5 "hello world" -``` - -The above returns `hello` - -## trunc - -Truncate a string (and add no suffix) - -``` -trunc 5 "hello world" -``` - -The above produces `hello`. - -``` -trunc -5 "hello world" -``` - -The above produces `world`. - -## contains - -Test to see if one string is contained inside of another: - -``` -contains "cat" "catch" -``` - -The above returns `true` because `catch` contains `cat`. - -## hasPrefix and hasSuffix - -The `hasPrefix` and `hasSuffix` functions test whether a string has a given -prefix or suffix: - -``` -hasPrefix "cat" "catch" -``` - -The above returns `true` because `catch` has the prefix `cat`. - -## quote and squote - -These functions wrap a string in double quotes (`quote`) or single quotes -(`squote`). - -## cat - -The `cat` function concatenates multiple strings together into one, separating -them with spaces: - -``` -cat "hello" "beautiful" "world" -``` - -The above produces `hello beautiful world` - -## indent - -The `indent` function indents every line in a given string to the specified -indent width. This is useful when aligning multi-line strings: - -``` -indent 4 $lots_of_text -``` - -The above will indent every line of text by 4 space characters. - -## nindent - -The `nindent` function is the same as the indent function, but prepends a new -line to the beginning of the string. - -``` -nindent 4 $lots_of_text -``` - -The above will indent every line of text by 4 space characters and add a new -line to the beginning. - -## replace - -Perform simple string replacement. - -It takes three arguments: - -- string to replace -- string to replace with -- source string - -``` -"I Am Henry VIII" | replace " " "-" -``` - -The above will produce `I-Am-Henry-VIII` - -## plural - -Pluralize a string. - -``` -len $fish | plural "one anchovy" "many anchovies" -``` - -In the above, if the length of the string is 1, the first argument will be -printed (`one anchovy`). Otherwise, the second argument will be printed -(`many anchovies`). - -The arguments are: - -- singular string -- plural string -- length integer - -NOTE: Sprig does not currently support languages with more complex pluralization -rules. And `0` is considered a plural because the English language treats it -as such (`zero anchovies`). The Sprig developers are working on a solution for -better internationalization. - -## regexMatch, mustRegexMatch - -Returns true if the input string contains any match of the regular expression. - -``` -regexMatch "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$" "test@acme.com" -``` - -The above produces `true` - -`regexMatch` panics if there is a problem and `mustRegexMatch` returns an error to the -template engine if there is a problem. - -## regexFindAll, mustRegexFindAll - -Returns a slice of all matches of the regular expression in the input string. -The last parameter n determines the number of substrings to return, where -1 means return all matches - -``` -regexFindAll "[2,4,6,8]" "123456789" -1 -``` - -The above produces `[2 4 6 8]` - -`regexFindAll` panics if there is a problem and `mustRegexFindAll` returns an error to the -template engine if there is a problem. - -## regexFind, mustRegexFind - -Return the first (left most) match of the regular expression in the input string - -``` -regexFind "[a-zA-Z][1-9]" "abcd1234" -``` - -The above produces `d1` - -`regexFind` panics if there is a problem and `mustRegexFind` returns an error to the -template engine if there is a problem. - -## regexReplaceAll, mustRegexReplaceAll - -Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. -Inside string replacement, $ signs are interpreted as in Expand, so for instance $1 represents the text of the first submatch - -``` -regexReplaceAll "a(x*)b" "-ab-axxb-" "${1}W" -``` - -The above produces `-W-xxW-` - -`regexReplaceAll` panics if there is a problem and `mustRegexReplaceAll` returns an error to the -template engine if there is a problem. - -## regexReplaceAllLiteral, mustRegexReplaceAllLiteral - -Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement -The replacement string is substituted directly, without using Expand - -``` -regexReplaceAllLiteral "a(x*)b" "-ab-axxb-" "${1}" -``` - -The above produces `-${1}-${1}-` - -`regexReplaceAllLiteral` panics if there is a problem and `mustRegexReplaceAllLiteral` returns an error to the -template engine if there is a problem. - -## regexSplit, mustRegexSplit - -Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. The last parameter `n` determines the number of substrings to return, where `-1` means return all matches - -``` -regexSplit "z+" "pizza" -1 -``` - -The above produces `[pi a]` - -`regexSplit` panics if there is a problem and `mustRegexSplit` returns an error to the -template engine if there is a problem. - -## regexQuoteMeta - -Returns a string that escapes all regular expression metacharacters inside the argument text; -the returned string is a regular expression matching the literal text. - -``` -regexQuoteMeta "1.2.3" -``` - -The above produces `1\.2\.3` - -## See Also... - -The [Conversion Functions](conversion.md) contain functions for converting strings. The [String List Functions](string_slice.md) contains -functions for working with an array of strings. diff --git a/docs/sprig/url.md b/docs/sprig/url.md deleted file mode 100644 index 21d54a29..00000000 --- a/docs/sprig/url.md +++ /dev/null @@ -1,33 +0,0 @@ -# URL Functions - -## urlParse -Parses string for URL and produces dict with URL parts - -``` -urlParse "http://admin:secret@server.com:8080/api?list=false#anchor" -``` - -The above returns a dict, containing URL object: -```yaml -scheme: 'http' -host: 'server.com:8080' -path: '/api' -query: 'list=false' -opaque: nil -fragment: 'anchor' -userinfo: 'admin:secret' -``` - -For more info, check https://golang.org/pkg/net/url/#URL - -## urlJoin -Joins map (produced by `urlParse`) to produce URL string - -``` -urlJoin (dict "fragment" "fragment" "host" "host:80" "path" "/path" "query" "query" "scheme" "http") -``` - -The above returns the following string: -``` -proto://host:80/path?query#fragment -``` diff --git a/docs/sprig/uuid.md b/docs/sprig/uuid.md deleted file mode 100644 index 1b57a330..00000000 --- a/docs/sprig/uuid.md +++ /dev/null @@ -1,9 +0,0 @@ -# UUID Functions - -Sprig can generate UUID v4 universally unique IDs. - -``` -uuidv4 -``` - -The above returns a new UUID of the v4 (randomly generated) type. diff --git a/docs/static/img/android-screenshot-template-custom.png b/docs/static/img/android-screenshot-template-custom.png new file mode 100644 index 00000000..8325e9a4 Binary files /dev/null and b/docs/static/img/android-screenshot-template-custom.png differ diff --git a/docs/static/img/android-screenshot-template-predefined.png b/docs/static/img/android-screenshot-template-predefined.png new file mode 100644 index 00000000..ba77c31d Binary files /dev/null and b/docs/static/img/android-screenshot-template-predefined.png differ diff --git a/docs/static/img/screenshot-github-webhook-config.png b/docs/static/img/screenshot-github-webhook-config.png new file mode 100644 index 00000000..46b784b3 Binary files /dev/null and b/docs/static/img/screenshot-github-webhook-config.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 8006eac4..ef746518 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -94,7 +94,6 @@ nav: - "Integrations + projects": integrations.md - "Release notes": releases.md - "Emojis 🥳 🎉": emojis.md - - "Template Functions": sprig.md - "Troubleshooting": troubleshooting.md - "Known issues": known-issues.md - "Deprecation notices": deprecations.md diff --git a/server/config.go b/server/config.go index c5560010..9c1c4e10 100644 --- a/server/config.go +++ b/server/config.go @@ -11,6 +11,8 @@ import ( // Defines default config settings (excluding limits, see below) const ( DefaultListenHTTP = ":80" + DefaultConfigFile = "/etc/ntfy/server.yml" + DefaultTemplateDir = "/etc/ntfy/templates" DefaultCacheDuration = 12 * time.Hour DefaultCacheBatchTimeout = time.Duration(0) DefaultKeepaliveInterval = 45 * time.Second // Not too frequently to save battery (Android read timeout used to be 77s!) @@ -173,7 +175,7 @@ type Config struct { // NewConfig instantiates a default new server config func NewConfig() *Config { return &Config{ - File: "", // Only used for testing + File: DefaultConfigFile, // Only used for testing BaseURL: "", ListenHTTP: DefaultListenHTTP, ListenHTTPS: "", @@ -196,6 +198,7 @@ func NewConfig() *Config { AttachmentTotalSizeLimit: DefaultAttachmentTotalSizeLimit, AttachmentFileSizeLimit: DefaultAttachmentFileSizeLimit, AttachmentExpiryDuration: DefaultAttachmentExpiryDuration, + TemplateDir: DefaultTemplateDir, KeepaliveInterval: DefaultKeepaliveInterval, ManagerInterval: DefaultManagerInterval, DisallowedTopics: DefaultDisallowedTopics, @@ -258,6 +261,5 @@ func NewConfig() *Config { WebPushEmailAddress: "", WebPushExpiryDuration: DefaultWebPushExpiryDuration, WebPushExpiryWarningDuration: DefaultWebPushExpiryWarningDuration, - TemplateDir: "", } } diff --git a/server/server.yml b/server/server.yml index e1a58232..db968498 100644 --- a/server/server.yml +++ b/server/server.yml @@ -126,6 +126,26 @@ # attachment-file-size-limit: "15M" # attachment-expiry-duration: "3h" +# Template directory for message templates. +# +# When "X-Template: " (aliases: "Template: ", "Tpl: ") or "?template=" is set, transform the message +# based on one of the built-in pre-defined templates, or on a template defined in the "template-dir" directory. +# +# Template files must have the ".yml" extension and must be formatted as YAML. They may contain "title" and "message" keys, +# which are interpreted as Go templates. +# +# Example template file (e.g. /etc/ntfy/templates/grafana.yml): +# title: | +# {{- if eq .status "firing" }} +# {{ .title | default "Alert firing" }} +# {{- else if eq .status "resolved" }} +# {{ .title | default "Alert resolved" }} +# {{- end }} +# message: | +# {{ .message | trunc 2000 }} +# +# template-dir: "/etc/ntfy/templates" + # If enabled, allow outgoing e-mail notifications via the 'X-Email' header. If this header is set, # messages will additionally be sent out as e-mail using an external SMTP server. # diff --git a/server/server_test.go b/server/server_test.go index a783dbd2..c904cbb7 100644 --- a/server/server_test.go +++ b/server/server_test.go @@ -2918,7 +2918,7 @@ func TestServer_MessageTemplate_Range(t *testing.T) { require.Equal(t, 200, response.Code) m := toMessage(t, response.Body.String()) - require.Equal(t, "Severe URLs:\n- https://severe1.com\n- https://severe2.com\n", m.Message) + require.Equal(t, "Severe URLs:\n- https://severe1.com\n- https://severe2.com", m.Message) } func TestServer_MessageTemplate_ExceedMessageSize_TemplatedMessageOK(t *testing.T) { @@ -2971,8 +2971,7 @@ Labels: Annotations: - summary = 15m load average too high Source: localhost:3000/alerting/grafana/NW9oDw-4z/view -Silence: localhost:3000/alerting/silence/new?alertmanager=grafana&matcher=alertname%3DLoad+avg+15m+too+high&matcher=grafana_folder%3DNode+alerts&matcher=instance%3D10.108.0.2%3A9100&matcher=job%3Dnode-exporter -`, m.Message) +Silence: localhost:3000/alerting/silence/new?alertmanager=grafana&matcher=alertname%3DLoad+avg+15m+too+high&matcher=grafana_folder%3DNode+alerts&matcher=instance%3D10.108.0.2%3A9100&matcher=job%3Dnode-exporter`, m.Message) } func TestServer_MessageTemplate_GitHub(t *testing.T) { @@ -3073,18 +3072,75 @@ func TestServer_MessageTemplate_UnsafeSprigFunctions(t *testing.T) { var ( //go:embed testdata/webhook_github_comment_created.json githubCommentCreatedJSON string + + //go:embed testdata/webhook_github_issue_opened.json + githubIssueOpenedJSON string ) -func TestServer_MessageTemplate_FromNamedTemplate(t *testing.T) { +func TestServer_MessageTemplate_FromNamedTemplate_GitHubCommentCreated(t *testing.T) { t.Parallel() s := newTestServer(t, newTestConfig(t)) - response := request(t, s, "POST", "/mytopic", githubCommentCreatedJSON, map[string]string{ - "Template": "github", - }) + response := request(t, s, "POST", "/mytopic?template=github", githubCommentCreatedJSON, nil) require.Equal(t, 200, response.Code) m := toMessage(t, response.Body.String()) - require.Equal(t, "💬 New comment on issue #1389 — instant alerts without Pull to refresh", m.Title) - require.Equal(t, "💬 New comment on issue #1389 — instant alerts without Pull to refresh", m.Message) + require.Equal(t, "💬 [ntfy] New comment on issue #1389 instant alerts without Pull to refresh", m.Title) + require.Equal(t, `Commenter: https://github.com/wunter8 +Repository: https://github.com/binwiederhier/ntfy +Comment link: https://github.com/binwiederhier/ntfy/issues/1389#issuecomment-3078214289 + +Comment: +These are the things you need to do to get iOS push notifications to work: +1. open a browser to the web app of your ntfy instance and copy the URL (including "http://" or "https://", your domain or IP address, and any ports, and excluding any trailing slashes) +2. put the URL you copied in the ntfy `+"`"+`base-url`+"`"+` config in server.yml or NTFY_BASE_URL in env variables +3. put the URL you copied in the default server URL setting in the iOS ntfy app +4. set `+"`"+`upstream-base-url`+"`"+` in server.yml or NTFY_UPSTREAM_BASE_URL in env variables to "https://ntfy.sh" (without a trailing slash)`, m.Message) +} + +func TestServer_MessageTemplate_FromNamedTemplate_GitHubIssueOpened(t *testing.T) { + t.Parallel() + s := newTestServer(t, newTestConfig(t)) + response := request(t, s, "POST", "/mytopic?template=github", githubIssueOpenedJSON, nil) + require.Equal(t, 200, response.Code) + m := toMessage(t, response.Body.String()) + require.Equal(t, "🐛 [ntfy] Issue opened: #1391 http 500 error (ntfy error 50001)", m.Title) + require.Equal(t, `Opened by: https://github.com/TheUser-dev +Repository: https://github.com/binwiederhier/ntfy +Issue link: https://github.com/binwiederhier/ntfy/issues/1391 +Labels: 🪲 bug + +Description: +:lady_beetle: **Describe the bug** +When sending a notification (especially when it happens with multiple requests) this error occurs + +:computer: **Components impacted** +ntfy server 2.13.0 in docker, debian 12 arm64 + +:bulb: **Screenshots and/or logs** +`+"```"+` +closed with HTTP 500 (ntfy error 50001) (error=database table is locked, http_method=POST, http_path=/_matrix/push/v1/notify, tag=http, visitor_auth_limiter_limit=0.016666666666666666, visitor_auth_limiter_tokens=30, visitor_id=ip:, visitor_ip=, visitor_messages=448, visitor_messages_limit=17280, visitor_messages_remaining=16832, visitor_request_limiter_limit=0.2, visitor_request_limiter_tokens=57.049697891799994, visitor_seen=2025-07-16T15:06:35.429Z) +`+"```"+` + +:crystal_ball: **Additional context** +Looks like this has already been fixed by #498, regression?`, m.Message) +} + +func TestServer_MessageTemplate_FromNamedTemplate_GitHubIssueOpened_OverrideConfigTemplate(t *testing.T) { + t.Parallel() + c := newTestConfig(t) + c.TemplateDir = t.TempDir() + require.NoError(t, os.WriteFile(filepath.Join(c.TemplateDir, "github.yml"), []byte(` +title: | + Custom title: action={{ .action }} trunctitle={{ .issue.title | trunc 10 }} +message: | + Custom message {{ .issue.number }} +`), 0644)) + s := newTestServer(t, c) + response := request(t, s, "POST", "/mytopic?template=github", githubIssueOpenedJSON, nil) + fmt.Println(response.Body.String()) + require.Equal(t, 200, response.Code) + m := toMessage(t, response.Body.String()) + require.Equal(t, "Custom title: action=opened trunctitle=http 500 e", m.Title) + require.Equal(t, "Custom message 1391", m.Message) } func newTestConfig(t *testing.T) *Config { @@ -3093,6 +3149,7 @@ func newTestConfig(t *testing.T) *Config { conf.CacheFile = filepath.Join(t.TempDir(), "cache.db") conf.CacheStartupQueries = "pragma journal_mode = WAL; pragma synchronous = normal; pragma temp_store = memory;" conf.AttachmentCacheDir = t.TempDir() + conf.TemplateDir = t.TempDir() return conf } diff --git a/server/templates/alertmanager.yml b/server/templates/alertmanager.yml new file mode 100644 index 00000000..803bbfcb --- /dev/null +++ b/server/templates/alertmanager.yml @@ -0,0 +1,29 @@ +title: | + {{- if eq .status "firing" }} + 🚨 Alert: {{ (first .alerts).labels.alertname }} + {{- else if eq .status "resolved" }} + ✅ Resolved: {{ (first .alerts).labels.alertname }} + {{- else }} + {{ fail "Unsupported Alertmanager status." }} + {{- end }} +message: | + Status: {{ .status | title }} + Receiver: {{ .receiver }} + + {{- range .alerts }} + Alert: {{ .labels.alertname }} + Instance: {{ .labels.instance }} + Severity: {{ .labels.severity }} + Starts at: {{ .startsAt }} + {{- if .endsAt }}Ends at: {{ .endsAt }}{{ end }} + {{- if .annotations.summary }} + Summary: {{ .annotations.summary }} + {{- end }} + {{- if .annotations.description }} + Description: {{ .annotations.description }} + {{- end }} + Source: {{ .generatorURL }} + + {{ end }} + + diff --git a/server/templates/github.yml b/server/templates/github.yml index 5d1b0b46..2c2922a2 100644 --- a/server/templates/github.yml +++ b/server/templates/github.yml @@ -6,7 +6,7 @@ title: | 👀 {{ .sender.login }} started watching {{ .repository.name }} {{- else if and .comment (eq .action "created") }} - 💬 New comment on #{{ .issue.number }}: {{ .issue.title }} + 💬 New comment on issue #{{ .issue.number }} {{ .issue.title }} {{- else if .pull_request }} 🔀 Pull request {{ .action }}: #{{ .pull_request.number }} {{ .pull_request.title }} @@ -47,6 +47,7 @@ message: | {{ .action | title }} by: {{ .issue.user.html_url }} Repository: {{ .repository.html_url }} Issue link: {{ .issue.html_url }} + {{ if .issue.labels }}Labels: {{ range .issue.labels }}{{ .name }} {{ end }}{{ end }} {{ if .issue.body }} Description: {{ .issue.body | trunc 2000 }}{{ end }} diff --git a/server/templates/grafana.yml b/server/templates/grafana.yml index 42a16deb..658aa550 100644 --- a/server/templates/grafana.yml +++ b/server/templates/grafana.yml @@ -1,9 +1,11 @@ -message: | - {{if .alerts}} - {{.alerts | len}} alert(s) triggered - {{else}} - No alerts triggered. - {{end}} title: | - ⚠️ Grafana alert: {{.title}} + {{- if eq .status "firing" }} + 🚨 {{ .title | default "Alert firing" }} + {{- else if eq .status "resolved" }} + ✅ {{ .title | default "Alert resolved" }} + {{- else }} + ⚠️ Unknown alert: {{ .title | default "Alert" }} + {{- end }} +message: | + {{ .message | trunc 2000 }} diff --git a/server/testdata/webhook_alertmanager_firing.json b/server/testdata/webhook_alertmanager_firing.json new file mode 100644 index 00000000..9155bd9e --- /dev/null +++ b/server/testdata/webhook_alertmanager_firing.json @@ -0,0 +1,33 @@ +{ + "version": "4", + "groupKey": "...", + "status": "firing", + "receiver": "webhook-receiver", + "groupLabels": { + "alertname": "HighCPUUsage" + }, + "commonLabels": { + "alertname": "HighCPUUsage", + "instance": "server01", + "severity": "critical" + }, + "commonAnnotations": { + "summary": "High CPU usage detected" + }, + "alerts": [ + { + "status": "firing", + "labels": { + "alertname": "HighCPUUsage", + "instance": "server01", + "severity": "critical" + }, + "annotations": { + "summary": "High CPU usage detected" + }, + "startsAt": "2025-07-17T07:00:00Z", + "endsAt": "0001-01-01T00:00:00Z", + "generatorURL": "http://prometheus.local/graph?g0.expr=..." + } + ] +} diff --git a/server/testdata/webhook_grafana_resolved.json b/server/testdata/webhook_grafana_resolved.json new file mode 100644 index 00000000..41494578 --- /dev/null +++ b/server/testdata/webhook_grafana_resolved.json @@ -0,0 +1,51 @@ +{ + "receiver": "ntfy\\.example\\.com/alerts", + "status": "resolved", + "alerts": [ + { + "status": "resolved", + "labels": { + "alertname": "Load avg 15m too high", + "grafana_folder": "Node alerts", + "instance": "10.108.0.2:9100", + "job": "node-exporter" + }, + "annotations": { + "summary": "15m load average too high" + }, + "startsAt": "2024-03-15T02:28:00Z", + "endsAt": "2024-03-15T02:42:00Z", + "generatorURL": "localhost:3000/alerting/grafana/NW9oDw-4z/view", + "fingerprint": "becbfb94bd81ef48", + "silenceURL": "localhost:3000/alerting/silence/new?alertmanager=grafana&matcher=alertname%3DLoad+avg+15m+too+high&matcher=grafana_folder%3DNode+alerts&matcher=instance%3D10.108.0.2%3A9100&matcher=job%3Dnode-exporter", + "dashboardURL": "", + "panelURL": "", + "values": { + "B": 18.98211314475876, + "C": 0 + }, + "valueString": "[ var='B' labels={__name__=node_load15, instance=10.108.0.2:9100, job=node-exporter} value=18.98211314475876 ], [ var='C' labels={__name__=node_load15, instance=10.108.0.2:9100, job=node-exporter} value=0 ]" + } + ], + "groupLabels": { + "alertname": "Load avg 15m too high", + "grafana_folder": "Node alerts" + }, + "commonLabels": { + "alertname": "Load avg 15m too high", + "grafana_folder": "Node alerts", + "instance": "10.108.0.2:9100", + "job": "node-exporter" + }, + "commonAnnotations": { + "summary": "15m load average too high" + }, + "externalURL": "localhost:3000/", + "version": "1", + "groupKey": "{}:{alertname=\"Load avg 15m too high\", grafana_folder=\"Node alerts\"}", + "truncatedAlerts": 0, + "orgId": 1, + "title": "[RESOLVED] Load avg 15m too high Node alerts (10.108.0.2:9100 node-exporter)", + "state": "ok", + "message": "**Resolved**\n\nValue: B=18.98211314475876, C=0\nLabels:\n - alertname = Load avg 15m too high\n - grafana_folder = Node alerts\n - instance = 10.108.0.2:9100\n - job = node-exporter\n" +}