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.

== 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 ->
    val accountName = knownUser.account
    val inChannel = "#channel" in knownUser
    val allChannels = knownUser.channels
}
----

==== 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

TODO

=== Messages

TODO

=== Utility methods

TODO

=== IRCv3 support

TODO