feat(outbound): classify relay errors as permanent or bad mailbox

- Add IsPermanent for SMTP 5xx and PermanentError
- Add IsBadMailbox for enhanced status 5.1.x only, so a misconfigured relay says nothing about recipients
This commit is contained in:
tgiachi 2026-11-09 15:46:27 +01:00
commit ecbab4d18c
2 changed files with 102 additions and 0 deletions

View file

@ -4,6 +4,7 @@ package outbound
import (
"bytes"
"context"
"errors"
"fmt"
"net"
"sync"
@ -79,3 +80,36 @@ func (f *Fake) Send(_ context.Context, from string, to []string, data []byte) er
f.Sent = append(f.Sent, Sent{from, append([]string(nil), to...), append([]byte(nil), data...)})
return nil
}
// PermanentError marks a failure that retrying cannot fix. SMTP 5xx replies are
// permanent without being wrapped in it; use it for other sources (and in tests).
type PermanentError struct {
Err error
BadMailbox bool // the destination mailbox is invalid
}
func (e *PermanentError) Error() string { return e.Err.Error() }
func (e *PermanentError) Unwrap() error { return e.Err }
// IsPermanent reports whether err is a permanent failure: an SMTP 5xx reply or a PermanentError.
func IsPermanent(err error) bool {
var pe *PermanentError
if errors.As(err, &pe) {
return true
}
var se *smtp.SMTPError
return errors.As(err, &se) && se.Code >= 500 && se.Code <= 599
}
// IsBadMailbox reports whether err says the destination mailbox is invalid (SMTP
// enhanced status 5.1.x). Other permanent errors, such as "relay access denied",
// say nothing about the recipient.
func IsBadMailbox(err error) bool {
var pe *PermanentError
if errors.As(err, &pe) {
return pe.BadMailbox
}
var se *smtp.SMTPError
return errors.As(err, &se) && se.Code >= 500 && se.Code <= 599 &&
se.EnhancedCode[0] == 5 && se.EnhancedCode[1] == 1
}

View file

@ -2,6 +2,7 @@ package outbound
import (
"context"
"errors"
"fmt"
"io"
"net"
@ -128,3 +129,70 @@ func TestSMTPRelayDefaultBatchSize(t *testing.T) {
t.Fatalf("default batch size must be %d, got %d transactions", DefaultBatchSize, len(cap.msgs))
}
}
func TestClassifyErrors(t *testing.T) {
smtpErr := func(code int, enh smtp.EnhancedCode) error {
return &smtp.SMTPError{Code: code, EnhancedCode: enh, Message: "x"}
}
cases := []struct {
name string
err error
perm, mailbox bool
}{
{"nil", nil, false, false},
{"plain", errors.New("connection refused"), false, false},
{"451", smtpErr(451, smtp.EnhancedCode{4, 3, 0}), false, false},
{"421", smtpErr(421, smtp.NoEnhancedCode), false, false},
{"550 unknown mailbox", smtpErr(550, smtp.EnhancedCode{5, 1, 1}), true, true},
{"553 bad address syntax", smtpErr(553, smtp.EnhancedCode{5, 1, 3}), true, true},
{"554 relay denied", smtpErr(554, smtp.EnhancedCode{5, 7, 1}), true, false},
{"550 no enhanced code", smtpErr(550, smtp.NoEnhancedCode), true, false},
{"wrapped", fmt.Errorf("batch 0-1: %w", smtpErr(550, smtp.EnhancedCode{5, 1, 1})), true, true},
{"explicit permanent", &PermanentError{Err: errors.New("no")}, true, false},
{"explicit bad mailbox", &PermanentError{Err: errors.New("no"), BadMailbox: true}, true, true},
}
for _, c := range cases {
if got := IsPermanent(c.err); got != c.perm {
t.Errorf("%s: IsPermanent = %v", c.name, got)
}
if got := IsBadMailbox(c.err); got != c.mailbox {
t.Errorf("%s: IsBadMailbox = %v", c.name, got)
}
}
}
type rejecting struct{ err error }
func (r rejecting) NewSession(*smtp.Conn) (smtp.Session, error) { return &rejectSession{r.err}, nil }
type rejectSession struct{ err error }
func (s *rejectSession) Reset() {}
func (s *rejectSession) Logout() error { return nil }
func (s *rejectSession) Mail(string, *smtp.MailOptions) error { return nil }
func (s *rejectSession) Rcpt(string, *smtp.RcptOptions) error { return s.err }
func (s *rejectSession) Data(io.Reader) error { return nil }
func TestRelayRejectionsAreClassifiedFromTheWire(t *testing.T) {
for name, tc := range map[string]struct {
err error
perm, mailbox bool
}{
"unknown user": {&smtp.SMTPError{Code: 550, EnhancedCode: smtp.EnhancedCode{5, 1, 1}, Message: "no such user"}, true, true},
"relay denied": {&smtp.SMTPError{Code: 554, EnhancedCode: smtp.EnhancedCode{5, 7, 1}, Message: "relay access denied"}, true, false},
"try later": {&smtp.SMTPError{Code: 451, EnhancedCode: smtp.EnhancedCode{4, 3, 0}, Message: "try later"}, false, false},
} {
srv := smtp.NewServer(rejecting{tc.err})
ln, _ := net.Listen("tcp", "127.0.0.1:0")
go srv.Serve(ln)
r := &SMTPRelay{Addr: ln.Addr().String()}
err := r.Send(context.Background(), "b@x.org", []string{"a@x.com"}, []byte("Subject: x\r\n\r\nx\r\n"))
srv.Close()
if err == nil {
t.Fatalf("%s: want an error", name)
}
if IsPermanent(err) != tc.perm || IsBadMailbox(err) != tc.mailbox {
t.Errorf("%s: permanent=%v mailbox=%v for %v", name, IsPermanent(err), IsBadMailbox(err), err)
}
}
}