hanabi

Simple IRC server designed to build bridges.


Keywords
bridge, elixir, irc, server
License
MIT

Documentation

Hanabi

Hanabi is a (work in progress) IRC server designed to build bridges between services. I would like to keep this library as simple as possible, therefore it currently only implements [1] RFC1459.

Since Hanabi is an IRC server, messages and errors are designed to match the definitions of the IRC specification : see Hanabi.IRC.Message for message structures and Hanabi.IRC.Numeric for reply/error codes. Most of the interactions with this library are done via the Hanabi.User and Hanabi.Channel modules.

[1] : only the client<->server part, you can't connect other servers to hanabi.

Useful links

Configuration

In order to use this library, you must add hanabi to your list of depenencies in mix.exs :

def deps do
  [
    {:hanabi, "~> 0.1.2"}
  ]
end

You also have to add the following to your config/config.exs file :

config :hanabi, port: 6667,
                hostname: "my.awesome.hostname",
                motd: "/path/to/motd.txt"
                network_name: "Hanabi Demo",
                network_created_on: "on 2017-12-04 17:22"
                # server-wide password (PASS) if set
                # , password: "mypassword"

Examples

Here are a few basic example. Feel free to ask for more examples here !

Sending a private message to an user/channel

# Sending to an user
iex> receiver = Hanabi.User.get_by(:nick, "fnux")
%Hanabi.User{channels: ["#test"], hostname: 'localhost', key: #Port<0.5044>,
 nick: "fnux", pid: nil, port: #Port<0.5044>, realname: "realname", type: :irc,
 username: "fnux"}

iex> sender = Hanabi.User.get_by(:nick, "sender")
# ...

###
# Using the helper
iex> Hanabi.User.send_privmsg sender, receiver, "Hello fnux! How are you?"
:ok

###
# Manually
iex> msg = %Hanabi.IRC.Message{prefix: Hanabi.User.ident_for(sender),
command: "PRIVMSG", middle: receiver.nick, trailing: "Hello fnux! How are you?"}
# ...

iex> Hanabi.User.send receiver, msg
:ok
# Sending to a channel
iex> user = Hanabi.User.get_by(:nick, "fnux")
%Hanabi.User{channels: ["#test"], hostname: 'localhost', key: #Port<0.5044>,
 nick: "fnux", pid: nil, port: #Port<0.5044>, realname: "realname", type: :irc,
 username: "fnux"}

###
# Using the helper
iex> Hanabi.Channel.send_privmsg sender, "#test", "Hi there!"
:ok

###
# Manually
iex> msg = %Hanabi.IRC.Message{prefix: Hanabi.User.ident_for(sender),
command: "PRIVMSG", middle: "#test", trailing: "Hi there!"}
# ...

iex> Hanabi.Channel.broadcast "#test", msg
:ok

Simple handling of a virtual user

defmodule MyApp.IrcUser do
  alias Hanabi.User
  use GenServer

  @user %User{key: :default, type: :virtual, nick: "default",
  username: "default", realname: "Default User", hostname: "localhost"}

  def start_link() do
    GenServer.start_link(__MODULE__, nick)
  end

  def init(nick) do
    # register itself as the `default` user
    user = struct(@user, pid: self())
    {:ok, user.key} = User.add(user)
  end

  def handle_info(%Message{}=msg, state) do
    # msg is a message's struct as defined in Hanabi.IRC.Message :
    # %Hanabi.IRC.Message{prefix: "sender!~sender@localhost",
    # command: "PRIVMSG", middle: "default",
    # trailing: "Hi! How are you?"}
 
    # do stuff

    {:noreply, state}
  end

  # catch-all used for debugging
  def handle_info(msg, state) do
    IO.inspect msg

    {:noreply, state}
  end
end