external/ibm-public/postfix/dist/implementation-notes/ENHANCED_STATUS_CODES

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