feat(templates): expose public app URLs in notification data

Author: gi8lino

README.md

@@ -99,6 +99,7 @@ Core settings:
 | -------------------- | --------------------------- | ----------- | -------------------------------------------------------------------------- |
 | `--listen-address`   | `OVERDUE__LISTEN_ADDRESS`   | `:8080`     | HTTP server listen address.                                                |
 | `--route-prefix`     | `OVERDUE__ROUTE_PREFIX`     | empty       | Path prefix to mount the service under.                                    |
+| `--public-url`       | `OVERDUE__PUBLIC_URL`       | empty       | Externally reachable base URL used in notification templates.              |
 | `--check-in-name`    | `OVERDUE__CHECK_IN_NAME`    | `default`   | Name of the check-in monitor used in notifications.                        |
 | `--check-in-path`    | `OVERDUE__CHECK_IN_PATH`    | `/check-in` | Route used to receive check-ins.                                           |
 | `--start-active`     | `OVERDUE__START_ACTIVE`     | `false`     | Activate the monitor at startup instead of waiting for the first check-in. |
@@ -112,6 +113,7 @@ Environment variables use the `OVERDUE__` prefix. Flag names are uppercased and
 Dynamic notification flags include the target name:
 
 ```text
+--public-url                      -> OVERDUE__PUBLIC_URL
 --webhook.ops.url                  -> OVERDUE__WEBHOOK_OPS_URL
 --webhook.ops.method               -> OVERDUE__WEBHOOK_OPS_METHOD
 --webhook.ops.custom-data          -> OVERDUE__WEBHOOK_OPS_CUSTOM_DATA
@@ -158,7 +160,7 @@ Custom templates can be mounted into the container and referenced by path:
 -e OVERDUE__WEBHOOK_OPS_TEMPLATE=/etc/overdue/slack.tmpl
 ```
 
-Webhook templates must render valid JSON. Email templates may render text or HTML.
+Webhook templates must render valid JSON. Email templates may render text or HTML. When `--public-url` is configured, templates can use `.App.PublicURL`, `.App.CheckInURL`, and `.App.StatusURL`.
 
 See [docs/templates.md](docs/templates.md) for built-in templates, template data, and helper functions.
 
@@ -187,3 +189,5 @@ See [docs/api.md](docs/api.md) for response examples and route prefix details.
 ## License
 
 This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
+
+

docs/configuration.md

@@ -10,6 +10,7 @@ Environment variables use the `OVERDUE__` prefix. Flag names are uppercased and
 --expected-every        -> OVERDUE__EXPECTED_EVERY
 --alerting-delay        -> OVERDUE__ALERTING_DELAY
 --check-in-name         -> OVERDUE__CHECK_IN_NAME
+--public-url            -> OVERDUE__PUBLIC_URL
 --response-details      -> OVERDUE__RESPONSE_DETAILS
 ```
 
@@ -38,6 +39,7 @@ Dynamic notification flags include the target name:
 | -------------------- | --------------------------- | ----------- | -------------------------------------------------------------------------- |
 | `--listen-address`   | `OVERDUE__LISTEN_ADDRESS`   | `:8080`     | HTTP server listen address.                                                |
 | `--route-prefix`     | `OVERDUE__ROUTE_PREFIX`     | empty       | Path prefix to mount the service under.                                    |
+| `--public-url`       | `OVERDUE__PUBLIC_URL`       | empty       | Externally reachable base URL used in notification templates.              |
 | `--check-in-name`    | `OVERDUE__CHECK_IN_NAME`    | `default`   | Name of the check-in monitor used in notifications.                        |
 | `--check-in-path`    | `OVERDUE__CHECK_IN_PATH`    | `/check-in` | Route used to receive check-ins.                                           |
 | `--expected-every`   | `OVERDUE__EXPECTED_EVERY`   | required    | Maximum time between check-ins.                                            |
@@ -132,6 +134,34 @@ This becomes:
 /overdue
 ```
 
+## Public URL
+
+Use `--public-url` to expose externally reachable links to notification templates. The value may include an ingress or reverse-proxy path prefix. It is not derived from `--listen-address`, because listen addresses such as `:8080` or `0.0.0.0:8080` are usually not public URLs.
+
+```sh
+overdue \
+  --public-url=https://example.com/overdue \
+  --check-in-path=/check-in \
+  --expected-every=1m \
+  --alerting-delay=10s
+```
+
+Templates can then use:
+
+```gotemplate
+{{ .App.PublicURL }}
+{{ .App.CheckInURL }}
+{{ .App.StatusURL }}
+```
+
+With the example above, those values are:
+
+```text
+.App.PublicURL  = https://example.com/overdue
+.App.CheckInURL = https://example.com/overdue/check-in
+.App.StatusURL  = https://example.com/overdue/status
+```
+
 ## Authentication
 
 Set `--auth-token` to require bearer-token auth for `/check-in` and `/status`.
@@ -187,3 +217,5 @@ Use it through the environment when possible:
 ```sh
 export OVERDUE__AUTH_TOKEN="$(openssl rand -hex 32)"
 ```
+
+

docs/notifications.md

@@ -23,6 +23,8 @@ And this creates an email target named `primary`:
 
 If no notification targets are configured, Overdue still runs and records status, but sends no notifications.
 
+Set `--public-url` when notification templates should include externally reachable Overdue links. The value is exposed as `.App.PublicURL`; `.App.CheckInURL` and `.App.StatusURL` are derived from it.
+
 ## Environment variables
 
 Dynamic notification flags include the target name.
@@ -269,3 +271,5 @@ For fan-out delivery, successful targets are not called again on the next retry.
 Retry backoff starts at `1s` and is capped at `1m`.
 
 Both alerting and resolved notifications keep their `.NotificationID` across retries.
+
+

docs/templates.md

@@ -63,8 +63,11 @@ Notification templates receive a check-in lifecycle event.
 | `.Resolved`       | bool              | `true` for resolved notifications.                                                            |
 | `.Title`          | string            | Rendered notification title. Available in body and subject templates.                         |
 | `.Text`           | string            | Rendered notification text. Available in body templates.                                      |
+| `.App`            | struct            | Application link data derived from `--public-url`. Empty when no public URL is configured.    |
 | `.CustomData`     | map[string]string | Target-local custom data from `--webhook.<name>.custom-data` or `--email.<name>.custom-data`. |
 
+`.App` contains `.App.PublicURL`, `.App.CheckInURL`, and `.App.StatusURL`. `--public-url` is the externally reachable base URL and may include a path prefix. `.App.CheckInURL` appends the configured check-in path, and `.App.StatusURL` appends `/status`.
+
 Custom data keys that are valid Go template identifiers can be read with dot notation, such as `.CustomData.channel`. Other keys can be read with `index`, such as `{{ index .CustomData "team-name" }}`.
 
 Example:
@@ -74,7 +77,8 @@ Example:
 
 Check-in: {{ .CheckInName }}
 Status: {{ .Status }}
-Channel: {{ .CustomData.channel | default "#alertmanager" | withPrefix "#" }}
+Channel: {{ .CustomData.channel | default "alertmanager" | withPrefix "#" }}
+Status URL: {{ .App.StatusURL }}
 Expected by: {{ .ExpectedBy.Format "2006-01-02 15:04:05 MST" }}
 Alerting at: {{ .AlertingAt.Format "2006-01-02 15:04:05 MST" }}
 ```
@@ -100,7 +104,7 @@ The helpers can also be called without pipelines:
 
 ```gotemplate
 {{ json .Text }}
-{{ when "Resolved at" "Notified at" .Resolved }}
+{{ when .Resolved "Resolved at" "Notified at" }}
 {{ default "unknown" .CheckInName }}
 {{ withPrefix "#" .CustomData.channel }}
 {{ withSuffix "/" .CustomData.path }}
@@ -135,7 +139,10 @@ For Slack channel rendering, combine `default`, `withPrefix`, and `json`:
 
 ```gotemplate
 {
-  "channel": {{ .CustomData.channel | default "#alertmanager" | withPrefix "#" | json }},
-  "text": {{ .Text | json }}
+  "channel": {{ .CustomData.channel | default "alertmanager" | withPrefix "#" | json }},
+  "text": {{ .Text | json }},
+  "status_url": {{ .App.StatusURL | json }}
 }
 ```
+
+

internal/app/run.go

@@ -46,6 +46,7 @@ func Run(
 		"check-in receiver configured",
 		"listenAddr", flags.ListenAddr,
 		"routePrefix", flags.RoutePrefix,
+		"publicURL", flags.PublicURL,
 		"checkInName", flags.CheckInName,
 		"checkInPath", flags.CheckInPath,
 		"expectedEvery", flags.ExpectedEvery.String(),

internal/flag/flag.go

@@ -13,6 +13,7 @@ import (
 	"github.com/containeroo/httputils"
 	"github.com/containeroo/overdue/internal/logging"
 	"github.com/containeroo/overdue/internal/notification/notifier"
+	"github.com/containeroo/overdue/internal/notification/render"
 	"github.com/containeroo/overdue/internal/notification/targets"
 	"github.com/containeroo/tinyflags"
 )
@@ -26,6 +27,7 @@ const (
 type Config struct {
 	ListenAddr      string
 	RoutePrefix     string
+	PublicURL       string
 	CheckInName     string
 	CheckInPath     string
 	ExpectedEvery   time.Duration
@@ -62,6 +64,26 @@ func ParseArgs(args []string, version string) (Config, error) {
 		Placeholder("PATH").
 		Value()
 
+	tf.StringVar(&cfg.PublicURL, "public-url", "", "Externally reachable base URL used in notification templates").
+		Finalize(func(s string) string {
+			return strings.TrimRight(strings.TrimSpace(s), "/")
+		}).
+		FinalizeDefaultValue().
+		Placeholder("URL").
+		Validate(func(raw string) error {
+			if strings.TrimSpace(raw) == "" {
+				return nil
+			}
+
+			u, err := url.Parse(raw)
+			if err != nil || u.Scheme == "" || u.Host == "" {
+				return errors.New("public-url must be a valid absolute URL")
+			}
+
+			return nil
+		}).
+		Value()
+
 	tf.StringVar(&cfg.CheckInName, "check-in-name", "default", "Name of the check-in monitor used in notifications").
 		Finalize(strings.TrimSpace).
 		Placeholder("NAME").
@@ -279,6 +301,7 @@ func ParseArgs(args []string, version string) (Config, error) {
 	if err != nil {
 		return Config{}, err
 	}
+	notifyConfig.App = render.NewAppData(version, cfg.PublicURL, cfg.CheckInPath)
 
 	cfg.ListenAddr = (*listenAddr).String()
 	cfg.Notify = notifyConfig

internal/flag/flag_test.go

@@ -51,6 +51,35 @@ func TestParseArgs(t *testing.T) {
 		assert.Equal(t, logging.LogFormatText, cfg.LogFormat)
 	})
 
+	t.Run("builds app template data from public url", func(t *testing.T) {
+		t.Parallel()
+
+		cfg, err := ParseArgs([]string{
+			"--expected-every=10s",
+			"--alerting-delay=2s",
+			"--public-url=https://overdue.example.test/overdue/",
+			"--check-in-path=custom-check-in/",
+		}, "dev")
+
+		require.NoError(t, err)
+		assert.Equal(t, "https://overdue.example.test/overdue", cfg.PublicURL)
+		assert.Equal(t, "https://overdue.example.test/overdue", cfg.Notify.App.PublicURL)
+		assert.Equal(t, "https://overdue.example.test/overdue/custom-check-in", cfg.Notify.App.CheckInURL)
+		assert.Equal(t, "https://overdue.example.test/overdue/status", cfg.Notify.App.StatusURL)
+	})
+
+	t.Run("rejects invalid public url", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := ParseArgs([]string{
+			"--expected-every=10s",
+			"--alerting-delay=2s",
+			"--public-url=not-a-url",
+		}, "dev")
+
+		require.Error(t, err)
+	})
+
 	t.Run("reads startup and response detail flags", func(t *testing.T) {
 		t.Parallel()
 

internal/flag/notify_test.go

@@ -157,7 +157,6 @@ func TestNotifyConfigFromDynamicGroups(t *testing.T) {
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), `invalid "--email.ops.headers"`)
 	})
-
 }
 
 func TestWebhookConfigsFromDynamicGroupDefaults(t *testing.T) {
@@ -324,15 +323,6 @@ func notifyTestFlagSet(t *testing.T, args []string) *tinyflags.FlagSet {
 	return fs
 }
 
-func notifyTestContentTemplates(prefix string) render.ContentTemplates {
-	return render.ContentTemplates{
-		Title:         prefix + " title",
-		ResolvedTitle: prefix + " resolved title",
-		Text:          prefix + " text",
-		ResolvedText:  prefix + " resolved text",
-	}
-}
-
 func notifyTestDefaultContentTemplates() render.ContentTemplates {
 	return render.ContentTemplates{
 		Title:         `[OVERDUE] Event Notification`,

internal/notification/notifier/builder.go

@@ -9,6 +9,7 @@ import (
 	"github.com/containeroo/overdue/internal/monitor"
 	"github.com/containeroo/overdue/internal/notification/delivery"
 	"github.com/containeroo/overdue/internal/notification/dispatch"
+	"github.com/containeroo/overdue/internal/notification/render"
 	"github.com/containeroo/overdue/internal/notification/targets"
 )
 
@@ -20,13 +21,13 @@ func New(templateFS fs.FS, cfg Config, logger *slog.Logger) (delivery.Notifier,
 
 	notifiers := make([]delivery.Notifier, 0, len(cfg.Webhooks)+len(cfg.Emails))
 
-	webhooks, err := buildWebhookNotifiers(templateFS, cfg.Webhooks, logger)
+	webhooks, err := buildWebhookNotifiers(templateFS, cfg.App, cfg.Webhooks, logger)
 	if err != nil {
 		return nil, err
 	}
 	notifiers = append(notifiers, webhooks...)
 
-	emails, err := buildEmailNotifiers(templateFS, cfg.Emails, logger)
+	emails, err := buildEmailNotifiers(templateFS, cfg.App, cfg.Emails, logger)
 	if err != nil {
 		return nil, err
 	}
@@ -60,10 +61,10 @@ func ValidateRuntimeTemplates(
 
 // validateTemplates renders configured notification templates with representative events.
 func validateTemplates(templateFS fs.FS, cfg Config, alertingEvent, resolvedEvent monitor.Event) error {
-	if err := validateWebhookTemplates(templateFS, cfg.Webhooks, alertingEvent, resolvedEvent); err != nil {
+	if err := validateWebhookTemplates(templateFS, cfg.App, cfg.Webhooks, alertingEvent, resolvedEvent); err != nil {
 		return err
 	}
-	if err := validateEmailTemplates(templateFS, cfg.Emails, alertingEvent, resolvedEvent); err != nil {
+	if err := validateEmailTemplates(templateFS, cfg.App, cfg.Emails, alertingEvent, resolvedEvent); err != nil {
 		return err
 	}
 	return nil
@@ -101,8 +102,9 @@ func templateValidationEvents(
 }
 
 // validateWebhookTemplates renders all webhook templates for configured webhook targets.
-func validateWebhookTemplates(templateFS fs.FS, configs []targets.WebhookConfig, alertingEvent, resolvedEvent monitor.Event) error {
+func validateWebhookTemplates(templateFS fs.FS, app render.AppData, configs []targets.WebhookConfig, alertingEvent, resolvedEvent monitor.Event) error {
 	for _, cfg := range configs {
+		cfg.ContentTemplates.App = app
 		renderer, err := targets.NewWebhookRenderer(templateFS, cfg.Template, cfg.ContentTemplates)
 		if err != nil {
 			return err
@@ -115,8 +117,9 @@ func validateWebhookTemplates(templateFS fs.FS, configs []targets.WebhookConfig,
 }
 
 // validateEmailTemplates renders all email body and subject templates for configured email targets.
-func validateEmailTemplates(templateFS fs.FS, configs []targets.EmailConfig, alertingEvent, resolvedEvent monitor.Event) error {
+func validateEmailTemplates(templateFS fs.FS, app render.AppData, configs []targets.EmailConfig, alertingEvent, resolvedEvent monitor.Event) error {
 	for _, cfg := range configs {
+		cfg.ContentTemplates.App = app
 		renderer, err := targets.NewEmailRenderer(
 			templateFS,
 			cfg.Template,
@@ -137,12 +140,14 @@ func validateEmailTemplates(templateFS fs.FS, configs []targets.EmailConfig, ale
 // buildWebhookNotifiers builds webhook notifiers from typed webhook configuration.
 func buildWebhookNotifiers(
 	templateFS fs.FS,
+	app render.AppData,
 	configs []targets.WebhookConfig,
 	logger *slog.Logger,
 ) (notifiers []delivery.Notifier, err error) {
 	notifiers = make([]delivery.Notifier, 0, len(configs))
 
 	for _, cfg := range configs {
+		cfg.ContentTemplates.App = app
 		renderer, err := targets.NewWebhookRenderer(templateFS, cfg.Template, cfg.ContentTemplates)
 		if err != nil {
 			return nil, err
@@ -161,12 +166,14 @@ func buildWebhookNotifiers(
 // buildEmailNotifiers builds email notifiers from typed email configuration.
 func buildEmailNotifiers(
 	templateFS fs.FS,
+	app render.AppData,
 	configs []targets.EmailConfig,
 	logger *slog.Logger,
 ) (notifiers []delivery.Notifier, err error) {
 	notifiers = make([]delivery.Notifier, 0, len(configs))
 
 	for _, cfg := range configs {
+		cfg.ContentTemplates.App = app
 		renderer, err := targets.NewEmailRenderer(
 			templateFS,
 			cfg.Template,