[geary] Document and tweak IMAP keep-alive periods and TCP socket timeouts.

[Michael Gratton <mjog src gnome org>]

commit ae5f6a4d31208093c8310966fc3596a6733f85e6
Author: Michael James Gratton <mike vee net>
Date:   Mon Nov 20 16:49:02 2017 +1100

    Document and tweak IMAP keep-alive periods and TCP socket timeouts.

 .../imap/transport/imap-client-connection.vala     |   34 +++++++----
 src/engine/imap/transport/imap-client-session.vala |   63 +++++++++++++++-----
 2 files changed, 71 insertions(+), 26 deletions(-)
---
diff --git a/src/engine/imap/transport/imap-client-connection.vala 
b/src/engine/imap/transport/imap-client-connection.vala
index bf7da00..5f52705 100644
--- a/src/engine/imap/transport/imap-client-connection.vala
+++ b/src/engine/imap/transport/imap-client-connection.vala
@@ -5,24 +5,36 @@
  */
 
 public class Geary.Imap.ClientConnection : BaseObject {
+
+    /** Default un-encrypted IMAP network port */
     public const uint16 DEFAULT_PORT = 143;
+
+    /** Default encrypted IMAP network port */
     public const uint16 DEFAULT_PORT_SSL = 993;
-    
+
     /**
-     * This is set very high to allow for IDLE connections to remain connected even when
-     * there is no traffic on them.  The side-effect is that if the physical connection is dropped,
-     * no error is reported and the connection won't know about it until the next send operation.
+     * Default socket timeout duration.
      *
-     * RECOMMENDED_TIMEOUT_SEC is more realistic in that if a connection is hung it's important
-     * to detect it early and drop it, at the expense of more keepalive traffic.
+     * This is set to the highest value required by RFC 3501 to allow
+     * for IDLE connections to remain connected even when there is no
+     * traffic on them.  The side-effect is that if the physical
+     * connection is dropped, no error is reported and the connection
+     * won't know about it until the next send operation.
      *
-     * In general, whatever timeout is used for the ClientConnection must be slightly higher than
-     * the keepalive timeout used by ClientSession, otherwise the ClientConnection will be dropped
-     * before the keepalive is sent.
+     * {@link RECOMMENDED_TIMEOUT_SEC} is more realistic in that if a
+     * connection is hung it's important to detect it early and drop
+     * it, at the expense of more keepalive traffic.
+     *
+     * In general, whatever timeout is used for the ClientConnection
+     * must be slightly higher than the keepalive timeout used by
+     * {@link ClientSession}, otherwise the ClientConnection will be
+     * dropped before the keepalive is sent.
      */
-    public const uint DEFAULT_TIMEOUT_SEC = ClientSession.MIN_KEEPALIVE_SEC + 15;
+    public const uint DEFAULT_TIMEOUT_SEC = ClientSession.MAX_KEEPALIVE_SEC;
+
+    /** Recommended socket timeout duration. */
     public const uint RECOMMENDED_TIMEOUT_SEC = ClientSession.RECOMMENDED_KEEPALIVE_SEC + 15;
-    
+
     /**
      * The default timeout for an issued command to result in a response code from the server.
      *
diff --git a/src/engine/imap/transport/imap-client-session.vala 
b/src/engine/imap/transport/imap-client-session.vala
index 32e2a89..ea4bc07 100644
--- a/src/engine/imap/transport/imap-client-session.vala
+++ b/src/engine/imap/transport/imap-client-session.vala
@@ -23,25 +23,58 @@
  * {@link send_command_async} and {@link send_multiple_commands_async}.
  */
 public class Geary.Imap.ClientSession : BaseObject {
-    // 30 min keepalive required to maintain session
-    public const uint MIN_KEEPALIVE_SEC = 30 * 60;
-    
-    // 10 minutes is more realistic, as underlying sockets will not necessarily report errors if
-    // physical connection is lost
-    public const uint RECOMMENDED_KEEPALIVE_SEC = 10 * 60;
-    
-    // A more aggressive keepalive will detect when a connection has died, thereby giving the client
-    // a chance to reestablish a connection without long lags.
+
+    /**
+     * Maximum keep-alive interval required to maintain a session.
+     *
+     * RFC 3501 requires servers have a minimum idle timeout of 30
+     * minutes, so the keep-alive interval should be set to less than
+     * this.
+     */
+    public const uint MAX_KEEPALIVE_SEC = 30 * 60;
+
+    /**
+     * Recommended keep-alive interval required to maintain a session.
+     *
+     * Although many servers will allow a timeout of at least what RFC
+     * 3501 requires, devices in between (e.g. NAT gateways) may have
+     * much shorter timeouts. Thus this is set much lower than what
+     * the RFC allows.
+     */
+    public const uint RECOMMENDED_KEEPALIVE_SEC = (10 * 60) - 30;
+
+    /**
+     * An aggressive keep-alive interval for polling for updates.
+     *
+     * Since a server may respond to NOOP with untagged responses for
+     * new messages or status updates, this is a useful timeout for
+     * polling for changes.
+     */
     public const uint AGGRESSIVE_KEEPALIVE_SEC = 5 * 60;
-    
-    // NOOP is only sent after this amount of time has passed since the last received
-    // message on the connection dependent on connection state (selected/examined vs. authorized)
+
+    /**
+     * Default keep-alive interval in the Selected state.
+     *
+     * This uses @{link AGGRESSIVE_KEEPALIVE_SEC} so that without IMAP
+     * IDLE, changes to the mailbox are still noticed without too much
+     * delay.
+     */
     public const uint DEFAULT_SELECTED_KEEPALIVE_SEC = AGGRESSIVE_KEEPALIVE_SEC;
+
+    /**
+     * Default keep-alive interval in the Selected state with IDLE.
+     *
+     * This uses @{link RECOMMENDED_KEEPALIVE_SEC} because IMAP IDLE
+     * will notify about changes to the mailbox as it happens .
+     */
+    public const uint DEFAULT_SELECTED_WITH_IDLE_KEEPALIVE_SEC = RECOMMENDED_KEEPALIVE_SEC;
+
+    /** Default keep-alive interval when not in the Selected state. */
     public const uint DEFAULT_UNSELECTED_KEEPALIVE_SEC = RECOMMENDED_KEEPALIVE_SEC;
-    public const uint DEFAULT_SELECTED_WITH_IDLE_KEEPALIVE_SEC = AGGRESSIVE_KEEPALIVE_SEC;
-    
+
     private const uint GREETING_TIMEOUT_SEC = ClientConnection.DEFAULT_COMMAND_TIMEOUT_SEC;
-    
+
+
     /**
      * The various states an IMAP {@link ClientSession} may be in at any moment.
      *