1Postfix enhanced status code implementation notes 2================================================= 3 4RFC 3463 Enhanced status code support is implemented in stages. In 5the first stage, the goal is to minimize code changes (it's several 6hundred pages of context diffs already). For this reason, the 7pre-existing status variables (success, defer, etc.) are still 8updated separately from the diagnostic text and the RFC 3463 enhanced 9status code. All this means that one has to be careful when updating 10the code, to keep things in sync. 11 12Specific issues that one should be aware of: 13 14- In the SMTP client, update the enhanced status code and text 15whenever smtp_errno or resp->code are updated, or place an explicit 16comment that says no update is needed. 17 18- In the SMTP client, don't worry about the initial enhanced status 19digit when reporting failure to look up or connect to a host. For 20convenience, the SMTP client top-level code automatically changes 21the initial digit into '4' or '5' as appropriate. 22 23- In the SMTP server, don't worry about the initial enhanced status 24code digit when an smtpd_mumble_restriction rejects access. For 25convenience, the smtpd_check_reject() routine automatically changes 26the initial digit into '4' or '5' as appropriate. 27 28- Some low-level support routines update the diagnostic text but 29not the enhanced status code. To identify these, search for functions 30that are called with why->vstring as output parameter, and make 31sure that the caller updates the enhanced status code in all 32appropriate cases. 33 34- By design, the pipe, local and virtual delivery agent code never 35update the diagnostic text separately from the enhanced status code. 36 37- Don't rely on the system errno value after calling a routine that 38performs or prepares for mail delivery. Instead, have that routine 39update the enhanced status code (and text) when the error happens. 40This was an issue with mailbox, maildir and file delivery. Currently 41there remains one exception to this errno usage rule; the maildir 42delivery routines log a helpful warning when delivery fails with 43EACCES. The latter happens to work because mbox_open() does not 44need to unlock the output file, so it won't clobber the errno value. 45 46- Avoid passing around strings that combine enhanced status code 47and diagnostic text. Instead, use separate variables for status 48code and text, so that the compiler can enforce that everything has 49a status code. Currently there are two exceptions to this rule: 50the cleanup server status reply, and the delivery agent status 51reply. Once these protocols are updated we can remove the dns_prepend() 52routine. The third exception, enhanced status codes in external 53command output, is a feature. 54 55- The bounce/defer/sent library modules will catch the cases where 56an enhanced status code does not match the reject/defer/success 57status. They log a warning message, and replace the incorrect 58enhanced status code by a generic one. 59