Support IRCv3 away notifications

Issue #15

CHANGELOG

 vNEXT (in development)
 
+ * Away support:
+   * Added sendAway() method
+   * Added UserAway event and fanned-out ChannelAway
  * (Internal) improved the way byte buffers are used to
    reduce array copying and clean up code
 

docs/index.adoc

 Raised when a user changes the topic of a channel we are joined to. If
 the topic was cleared/removed, the `topic` parameter will be `null`.
 
+==== ChannelAway
+* Type: IrcEvent, TargetedEvent, SourcedEvent
+* Properties:
+** `user`: `User` - the user whose away state has changed
+** `target`: `String` - the channel that the user is in
+** `message`: `String?` - the away message, or `null` if the user is back
+
+After a <<UserAway>> event, KtIrc will "fan out" the event to all of the
+channels that we share with the user and raise a `ChannelAway`
+event for each channel. This is designed to make implementing certain features
+easier; if you fully handle a UserAway event there is no need to also
+handle the ChannelAway events, and vice-versa.
+
 === Channel/User events
 
 TODO
 
 TODO
 
+==== UserAway
+* Type: IrcEvent, SourcedEvent
+* Properties:
+** `user`: `User` - the user who has changed their away state
+** `message`: `String?` - the away message, or `null` if the user is back
+
+Raised when we are informed that a user has changed away states. If the server
+supports the `away-notify` capability we will receive notifications for all
+users in our common channels; otherwise, we will only receive notifications
+for our own user.
+
+If the user is away but we don't know the reason for it, the `message`
+property will be empty.
+
 ==== UserQuit
 
 TODO
 3+h| Capability negotiation
 
 | https://ircv3.net/specs/core/capability-negotiation.html[CAP]
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See <<Supported capabilities>> for the caps KtIrc will negotiate
 
 | https://ircv3.net/specs/core/capability-negotiation.html#cap-ls-version[CAP 302]
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See <<Supported capabilities>> for the caps KtIrc will negotiate
 
 | https://ircv3.net/specs/core/capability-negotiation.html#cap-notify[cap-notify]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 3+h| Published specifications
 
 | https://ircv3.net/specs/extensions/account-notify-3.1.html[account-notify] v3.1
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See <<UserAccountChanged>>
 
 | https://ircv3.net/specs/extensions/account-tag-3.2.html[account-tag] v3.2
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Accounts are automatically added to `User` properties in events
 
 | https://ircv3.net/specs/extensions/away-notify-3.1.html[away-notify] v3.1
-| {set:cellbgcolor:orange} Partial support
+| {set:cellbgcolor:#eeeeaa} Partial support
 | {set:cellbgcolor!}
-Negotiated but not yet exposed as an event
+See <<UserAway>>. State not yet tracked.
 
 | https://ircv3.net/specs/extensions/batch-3.2.html[batch] v3.2
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See <<BatchReceived>>
 
 | https://ircv3.net/specs/extensions/chghost-3.2.html[chghost] v3.2
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See <<UserHostChanged>>
 
 | https://ircv3.net/specs/extensions/echo-message-3.2.html[echo-message] v3.2
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See also the `alwaysEchoMessages` <<Behaviour>>
 
 | https://ircv3.net/specs/extensions/extended-join-3.1.html[extended-join] v3.1
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Additional details are automatically added to `User` properties in events
 
 | https://ircv3.net/specs/extensions/invite-notify-3.2.html[invite-notify] v3.2
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://ircv3.net/specs/extensions/message-tags.html[message-tags]
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Exposed in the metadata property of <<Events>>
 
 | https://ircv3.net/specs/core/monitor-3.2.html[monitor]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://ircv3.net/specs/extensions/multi-prefix-3.1.html[multi-prefix] v3.1
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Automatically included in <<ChannelState>>
 
 | https://ircv3.net/specs/extensions/sasl-3.1.html[SASL] v3.1
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 See <<SASL configuration>>
 
 | https://ircv3.net/specs/extensions/sasl-3.2.html[SASL] v3.2
-| {set:cellbgcolor:orange} Partial support
+| {set:cellbgcolor:#eeeeaa} Partial support
 | {set:cellbgcolor!}
 Notifications via `cap-notify` not yet supported. See <<SASL configuration>>
 
 | https://ircv3.net/specs/extensions/server-time-3.2.html[server-time] v3.2
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Exposed in the metadata property of <<Events>>
 
 | https://ircv3.net/specs/extensions/sts.html[sts]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://ircv3.net/specs/extensions/userhost-in-names-3.2.html[userhost-in-names] v3.2
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Automatically included in <<UserState>>
 
 | https://ircv3.net/specs/extensions/webirc.html[webirc]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 3+h| Draft specifications
 
 | https://github.com/ircv3/ircv3-specifications/pull/363[brb]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/308[channel renaming]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/349[chathistory]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/346[delivered]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/304[editmsg]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://ircv3.net/specs/extensions/labeled-response.html[labeled-response]
-| {set:cellbgcolor:green} Supported
+| {set:cellbgcolor:#a7eeaa} Supported
 | {set:cellbgcolor!}
 Exposed in the metadata property of <<Events>>
 
 | https://ircv3.net/specs/extensions/message-ids.html[message-ids]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/330[migrate]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://ircv3.net/specs/client-tags/react.html[react]
-| {set:cellbgcolor:orange} Partial support
+| {set:cellbgcolor:#eeeeaa} Partial support
 | {set:cellbgcolor!}
 Sending via <<React>> method, no events generated
 
 | https://github.com/ircv3/ircv3-specifications/pull/347[read]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/276[register]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://ircv3.net/specs/client-tags/reply.html[reply]
-| {set:cellbgcolor:orange} Partial support
+| {set:cellbgcolor:#eeeeaa} Partial support
 | {set:cellbgcolor!}
 Sending via <<Reply>> method, not processed on incoming messages
 
 | https://github.com/ircv3/ircv3-specifications/pull/306[resume]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/361[setname]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/357[standard replies]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
 | https://github.com/ircv3/ircv3-specifications/pull/348[typing]
-| {set:cellbgcolor:red} Not yet supported
+| {set:cellbgcolor:#f7d5d3} No support
 | {set:cellbgcolor!}
 
-3+^h|Vendor specifications
+3+h|Vendor specifications
 
 |===

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

     override val replacedUsers: Array<String>? = null
 }
 
+/**
+ * Raised when a user's away state changes, and they are in a common channel. If [message] is null then the user is
+ * now back.
+ *
+ * This event is only raised for other users if the server supports the 'away-notify' capability.
+ */
+class ChannelAway(metadata: EventMetadata, override val user: User, channel: String, val message: String?)
+    : TargetedEvent(metadata, channel), SourcedEvent
+
 /** Raised when a batch of the channel's member list has been received. More batches may follow. */
 class ChannelNamesReceived(metadata: EventMetadata, channel: String, val names: List<String>) : TargetedEvent(metadata, channel)
 
  */
 class UserAccountChanged(metadata: EventMetadata, override val user: User, val newAccount: String?) : IrcEvent(metadata), SourcedEvent
 
+/**
+ * Raised when a user's away state changes. If [message] is null then the user is now back.
+ *
+ * This event is only raised for other users if the server supports the 'away-notify' capability.
+ */
+class UserAway(metadata: EventMetadata, override val user: User, val message: String?) : IrcEvent(metadata), SourcedEvent
+
 /** Raised when available server capabilities are received. More batches may follow. */
 class ServerCapabilitiesReceived(metadata: EventMetadata, val capabilities: Map<String, String>) : IrcEvent(metadata)
 

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

     override fun mutateEvent(client: IrcClient, messageEmitter: MessageEmitter, event: IrcEvent) = sequence<IrcEvent> {
         yield(event)
         when (event) {
+            is UserAway -> handleAway(client, event)
             is UserQuit -> handleQuit(client, event)
             is UserNickChanged -> handleNickChanged(client, event)
         }
     }.toList()
 
+
     private suspend fun SequenceScope<IrcEvent>.handleQuit(client: IrcClient, event: UserQuit) {
         client.channelState.forEach {
             if (it.users.contains(event.user.nickname)) {
         }
     }
 
+    private suspend fun SequenceScope<IrcEvent>.handleAway(client: IrcClient, event: UserAway) {
+        client.channelState.forEach {
+            if (it.users.contains(event.user.nickname)) {
+                yield(ChannelAway(event.metadata, event.user, it.name, event.message))
+            }
+        }
+    }
+
     private suspend fun SequenceScope<IrcEvent>.handleNickChanged(client: IrcClient, event: UserNickChanged) {
         client.channelState.forEach {
             it.users[event.user.nickname]?.let { chanUser ->

src/main/kotlin/com/dmdirc/ktirc/messages/InternalMessageBuilders.kt

+package com.dmdirc.ktirc.messages
+
+import com.dmdirc.ktirc.IrcClient
+
+/** Sends a message to ask the server to list capabilities. */
+internal fun IrcClient.sendCapabilityList() = send("CAP", "LS", "302")
+
+/** Sends a message indicating the end of capability negotiation. */
+internal fun IrcClient.sendCapabilityEnd() = send("CAP", "END")
+
+/** Sends a message requesting the specified caps are enabled. */
+internal fun IrcClient.sendCapabilityRequest(capabilities: Collection<String>) =
+        send("CAP", "REQ", capabilities.joinToString(" "))
+
+/** Sends the connection password to the server. */
+internal fun IrcClient.sendPassword(password: String) = send("PASS", password)
+
+/** Sends a response to a PING event. */
+internal fun IrcClient.sendPong(nonce: ByteArray) = send("PONG", String(nonce))
+
+/** Sends a message to register a user with the server. */
+internal fun IrcClient.sendUser(userName: String, realName: String) = send("USER", userName, "0", "*", realName)
+
+/** Starts an authentication request. */
+internal fun IrcClient.sendAuthenticationMessage(data: String = "+") = send("AUTHENTICATE", data)

src/main/kotlin/com/dmdirc/ktirc/messages/MessageBuilders.kt

 import com.dmdirc.ktirc.IrcClient
 import com.dmdirc.ktirc.model.MessageTag
 
-/** Sends a message to ask the server to list capabilities. */
-internal fun IrcClient.sendCapabilityList() = send("CAP", "LS", "302")
-
-/** Sends a message indicating the end of capability negotiation. */
-internal fun IrcClient.sendCapabilityEnd() = send("CAP", "END")
-
-/** Sends a message requesting the specified caps are enabled. */
-internal fun IrcClient.sendCapabilityRequest(capabilities: Collection<String>) =
-        send("CAP", "REQ", capabilities.joinToString(" "))
-
 /** Sends a request to join the given channel. */
 fun IrcClient.sendJoin(channel: String) = send("JOIN", channel)
 
 /** Sends a request to change to the given nickname. */
 fun IrcClient.sendNickChange(nick: String) = send("NICK", nick)
 
-/** Sends the connection password to the server. */
-internal fun IrcClient.sendPassword(password: String) = send("PASS", password)
-
-/** Sends a response to a PING event. */
-internal fun IrcClient.sendPong(nonce: ByteArray) = send("PONG", String(nonce))
+/** Sends a request to set or unset our away state. */
+fun IrcClient.sendAway(reason: String? = null) =
+        // We need to pass emptyMap() in the second case to avoid using the deprecated send(String) method
+        // Once that's removed, the redundant map can be taken out.
+        reason?.let { send("AWAY", reason) } ?: send(emptyMap(), "AWAY")
 
 /** Sends a CTCP message of the specified [type] and with optional [data] to [target] (a user or a channel). */
 fun IrcClient.sendCtcp(target: String, type: String, data: String? = null) =
     send(inReplyTo?.let { tags + (MessageTag.Reply to inReplyTo) } ?: tags, "TAGMSG", target)
 }
 
-/** Sends a message to register a user with the server. */
-internal fun IrcClient.sendUser(userName: String, realName: String) = send("USER", userName, "0", "*", realName)
-
-/** Starts an authentication request. */
-internal fun IrcClient.sendAuthenticationMessage(data: String = "+") = send("AUTHENTICATE", data)
-
 /**
  * Utility method for creating a map of tags to avoid type inference problems.
  */

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

+package com.dmdirc.ktirc.messages.processors
+
+import com.dmdirc.ktirc.events.UserAway
+import com.dmdirc.ktirc.model.IrcMessage
+import com.dmdirc.ktirc.model.asUser
+
+internal class AwayProcessor : MessageProcessor {
+
+    override val commands = arrayOf("AWAY")
+
+    override fun process(message: IrcMessage) = sequence {
+        when (message.command) {
+            "AWAY" -> message.prefix?.let { yield(UserAway(message.metadata, it.asUser(), message.awayMessage)) }
+        }
+    }.toList()
+
+    private val IrcMessage.awayMessage: String?
+        get() = if (params.isEmpty()) null else String(params[0])
+
+}
+

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

 
 internal val messageProcessors = listOf(
         AccountProcessor(),
+        AwayProcessor(),
         AuthenticationProcessor(),
         BatchProcessor(),
         CapabilityProcessor(),

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

         assertTrue("#dumpsterdiving" in names)
     }
 
+    @Test
+    fun `raises ChannelAway event for each channel a user shares when away`() {
+        with (ChannelState("#thegibson") { CaseMapping.Rfc }) {
+            users += ChannelUser("ZeroCool")
+            fakeChannelStateMap += this
+        }
+
+        with (ChannelState("#dumpsterdiving") { CaseMapping.Rfc }) {
+            users += ChannelUser("ZeroCool")
+            fakeChannelStateMap += this
+        }
+
+        with (ChannelState("#chat") { CaseMapping.Rfc }) {
+            users += ChannelUser("AcidBurn")
+            fakeChannelStateMap += this
+        }
+
+        val quitEvent = UserAway(EventMetadata(TestConstants.time), User("zerocool", "dade", "root.localhost"), "Hack the planet!")
+        val events = mutator.mutateEvent(ircClient, messageEmitter, quitEvent)
+
+        val names = mutableListOf<String>()
+        assertEquals(3, events.size)
+        assertSame(quitEvent, events[0])
+        events.subList(1, events.size).forEach { event ->
+            (event as ChannelAway).let {
+                assertEquals(TestConstants.time, it.metadata.time)
+                assertEquals("zerocool", it.user.nickname)
+                assertEquals("Hack the planet!", it.message)
+                names.add(it.target)
+            }
+        }
+
+        assertTrue("#thegibson" in names)
+        assertTrue("#dumpsterdiving" in names)
+    }
+
     @Test
     fun `raises ChannelNickChanged event for each channel a user changes nicks in`() {
         with (ChannelState("#thegibson") { CaseMapping.Rfc }) {

src/test/kotlin/com/dmdirc/ktirc/messages/MessageBuildersTest.kt

         verify { mockClient.send("NICK", "AcidBurn") }
     }
 
+    @Test
+    fun `sendAway sends blank AWAY message with no args`() {
+        mockClient.sendAway()
+        verify { mockClient.send(emptyMap(), "AWAY") }
+    }
+
+    @Test
+    fun `sendAway sends AWAY message with reason`() {
+        mockClient.sendAway("Hacking the planet")
+        verify { mockClient.send("AWAY", "Hacking the planet") }
+    }
+
     @Test
     fun `sendPassword sends correct PASS message`() {
         mockClient.sendPassword("hacktheplanet")

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

+package com.dmdirc.ktirc.messages.processors
+
+import com.dmdirc.ktirc.TestConstants
+import com.dmdirc.ktirc.model.IrcMessage
+import com.dmdirc.ktirc.model.User
+import com.dmdirc.ktirc.params
+import com.dmdirc.ktirc.util.currentTimeProvider
+import org.junit.jupiter.api.Assertions
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertNull
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+
+internal class AwayProcessorTest {
+
+    @BeforeEach
+    fun setUp() {
+        currentTimeProvider = { TestConstants.time }
+    }
+
+    @Test
+    fun `raises away changed event with reason`() {
+        val events = AwayProcessor().process(
+                IrcMessage(emptyMap(), "acidburn!libby@root.localhost".toByteArray(), "AWAY", params("Hacking the planet")))
+        assertEquals(1, events.size)
+
+        val event = events[0]
+        assertEquals(TestConstants.time, event.metadata.time)
+        assertEquals(User("acidburn", "libby", "root.localhost"), event.user)
+        assertEquals("Hacking the planet", event.message)
+    }
+
+    @Test
+    fun `raises away changed event with no reason`() {
+        val events = AwayProcessor().process(
+                IrcMessage(emptyMap(), "acidburn!libby@root.localhost".toByteArray(), "AWAY", emptyList()))
+        assertEquals(1, events.size)
+
+        val event = events[0]
+        assertEquals(TestConstants.time, event.metadata.time)
+        assertEquals(User("acidburn", "libby", "root.localhost"), event.user)
+        assertNull(event.message)
+    }
+
+    @Test
+    fun `does nothing on away if prefix missing`() {
+        val events = AwayProcessor().process(IrcMessage(emptyMap(), null, "AWAY", params("*")))
+        Assertions.assertEquals(0, events.size)
+    }
+
+}