aicoded.dev

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

  1. Declare mail in the permission list: email.from, the one address the app sends from, and email.to_domains, the only domains it may send to. people has from: people@acme.example and to_domains: [acme.example], and reads the team's address from the setting team_address.

  2. 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.AddUser calls 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.

  3. 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 in aicoded dev until 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 of to_domains exactly (E-MAIL-003).
  4. 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

See also

Markdown · Source on GitHub · framework f46741f