KtIrc/docs/index.adoc

= KtIrc {version}
Chris Smith
:version: 0.11.0
:toc: left
:toc-position: left
:toclevels: 5

== About KtIrc

KtIrc is a Kotlin JVM library for connecting to and interacting with IRC servers.
It is still in an early stage of development. Its main features:

.Built for Kotlin
KtIrc is written in and designed for use in Kotlin; it uses extension methods,
DSLs, sealed classes, and so on, to make it much easier to use than an
equivalent Java library.

.Coroutine-powered
KtIrc uses co-routines for all of its input/output which lets it deal with
IRC messages in the background while your app does other things, without
the overhead of creating a new thread per IRC client.

.Modern IRC standards
KtIrc supports many IRCv3 features such as SASL authentication, message IDs,
server timestamps, replies, reactions, account tags, and more. These features
(where server support is available) make it easier to develop bots and
clients, and enhance IRC with new user-facing functionality.

== Getting started

=== Installing

All you need to do to start using KtIrc is add a single dependency.
KtIrc is published to JCenter, making it quick and easy to pull in
to almost any project. The examples below show how to add the JCenter
repository and then the KtIrc dependency; you may already be using
JCenter for other dependencies -- in that case just skip the
repository configuration!

[TIP]
====
KtIrc adheres to semantic versioning: you can expect to upgrade between
minor versions without problems (e.g. from `0.1.2` to `0.13.7`); major
version changes may include breaking changes such as the removal of
deprecated methods. You should check the changelog before updating to
a new major version.
====

.Gradle (using Kotlin DSL)
[source,kotlin,subs="attributes"]
----
repositories {
    jcenter()
}

dependencies {
    implementation("com.dmdirc:ktirc:{version}")
}
----

.Gradle (using Groovy DSL)
[source,groovy,subs="attributes"]
----
buildscript {
    repositories {
        jcenter()
    }
}

implementation 'com.dmdirc:ktirc:{version}'
----

.Maven
[source,xml,subs="attributes"]
----
<repositories>
    <repository>
      <id>jcenter</id>
      <url>https://jcenter.bintray.com</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.dmdirc</groupId>
        <artifactId>ktirc</artifactId>
        <version>{version}</version>
    </dependency>
</dependencies>
----

=== Creating your first client

KtIrc provides a DSL ("domain specific language") for configuring a
client that allows you to set the connection details, the user's
details, and configure the behaviour of KtIrc itself. The DSL is
accessed through the `IrcClient` function. For full details of all
supported options, see the <<IrcClient DSL>> reference.

A basic client will look like this:

[source,kotlin]
----
val client = IrcClient {
    server {
        host = "my.server.com"
    } 
    profile {
        nickname = "nick"
        username = "username"
        realName = "Hi there"
    }
}
----

=== Connecting and handling events

Getting KtIrc to start connecting is as simple as calling the `connect()`
method, but before that we probably want to add an event listener to deal
with incoming messages:

[source,kotlin]
----
client.onEvent { event -> <1>
    when (event) { <2>
        is ServerReady ->
            client.sendJoin("#ktirc") <3>
        is ServerDisconnected ->
            client.connect()
        is MessageReceived ->
            if (event.message == "!test") <4>
                client.reply(event, "Test successful!") <5>
    }
}

client.connect() <6>
----
<1> An event listener is registered using the `onEvent` method. It receives
    a single IrcEvent.
<2> A Kotlin `when` statement provides a convenient way to switch on the
    type of event received.
<3> Most common IRC commands have `send` methods defined to quickly and
    safely send the message with the right formatting.
<4> Kotlin smart-casts the event, so you can access the properties specific
    to the matched event class, such as `message`.
<5> The IrcClient class provides useful methods to react and respond to
    events.
<6> The connect() method starts connecting and returns immediately. You'll
    receive events updating you on the progress.

In this example, we're waiting for three events: `ServerReady`, which occurs
after we have connected and the server has sent us all of the pre-amble
such as its configuration and capabilities; `ServerDisconnected` which
is raised whenever KtIrc gets disconnected from (or fails to connect to) the
IRC server; and `MessageReceived` which occurs, unsuprisingly, whenever a
message is received. KtIrc has many events: for more information, see the
<<Events>> reference.

[CAUTION]
====
With this code, KtIrc will immediately try to reconnect as soon as it is
disconnected. If the server closes the connection early (due to, for
example, a bad password or the user being banned) this will result in a
huge number of connection attempts in a short time. In real code you should
always delay reconnections -- preferably with a backoff -- to avoid
excessive connection attempts.
====

You can see that KtIrc provides a number of useful methods for sending
requests to the server, and reacting and responding to events. IRC
commands that KtIrc supports can be invoked using the `send*` methods,
which are documented in the <<Messages>> reference. Other useful methods
such as `reply` can be found in the <<Utility methods>> reference.

== IrcClient DSL

The DSL for creating a new `IrcClient` allows you to set a number of
options relating to how KtIrc connects, what user details it provides,
and how it behaves. The full range of options available in the DSL is
shown below:

[source,kotlin]
----
server {
    host = "irc.example.com"
    port = 6667
    useTls = true
    password = "H4ckTh3Pl4n3t"
}

profile {
    nickname = "MyBot"
    username = "bot"
    realName = "Botomatic v1.2"
}

behaviour {
    requestModesOnJoin = true
    alwaysEchoMessages = true
}

sasl {
    mechanisms += "PLAIN"
    username = "botaccount"
    password = "s3cur3"
}
----

=== Server settings

The server block allows you to specify the details of the IRC server you
wish to connect to:

 * `host` - the hostname or IP address of the server *(required)*
 * `port` - the port to connect on _(default: 6667)_
 * `useTls` - whether to use a secure connection or not _(default: false)_
 * `password` - the password to provide to the server _(default: null)_

An alternative more compact syntax is available for configuring server details:

[source,kotlin]
----
server("irc.example.com", 6667, true, "H4ckTh3Pl4n3t")
----

You can, if you wish, combine the two or use named parameters:

[source,kotlin]
----
server(useTls = true, port = 6697) {
    host = "irc.example.com"
    password = "H4ckTh3Pl4n3t"
}
----

=== User profile

The user profile controls how KtIrc will present itself to the IRC server, and
how other users on that server will see the KtIrc user:

 * `nickname` - the initial nickname you wish to use *(required)*
 * `username` - the "username" to provide to the server _(default: KtIrc)_
 * `realName` - the "real name" that will be seen by other clients
   _(default: KtIrc User)_

[TIP]
====
The "username" is sometimes called the "ident" or "gecos". Some IRC servers
will check for an ident reply from your host and use that in place of the
username provided if it gets a response. The username (or ident reply)
becomes part of your client's hostmask, and is visible to other users. It
is unrelated to nickserv or other account usernames.
====

As with the <<Server settings>> you can use a more compact syntax:

[source,kotlin]
----
profile("nickname", "username", "real name")
----

=== Behaviour

The behaviour block allows you to tweak how KtIrc itself operates. These
options allow you perform common operations automatically, or enjoy more
advanced IRC features even if the server doesn't support them:

 * `requestModesOnJoin` - if enabled, automatically requests channel modes
   when the client joins a new channel _(default: false)_
 * `alwaysEchoMessages` - if enabled, every message you send will result
   in a `MessageReceived` event being returned. Servers that support the
   IRCv3 `echo-message` capability will do this automatically; enabling the
   behaviour will make all servers act the same way _(default: false)_

The behaviour block is optional in its entirety.

=== SASL configuration

SASL ("Simple Authentication and Security Layer") is a standard mechanism
for securely authenticating to a service that has recently been adopted
for use in IRC. SASL supports a number of 'mechanisms' that describe how
the data will be exchanged between the client and server. KtIrc supports
the following mechanisms:

 * `EXTERNAL` - the server uses some external means to authenticate the
   client, instead of a username and password. On most servers this
   means checking the client certificate against one registered with
   the user's account. _(disabled by default)_
 * `PLAIN` - the client sends the username and password in plain text
   during the connection phase. This offers slightly more security
   than calling `nickserv identify` (for example) after connecting.
 * `SCRAM-SHA-1` - this mechanism involves a "salted challenge" being
   completed which results in both the server and the client proving that
   they know the user's password, but without it every being transmitted.
   This is based on the `SHA-1` algorithm which has known issues, but is
   more than sufficient when used in this manner.
 * `SCRAM-SHA-256` - the same as `SCRAM-SHA-1` but using the `SHA-256`
   algorithm instead, which is more modern and secure.

To use `PLAIN`, `SCRAM-SHA-1` or `SCRAM-SHA-256`, you must supply a username
and password in the configuration:

[source,kotlin]
----
sasl {
    username = "botaccount"
    password = "s3cur3"
}
----

KtIrc enables `SCRAM-SHA-256`, `SCRAM-SHA-1` and `PLAIN` by default, and will
use them in that order of preference if the server supports more than one.
You can modify the `mechanisms` parameter if you wish to disable one:


[source,kotlin]
----
sasl {
    mechanisms -= "PLAIN"
    username = "botaccount"
    password = "s3cur3"
}
----

You can also clear all the default mechanisms and provide your own list:

[source,kotlin]
----
sasl {
    mechanisms("SCRAM-SHA-256", "PLAIN")
    username = "botaccount"
    password = "s3cur3"
}
----


If you wish to enable the `EXTERNAL` mechanism, you do not need to provide
a username or password:

[source,kotlin]
----
sasl {
    mechanisms("EXTERNAL")
}
----

Alternatively, if you wish to enable `EXTERNAL` but fall back to other
mechanisms if it doesn't work:

[source,kotlin]
----
sasl {
    mechanisms += "EXTERNAL"
    username = "botaccount"
    password = "s3cur3"
}
----

The SASL block is optional in its entirety.

== State

KtIrc attempts to track all reasonable state of the IRC network. This includes
details about the server, channels the client is joined to, and users that are
also in those channels. The state is exposed in a several fields accessible
from the `IrcClient`:

=== ServerState

The server state provides information about the server, and our connection to
it.

[IMPORTANT]
====
The server state will be updated frequently while KtIrc is connecting to a
server. The values within it should not be relied upon until a `ServerReady`
event is received, as they may be incomplete or estimates before then.
====

.serverState.status (ServerStatus)
Provides an enum containing the current server state. One of:

* `Disconnected` - the server is not connected
* `Connecting` - we are attempting to establish a connection
* `Negotiating` - we are logging in, negotiating capabilities, etc
* `Ready` - we are connected and commands may be sent

.serverState.localNickname (String)
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.

.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
value provided by the server. For example, you may connect to
`irc.example.com` and during the negotiation phase KtIrc will see that it
is actually talking to `server3.uk.irc.example.com` and update the
serverName to reflect that.

[TIP]
====
For a user-friendly identifier most servers provide a `NETWORK` token in
the ISUPPORT reply, which is available via the <<Features>> property.
====

.serverState.channelModePrefix (ModePrefixMapping)
Provides a mapping from channel user modes (such as "o" for op, "v" for
voice) to the prefixes used before nicknames (such as "@" and "+").

To map prefixes to modes, you can use the `getMode()` or `getModes()`
functions:

[source,kotlin]
----
getMode('@') == 'o'
getModes("@+") == "ov"
----

.serverState.channelTypes (String)
Contains the types of channels that are allowed by the server, such as
`\#&amp;` for normal channels ("#") and local channels ("&").

==== Capabilities

The IRCv3 specifications introduce the concept of 'capability negotiation'.
This allows the client and server to negotiate and enable new capabilities
that are mutually supported.

The capabilities state contains the following properties:

.serverState.capabilities.negotiationState (CapabilitiesNegotiationState)
The current state of negotiating with the server. One of:

* `AWAITING_LIST` - we have requested a list of capabitilies and are awaiting
  a reply
* `AWAITING_ACK` - we have sent the capabilities we want to enable, and are
  waitin for the server to acknowledge them
* `AUTHENTICATING` - we are attempting to authenticate with SASL
* `FINISHED` - we have completed negotiation

Where a server does not support IRCv3 capability negotiation, the state will
remain at `AWAITING_LIST`.

.serverState.capabilities.advertisedCapabilities (Map<String, String>)
Contains a map of capability names to values that the server offered. This
should only be required for advance use cases, such as looking up the 
languages offered by a server when providing the user with a choice of
translations.

.serverState.capabilities.enabledCapabilities (Map<Capability, String>)
Contains a map of capabilities that KtIrc has successfully negotiated with
the server.

===== Supported capabilities

* `sasl` - used to perform SASL authentication during connection
* `message-tags` - allows arbitrary tags on messages
* `server-time` - the server adds a timestamp tag to each incoming message
* `account-tag` - the server adds an account tag to incoming user messages
* `userhost-in-names` - the NAMES reply includes users hosts not just nicknames
* `multi-prefix` - all modes are included in nick prefixes (e.g. `@+nick`)
* `extended-join` - more information is sent when a user joins a channel
* `batch` - allows multi-line responses to be batched together
* `echo-message` - echos the client's own messages back to it
* `draft/labeled-responses` - responses are labeled so the client knows which
  incoming message corresponds to which command it sent
* `account-notify` - the server sends a message when a user's account changes
* `away-notify` - the server sends a message when a user's away state changes
* `chghost` - the server sends a message when a user's host changes

==== Features

Features are KtIrc's way of exposing the information the server declares in
its ISUPPORT messages. These describe how the server is configured, and what
limits are placed on clients. You access features using the `features` map
in the server state:

[source,kotlin]
----
ircClient.serverState.features[ServerFeature.Network]
----

The following features are available:

* `Network` - the name of the network the server belongs to __(String?)__
* `ServerCaseMapping` - the current case mapping of the server __(CaseMapping!)__
* `Modeprefixes` - the user mode prefix mapping (e.g. ov to @+) __(ModePrefixMapping!)__
* `MaximumChannels` - the maximum number of channels a user can join __(Int?)__
* `ChannelModes` - the modes supported in channels __(Array<String>?)__
* `ChannelTypes` - the types of channel supported (e.g. "#&") __(String!)__
* `MaximumChannelNameLength` - how long channel names may be __(Int!)__
* `WhoxSupport` - whether the server supports extended whos ("WHOX") __(Boolean!)__

[NOTE]
====
If the server does not define a feature, KtIrc will either fall back to a
default value based on the IRC RFCs or common practice (for those features
identified with a non-null type such as `Int!` or `String!`); otherwise
the value of the feature will be `null` (such as for those identified as
`Int?` or `String?` types).
====

=== UserState

The client's UserState object tracks the details of all users in common
channels. It can be used to find the most up-to-date and comprehensive
information for those users, as well as the set of channels that we share
with them.

The UserState is accessed via the `userState` property of IrcClient and
acts as a map, accessible using either a nickname or a `User` object:

[source,kotlin]
----
ircClient.userState["acidBurn"]

val user: User = myIrcEvent.user
ircClient.userState[user]
----

The UserState returns a `KnownUser` object which exposes a `details`
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:

[source,kotlin]
----
ircClient.userState["acidBurn"]?.let { knownUser -> <1>
    val accountName = knownUser.account
    val inChannel = "#channel" in knownUser <2>
    val allChannels = knownUser.channels <3>
}
----
<1> If the user isn't known, the call to `get` (using the `[]` operator)
    returns null, so we use a `let` statement to deal only with the case
    that the user is found.
<2> Check if the user is present on the common channel `#channel`. If
    the KtIrc client is not joined to that channel, it will always return
    false. You can also use the `contains("#channel")` method instead of
    the `in` operator.
<3> Returns all common channels we share with the user; will never
    include channels that the KtIrc client is not joined to.

=== ChannelState

The ChannelState keeps track of the state for all channels that the client
is joined to. It is indexed by channel name:

[source,kotlin]
----
ircClient.channelState["#ktirc"]
----

Each channel's state contains the following properties:

* `receivingUserList` - boolean value indicating whether we are in the process
  of receiving the list of users for the channel. If we are, the `users`
  property will be incomplete.
* `modesDiscovered` - boolean value indicating whether we have received the
  full set of modes set on the channel. The `requestModesOnJoin` <<Behaviour>>
  allows you to make KtIrc request these automatically.
* `topic` - a ChannelTopic object representing the current channel topic.
  If no topic is set, then a ChannelTopic with `null` properties will be
  provided.
* `users` - a map of all known users in the channel, see <<Channel users>>
  for more information
* `modes` - A map of the current channel modes and their values. Only
  complete if `modesDiscovered` is true.

==== Channel users

Channel users are accessed using the `users` property, which provides an
iterable map of nickname to `ChannelUser`. Each `ChannelUser` contains
the nickname and current modes for that user. To get further details about
a user, such as their hostmask or real name, you should query the <<UserState>>
with the given nickname.

[source,kotlin]
----
ircClient.channelState["#ktirc"]?.users?.forEach { user ->
    println("${user.nickname} has modes ${user.modes}")
}
----

== Events

Incoming lines from the IRC server are covered by KtIrc to subclasses of
`IrcEvent`. These, along with other more advance events, are then published
to users of the client using the `onEvent` method in `IrcClient`.

All events extend `IrcEvent`, which offers a single `metadata` property.
This contains details related to the event:

* `time` - the time at which the message occurred (if the server supports
  the `server-time` capability), or the time at which we received it.
  Always present.
* `batchId` - an opaque string identifier for the batch the message is
  part of (if the server supports the `batch` capability). Null for
  messages not in a batch.
* `messageId` - a unique, opaque string identifier for the message if
  the server supports the `msgid` tag. Null otherwise.
* `label` - a unique, opaque string identifier that ties a message to
  a labelled command that was sent by KtIrc, if the server supports
  the `labelled-replies` capability. Null otherwise.

Several specialised versions of `IrcEvent` are used which allow for easier
processing:

.TargetedEvent

A `TargetedEvent` is one that is targeted at either a user or a channel.
`TargetedEvent` exposes a string `target` property that identifies the
target of the message. This allows you to direct messages to the right
handler or UI component more easily:

[source,kotlin]
----
ircClient.onEvent { event ->
    when (event) {
        is TargetedEvent -> dispatchEvent(event.target, event)
    }
}
----

.SourcedEvent

A large number of events come from a remote IRC user, and it can be
useful to handle these in the same way. KtIrc offers a `SourcedEvent`
interface for all events that originate from a user, and it exposes
a single `user` property:

[source,kotlin]
----
ircClient.onEvent { event ->
    when (event) {
        is SourcedEvent -> notifyAboutUserActivity(event.user)
    }
}
----

.ChannelMembershipAdjustment

A number of events describe how the membership of a channel changes --
namely, joins, parts, quits, kicks, names replies, and nick changes.
All of these events implement the `ChannelMembershipAdjustment` interface
which reduces the amount of logic you need to do if you wish to maintain
a membership list (for example in a UI). The interface exposes three
properties:

* `addedUser` - a single nickname to be added _(String)_
* `removedUser` - a single nickname to be removed _(String)_
* `replacedUsers` - a list of nicknames to replace any existing ones with
  _(Array<String>)_

All the properties are nullable, and most events will only populate
one of the three.

=== Server events

==== ServerConnecting
* Type: IrcEvent
* Properties: _(none)_

This event is raised by KtIrc as soon as it starts attempting to connect to
a server. It will be followed by either a <<ServerConnected>> or a
<<ServerConnectionError>> event at some point.

==== ServerConnected
* Type: IrcEvent
* Properties: _(none)_

This event is raised by KtIrc when it has connected to the server, and is
starting the process of registering, negotiating capabilities, etc.
The server will *not* yet be ready for use - a <<ServerReady>> event will
follow once all of the initial setup has completed.

==== ServerConnectionError
* Type: IrcEvent
* Properties:
** `error`: `ConnectionError` - the type of error that occurred
** `details`: `String?` - information about the error, if available

This event is raised by KtIrc when a problem occurred while connecting
to the server. The `ConnectionError` enum will provide the cause of
the error, if known:

* `UnresolvableAddress` - the hostname provided could not be resolved
  to an IP address
* `ConnectionRefused` - the server did not answer a connection request
  on the given port
* `BadTlsCertificate` - there was an issue with the TLS certificate the
  server presented (e.g. it was out of date, for the wrong domain, etc)
* `Unknown` - the exact cause of the error isn't known

This event will be followed by a <<ServerDisconnected>> event.

==== ServerWelcome
* Type: IrcEvent
* Properties:
** `server`: `String` - the name the server supplied for itself
** `localNick`: `String` - the nickname the server says we are using

This event is raised in response to the server sending a 001 WELCOME
message. It contains the name that the server supplied for itself
(for example, KtIrc may connect to a round-robin address like
`irc.example.com` and the server it actually connects to then
identifies itself as `node3.uk.irc.example.com`), and the nickname
that the server says we are using.

==== ServerFeaturesUpdated
* Type: IrcEvent
* Properties:
** `serverFeatures`: `ServerFeatureMap` - the features supplied by the server

Corresponds to the server sending a single 005 ISUPPORT line. Multiple
events of this type may be raised in quick succession when features are
split over multiple lines.

In general, you should wait for a <<ServerReady>> event and then query the
<<Features>> instead of relying on this event.

==== ServerReady
* Type: IrcEvent
* Properties: _(none)_

This event is raised by KtIrc when it has connected to a server,
registered with the IRC network, and received all of the server's
initial data describing its configurations and its features.

At this point it is safe to start issuing commands, checking
state, joining channels, etc.

==== PingReceived
* Type: IrcEvent
* Properties:
** `nonce`: `ByteArray` - the unique data that must be included in the reply

Raised when the IRC server sends a PING message to the client. KtIrc will
automatically reply with an appropriate PONG.

==== ServerCapabilitiesReceived

TODO

==== ServerCapabilitiesAcknowledged

TODO

==== ServerCapabilitiesFinished

TODO

==== MotdLineReceived

TODO

==== MotdFinished

TODO

=== Channel events

==== ChannelJoined

TODO

==== ChannelJoinFailed

TODO

==== ChannelParted

TODO

==== ChannelUserKicked

TODO

==== ChannelQuit

TODO

==== ChannelNickChanged

TODO

==== ChannelNamesReceived

TODO

==== ChannelNamesFinished

TODO

==== ChannelTopicDiscovered

TODO

==== ChannelTopicMetadataDiscovered

TODO

==== ChannelTopicChanged

TODO


=== Channel/User events

TODO

==== MessageReceived

TODO

==== NoticeReceived

TODO

==== ActionReceived

TODO

==== CtcpReceived

TODO

==== CtcpReplyReceived

TODO

==== UserQuit

TODO

==== UserNickChanged

TODO

==== UserHostChanged

TODO

==== UserAccountChanged

TODO

==== ModeChanged

TODO


=== Other events

==== AuthenticationMessage

TODO

==== SaslFinished

TODO

==== SaslMechanismNotAvailableError

TODO

==== BatchStarted

TODO

==== BatchFinished

TODO

==== BatchReceived

TODO

==== NicknameChangeFailed

TODO

== Messages

TODO

== Utility methods

TODO

== IRCv3 support

TODO