Send mail after a write
Mail someone once a change is saved, and only once: commit the change first, then send the mail with an idempotency key that names what it is about. The example adds a user in the people example and mails the team.
Steps
-
Declare mail in the permission list:
email.from, the one address the app sends from, andemail.to_domains, the only domains it may send to. people hasfrom: people@acme.exampleandto_domains: [acme.example], and reads the team's address from the settingteam_address. -
Make the change in one transaction, and commit it before anything leaves the app:
// addUser is AddUser with the database db and the photo store store. func addUser(ctx context.Context, db *sql.DB, store photoStore, u User, photos []Photo) (err error) { ctx, span := telemetry.Start(ctx, "users.add") span.SetAttr("photos", strconv.Itoa(len(photos))) defer func() { if err != nil { span.RecordError(err) } span.End() }() tx, err := db.BeginTx(ctx, nil) if err != nil { return err } defer func() { _ = tx.Rollback() }() var taken bool if err := tx.QueryRowContext(ctx, loginExists, u.Login).Scan(&taken); err != nil { return err } if taken { return ErrLoginTaken } if err := insert(ctx, tx, u); err != nil { // An add of the same login that committed after the check above makes the UNIQUE index // refuse this one, with an error that names the login: check again, outside this // transaction. if db.QueryRowContext(ctx, loginExists, u.Login).Scan(&taken) == nil && taken { return ErrLoginTaken } return err } var stored []string // the folder this add made and the files it wrote, in that order defer func() { if err != nil { if rerr := removePhotos(store, stored); rerr != nil { err = errors.Join(err, rerr) } } }() if len(photos) > 0 { _, serr := store.Stat(u.Login) if err := store.Mkdir(u.Login); err != nil { return err } if errors.Is(serr, fs.ErrNotExist) { stored = append(stored, u.Login) } } for _, p := range photos { name := u.Login + "/" + p.Name if err := store.WriteFile(name, p.Data); err != nil { return err } stored = append(stored, name) } return tx.Commit() }Deps.AddUsercalls it with the app's database and photo store. Its span,users.add, records only how many photos there are: no login, name or file name reaches telemetry. -
Send the mail once the change is committed, with
IdempotencyKey:// ProcessAdd adds the user with their photos, tells the open users pages and the team, and // opens the new user's page. It logs nothing about the form. func (p *DP) ProcessAdd(ctx context.Context, _ *web.Request, _ web.ResponseWriter, f *FormAddValues) error { u := readUser(f) photos := readPhotos(f) if f.HasError() { return nil } err := p.d.AddUser(ctx, u, photos) if errors.Is(err, deps.ErrLoginTaken) { f.Login.SetError("That login is taken.") return nil } if err != nil { return err } p.d.UsersAdded.Publish(struct{}{}) _, err = mailer.Send(ctx, mailer.Message{ IdempotencyKey: "user-" + u.Login, To: []mailer.Address{{Address: p.d.TeamAddress}}, Subject: "User " + u.Login + " added", Text: fmt.Sprintf("%s (%s) joined the team %s.\n", u.Name, u.Login, u.Team), }) if err != nil { return err } return web.Redirect("/users/" + u.Login) }- The key names what the mail is about,
user-<login>. Sending the same key again sends nothing and returns the first message's id while the runner remembers the key: on the platform for 24 hours and until the runner restarts, and inaicoded devuntil it restarts. A retry after that sends the mail again. A message without a key is refused (E-MAIL-001). - A transaction that fails sends nothing, since the mail goes only after the commit.
- The sender is always
email.from, and the domain of every recipient must be one ofto_domainsexactly (E-MAIL-003).
- The key names what the mail is about,
-
When the mail is about what the viewer wrote rather than about a record, make the key from what was written. The contact form hashes the viewer, the topic and the message, so a message sent twice within a day is mailed once:
// contactKey names a message by its sender, topic and text, so that a message sent twice within // a day is mailed once. func contactKey(subject, topic, message string) string { sum := sha256.Sum256([]byte(subject + "\x00" + topic + "\x00" + message)) return "contact-" + hex.EncodeToString(sum[:16]) }Add a form shows the whole form.
Put no form value in a log line or a span, which aicoded check refuses (E-LINT-008): the mail
carries it to the team, and nothing else needs it.
Check it
aicoded checkgenerates, builds, vets, lints and tests the app.aicoded devcatches mail instead of sending it, after checking it against the mail rules and the permission list. Add a user as a persona with the rolesstaffandhr, and the dev UI's Mail page shows one message,User <login> added.- The dev UI's Traces page shows the request with the spans
users.addandmailer.send.