Added pong handling, docs for sendPings

docs/index.adoc

@@ -237,6 +237,12 @@ profile {
 behaviour {
     requestModesOnJoin = true
     alwaysEchoMessages = true
+    preferIPv6 = false
+    sendPings {
+        sendPeriod = Duration.ofSeconds(120)
+        responseGracePeriod = Duration.ofSeconds(30)
+        incomingLinesResetTimer = true
+    }
 }
 
 sasl {
@@ -318,6 +324,41 @@ advanced IRC features even if the server doesn't support them:
 
 The behaviour block is optional in its entirety.
 
+==== Ping timeouts
+
+The behaviour config has an optional `sendPings` configuration, which
+instructs KtIrc to automatically send ping requests to the server.
+This ensures that the server is still connected and operating properly,
+and will trigger a disconnect if that is not the case.
+
+The sendPings block looks like:
+
+[source,kotlin]
+----
+sendPings {
+    sendPeriod = Duration.ofSeconds(120) <1>
+    responseGracePeriod = Duration.ofSeconds(30) <2>
+    incomingLinesResetTimer = true <3>
+}
+----
+<1> The `sendPeriod` defines how often KtIrc should send pings. Most
+    applications will probably want to send pings somewhere between
+    every 30 seconds and every minute or two. If the `sendPings`
+    block is present, this field is required.
+<2> The `responseGracePeriod` defines how long KtIrc will wait for a
+    response from the server before it considers the server to be
+    malfunctioning. Setting this too low will result in disconnects
+    when the connection to the server is merely suffering from high
+    latency, rather than irreparably broken.  If the `sendPings`
+    block is present, this field is required.
+<3> The only optional field in the `sendPings` block, the
+    `incomingLinesResetTimer` setting determines whether KtIrc will
+    treat _any_ incoming line in the same way as a `PONG` response;
+    in effect it prevents KtIrc from disconnecting from a server
+    suffering from high latency as long as the server keeps sending
+    _something_. When disabled (or not specified), KtIrc will require
+    an explicit `PONG` reply.
+
 === SASL configuration
 
 SASL ("Simple Authentication and Security Layer") is a standard mechanism
@@ -1179,6 +1220,14 @@ If the user is no longer logged in to an account, `newAccount` will be
 Raised when the IRC server sends a PING message to the client. KtIrc will
 automatically reply with an appropriate PONG.
 
+==== PongReceived
+* Type: IrcEvent
+* Properties:
+** `nonce`: `ByteArray` - the unique data that was sent in the PING
+
+Raised when the IRC server sends a PONG message to the client. KtIrc can
+automatically send pings and handle pongs, see <<Ping timeouts>>.
+
 ==== ServerFeaturesUpdated
 * Type: IrcEvent
 * Properties:

src/main/kotlin/com/dmdirc/ktirc/events/Events.kt

@@ -104,6 +104,9 @@ class ServerFeaturesUpdated(metadata: EventMetadata, val serverFeatures: ServerF
 /** Raised whenever a PING is received from the server. */
 class PingReceived(metadata: EventMetadata, val nonce: ByteArray) : IrcEvent(metadata)
 
+/** Raised whenever a PONG is received from the server. */
+class PongReceived(metadata: EventMetadata, val nonce: ByteArray) : IrcEvent(metadata)
+
 /** Raised when a user joins a channel. */
 class ChannelJoined(metadata: EventMetadata, override val user: User, channel: String)
     : TargetedEvent(metadata, channel), SourcedEvent, ChannelMembershipAdjustment {

src/main/kotlin/com/dmdirc/ktirc/messages/processors/PingProcessor.kt

@@ -1,13 +1,17 @@
 package com.dmdirc.ktirc.messages.processors
 
 import com.dmdirc.ktirc.events.PingReceived
-import com.dmdirc.ktirc.messages.processors.MessageProcessor
+import com.dmdirc.ktirc.events.PongReceived
 import com.dmdirc.ktirc.model.IrcMessage
 
 internal class PingProcessor : MessageProcessor {
 
-    override val commands = arrayOf("PING")
+    override val commands = arrayOf("PING", "PONG")
 
-    override fun process(message: IrcMessage) = listOf(PingReceived(message.metadata, message.params[0]))
+    override fun process(message: IrcMessage) = if (message.command == "PING") {
+        listOf(PingReceived(message.metadata, message.params[0]))
+    } else {
+        listOf(PongReceived(message.metadata, message.params[0]))
+    }
 
 }

src/test/kotlin/com/dmdirc/ktirc/messages/processors/PingProcessorTest.kt

@@ -0,0 +1,42 @@
+package com.dmdirc.ktirc.messages.processors
+
+import com.dmdirc.ktirc.TestConstants
+import com.dmdirc.ktirc.events.PingReceived
+import com.dmdirc.ktirc.events.PongReceived
+import com.dmdirc.ktirc.model.IrcMessage
+import com.dmdirc.ktirc.params
+import com.dmdirc.ktirc.util.currentTimeProvider
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+
+internal class PingProcessorTest {
+
+    @BeforeEach
+    fun setUp() {
+        currentTimeProvider = { TestConstants.time }
+    }
+
+    @Test
+    fun `raises ping event with nonce`() {
+        val events = PingProcessor().process(
+                IrcMessage(emptyMap(), null, "PING", params("12345")))
+        assertEquals(1, events.size)
+
+        val event = events[0] as PingReceived
+        assertEquals(TestConstants.time, event.metadata.time)
+        assertEquals("12345", String(event.nonce))
+    }
+
+    @Test
+    fun `raises pong event with nonce`() {
+        val events = PingProcessor().process(
+                IrcMessage(emptyMap(), null, "PONG", params("12345")))
+        assertEquals(1, events.size)
+
+        val event = events[0] as PongReceived
+        assertEquals(TestConstants.time, event.metadata.time)
+        assertEquals("12345", String(event.nonce))
+    }
+
+}