refactor(flags): split flags into smaller files

Author: gi8lino

Makefile

@@ -6,7 +6,7 @@ TEST_FLAGS ?= -covermode=atomic -count=1 -parallel=4 -timeout=5m
 
 BASE_URL ?= http://localhost:8080
 ROUTE_PREFIX ?=
-CHECK_IN_PATH ?= /check-in
+CHECKIN_CHECKIN_PATH ?= /checkin
 AUTH_TOKEN ?=
 RUN_ARGS ?= --expected-every=5s --overdue-delay=3s
 
@@ -90,7 +90,7 @@ run-test: ## Run a local instance with example webhook and email settings.
 	go run . \
 		--expected-every=5s \
 		--alerting-delay=3s \
-		--check-in-name=prometheus \
+		--name=prometheus \
 		--webhook.ops.url=https://slack.com/api/chat.postMessage \
 		--webhook.ops.headers="Authorization=Bearer $${SLACK_TOKEN}" \
 		--webhook.ops.template=builtin:slack-chat-post-message \
@@ -110,11 +110,11 @@ run-test: ## Run a local instance with example webhook and email settings.
 
 .PHONY: check-in
 check-in: ## Send a local check-in request. Example: make check-in | jq .
-	@$(CURL) $(CURL_FLAGS) $(AUTH_HEADER) -X POST "$(BASE_URL)$(ROUTE_PREFIX)$(CHECK_IN_PATH)"
+	@$(CURL) $(CURL_FLAGS) $(AUTH_HEADER) -X POST "$(BASE_URL)$(ROUTE_PREFIX)$(CHECKIN_PATH)"
 
 .PHONY: check-in-details
 check-in-details: ## Send a local check-in request with details. Example: make check-in-details | jq .
-	@$(CURL) $(CURL_FLAGS) $(AUTH_HEADER) -X POST "$(BASE_URL)$(ROUTE_PREFIX)$(CHECK_IN_PATH)?details=true"
+	@$(CURL) $(CURL_FLAGS) $(AUTH_HEADER) -X POST "$(BASE_URL)$(ROUTE_PREFIX)$(CHECKIN_PATH)?details=true"
 
 .PHONY: status
 status: ## Send a local status request. Example: make status | jq .
@@ -165,3 +165,5 @@ endpoints-details: ## Test all local endpoints. Example: make endpoints-details
 .PHONY: help
 help: ## Display this help.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+

README.md

@@ -65,7 +65,7 @@ docker run --rm -p 8080:8080 \
 Send a check-in:
 
 ```sh
-curl -XPOST http://localhost:8080/check-in
+curl -XPOST http://localhost:8080/checkin
 ```
 
 Read the current status:
@@ -100,8 +100,8 @@ 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.                                           |
+| `--name`             | `OVERDUE__NAME`           | `default`   | Name of the check-in monitor used in notifications.                        |
+| `--path`             | `OVERDUE__PATH`           | `/checkin`  | 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. |
 | `--response-details` | `OVERDUE__RESPONSE_DETAILS` | `false`     | Return detailed timing fields from check-in responses by default.          |
 | `--auth-token`       | `OVERDUE__AUTH_TOKEN`       | empty       | Optional bearer token required for check-in and status requests.           |
@@ -113,6 +113,8 @@ Environment variables use the `OVERDUE__` prefix. Flag names are uppercased and
 Dynamic notification flags include the target name:
 
 ```text
+--name                            -> OVERDUE__NAME
+--path                            -> OVERDUE__PATH
 --public-url                      -> OVERDUE__PUBLIC_URL
 --webhook.ops.url                  -> OVERDUE__WEBHOOK_OPS_URL
 --webhook.ops.method               -> OVERDUE__WEBHOOK_OPS_METHOD
@@ -160,20 +162,20 @@ 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. When `--public-url` is configured, templates can use `.App.PublicURL`, `.App.CheckInURL`, and `.App.StatusURL`.
+Webhook templates must render valid JSON. Email templates may render text or HTML. When `--public-url` is configured, templates can use `.App.Version`, `.App.PublicURL`, `.App.CheckInURL`, and `.App.StatusURL`.
 
 See [docs/templates.md](docs/templates.md) for built-in templates, template data, and helper functions.
 
 ## HTTP API
 
 | Method        | Path        | Description                |
 | ------------- | ----------- | -------------------------- |
-| `GET`, `POST` | `/check-in` | Records a check-in.        |
+| `GET`, `POST` | `/checkin` | Records a check-in.        |
 | `GET`         | `/status`   | Returns the monitor state. |
 | `GET`         | `/version`  | Returns build information. |
 | `GET`, `POST` | `/healthz`  | Returns a health response. |
 
-The check-in path is configurable with `--check-in-path`. The other routes are mounted under `--route-prefix` when a route prefix is configured.
+The check-in endpoint path is configurable with `--path`. The other routes are mounted under `--route-prefix` when a route prefix is configured.
 
 See [docs/api.md](docs/api.md) for response examples and route prefix details.
 

docs/api.md

@@ -4,16 +4,16 @@ Overdue exposes a small HTTP API.
 
 | Method        | Path        | Description                | Auth required with `--auth-token` |
 | ------------- | ----------- | -------------------------- | --------------------------------- |
-| `GET`, `POST` | `/check-in` | Records a check-in.        | yes                               |
+| `GET`, `POST` | `/checkin` | Records a check-in.        | yes                               |
 | `GET`         | `/status`   | Returns monitor state.     | yes                               |
 | `GET`         | `/version`  | Returns build information. | no                                |
 | `GET`, `POST` | `/healthz`  | Returns `ok`.              | no                                |
 
-The check-in path is configurable with `--check-in-path`.
+The check-in endpoint path is configurable with `--path`.
 
 The other routes are mounted under `--route-prefix` when a route prefix is configured.
 
-## `GET /check-in` and `POST /check-in`
+## `GET /checkin` and `POST /checkin`
 
 Records a check-in.
 
@@ -215,8 +215,8 @@ overdue \
 Routes become:
 
 ```text
-GET  /overdue/check-in
-POST /overdue/check-in
+GET  /overdue/checkin
+POST /overdue/checkin
 GET  /overdue/status
 GET  /overdue/version
 GET  /overdue/healthz
@@ -236,3 +236,5 @@ This becomes:
 ```
 
 
+
+

docs/configuration.md

@@ -9,7 +9,8 @@ Environment variables use the `OVERDUE__` prefix. Flag names are uppercased and
 ```text
 --expected-every        -> OVERDUE__EXPECTED_EVERY
 --alerting-delay        -> OVERDUE__ALERTING_DELAY
---check-in-name         -> OVERDUE__CHECK_IN_NAME
+--name                  -> OVERDUE__NAME
+--path                  -> OVERDUE__PATH
 --public-url            -> OVERDUE__PUBLIC_URL
 --response-details      -> OVERDUE__RESPONSE_DETAILS
 ```
@@ -40,8 +41,8 @@ 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.                                           |
+| `--name`             | `OVERDUE__NAME`           | `default`   | Name of the check-in monitor used in notifications.                        |
+| `--path`             | `OVERDUE__PATH`           | `/checkin`  | Route used to receive check-ins.                                           |
 | `--expected-every`   | `OVERDUE__EXPECTED_EVERY`   | required    | Maximum time between check-ins.                                            |
 | `--alerting-delay`   | `OVERDUE__ALERTING_DELAY`   | required    | Extra time after the expected deadline before notifications fire.          |
 | `--start-active`     | `OVERDUE__START_ACTIVE`     | `false`     | Activate the monitor at startup instead of waiting for the first check-in. |
@@ -114,8 +115,8 @@ overdue \
 Routes become:
 
 ```text
-GET /overdue/check-in
-POST /overdue/check-in
+GET /overdue/checkin
+POST /overdue/checkin
 GET  /overdue/status
 GET  /overdue/version
 GET  /overdue/healthz
@@ -141,14 +142,15 @@ Use `--public-url` to expose externally reachable links to notification template
 ```sh
 overdue \
   --public-url=https://example.com/overdue \
-  --check-in-path=/check-in \
+  --path=/checkin \
   --expected-every=1m \
   --alerting-delay=10s
 ```
 
 Templates can then use:
 
 ```gotemplate
+{{ .App.Version }}
 {{ .App.PublicURL }}
 {{ .App.CheckInURL }}
 {{ .App.StatusURL }}
@@ -158,13 +160,13 @@ With the example above, those values are:
 
 ```text
 .App.PublicURL  = https://example.com/overdue
-.App.CheckInURL = https://example.com/overdue/check-in
+.App.CheckInURL = https://example.com/overdue/checkin
 .App.StatusURL  = https://example.com/overdue/status
 ```
 
 ## Authentication
 
-Set `--auth-token` to require bearer-token auth for `/check-in` and `/status`.
+Set `--auth-token` to require bearer-token auth for `/checkin` and `/status`.
 
 ```sh
 overdue \
@@ -184,7 +186,7 @@ export OVERDUE__AUTH_TOKEN=0123456789abcdef0123456789abcdef
 Send authorized requests:
 
 ```sh
-curl -XPOST http://localhost:8080/check-in \
+curl -XPOST http://localhost:8080/checkin \
   -H 'Authorization: Bearer 0123456789abcdef0123456789abcdef'
 
 curl http://localhost:8080/status \

docs/deployment.md

@@ -28,7 +28,7 @@ docker run --rm -p 8080:8080 \
 Check in:
 
 ```sh
-curl -XPOST http://localhost:8080/check-in \
+curl -XPOST http://localhost:8080/checkin \
   -H "Authorization: Bearer $OVERDUE_TOKEN"
 ```
 
@@ -97,3 +97,5 @@ The top-level directory command applies the core manifests only. Apply the optio
 Expose the service through your ingress or gateway as usual.
 
 If Overdue is mounted below a path prefix, set `OVERDUE__ROUTE_PREFIX` and make sure your ingress forwards the same prefix.
+
+

docs/notifications.md

@@ -23,7 +23,7 @@ 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.
+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. `.App.Version` is always available.
 
 ## Environment variables
 

docs/templates.md

@@ -63,10 +63,10 @@ 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.    |
+| `.App`            | struct            | Application metadata and links. URL fields are 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`.
+`.App` contains `.App.Version`, `.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 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" }}`.
 
@@ -76,6 +76,7 @@ Example:
 {{ .Title }}
 
 Check-in: {{ .CheckInName }}
+Version: {{ .App.Version }}
 Status: {{ .Status }}
 Channel: {{ .CustomData.channel | default "alertmanager" | withPrefix "#" }}
 Status URL: {{ .App.StatusURL }}

internal/app/run.go

@@ -47,21 +47,21 @@ func Run(
 		"listenAddr", flags.ListenAddr,
 		"routePrefix", flags.RoutePrefix,
 		"publicURL", flags.PublicURL,
-		"checkInName", flags.CheckInName,
-		"checkInPath", flags.CheckInPath,
-		"expectedEvery", flags.ExpectedEvery.String(),
-		"alertingDelay", flags.AlertingDelay.String(),
-		"startActive", flags.StartActive,
+		"name", flags.CheckIn.Name,
+		"path", flags.CheckIn.Path,
+		"expectedEvery", flags.CheckIn.ExpectedEvery.String(),
+		"alertingDelay", flags.CheckIn.AlertingDelay.String(),
+		"startActive", flags.CheckIn.StartActive,
 		"responseDetails", flags.ResponseDetails,
 		"initialPhase", monitor.PhaseScheduled,
 	)
 
 	if err := notifier.ValidateRuntimeTemplates(
 		templateFS,
 		flags.Notify,
-		flags.CheckInName,
-		flags.ExpectedEvery,
-		flags.AlertingDelay,
+		flags.CheckIn.Name,
+		flags.CheckIn.ExpectedEvery,
+		flags.CheckIn.AlertingDelay,
 	); err != nil {
 		setupLog.Error("notification template validation error", "error", err)
 		return err
@@ -83,21 +83,21 @@ func Run(
 	defer stop()
 
 	mon := monitor.New(
-		flags.CheckInName,
-		flags.ExpectedEvery,
-		flags.AlertingDelay,
+		flags.CheckIn.Name,
+		flags.CheckIn.ExpectedEvery,
+		flags.CheckIn.AlertingDelay,
 		logger.With("component", "monitor"),
 	)
 
 	sched := scheduler.New(mon, notify, reg, logger.With("component", "scheduler"))
-	if flags.StartActive {
+	if flags.CheckIn.StartActive {
 		activatedAt := time.Now()
 		sched.RecordCheckIn(activatedAt)
 		setupLog.Info(
 			"check-in monitor activated at startup",
 			"activatedAt", activatedAt,
-			"expectedBy", activatedAt.Add(flags.ExpectedEvery),
-			"alertingAt", activatedAt.Add(flags.ExpectedEvery+flags.AlertingDelay),
+			"expectedBy", activatedAt.Add(flags.CheckIn.ExpectedEvery),
+			"alertingAt", activatedAt.Add(flags.CheckIn.ExpectedEvery+flags.CheckIn.AlertingDelay),
 		)
 	}
 	sched.Run(ctx)
@@ -113,14 +113,14 @@ func Run(
 		logger.With("component", "api"),
 	)
 
-	router := routes.NewRouter(flags.CheckInPath, flags.RoutePrefix, api)
+	router := routes.NewRouter(flags.CheckIn.Path, flags.RoutePrefix, api)
 	if err := server.Run(
 		ctx,
-		flags.ListenAddr,
+		flags.ListenAddr.String(),
 		router,
 		logger.With("component", "server"),
 	); err != nil {
-		setupLog.Error("server run", "listenAddr", flags.ListenAddr, "error", err)
+		setupLog.Error("server run", "listenAddr", flags.ListenAddr.String(), "error", err)
 		return err
 	}
 

internal/app/run_test.go

@@ -41,7 +41,7 @@ func TestRun(t *testing.T) {
 
 		waitForHTTPStatus(t, client, baseURL+"/healthz", http.MethodGet, http.StatusOK)
 
-		req, err := http.NewRequestWithContext(ctx, http.MethodPost, baseURL+"/check-in", nil)
+		req, err := http.NewRequestWithContext(ctx, http.MethodPost, baseURL+"/checkin", nil)
 		require.NoError(t, err)
 
 		resp, err := client.Do(req)