diff options
Diffstat (limited to 'src/mailman/mta/docs/connection.txt')
| -rw-r--r-- | src/mailman/mta/docs/connection.txt | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/src/mailman/mta/docs/connection.txt b/src/mailman/mta/docs/connection.txt new file mode 100644 index 000000000..8924826c8 --- /dev/null +++ b/src/mailman/mta/docs/connection.txt @@ -0,0 +1,157 @@ +=============== +MTA connections +=============== + +Outgoing connections to the outgoing mail transport agent (MTA) are mitigated +through a Connection class, which can transparently manage multiple sessions +in a single connection. + + >>> from mailman.mta.connection import Connection + +The number of sessions per connections is specified when the Connection object +is created, as is the host and port number of the SMTP server. Zero means +there's an unlimited number of sessions per connection. + + >>> connection = Connection( + ... config.mta.smtp_host, int(config.mta.smtp_port), 0) + +At the start, there have been no connections to the server. + + >>> smtpd.get_connection_count() + 0 + +By sending a message to the server, a connection is opened. + + >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + {} + + >>> smtpd.get_connection_count() + 1 + +We can reset the connection count back to zero. + + >>> from smtplib import SMTP + >>> def reset(): + ... smtpd = SMTP() + ... smtpd.connect(config.mta.smtp_host, int(config.mta.smtp_port)) + ... smtpd.docmd('RSET') + + >>> reset() + >>> smtpd.get_connection_count() + 0 + + >>> connection.quit() + + +Sessions per connection +======================= + +Let's say we specify a maximum number of sessions per connection of 2. When +the third message is sent, the connection is torn down and a new one is +created. + +The connection count starts at zero. + + >>> connection = Connection( + ... config.mta.smtp_host, int(config.mta.smtp_port), 2) + + >>> smtpd.get_connection_count() + 0 + +We send two messages through the Connection object. Only one connection is +opened. + + >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + {} + + >>> smtpd.get_connection_count() + 1 + + >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + {} + + >>> smtpd.get_connection_count() + 1 + +The third message causes a third session, which exceeds the maximum. So the +current connection is closed and a new one opened. + + >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + {} + + >>> smtpd.get_connection_count() + 2 + +A fourth message does not cause a new connection to be made. + + >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + {} + + >>> smtpd.get_connection_count() + 2 + +But a fifth one does. + + >>> connection.sendmail('anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + {} + + >>> smtpd.get_connection_count() + 3 + + +No maximum +========== + +A value of zero means that there is an unlimited number of sessions per +connection. + + >>> connection = Connection( + ... config.mta.smtp_host, int(config.mta.smtp_port), 0) + >>> reset() + +Even after ten messages are sent, there's still been only one connection to +the server. + + >>> connection.debug = True + >>> for i in range(10): + ... # Ignore the results. + ... results = connection.sendmail( + ... 'anne@example.com', ['bart@example.com'], """\ + ... From: anne@example.com + ... To: bart@example.com + ... Subject: aardvarks + ... + ... """) + + >>> smtpd.get_connection_count() + 1 |