= 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 <> 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 <> 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 <> reference. Other useful methods such as `reply` can be found in the <> 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 <> 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 <>, 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 <>, 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 <> 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 `\#&` 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) 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) 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?)__ * `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` <> 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 <> 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 <> 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)_ 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 <> or a <> 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 <> 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 <> 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 <> event and then query the <> 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