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