E-MailRelay Design and implementation ===================================== Module structure ---------------- There are three C++ libraries in the E-MailRelay code: "glib" provides low-level classes for file-system abstraction, date and time representation, string utility functions, logging, command line parsing etc., "gnet" provides network classes using the Berkley socket and Winsock APIs, and "gsmtp" contains SMTP and message-store classes. All three libraries are portable between POSIX-like systems (eg. Linux) and Windows. Under Windows there is an additional library for event handling. Windows has historically built network event processing on top of the GUI event system, rather then implementing network events using a generic event notification system as POSIX systems do. This means that the "gnet" library has to be able to create GUI windows in order to process network events. The extra GUI and event classes are put into a separate library in the "src/win32" directory, using the namespace "GGui". Class structure --------------- The message-store functionality uses three abstract interfaces: "MessageStore", "NewMessage" and "StoredMessage". The "NewMessage" interface is used to create messages within the store, and the "StoredMessage" interface is used for reading and extracting messages from the store. The concrete implementation classes based on these interfaces are respectively "FileStore", "NewFile" and "StoredFile". The interaction between the server protocol class and the message store is mediated by the "ProtocolMessage" interface. Two main implementations of this interface are supplied: one for normal spooling ("ProtocolMessageStore"), and another for immediate forwarding ("ProtocolMessageForward"). The protocol and message-store functionality are brought together by the high-level "GSmtp::Server" and "GSmtp::Client" classes. Simplified class diagrams for the *GNet* [gnet-classes.png] and *GSmtp* [gsmtp-classes.png] namespaces are available. Event model ----------- The E-MailRelay server uses non-blocking socket i/o, with a select() event loop. This event model means that the server can handle multiple clients simultaneously from a single thread and the only significant blocking occurs when external programs are executed (see "--filter" and "--verifier"). See *C10K Problem* [http://www.kegel.com/c10k.html] for a discussion of different network event models. At higher levels the slot/signal design pattern is used to propagate events between objects (not to be confused with operating system signals). Protocol implementation ----------------------- The SMTP protocols (client-side and server-side) are implemented using state machines. This fits well with the single-threaded, non-blocking event model since the protocol state can be stored as data within an object rather than being implicit in the progress of a thread's execution. Diagrams -------- Class diagrams: * *GNet namespace* [gnet-classes.png] * *GSmtp namespace* [gsmtp-classes.png] State transition diagrams: * *GNet::Client* [gnet-client.png] * *GSmtp::ServerProtocol* [gsmtp-serverprotocol.png] * *GSmtp::ScannerClient* [gsmtp-scannerclient.png] Sequence diagrams: * *Proxy mode forwarding* [sequence-3.png] * *Scanning* [sequence-4.png] * *ProtocolMessage::prepare() returns false* [sequence-1.png] * *ProtocolMessage::prepare() returns true* [sequence-2.png] Directory structure ------------------- # src Parent directory for source code. # src/glib A low-level class library, including classes for file-system abstraction, date and time, string utility functions, logging, command line parsing etc. # src/gnet A network library using Berkley sockets or Winsock. # src/gsmtp An SMTP library. # src/win32 Additional classes for windows event processing. # src/main Application-level classes for E-MailRelay. # lib Parent directory for ANSI C++ fixes # lib/gcc2.95 Standard headers which are missing in gcc2.95 # lib/msvc6.0 Standard headers which are missing (or broken) in msvc6.0 Portability ----------- The E-MailRelay code is written in ISO C++, although avoiding less-widely supported language features like "mutable", templated methods and "export". The header files "gdef.h" in "src/glib", and "gnet.h" in "src/gnet" are intended to be used to fix up compiler portability issues such as missing standard types, non-standard system headers etc. Conditional compilation directives ("#if" etc.) are largely confined to these headers in order to improve readability. Deficiencies in the ISO standard headers files provided by the compiler are fixed up by files in the "lib" directory tree. For example, the msvc6.0 compiler sometimes does not put its names into the "std" namespace, even though the std-namespace headers are used. This can be worked round by additional "using" declarations in the "lib/msvc6.0" headers. These work-rounds are kept out of the "src" tree because they are likely to be fixed in later compiler releases. Standards-compliant compilers should not need to include any headers from the "lib" directory tree. Windows/unix portability is generally addressed by providing a common class declaration with two implementations. Where necessary a "pimple" pattern is used to hide the system-specific parts of the declaration. A good example is the "G::Directory" class used for iterating through files in a directory. The header file "src/glib/gdirectory.h" is common to both systems, but two implementations are provided in "gdirectory_unix.cpp" and "gdirectory_win32.cpp". The unix implementation uses opendir() and glob(), while the windows implementation uses FindFirstFile(). Sometimes only small parts of the implementation are system-specific. In these cases there are three source files per header. For example, "gsocket.cpp", "gsocket_win32.cpp" and "gsocket_unix.cpp" in the "src/gnet" directory. Compile-time features --------------------- The following compile-time features can be enabled with some effort: # IPv6 IPv6 is supported at compile-time by selecting source files in the "src/gnet" directory ending "_ipv6.cpp" rather than "_ipv4.cpp". The code has been tested to a limited extent on Linux. # Verbose logging Verbose logging is enabled by defining the pre-processor symbol "_DEBUG". The configure script's "--enable-debug" switch can be used to do this. (See "src/glib/glog.h".) # Multiple listening ports The server can be made to listen on several different addresses. Look at the "Server" constructor in "src/main/gsmtpserver.cpp", set the boolean variable "normal" to false and then edit the hard-coded address strings as needed. If the addresses need different port numbers then pass them to bind() in the third parameter. Windows build ------------- Simple MSVC project files are provided in the "src/main" directory, bundled into the "emailrelay.dws" workspace. Makefiles for the *MinGW* [http://www.mingw.org/] system (gcc on Windows) are also provided. Style ----- The commenting style used in header files is compatible with doxygen if passed through the simple awk-based pre-processor "emailrelay-doxygen-filter.sh". A "make" in the "doc" directory will run doxygen if it is found on your path. Patterns -------- Gang-of-four Design Patterns (ISBN 0-201-63361-2): + Factory method - GNet::EventLoop::create() - GNet::Server::newPeer() - GSmtp::MessageStore::newMessage() + Iterator - G::DirectoryIterator - GNet::EventHandlerList::begin()/end() - GSmtp::MessageStore::iterator() + Singleton - G::LogOutput - GGui::ApplicationInstance - GNet::EventLoop + Facade - G::File - GNet::Address + Adapter/Mediator - GSmtp::ProtocolMessage Lakos' Large Scale C++ Software Design patterns (ISBN 0-201-63362-0): + Insulation; fully insulating concrete class (Meyer's Effective C++ Item 34, pimple pattern) - G::DirectoryIterator - GNet::Address - GNet::Resolver - GSmtp::ProtocolMessage + Insulation; protocol class - GNet::EventHandler - GSmtp::NewMessage - GSmtp::StoredMessage - GSmtp::ProtocolMessage - GSmtp::ServerProtocol::Sender - GSmtp::ClientProtocol::Sender Meyer's More Effective C++ patterns (ISBN 0-201-63371-X): + Reference counting (Item 29) - GSmtp::MessageStore::Iterator - G::Slot0 + Lazy evaluation (Item 17) - GNet::EventHandlerList::list() - G::Date::weekday() Other patterns: + Finite state machine - GSmtp::ServerProtocol + Slot/signal - G::Slot0 - G::Signal0 + Exception-safe assignment using swap - G::Slot0 Idioms ------ The "<<=" operator defined in "src/glib/gmemory.h" is used idiomatically to reassign a std::auto_ptr<>. Copyright (C) 2001-2005 Graeme Walker . All rights reserved.