DSL for ping timeout settings

src/main/kotlin/com/dmdirc/ktirc/Dsl.kt

@@ -1,17 +1,13 @@
 package com.dmdirc.ktirc
 
+import java.time.Duration
+
 /**
  * Dsl marker for [IrcClient] dsl.
  */
 @DslMarker
 annotation class IrcClientDsl
 
-internal data class IrcClientConfig(
-        val server: ServerConfig,
-        val profile: ProfileConfig,
-        val behaviour: ClientBehaviour,
-        val sasl: SaslConfig?)
-
 /**
  * Dsl for configuring an IRC Client.
  *
@@ -206,12 +202,63 @@ class SaslConfig {
     }
 }
 
+@IrcClientDsl
+class PingConfig {
+
+    /**
+     * The period of time we will wait between sending pings to the server.
+     *
+     * If [incomingLinesResetTimer] is enabled, then a ping will be sent this period of time after the last line
+     * is received from the server. Otherwise, it will be sent this period of time after the last PONG response.
+     */
+    var sendPeriod: Duration? = null
+
+    /**
+     * The period of time to wait for a reply.
+     *
+     * If the server does not respond to a PING in this period, we consider it stoned and disconnect.
+     */
+    var responseGracePeriod: Duration? = null
+
+    /**
+     * Whether to treat incoming lines from the server as an indication that it is still active.
+     *
+     * This reduces the amount of pings that KtIrc will send, but can result in KtIrc staying connected even if the
+     * server is severely lagged or ignores all lines sent to it (for example).
+     */
+    var incomingLinesResetTimer: Boolean = false
+
+}
+
 /**
  * Dsl for configuring the behaviour of an [IrcClient].
  */
 @IrcClientDsl
 class BehaviourConfig : ClientBehaviour {
+
     override var requestModesOnJoin = false
     override var alwaysEchoMessages = false
     override var preferIPv6 = true
+
+    override var pingTimeouts: PingTimeouts? = null
+        internal set(value) {
+            check(field == null) { "ping timeouts may only be specified once" }
+            field = value
+        }
+
+    /**
+     * Configures how frequently KtIrc will send pings, and how it will deal with non-responsive servers.
+     *
+     * If not specified, KtIrc will not send pings.
+     *
+     * See [PingConfig].
+     */
+    @IrcClientDsl
+    fun sendPings(block: PingConfig.() -> Unit) {
+        val config = PingConfig().apply(block)
+        requireNotNull(config.sendPeriod) { "send period must be specified" }
+        requireNotNull(config.responseGracePeriod) { "response grace period must be specified" }
+        pingTimeouts = IrcPingTimeouts(config.sendPeriod!!, config.responseGracePeriod!!, config.incomingLinesResetTimer)
+    }
+
 }

src/main/kotlin/com/dmdirc/ktirc/IrcClient.kt

@@ -7,6 +7,7 @@ import com.dmdirc.ktirc.messages.tagMap
 import com.dmdirc.ktirc.model.*
 import com.dmdirc.ktirc.util.RemoveIn
 import kotlinx.coroutines.Deferred
+import java.time.Duration
 
 /**
  * Primary interface for interacting with KtIrc.
@@ -186,6 +187,36 @@ internal interface ExperimentalIrcClient : IrcClient {
 
 }
 
+/**
+ * Defines the configuration for sending pings and dealing with ping timeouts.
+ */
+interface PingTimeouts {
+
+    /**
+     * The period of time we will wait between sending pings to the server.
+     *
+     * If [incomingLinesResetTimer] is enabled, then a ping will be sent this period of time after the last line
+     * is received from the server. Otherwise, it will be sent this period of time after the last PONG response.
+     */
+    val sendPeriod: Duration
+
+    /**
+     * The period of time to wait for a reply.
+     *
+     * If the server does not respond to a PING in this period, we consider it stoned and disconnect.
+     */
+    val responseGracePeriod: Duration
+
+    /**
+     * Whether to treat incoming lines from the server as an indication that it is still active.
+     *
+     * This reduces the amount of pings that KtIrc will send, but can result in KtIrc staying connected even if the
+     * server is severely lagged or ignores all lines sent to it (for example).
+     */
+    val incomingLinesResetTimer: Boolean
+
+}
+
 /**
  * Defines the behaviour of an [IrcClient].
  */
@@ -210,6 +241,14 @@ interface ClientBehaviour {
      */
     val preferIPv6: Boolean
 
+    /**
+     * The settings to use for sending pings to the server, and timing out connections that don't reply to those
+     * pings.
+     *
+     * If unset (i.e., `null`), no pings will be sent, and KtIrc will never time out servers.
+     */
+    val pingTimeouts: PingTimeouts?
+
 }
 
 /**

src/main/kotlin/com/dmdirc/ktirc/IrcClientImpl.kt

@@ -23,6 +23,17 @@ import java.net.InetAddress
 import java.time.Duration
 import java.util.logging.Level
 
+internal data class IrcClientConfig(
+        val server: ServerConfig,
+        val profile: ProfileConfig,
+        val behaviour: ClientBehaviour,
+        val sasl: SaslConfig?)
+
+internal data class IrcPingTimeouts(
+        override val sendPeriod: Duration,
+        override val responseGracePeriod: Duration,
+        override val incomingLinesResetTimer: Boolean) : PingTimeouts
+
 /**
  * Concrete implementation of an [IrcClient].
  */

src/test/kotlin/com/dmdirc/ktirc/DslTest.kt

@@ -3,6 +3,7 @@ package com.dmdirc.ktirc
 import org.junit.jupiter.api.Assertions.*
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
+import java.time.Duration
 
 internal class IrcClientConfigBuilderTest {
 
@@ -212,6 +213,92 @@ internal class IrcClientConfigBuilderTest {
         assertFalse(config.behaviour.requestModesOnJoin)
     }
 
+    @Test
+    fun `defaults to null ping timeouts if sendPings omitted`() {
+        val config = IrcClientConfigBuilder().apply {
+            profile { nickname = "acidBurn" }
+            server { host = "thegibson.com" }
+            behaviour {
+                requestModesOnJoin = true
+            }
+        }.build()
+
+        assertNull(config.behaviour.pingTimeouts)
+    }
+
+    @Test
+    fun `throws if sendPings specified without send period`() {
+        assertThrows<IllegalArgumentException> {
+            IrcClientConfigBuilder().apply {
+                profile { nickname = "acidBurn" }
+                server { host = "thegibson.com" }
+                behaviour {
+                    requestModesOnJoin = true
+                    sendPings {
+                        responseGracePeriod = Duration.ofSeconds(10)
+                    }
+                }
+            }.build()
+        }
+    }
+
+    @Test
+    fun `throws if sendPings specified without grace period`() {
+        assertThrows<IllegalArgumentException> {
+            IrcClientConfigBuilder().apply {
+                profile { nickname = "acidBurn" }
+                server { host = "thegibson.com" }
+                behaviour {
+                    requestModesOnJoin = true
+                    sendPings {
+                        sendPeriod = Duration.ofSeconds(10)
+                    }
+                }
+            }.build()
+        }
+    }
+
+    @Test
+    fun `throws if sendPings specified twice`() {
+        assertThrows<IllegalStateException> {
+            IrcClientConfigBuilder().apply {
+                profile { nickname = "acidBurn" }
+                server { host = "thegibson.com" }
+                behaviour {
+                    requestModesOnJoin = true
+                    sendPings {
+                        sendPeriod = Duration.ofSeconds(10)
+                        responseGracePeriod = Duration.ofSeconds(10)
+                    }
+                    sendPings {
+                        sendPeriod = Duration.ofSeconds(10)
+                        responseGracePeriod = Duration.ofSeconds(10)
+                    }
+                }
+            }.build()
+        }
+    }
+
+    @Test
+    fun `configures ping timeouts`() {
+        val config = IrcClientConfigBuilder().apply {
+            profile { nickname = "acidBurn" }
+            server { host = "thegibson.com" }
+            behaviour {
+                requestModesOnJoin = true
+                sendPings {
+                    sendPeriod = Duration.ofSeconds(50)
+                    responseGracePeriod = Duration.ofSeconds(100)
+                    incomingLinesResetTimer = true
+                }
+            }
+        }.build()
+
+        assertEquals(50, config.behaviour.pingTimeouts?.sendPeriod?.seconds)
+        assertEquals(100, config.behaviour.pingTimeouts?.responseGracePeriod?.seconds)
+        assertEquals(true, config.behaviour.pingTimeouts?.incomingLinesResetTimer)
+    }
+
     @Test
     fun `applies sasl settings`() {
         val config = IrcClientConfigBuilder().apply {