Expose the local user object directly

CHANGELOG

    * Added sendAway() method
    * Added UserAway event and fanned-out ChannelAway
    * Away message is now updated in the UserState
+ * Added IrcClient.localUser property, returning the local User
+ * Deprecated ServerState.localNickname in favour of localUser.
  * (Internal) improved the way byte buffers are used to
    reduce array copying and clean up code
 

docs/index.adoc

 * `Negotiating` - we are logging in, negotiating capabilities, etc
 * `Ready` - we are connected and commands may be sent
 
-.serverState.localNickname (String)
+.serverState.localNickname (String) [DEPRECATED]
 The current nickname we are using on the IRC server. While connecting this
 will default to the nickname from the <<User profile>>, but it may be updated
 if e.g. the nick is in use or not allowed.
 
+[WARNING]
+====
+This property is deprecated in favour of the <<LocalUser>> property of `IrcClient`.
+You should migrate to using `localUser.nickname` in place of `serverSate.localNickname`.
+====
+
 .serverState.serverName (String)
 The name the server uses for itself. While connecting this defaults to the
 hostname given in the <<Server settings>>, but it will be updated to the
 ----
 
 The UserState returns a `KnownUser` object which exposes a `details`
-property containing the user details, and a `channels` property
+property containing the <<User>> details, and a `channels` property
 containing the common channel names. You can also use the `in`
 operator to check if the user is in a channel:
 
 <3> Returns all common channels we share with the user; will never
     include channels that the KtIrc client is not joined to.
 
+==== User
+
+User objects have the following properties:
+
+* `nickname` - the current nickname of the user, always set
+* `ident` - the ident (username/"gecos") of the user, if known (null otherwise)
+* `hostname` - the hostname of the user, if known (null otherwise)
+* `account` - the account of the user, if known (null if account unknown, or user not registered)
+* `realName` - the real name of the user, if known (null otherwise)
+* `awayMessage` - the away message of the user, if known (null if away state unknown, or user not away)
+
+=== LocalUser
+
+Contains a <<User>> instance corresponding to our own details on the IRC
+network. This is the same instance that would be returned from
+`ircClient.userState[nickname]` for the current nickname.
+
+While connecting this will default to a User with only a nickname, which will
+be taken from the <<User profile>>. It will be updated as more information
+is received from the IRC server.
+
 === ChannelState
 
 The ChannelState keeps track of the state for all channels that the client

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

      */
     val userState: UserState
 
+    /**
+     * Details of our user on IRC.
+     */
+    val localUser: User
+
     /**
      * The configured behaviour of the client.
      */
      * Utility method to determine if the given user is the one we are connected to IRC as. Should only be used after a
      * [com.dmdirc.ktirc.events.ServerReady] event has been received.
      */
-    fun isLocalUser(nickname: String) = caseMapping.areEquivalent(nickname, serverState.localNickname)
+    fun isLocalUser(nickname: String) = caseMapping.areEquivalent(nickname, localUser.nickname)
 
     /**
      * Determines if the given [target] appears to be a channel or not. Should only be used after a

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

 
     override val serverState = ServerState(config.profile.nickname, config.server.host, config.sasl)
     override val channelState = ChannelStateMap { caseMapping }
-    override val userState = UserState { caseMapping }
+    override val localUser = User(config.profile.nickname)
+    override val userState = UserState { caseMapping }.apply { this += localUser }
 
     private val messageHandler = MessageHandler(messageProcessors, eventMutators, eventHandlers)
     private val messageBuilder = MessageBuilder()
         if (command == "PRIVMSG" && behaviour.alwaysEchoMessages && !serverState.capabilities.enabledCapabilities.contains(Capability.EchoMessages)) {
             emitEvent(MessageReceived(
                     EventMetadata(currentTimeProvider()),
-                    userState[serverState.localNickname]?.details ?: User(serverState.localNickname),
+                    localUser,
                     arguments[0],
                     arguments[1]
             ))
         serverState.reset()
         channelState.clear()
         userState.reset()
+        localUser.reset(config.profile.nickname)
+        userState += localUser
         socket = null
         connecting.tryLock()
         connecting.unlock()

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

  * Utility to determine whether the given message is to our local user or not.
  */
 internal fun IrcClient.isToMe(message: MessageReceived) =
-        caseMapping.areEquivalent(message.target, serverState.localNickname)
+        caseMapping.areEquivalent(message.target, localUser.nickname)

src/main/kotlin/com/dmdirc/ktirc/events/handlers/UserStateHandler.kt

 
 import com.dmdirc.ktirc.IrcClient
 import com.dmdirc.ktirc.events.*
+import com.dmdirc.ktirc.model.User
 import com.dmdirc.ktirc.model.UserState
 
 internal class UserStateHandler : EventHandler {
             is UserHostChanged -> handleHostChanged(client, event)
             is UserQuit -> handleQuit(client.userState, event)
             is UserAway -> handleAway(client.userState, event)
+            is ServerWelcome -> handleServerWelcome(client.localUser, event)
         }
     }
 
         }
     }
 
+    private fun handleServerWelcome(localUser: User, event: ServerWelcome) {
+        localUser.nickname = event.localNick
+    }
+
 }

src/main/kotlin/com/dmdirc/ktirc/model/ServerState.kt

 import com.dmdirc.ktirc.events.EventMetadata
 import com.dmdirc.ktirc.events.IrcEvent
 import com.dmdirc.ktirc.io.CaseMapping
+import com.dmdirc.ktirc.util.RemoveIn
 import com.dmdirc.ktirc.util.logger
 import kotlinx.coroutines.channels.SendChannel
 import java.util.concurrent.atomic.AtomicLong
      * in use when connecting. Once you have received a [com.dmdirc.ktirc.events.ServerWelcome] event you can
      * rely on this value being current.
      * */
+    @RemoveIn("3.0.0")
+    @Deprecated("use ircClient.localUser.nickname instead")
     var localNickname: String = initialNickname
         internal set
 

src/main/kotlin/com/dmdirc/ktirc/model/User.kt

         other.realName?.let { realName = it }
         other.awayMessage?.let { awayMessage = it }
     }
+
+    internal fun reset(newNickname: String) {
+        nickname = newNickname
+        ident = null
+        hostname = null
+        account = null
+        realName = null
+        awayMessage = null
+    }
 }
 
 internal fun ByteArray.asUser() = String(this).asUser()

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

 import com.dmdirc.ktirc.io.LineBufferedSocket
 import com.dmdirc.ktirc.messages.tagMap
 import com.dmdirc.ktirc.model.*
+import com.dmdirc.ktirc.util.RemoveIn
 import com.dmdirc.ktirc.util.currentTimeProvider
 import com.dmdirc.ktirc.util.generateLabel
 import io.mockk.*
     @Test
     fun `indicates if user is local user or not`() {
         val client = IrcClientImpl(normalConfig)
-        client.serverState.localNickname = "[acidBurn]"
+        client.localUser.nickname = "[acidBurn]"
 
         assertTrue(client.isLocalUser(User("{acidBurn}", "libby", "root.localhost")))
         assertFalse(client.isLocalUser(User("acid-Burn", "libby", "root.localhost")))
     @Test
     fun `indicates if nickname is local user or not`() {
         val client = IrcClientImpl(normalConfig)
-        client.serverState.localNickname = "[acidBurn]"
+        client.localUser.nickname = "[acidBurn]"
 
         assertTrue(client.isLocalUser("{acidBurn}"))
         assertFalse(client.isLocalUser("acid-Burn"))
     @Test
     fun `uses current case mapping to check local user`() {
         val client = IrcClientImpl(normalConfig)
-        client.serverState.localNickname = "[acidBurn]"
+        client.localUser.nickname = "[acidBurn]"
         client.serverState.features[ServerFeature.ServerCaseMapping] = CaseMapping.Ascii
         assertFalse(client.isLocalUser(User("{acidBurn}", "libby", "root.localhost")))
     }
 
     @Test
-    @SuppressWarnings("deprecation")
+    @Deprecated("Tests deprecated method")
+    @RemoveIn("2.0.0")
     fun `sends text to socket`() = runBlocking {
         val client = IrcClientImpl(normalConfig)
         client.socketFactory = mockSocketFactory
     }
 
     @Test
+    @Deprecated("Tests deprecated method")
+    @RemoveIn("3.0.0")
     fun `defaults local nickname to profile`() {
         val client = IrcClientImpl(normalConfig)
         assertEquals(NICK, client.serverState.localNickname)
     }
 
+    @Test
+    fun `defaults local user to nickname in profile`() {
+        val client = IrcClientImpl(normalConfig)
+        assertEquals(User(NICK), client.localUser)
+    }
+
     @Test
     fun `defaults server name to host name`() {
         val client = IrcClientImpl(normalConfig)
     @Test
     fun `reset clears all state`() {
         with(IrcClientImpl(normalConfig)) {
-            userState += User("acidBurn")
+            userState += User("zeroCool")
             channelState += ChannelState("#thegibson") { CaseMapping.Rfc }
             serverState.serverName = "root.$HOST"
+            localUser.awayMessage = "Hacking the planet"
+
             reset()
 
-            assertEquals(0, userState.count())
+            assertEquals(1, userState.count())
             assertEquals(0, channelState.count())
             assertEquals(HOST, serverState.serverName)
+            assertEquals(User("AcidBurn"), localUser)
         }
     }
 

src/test/kotlin/com/dmdirc/ktirc/events/EventUtilsTest.kt

 internal class EventUtilsTest {
 
     private val fakeServerState = ServerState("", "")
+    private val fakeLocalUser = User("")
     private val ircClient = mockk<IrcClient> {
         every { serverState } returns fakeServerState
         every { caseMapping } returns CaseMapping.Ascii
+        every { localUser } returns fakeLocalUser
     }
 
     @BeforeEach
 
     @Test
     fun `reply sends response to user when message is private`() {
-        fakeServerState.localNickname = "zeroCool"
+        fakeLocalUser.nickname = "zeroCool"
         val message = MessageReceived(EventMetadata(TestConstants.time), User("acidBurn"), "Zerocool", "Hack the planet!")
 
         ircClient.reply(message, "OK")
 
     @Test
     fun `reply sends response with message ID to user when message is private`() {
-        fakeServerState.localNickname = "zeroCool"
+        fakeLocalUser.nickname = "zeroCool"
         val message = MessageReceived(EventMetadata(TestConstants.time, messageId = "abc123"), User("acidBurn"), "Zerocool", "Hack the planet!")
 
         ircClient.reply(message, "OK")
 
     @Test
     fun `react sends response to user when message is private`() {
-        fakeServerState.localNickname = "zeroCool"
+        fakeLocalUser.nickname = "zeroCool"
         val message = MessageReceived(EventMetadata(TestConstants.time, messageId = "msgId"), User("acidBurn"), "Zerocool", "Hack the planet!")
 
         ircClient.react(message, ":P")

src/test/kotlin/com/dmdirc/ktirc/events/handlers/UserStateHandlerTest.kt

 
     private val fakeServerState = ServerState("", "")
     private val fakeUserState = UserState { CaseMapping.Rfc }
+    private val fakeLocalUser = User("?")
 
     private val ircClient = mockk<IrcClient> {
         every { serverState } returns fakeServerState
         every { userState } returns fakeUserState
         every { isLocalUser(any<User>()) } answers { arg<User>(0).nickname == "zeroCool" }
         every { isLocalUser(any<String>()) } answers { arg<String>(0) == "zeroCool" }
+        every { localUser } returns fakeLocalUser
     }
 
     private val handler = UserStateHandler()
         assertEquals("Hacking the planet", fakeUserState["acidBurn"]?.details?.awayMessage)
     }
 
+    @Test
+    fun `updates local nickname on server welcome`() {
+        fakeUserState += User("AcidBurn")
+
+        handler.processEvent(ircClient, ServerWelcome(EventMetadata(TestConstants.time), "the.gibson", "acidBurn2"))
+
+        assertEquals("acidBurn2", fakeLocalUser.nickname)
+    }
+
 }

src/test/kotlin/com/dmdirc/ktirc/model/UserTest.kt

         assertEquals("Hacking the planet", user2.awayMessage)
     }
 
+    @Test
+    fun `resets all fields`() {
+        val user = User("acidBurn", "acidB", "root.localhost", "acidBurn", "Libby", "Hacking the planet!")
+        user.reset("burn")
+        assertEquals(User("burn"), user)
+    }
+
 }