Created
October 28, 2019 13:39
-
-
Save andrijac/e3f92c258cb8de0e10f6c8d8e9d6b9a7 to your computer and use it in GitHub Desktop.
Ten Commandments of How to Write an IMAP client by Mark Crispin
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Source: https://www.washington.edu/imap/documentation/commndmt.txt.html | |
/* ======================================================================== | |
* Copyright 1988-2006 University of Washington | |
* | |
* Licensed under the Apache License, Version 2.0 (the "License"); | |
* you may not use this file except in compliance with the License. | |
* You may obtain a copy of the License at | |
* | |
* http://www.apache.org/licenses/LICENSE-2.0 | |
* | |
* | |
* ======================================================================== | |
*/ | |
[I wrote this tongue-in-cheek, but there's a lot here that people who | |
build IMAP clients should take careful note. Most existing clients | |
violate at least one, generally several, of these commandments. | |
These are based on known user-visible problems that occur with various | |
commonly used clients. Put another way, behind each commandment is a | |
plethora of user (and server administrator) complaints caused by a | |
violator.] | |
Ten Commandments of How to Write an IMAP client | |
Mark Crispin | |
1. Thou shalt not assume that it is alright to open multiple IMAP | |
sessions selected on the same mailbox simultaneously, lest thou face | |
the righteous wrath of mail stores that doth not permit such access. | |
Instead, thou shalt labor mightily, even unto having to use thy brain | |
to thinketh the matter through, such that thy client use existing | |
sessions that are already open. | |
2. Thou shalt not abuse the STATUS command by using it to check for | |
new mail on a mailbox that you already have selected in an IMAP | |
session; for that session hath already told thou about new mail | |
without thy having to ask. | |
3. Thou shalt remember the 30 minute inactivity timeout, and remember | |
to speak to the IMAP server before that timeout expires. If thou | |
useth the IDLE command, thou shalt send DONE from the IDLE before 29 | |
minutes hath passed, and issue a new IDLE. If thou maketh no use of | |
IDLE, then thou shalt send NOOP every few minutes, and the server | |
shalt tell you about new mail, and there will be much rejoicing in the | |
land. | |
4. Thou shalt not assume that all names are both the name of a mailbox | |
and the name of a upper level of hierarchy that contains mailboxes; | |
lest thou face the righteous wrath of mail stores in which a mailbox | |
is a file and a level of hierarchy is a directory. Thou shalt pay | |
diligent attention to the \NoSelect and \NoInferiors flags, so that | |
your users may praise you with great praise. | |
5. Thou shalt learn and understand the unique features of IMAP, such | |
as the unsolicited data model, the strict ascending rule of UIDs, how | |
UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE | |
structures; so that thou may use the IMAP protocol effectively. For a | |
POP client hacked to babble IMAP protocol is still no more than a POP | |
client. | |
6. Thou shalt remember untagged data sent by the server, and when thou | |
needest data thou shalt consult your memory before asking the server. | |
For those who must analyze thy protocol transactions are weak of | |
stomach, and are likely to lose their recent meal should they see thou | |
repeatedly re-fetch static data. | |
7. Thou shalt labor with great effort to work within the IMAP | |
deleted/expunge model, even if thy own model is that of a trashcan; | |
for interoperability is paramount and a trashcan model can be done | |
entirely in the user interface. | |
8. Thou shalt not fear to open multiple IMAP sessions to the server; | |
but thou shalt use this technique with wisdom. For verily it is true; | |
if thou doth desire to monitor continuously five mailboxes for new | |
mail, it is better to have five IMAP sessions continuously open on the | |
mailboxes. It is generally not good to do a succession of five SELECT | |
or STATUS commands on a periodic basis; and it is truly wretched to | |
open and close five sessions to do a STATUS or SELECT on a periodic | |
basis. The cost of opening and closing a session is great, especially | |
if that session is SSL/TLS protected; and the cost of a STATUS or | |
SELECT can also be great. By comparison, the cost of an open session | |
doing an IDLE or getting a NOOP every few minutes is small. Great | |
praise shall be given to thy wisdom in doing what is less costly | |
instead of "common sense." | |
9. Thou shalt not abuse subscriptions, for verily the LIST command is | |
the proper way to discover mailboxes on the server. Thou shalt not | |
subscribe names to the user's subscription list without explicit | |
instructions from the user; nor shalt thou assume that only subscribed | |
names are valid. Rather, thou shalt treat subscribed names as akin to | |
a bookmarks, or perhaps akin to how Windows shows the "My Documents" | |
folder -- a set of names that are separate from the hierarchy, for | |
they are such. | |
10. Thou shalt use the LIST "*" wildcard only with great care. If | |
thou doth not fully comprehend the danger of "*", thou shalt use only | |
"%" and forget about the existance of "*". | |
Honor these commandments, and keep them holy in thy heart, so that thy | |
users shalt maximize their pleasure, and the server administrators | |
shalt sing thy praises and recommend thy work as a model for others to | |
emulate. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment