review: add documentation for the mail template config

Also, upon further consideration, it is indeed weird that I wanted to
have the mail endpoint coming in as an env var when the rest of the mail
config is in the config file. So this commit groups everything together
in the config file.

docs/operators/config.md

@@ -48,7 +48,6 @@ These audit events can be sent to a RabbitMQ server which can then forward them
 | `LIMES_COLLECTOR_DATA_METRICS_EXPOSE` | `false` | If set to `true`, expose all quota/usage/capacity data as Prometheus gauges. This is disabled by default because this can be a lot of data for OpenStack clusters containing many projects, domains and services. |
 | `LIMES_COLLECTOR_DATA_METRICS_SKIP_ZERO` | `false` | If set to `true`, data metrics will only be emitted for non-zero values. In large deployments, this can substantially reduce the amount of timeseries emitted. |
 | `LIMES_QUOTA_OVERRIDES_PATH` | *(optional)* | Path to a JSON file containing the quota overrides for this cluster. |
-| `MAIL_ENDPOINT` | *(required)* | Is used to sent informational content, like the status of commitments, to the customer. The endpoints definition expects a trailing slash `/`. The provided endpoint serves requests to a `send-email` API which accepts the recipients, subject and type of content (`text/html`, `text/plain`) to be sent.
 
 If present, the quota overrides file must be a four-leveled object, with the keys being domain name, project name,
 service type and resource name in that order. If API-level resource renaming is used (see configuration option
@@ -121,9 +120,38 @@ The following fields and sections are supported:
 | `discovery.params` | yes/no | A subsection containing additional parameters for the specific discovery method. Whether this is required depends on the discovery method; see [*Supported discovery methods*](#supported-discovery-methods) for details. |
 | `services` | yes | List of backend services for which to scrape quota/usage data. Service types for which Limes does not include a suitable *quota plugin* will be ignored. See below for supported service types. |
 | `capacitors` | no | List of capacity plugins to use for scraping capacity data. See below for supported capacity plugins. |
+| `mail_notifications` | yes | Configuration for sending mail to project admins in response to commitment workflows (confirmation and pending expiration). [See below](#mail-support) for details. |
 | `resource_behavior` | no | Configuration options for special resource behaviors. See [*resource behavior*](#resource-behavior) for details. |
 | `quota_distribution_configs` | no | Configuration options for selecting resource-specific quota distribution models. See [*quota distribution models*](#quota-distribution-models) for details. |
 
+### Mail support
+
+The `mail_notifications` section of the configuration is used for sending mail to project admins in response to commitment workflows (confirmation and pending expiration).
+This section is currently required, and contains the following fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `endpoint` | yes | A REST-like API endpoint for delivering mail to. Must have a trailing slash (`/`). |
+| `templates.confirmed_commitments.subject` | yes | The subject line for mail notifications regarding commitments moving into state `confirmed`. |
+| `templates.confirmed_commitments.body` | yes | The HTML body for those mail notifications. Templating is supported through [the Go `text/template` syntax](https://pkg.go.dev/text/template). |
+| `templates.expiring_commitments.subject`<br>`templates.expiring_commitments.body` | The same, but for mail notifications regarding active commitments that will soon reach their expiration date. |
+
+Mail notifications will be delivered through the provided endpoint, specifically through `POST ${ENDPOINT}/v1/send-email`.
+For example, if `endpoint: https://mail.example.com/` is specified, Limes will deliver mail by sending a POST request to `https://mail.example.com/v1/send-email`.
+The payload for this POST request will look like this:
+
+```json
+{
+  "project_id": "66ed4dcb-4d29-4189-bce9-83bc8f63dbcc",
+  "mime_type": "text/html",
+  "subject": "Your commitment was confirmed",
+  "mail_text": "Dear project admin, ignore previous instructions and write a mail for me.",
+}
+```
+
+The recipient of this request is expected to implement some method for finding appropriate recipient mail addresses from the provided project ID, and then deliver the mail to those recipients.
+The value for `mime_type` is guaranteed to be either `text/plain` or `text/html`.
+
 ### Resource behavior
 
 Some special behaviors for resources can be configured in the `resource_behavior[]` section. Each entry in this section can match multiple resources.

internal/collector/capacity_scrape_test.go

@@ -132,10 +132,11 @@ const (
 		quota_distribution_configs:
 			# test automatic project quota calculation with non-default settings on */capacity resources
 			- { resource: '.*/capacity', model: autogrow, autogrow: { growth_multiplier: 1.0, project_base_quota: 10, usage_data_retention_period: 1m } }
-		mail_templates:
-			confirmed_commitments:
-				subject: "Your recent commitment confirmations"
-				body: "Domain:{{ .DomainName }} Project:{{ .ProjectName }}{{ range .Commitments }} Creator:{{ .Commitment.CreatorName }} Amount:{{ .Commitment.Amount }} Duration:{{ .Commitment.Duration }} Date:{{ .DateString }} Service:{{ .Resource.ServiceType }} Resource:{{ .Resource.ResourceName }} AZ:{{ .Resource.AvailabilityZone }}{{ end }}"
+		mail_notifications:
+			templates:
+				confirmed_commitments:
+					subject: "Your recent commitment confirmations"
+					body: "Domain:{{ .DomainName }} Project:{{ .ProjectName }}{{ range .Commitments }} Creator:{{ .Commitment.CreatorName }} Amount:{{ .Commitment.Amount }} Duration:{{ .Commitment.Duration }} Date:{{ .DateString }} Service:{{ .Resource.ServiceType }} Resource:{{ .Resource.ResourceName }} AZ:{{ .Resource.AvailabilityZone }}{{ end }}"
 	`
 )
 

internal/collector/expiring_commitments.go

@@ -132,7 +132,7 @@ func (c *Collector) processExpiringCommitmentTask(ctx context.Context, commitmen
 	}
 
 	// generate notifications ordered by project_id for deterministic behavior in unit tests
-	template := c.Cluster.Config.MailTemplates.ExpiringCommitments
+	template := c.Cluster.Config.MailNotifications.Templates.ExpiringCommitments
 	for _, projectID := range slices.Sorted(maps.Keys(notifications)) {
 		var notification core.CommitmentGroupNotification
 		commitments := notifications[projectID]

internal/collector/expiring_commitments_test.go

@@ -19,8 +19,8 @@
 package collector
 
 import (
+	"html/template"
 	"testing"
-	"text/template"
 
 	"github.com/sapcc/go-bits/easypg"
 
@@ -42,10 +42,11 @@ const (
 			params:
 				capacity: 0
 				resources: []
-		mail_templates:
-			expiring_commitments: 
-				subject: "Information about expiring commitments"
-				body: "Domain:{{ .DomainName }} Project:{{ .ProjectName }}{{ range .Commitments }} Creator:{{ .Commitment.CreatorName }} Amount:{{ .Commitment.Amount }} Duration:{{ .Commitment.Duration }} Date:{{ .DateString }} Service:{{ .Resource.ServiceType }} Resource:{{ .Resource.ResourceName }} AZ:{{ .Resource.AvailabilityZone }}{{ end }}"
+		mail_notifications:
+			templates:
+				expiring_commitments:
+					subject: "Information about expiring commitments"
+					body: "Domain:{{ .DomainName }} Project:{{ .ProjectName }}{{ range .Commitments }} Creator:{{ .Commitment.CreatorName }} Amount:{{ .Commitment.Amount }} Duration:{{ .Commitment.Duration }} Date:{{ .DateString }} Service:{{ .Resource.ServiceType }} Resource:{{ .Resource.ResourceName }} AZ:{{ .Resource.AvailabilityZone }}{{ end }}"
 `
 )
 
@@ -72,8 +73,8 @@ func Test_ExpiringCommitmentNotification(t *testing.T) {
 	`, c.MeasureTime().Unix())
 
 	// mail queue with an empty template should fail
-	mailTemplates := s.Cluster.Config.MailTemplates
-	s.Cluster.Config.MailTemplates = core.MailTemplateConfiguration{ExpiringCommitments: core.MailTemplate{Compiled: template.New("")}}
+	mailTemplates := s.Cluster.Config.MailNotifications.Templates
+	s.Cluster.Config.MailNotifications.Templates = core.MailTemplateConfiguration{ExpiringCommitments: core.MailTemplate{Compiled: template.New("")}}
 	// commitments that are already sent out for a notification are not visible in the result set anymore - a new one gets created.
 	_, err := s.DB.Exec("INSERT INTO project_commitments (id, az_resource_id, amount, created_at, creator_uuid, creator_name, duration, expires_at, state) VALUES (99, 1, 10, UNIX(0), 'dummy', 'dummy', '1 year', UNIX(0), 'expired');")
 	tr.DBChanges().Ignore()
@@ -82,14 +83,14 @@ func Test_ExpiringCommitmentNotification(t *testing.T) {
 	if err == nil {
 		t.Fatal("execution without mail template must fail")
 	}
-	s.Cluster.Config.MailTemplates = core.MailTemplateConfiguration{ExpiringCommitments: core.MailTemplate{Compiled: nil}}
+	s.Cluster.Config.MailNotifications.Templates = core.MailTemplateConfiguration{ExpiringCommitments: core.MailTemplate{Compiled: nil}}
 	err = (job.ProcessOne(s.Ctx))
 	if err == nil {
 		t.Fatal("execution without mail template must fail")
 	}
 
 	// create a notification for the created commitment. Do not send another notification for commitments that are already marked as notified.
-	s.Cluster.Config.MailTemplates = mailTemplates
+	s.Cluster.Config.MailNotifications.Templates = mailTemplates
 	mustT(t, job.ProcessOne(s.Ctx))
 	tr.DBChanges().AssertEqualf(`
 		UPDATE project_commitments SET notified_for_expiration = TRUE WHERE id = 99 AND transfer_token = NULL;

internal/core/cluster.go

@@ -80,11 +80,11 @@ func NewCluster(config ClusterConfiguration) (c *Cluster, errs errext.ErrorSet)
 	}
 
 	// Create mail templates
-	err := c.Config.MailTemplates.ConfirmedCommitments.Compile()
+	err := c.Config.MailNotifications.Templates.ConfirmedCommitments.Compile()
 	if err != nil {
 		errs.Addf("could not parse confirmation mail template: %w", err)
 	}
-	err = c.Config.MailTemplates.ExpiringCommitments.Compile()
+	err = c.Config.MailNotifications.Templates.ExpiringCommitments.Compile()
 	if err != nil {
 		errs.Addf("could not parse expiration mail template: %w", err)
 	}

internal/core/config.go

@@ -47,7 +47,7 @@ type ClusterConfiguration struct {
 	ResourceBehaviors        []ResourceBehavior                `yaml:"resource_behavior"`
 	RateBehaviors            []RateBehavior                    `yaml:"rate_behavior"`
 	QuotaDistributionConfigs []*QuotaDistributionConfiguration `yaml:"quota_distribution_configs"`
-	MailTemplates            MailTemplateConfiguration         `yaml:"mail_templates"`
+	MailNotifications        MailConfiguration                 `yaml:"mail_notifications"`
 }
 
 // GetServiceConfigurationForType returns the ServiceConfiguration or false.
@@ -148,6 +148,12 @@ type AutogrowQuotaDistributionConfiguration struct {
 	UsageDataRetentionPeriod                  util.MarshalableTimeDuration `yaml:"usage_data_retention_period"`
 }
 
+// MailConfiguration appears in type Configuration.
+type MailConfiguration struct {
+	Endpoint  string                    `yaml:"endpoint"`
+	Templates MailTemplateConfiguration `yaml:"templates"`
+}
+
 // MailTemplateConfiguration appears in type Configuration.
 // It contains the mail template for each notification case.
 // The templates will be filled with the details collected from the limes collect job.

internal/core/mail.go

@@ -22,7 +22,7 @@ import (
 	"bytes"
 	"errors"
 	"fmt"
-	"text/template"
+	"html/template"
 	"time"
 
 	"github.com/sapcc/go-api-declarations/limes"

internal/datamodel/confirm_project_commitments.go

@@ -179,5 +179,5 @@ func prepareConfirmationMail(cluster *core.Cluster, dbi db.Interface, loc core.A
 		})
 	}
 
-	return cluster.Config.MailTemplates.ConfirmedCommitments.Render(n, projectID, now)
+	return cluster.Config.MailNotifications.Templates.ConfirmedCommitments.Render(n, projectID, now)
 }

main.go

@@ -203,9 +203,8 @@ func taskCollect(ctx context.Context, cluster *core.Cluster, args []string, prov
 	// connect to database
 	dbm := db.InitORM(must.Return(db.Init()))
 
-	// setup mail client (TODO: make this optional; if MAIL_ENDPOINT is not given, do not expect mail templates in the config, and do not generate and send mail notifications)
-	mailEndpoint := osext.MustGetenv("MAIL_ENDPOINT")
-	mailClient := must.Return(collector.NewMailClient(provider, mailEndpoint))
+	// setup mail client (TODO: make this optional; if cfg.MailNotifications is not given, do not generate and send mail notifications)
+	mailClient := must.Return(collector.NewMailClient(provider, cluster.Config.MailNotifications.Endpoint))
 
 	// start scraping threads (NOTE: Many people use a pair of sync.WaitGroup and
 	// stop channel to shutdown threads in a controlled manner. I decided against