irckit

README

go-irckit

Minimal IRC server (and maybe client) toolkit in Go.

Built to experiment with the IRC protocol, mostly implementing the RFCs from scratch so don't expect it to be super-robust or correct. Aimed to be a good foundation for bootstrapping quick proof-of-concepts on the IRC protocol.

Status: v0.0 (no stability guarantee); if you're using this, please open an issue with your API requirements.

Check the project's upcoming milestones to get a feel for what's prioritized.

Details

• Parsing and encoding is done by https://github.com/sorcix/irc
• Server implementation references: rfc1459, rfc2812, rfc2813. More modernly, ircv3.net.

License

MIT

Documentation

Index

• Variables
• func CmdIson(s Server, u *User, msg *irc.Message) error
• func CmdJoin(s Server, u *User, msg *irc.Message) error
• func CmdMotd(s Server, u *User, _ *irc.Message) error
• func CmdNames(s Server, u *User, msg *irc.Message) error
• func CmdNick(s Server, u *User, msg *irc.Message) error
• func CmdPart(s Server, u *User, msg *irc.Message) error
• func CmdPing(s Server, u *User, msg *irc.Message) error
• func CmdPrivMsg(s Server, u *User, msg *irc.Message) error
• func CmdQuit(s Server, u *User, msg *irc.Message) error
• func CmdWho(s Server, u *User, msg *irc.Message) error
• func ID(s string) string
• func SetLogger(l log.Logger)
• type Channel
  • func NewChannel(server Server, name string) Channel
• type Commands
  • func DefaultCommands() Commands
• type Conn
• type Event
• type EventKind
  • func (i EventKind) String() string
• type Handler
• type Prefixer
• type Publisher
  • func SyncPublisher() Publisher
• type Server
  • func NewServer(name string) Server
• type ServerConfig
  • func (c ServerConfig) Server() Server
• type User
  • func NewUser(c Conn) *User
  • func NewUserNet(c net.Conn) *User
  • func (u *User) Channels() []Channel
  • func (u *User) Close() error
  • func (user *User) Decode() (*irc.Message, error)
  • func (user *User) Encode(msgs ...*irc.Message) (err error)
  • func (u *User) ID() string
  • func (u *User) NumChannels() int
  • func (u *User) Prefix() *irc.Prefix
  • func (u *User) String() string
  • func (u *User) VisibleTo() []*User

Variables

var ErrHandshakeFailed = errors.New("handshake failed")

var ErrUnknownCommand = errors.New("unknown command")

The error returned when an invalid command is issued.

Functions

func CmdIson

func CmdIson(s Server, u *User, msg *irc.Message) error

CmdIson is a handler for the /ISON command.

func CmdJoin

func CmdJoin(s Server, u *User, msg *irc.Message) error

CmdJoin is a handler for the /JOIN command.

func CmdMotd

func CmdMotd(s Server, u *User, _ *irc.Message) error

CmdMotd is a handler for the /MOTD command.

func CmdNames

func CmdNames(s Server, u *User, msg *irc.Message) error

CmdNames is a handler for the /NAMES command.

func CmdNick

func CmdNick(s Server, u *User, msg *irc.Message) error

CmdNick is a handler for the /NICK command.

func CmdPart

func CmdPart(s Server, u *User, msg *irc.Message) error

CmdPart is a handler for the /PART command.

func CmdPing

func CmdPing(s Server, u *User, msg *irc.Message) error

CmdPing is a handler for the /PING command.

func CmdPrivMsg

func CmdPrivMsg(s Server, u *User, msg *irc.Message) error

CmdPrivMsg is a handler for the /PRIVMSG command.

func CmdQuit

func CmdQuit(s Server, u *User, msg *irc.Message) error

CmdQuit is a handler for the /QUIT command.

func CmdWho

func CmdWho(s Server, u *User, msg *irc.Message) error

CmdWho is a handler for the /WHO command.

func ID

func ID(s string) string

ID will normalize a name to be used as a unique identifier for comparison.

func SetLogger

func SetLogger(l log.Logger)

Types

type Channel

type Channel interface {
	Prefixer
	Publisher

	// ID is a normalized unique identifier for the channel
	ID() string

	// Created returns the time when the Channel was created.
	Created() time.Time

	// Names returns a sorted slice of Nicks in the channel
	Names() []string

	// Users returns a slice of Users in the channel.
	Users() []*User

	// HasUser returns whether a User is in the channel.
	HasUser(*User) bool

	// Invite prompts the User to join the Channel on behalf of Prefixer.
	Invite(from Prefixer, u *User) error

	// Join introduces the User to the channel (handler for JOIN).
	Join(u *User) error

	// Part removes the User from the channel (handler for PART).
	Part(u *User, text string)

	// Message transmits a message from a User to the channel (handler for PRIVMSG).
	Message(u *User, text string)

	// Topic sets the topic of the channel (handler for TOPIC).
	Topic(from Prefixer, text string)

	// Unlink will disassociate the Channel from its Server.
	Unlink()

	// Len returns the number of Users in the channel.
	Len() int

	// String returns the name of the channel
	String() string
}

Channel is a representation of a room in our server

func NewChannel

func NewChannel(server Server, name string) Channel

NewChannel returns a Channel implementation for a given Server.

type Commands

type Commands interface {
	Add(Handler)
	Run(Server, *User, *irc.Message) error
}

func DefaultCommands

func DefaultCommands() Commands

type Conn

type Conn interface {
	Close() error
	Encode(*irc.Message) error
	Decode() (*irc.Message, error)

	// ResolveHost returns the resolved host of the RemoteAddr
	ResolveHost() string
}

Conn abstracts the encoding/decoding and sending/receiving when speaking IRC.

type Event

type Event interface {
	// String returns a user-friendly presentation of the event.
	String() string
	// Kind is the event kind.
	Kind() EventKind
	// Server associated with the event (or nil).
	Server() Server
	// Channel associated with the event (or nil).
	Channel() Channel
	// User associated with the event (or nil).
	User() *User
	// Message returns the original irc.Message that triggered the event (or nil).
	Message() *irc.Message
}

Event is emitted by a Publisher.

type EventKind

type EventKind int

const (

	// ConnectEvent is emitted when a User successfully connects and handshakes with a Server.
	ConnectEvent EventKind
	// QuitEvent is emitted when a User is disconnected from a Server.
	QuitEvent
	// JoinEvent is emitted when a User joins a Channel.
	JoinEvent
	// PartEvent is emitted when a User leaves a Channel.
	PartEvent
	// UserMsgEvent is emitted when a User sends a message to another User.
	UserMsgEvent
	// ChanMsgEvent is emitted when a User sends a message to a Channel.
	ChanMsgEvent
	// EmptyChanEvent is emitted when the last User leaves a Channel.
	EmptyChanEvent
	// NewChanEvent is emitted when a new Channel is created.
	NewChanEvent
	// ShutdownEvent is emitted when the server shuts down.
	ShutdownEvent
)

func (EventKind) String

func (i EventKind) String() string

type Handler

type Handler struct {
	// Command is the IRC command that Call handles.
	Command string
	// Handler is a function that takes the server, user who sent the message, and a message to perform some command.
	Call func(s Server, u *User, msg *irc.Message) error
	// MinParams is the minimum number of params required on the message.
	MinParams int
}

Handler is a container for an irc.Message handler.

type Prefixer

type Prefixer interface {
	// Prefix returns a prefix configuration for the origin of the message.
	Prefix() *irc.Prefix
}

type Publisher

type Publisher interface {
	// Subscribe registers channel to receive events. Will skip events if channel is full.
	Subscribe(chan<- Event)

	// Publish emits the Event to all the subscribers.
	Publish(Event)

	// Close will close all the subscribing channels.
	Close() error
}

Publisher emits Events to existing subscribers.

func SyncPublisher

func SyncPublisher() Publisher

SyncPublisher creates a Publisher which blocks on all operations.

type Server

type Server interface {
	Prefixer
	Publisher

	// Name of the server (usually hostname).
	Name() string

	// Motd is the Message of the Day for the server.
	Motd() []string

	// Connect starts the handshake for a new user, blocks until it's completed or failed with an error.
	Connect(*User) error

	// Quit removes the user from all the channels and disconnects.
	Quit(*User, string)

	// HasUser returns an existing User with a given Nick.
	HasUser(string) (*User, bool)

	// RenameUser changes the Nick of a User if the new name is available.
	// Returns whether the rename was was successful.
	RenameUser(*User, string) bool

	// Channel gets or creates a new channel with the given name.
	Channel(string) Channel

	// HasChannel returns an existing Channel with a given name.
	HasChannel(string) (Channel, bool)

	// UnlinkChannel removes the channel from the server's storage if it
	// exists. Once removed, the server is free to create a fresh channel with
	// the same ID. The server is not responsible for evicting members of an
	// unlinked channel.
	UnlinkChannel(Channel)
}

func NewServer

func NewServer(name string) Server

NewServer creates a server.

type ServerConfig

type ServerConfig struct {
	// Name is used as the prefix for the server.
	Name string
	// Version string of the server (default: go-irckit).
	Version string
	// Motd is the message of the day for the server, list of message lines where each line should be max 80 chars.
	Motd []string
	// InviteOnly prevents regular users from joining and making new channels.
	InviteOnly bool
	// MaxNickLen is the maximum length for a NICK value (default: 32)
	MaxNickLen int

	// Publisher to use. If nil, a new SyncPublisher will be used.
	Publisher Publisher
	// DiscardEmpty setting will start a goroutine to discard empty channels.
	DiscardEmpty bool
	// NewChannel overrides the constructor for a new Channel in a given Server and Name.
	NewChannel func(s Server, name string) Channel
	// Commands is the handler registry to use (default: DefaultCommands())
	Commands Commands
}

ServerConfig produces a Server setup with configuration options.

func (ServerConfig) Server

func (c ServerConfig) Server() Server

type User

type User struct {
	Conn

	sync.RWMutex
	Nick string // From NICK command
	User string // From USER command
	Real string // From USER command
	Host string
	// contains filtered or unexported fields
}

func NewUser

func NewUser(c Conn) *User

NewUser creates a *User, wrapping a connection with metadata we need for our server.

func NewUserNet

func NewUserNet(c net.Conn) *User

NewUserNet creates a *User from a net.Conn connection.

func (*User) Channels

func (u *User) Channels() []Channel

func (*User) Close

func (u *User) Close() error

func (*User) Decode

func (user *User) Decode() (*irc.Message, error)

Decode will receive and return a decoded message, or an error.

func (*User) Encode

func (user *User) Encode(msgs ...*irc.Message) (err error)

Encode and send each msg until an error occurs, then returns.

func (*User) ID

func (u *User) ID() string

func (*User) NumChannels

func (u *User) NumChannels() int

func (*User) Prefix

func (u *User) Prefix() *irc.Prefix

func (*User) String

func (u *User) String() string

func (*User) VisibleTo

func (u *User) VisibleTo() []*User