Add NicknameChangeRequired event

CHANGELOG

 vNEXT (in development)
 
+ * Added NicknameChangeRequired event for the case when a nickname is
+   not allowed during connection and *MUST* be changed
+
 v0.11.0
 
  * Added SourcedEvent interface for events that have a user source attached

docs/index.adoc

 which are documented in the <<Messages>> reference. Other useful methods
 such as `reply` can be found in the <<Utility methods>> reference.
 
+=== Mandatory event handling
+
+In order to properly connect to IRC, stay connected, and handle
+incoming messages properly, the following events MUST be handled:
+
+.<<NicknameChangeRequired>>
+The nickname change required event occurs when connecting to a server
+if our initial nickname is taken. A new nickname must be supplied
+to continue connecting.
+
+.<<ServerDisconnected>>
+When KtIrc becomes disconnected from a server, or fails a connection
+attempt, it will raise this event. If you wish to stay connected
+to IRC you must call the `connect()` method to start a reconnection
+attempt after an appropriate delay.
+
+.<<BatchReceived>>
+On servers that support the IRCv3 batch capability, some incoming
+messages may be sent inside a batch. These could include join or
+quit messages during a netsplit, or other important messages you
+may need to process. At minimum, when receiving a BatchReceived
+event you should apply your normal processing to all the events
+contained within.
+
+
 == IrcClient DSL
 
 The DSL for creating a new `IrcClient` allows you to set a number of
 TODO
 
 ==== NicknameChangeFailed
+* Type: IrcEvent
+* Properties:
+** `cause`: `NicknameChangeError` - the reason the nickname must be changed
 
-TODO
+Raised when the server informs us that our desired nickname is not available
+for some reason. The `cause` parameter will contain a specific reason given
+by the server:
+
+* `ErroneousNickname` - the nickname is not allowed by the server (e.g. it used
+  restricted characters)
+* `AlreadyInUse` - the nickname is already in use
+* `Collision` - the nickname has collided with another somehow
+* `NoNicknameGiven` - no nickname was provided
+
+==== NicknameChangeRequired
+* Type: IrcEvent, NicknameChangeFailed
+* Properties:
+** `cause`: `NicknameChangeError` - the reason the nickname must be changed
+
+Raised during a connection attempt when there is a problem with the nickname
+that KtIrc was told to use. The exact problem will be detailed in the `cause`
+parameter, and has the same options as the <<NicknameChangeFailed>> event.
+
+Upon receiving this event, a new nickname MUST be chosen and sent to the
+server with the <<sendNickChange>> method. Failure to do so will result
+in the IRC server terminating the connection.
+
+WARNING: `NicknameChangeRequired` currently extends `NicknameChangeFailed`
+for backwards compatibility. This will be removed in KtIrc 2.0.0, and
+both events will need to be handled separately.
 
 == Messages
 
 TODO
 
+==== sendNickChange
+
+TODO
+
 == Utility methods
 
 TODO

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

 
 /**
  * Raised when attempting to set or change our nickname fails.
- *
- * If this happens before {ServerReady], the nickname must be changed for registration to continue.
  */
-class NicknameChangeFailed(metadata: EventMetadata, val cause: NicknameChangeError) : IrcEvent(metadata) {
-    /** Reasons a nick change may fail. */
-    enum class NicknameChangeError {
-        /** The nickname is not allowed by the server. */
-        ErroneousNickname,
-        /** The nickname is already in use. */
-        AlreadyInUse,
-        /** The nickname has collided with another somehow. */
-        Collision,
-        /** No nickname was provided. */
-        NoNicknameGiven
-    }
-}
+open class NicknameChangeFailed(metadata: EventMetadata, val cause: NicknameChangeError) : IrcEvent(metadata)
 
+/**
+ * Raised during a connection attempt if the nickname we wanted is not available.
+ *
+ * The nickname must be changed to continue connecting.
+ *
+ * In 2.0.0 this will no longer extend [NicknameChangeFailed] and will have to be handled separately.
+ */
+@RemoveIn("2.0.0")
+class NicknameChangeRequired(metadata: EventMetadata, cause: NicknameChangeError) : NicknameChangeFailed(metadata, cause)
+
+/** Reasons a nick change may fail. */
+enum class NicknameChangeError {
+    /** The nickname is not allowed by the server. */
+    ErroneousNickname,
+    /** The nickname is already in use. */
+    AlreadyInUse,
+    /** The nickname has collided with another somehow. */
+    Collision,
+    /** No nickname was provided. */
+    NoNicknameGiven
+}

src/main/kotlin/com/dmdirc/ktirc/events/mutators/EventMutator.kt

 internal val eventMutators = listOf(
         ServerReadyMutator(),
         ChannelFanOutMutator(),
+        NickChangeRequiredMutator(),
         BatchMutator()
 )

src/main/kotlin/com/dmdirc/ktirc/events/mutators/NickChangeRequiredMutator.kt

+package com.dmdirc.ktirc.events.mutators
+
+import com.dmdirc.ktirc.IrcClient
+import com.dmdirc.ktirc.events.IrcEvent
+import com.dmdirc.ktirc.events.NicknameChangeFailed
+import com.dmdirc.ktirc.events.NicknameChangeRequired
+import com.dmdirc.ktirc.io.MessageEmitter
+import com.dmdirc.ktirc.model.ServerStatus
+
+internal class NickChangeRequiredMutator : EventMutator {
+
+    override fun mutateEvent(client: IrcClient, messageEmitter: MessageEmitter, event: IrcEvent) =
+            if (event is NicknameChangeFailed && client.serverState.status < ServerStatus.Ready) {
+                listOf(NicknameChangeRequired(event.metadata, event.cause))
+            } else {
+                listOf(event)
+            }
+
+}

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

 package com.dmdirc.ktirc.messages.processors
 
+import com.dmdirc.ktirc.events.NicknameChangeError
 import com.dmdirc.ktirc.events.NicknameChangeFailed
 import com.dmdirc.ktirc.messages.ERR_ERRONEUSNICKNAME
 import com.dmdirc.ktirc.messages.ERR_NICKCOLLISION
 
     override fun process(message: IrcMessage) = listOf(NicknameChangeFailed(message.metadata, message.command.toNicknameChangeError()))
 
-    private fun String.toNicknameChangeError(): NicknameChangeFailed.NicknameChangeError = when(this) {
-        ERR_ERRONEUSNICKNAME -> NicknameChangeFailed.NicknameChangeError.ErroneousNickname
-        ERR_NICKCOLLISION -> NicknameChangeFailed.NicknameChangeError.Collision
-        ERR_NICKNAMEINUSE -> NicknameChangeFailed.NicknameChangeError.AlreadyInUse
-        ERR_NONICKNAMEGIVEN -> NicknameChangeFailed.NicknameChangeError.NoNicknameGiven
+    private fun String.toNicknameChangeError(): NicknameChangeError = when(this) {
+        ERR_ERRONEUSNICKNAME -> NicknameChangeError.ErroneousNickname
+        ERR_NICKCOLLISION -> NicknameChangeError.Collision
+        ERR_NICKNAMEINUSE -> NicknameChangeError.AlreadyInUse
+        ERR_NONICKNAMEGIVEN -> NicknameChangeError.NoNicknameGiven
         else -> throw IllegalArgumentException("Unknown nick change error")
     }
 

src/test/kotlin/com/dmdirc/ktirc/events/mutators/NickChangeRequiredMutatorTest.kt

+package com.dmdirc.ktirc.events.mutators
+
+import com.dmdirc.ktirc.IrcClient
+import com.dmdirc.ktirc.TestConstants
+import com.dmdirc.ktirc.events.*
+import com.dmdirc.ktirc.io.MessageEmitter
+import com.dmdirc.ktirc.model.ServerState
+import com.dmdirc.ktirc.model.ServerStatus
+import io.mockk.every
+import io.mockk.mockk
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Test
+
+internal class NickChangeRequiredMutatorTest {
+
+    private val mutator = NickChangeRequiredMutator()
+    private val fakeServerState = ServerState("acidBurn", "the.gibson")
+    private val mockClient = mockk<IrcClient> {
+        every { serverState } returns fakeServerState
+    }
+    private val mockEmitter = mockk<MessageEmitter>()
+
+    @Test
+    fun `returns other events before server ready`() {
+        fakeServerState.status = ServerStatus.Negotiating
+        val event = ServerConnected(EventMetadata(TestConstants.time))
+        val events = mutator.mutateEvent(mockClient, mockEmitter, event)
+        assertEquals(1, events.size)
+        assertEquals(event, events[0])
+    }
+
+    @Test
+    fun `returns other events after server ready`() {
+        fakeServerState.status = ServerStatus.Ready
+        val event = ServerConnected(EventMetadata(TestConstants.time))
+        val events = mutator.mutateEvent(mockClient, mockEmitter, event)
+        assertEquals(1, events.size)
+        assertEquals(event, events[0])
+    }
+
+    @Test
+    fun `returns nick change failed events after server ready`() {
+        fakeServerState.status = ServerStatus.Ready
+        val event = NicknameChangeFailed(EventMetadata(TestConstants.time), NicknameChangeError.AlreadyInUse)
+        val events = mutator.mutateEvent(mockClient, mockEmitter, event)
+        assertEquals(1, events.size)
+        assertEquals(event, events[0])
+    }
+
+    @Test
+    fun `returns nick change required event before server ready`() {
+        fakeServerState.status = ServerStatus.Negotiating
+        val event = NicknameChangeFailed(EventMetadata(TestConstants.time), NicknameChangeError.AlreadyInUse)
+        val events = mutator.mutateEvent(mockClient, mockEmitter, event)
+        assertEquals(1, events.size)
+        val received = events[0] as NicknameChangeRequired
+        assertEquals(event.metadata, received.metadata)
+        assertEquals(event.cause, received.cause)
+    }
+
+}

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

 package com.dmdirc.ktirc.messages.processors
 
 import com.dmdirc.ktirc.TestConstants
-import com.dmdirc.ktirc.events.NicknameChangeFailed
+import com.dmdirc.ktirc.events.NicknameChangeError
 import com.dmdirc.ktirc.messages.tagMap
 import com.dmdirc.ktirc.model.IrcMessage
 import com.dmdirc.ktirc.model.MessageTag
     fun `raises error event when nick in use`() {
         val events = processor.process(IrcMessage(tagMap(), null, "433", params("Nickname already in use")))
         assertEquals(1, events.size)
-        assertEquals(NicknameChangeFailed.NicknameChangeError.AlreadyInUse, events[0].cause)
+        assertEquals(NicknameChangeError.AlreadyInUse, events[0].cause)
     }
 
     @Test
     fun `raises error event when nick is erroneous`() {
         val events = processor.process(IrcMessage(tagMap(), null, "432", params("Nickname not allowed")))
         assertEquals(1, events.size)
-        assertEquals(NicknameChangeFailed.NicknameChangeError.ErroneousNickname, events[0].cause)
+        assertEquals(NicknameChangeError.ErroneousNickname, events[0].cause)
     }
 
     @Test
     fun `raises error event when nick collides`() {
         val events = processor.process(IrcMessage(tagMap(), null, "436", params("Nick collision")))
         assertEquals(1, events.size)
-        assertEquals(NicknameChangeFailed.NicknameChangeError.Collision, events[0].cause)
+        assertEquals(NicknameChangeError.Collision, events[0].cause)
     }
 
     @Test
     fun `raises error event when nick not provided`() {
         val events = processor.process(IrcMessage(tagMap(), null, "431", params("No nickname given")))
         assertEquals(1, events.size)
-        assertEquals(NicknameChangeFailed.NicknameChangeError.NoNicknameGiven, events[0].cause)
+        assertEquals(NicknameChangeError.NoNicknameGiven, events[0].cause)
     }
 
     @Test