pipes-irc-server/notes.md

Pipes Notes
===========

A set of monad transformers for streaming: Producers, Consumers,
Pipes, ListT

They provide two primitive actions:
* `await`
* `yield`

Producers `yield`, Consumers `await`

Pipes both `yield` and `await`

Effects neither `yield` nor `await`

Connectors:
* `for` handles `yield`
* `>~` handles `await`
* `>->` handles `yield` and `await`
* `>>=` (regular monad bind) handles return values

As connectors are applied to Producers, Consumers, and Pipes; the
return type changes until it becomes Effect, at which point all inputs
and outputs are handled and the resulting monad can be executed.



IRC Notes
=========

ABNF from rfc2812:
------------------

    message    =  [ ":" prefix SPACE ] command [ params ] crlf
    prefix     =  servername / ( nickname [ [ "!" user ] "@" host ] )
    command    =  1*letter / 3digit
    params     =  *14( SPACE middle ) [ SPACE ":" trailing ]
               =/ 14( SPACE middle ) [ SPACE [ ":" ] trailing ]

    nospcrlfcl =  %x01-09 / %x0B-0C / %x0E-1F / %x21-39 / %x3B-FF
                    ; any octet except NUL, CR, LF, " " and ":"
    middle     =  nospcrlfcl *( ":" / nospcrlfcl )
    trailing   =  *( ":" / " " / nospcrlfcl )

    SPACE      =  %x20        ; space character
    crlf       =  %x0D %x0A   ; "carriage return" "linefeed"

    target     =  nickname / server
    msgtarget  =  msgto *( "," msgto )
    msgto      =  channel / ( user [ "%" host ] "@" servername )
    msgto      =/ ( user "%" host ) / targetmask
    msgto      =/ nickname / ( nickname "!" user "@" host )
    channel    =  ( "#" / "+" / ( "!" channelid ) / "&" ) chanstring
                  [ ":" chanstring ]
    servername =  hostname
    host       =  hostname / hostaddr
    hostname   =  shortname *( "." shortname )
    shortname  =  ( letter / digit ) *( letter / digit / "-" )
                  *( letter / digit )
                    ; as specified in RFC 1123 [HNAME]
    hostaddr   =  ip4addr / ip6addr
    ip4addr    =  1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
    ip6addr    =  1*hexdigit 7( ":" 1*hexdigit )
    ip6addr    =/ "0:0:0:0:0:" ( "0" / "FFFF" ) ":" ip4addr
    nickname   =  ( letter / special ) *8( letter / digit / special / "-" )
    targetmask =  ( "$" / "#" ) mask
                    ; see details on allowed masks in section 3.3.1
    chanstring =  %x01-07 / %x08-09 / %x0B-0C / %x0E-1F / %x21-2B
    chanstring =/ %x2D-39 / %x3B-FF
                    ; any octet except NUL, BELL, CR, LF, " ", "," and ":"
    channelid  = 5( %x41-5A / digit )   ; 5( A-Z / 0-9 )

    user       =  1*( %x01-09 / %x0B-0C / %x0E-1F / %x21-3F / %x41-FF )
                    ; any octet except NUL, CR, LF, " " and "@"
    key        =  1*23( %x01-05 / %x07-08 / %x0C / %x0E-1F / %x21-7F )
                    ; any 7-bit US_ASCII character,
                    ; except NUL, CR, LF, FF, h/v TABs, and " "
    letter     =  %x41-5A / %x61-7A       ; A-Z / a-z
    digit      =  %x30-39                 ; 0-9
    hexdigit   =  digit / "A" / "B" / "C" / "D" / "E" / "F"
    special    =  %x5B-60 / %x7B-7D
                    ; "[", "]", "\", "`", "_", "^", "{", "|", "}"

    mask       =  *( nowild / noesc wildone / noesc wildmany )
    wildone    =  %x3F
    wildmany   =  %x2A
    nowild     =  %x01-29 / %x2B-3E / %x40-FF
                    ; any octet except NUL, "*", "?"
    noesc      =  %x01-5B / %x5D-FF
                    ; any octet except NUL and "\"
    matchone   =  %x01-FF
                    ; matches wildone
    matchmany  =  *matchone
                    ; matches wildmany

    Examples:

    a?c         ; Matches any string of 3 characters in length starting
                with "a" and ending with "c"

    a*c         ; Matches any string of at least 2 characters in length
                starting with "a" and ending with "c"

Server State
------------

* List of local connections, which may belong to clients (users and
  services) or other servers

* List of servers in the network
   * Server name, max of 63 chars
   * Hostmasks can group servers with matching names into a 'virtual
     server' seen by non-matching servers
   * Hopcount
   * Peer identifier token
   * Link flags

* List of clients in the network
   * Network-unique identifier; format depends on type
   * Server to which the client is connected

* List of users in the network
   * Has a unique nickname on the network (std says 9 chars max)
   * Name of the host the user is running on
   * Username of user on that host
   * Server the user is connected to

* List of services in the network known by the server
   * Service name = nickname + server name
   * Service type

* List of channels in the network known by the server
   * Channel name (prefix + up to 49 other chars)
   * Channel members
   * Channel modes

* Recent nickname changes

* Nickname re-use delay

Connection State
----------------

* A new connection starts out as Unregistered

* A password before registering is *optional*

* Connection can register as a user, service, or server

* Once registered, a client is told the id it was registered with

* Idle connections are periodically sent a PING and are disconnected
  if a PONG is not received in reply

* Flood control applicability and timer information

User State
----------

* User has a nickname that is first set during registration, but can
  later change.

* User has mode flags that can also be set during registration and
  change during operation.
    * a: away (set by AWAY, not MODE)
    * i: invisible
    * w: receives wallops
    * r: restricted connection (can't be cleared with MODE, but can be set)
    * o: operator (set by OPER, cleared with MODE)
    * O: local operator (set by OPER, cleared with MODE)
    * s: receives server notices

* User has a user name, hostname, and real name. These are set at
  registration and do not change thereafter.

* User has a hopcount to determine distance from local server

* Connection by which user can be sent messages

Service State
-------------

* Service name

* Servertoken

* Distribution mask

* Hopcount

* Type

Channel State
-------------

* Channels are typically created when users join them

* Services cannot join channels

* A channel has a name
   * Up to 50 chars, first char is prefix
   * &: local to single server
   * #: normal distribution
   * +: no channel modes
   * !: safe channels

* A channel (that is not a local-only channel) may have a channel mask
  to limit distribution

* A channel has a topic

* A channel has a set of joined users

* Channels may require keys to join

* Channels have modes, some of which are flags and some of which are
  records of management-related data, such as a list of channel ops.

* Channels may keep track of users that have been invited when they
  are set +i (invite-only)

Connection Registration
-----------------------

Valid combinations of registration commands are:

    NICK -> USER
    PASS -> NICK -> USER
    NICK -> PASS -> USER
    PASS -> SERVICE
    SERVICE

When registration succeeds for a user, the server sends the following:

    RPL_WELCOME
    RPL_YOURHOST
    RPL_CREATED
    RPL_MYINFO
    LUSER
    MOTD

When registration succeds for a service, the server sends the
following:

    RPL_YOURESERVICE
    RPL_YOURHOST
    RPL_MYINFO

The server then informs any other servers it is connected to of the
new client.

Commands
--------

### Connection Registration
* PASS <password>
  Needs server env for password
  Modifies connection state
  Errors: ERR_NEEDMOREPARAMS, ERR_ALREADYREGISTERED

* NICK <nickname> [ <hopcount> ]
  Hopcount should only be sent by servers
  Needs currently registered nicks to check for uniqueness
  Errors: ERR_NONICKNAMEGIVEN, ERR_ERRONEUSNICKNAME, ERR_NICKNAMEINUSE, ERR_NICKCOLLISION

* USER <username> <hostname> <servername> <:realname>
  hostname and servername are ignored when coming from clients
  Errors: ERR_NEEDMOREPARAMS, ERR_ALREADYREGISTERED

* SERVER <servername> <hopcount> <:info>
  Errors: ERR_ALREADYREGISTERED

* OPER <user> <password>
  Errors: ERR_NEEDMOREPARAMS, ERR_NOOPERHOST, ERR_PASSWDMISMATCH
  Reply: RPL_YOUREOPER

* QUIT <:quit message>

* SQUIT <server> <:comment>
  Errors: ERR_NOPRIVILEGES, ERR_NOSUCHSERVER

### Channel Operations
* JOIN <channel>{,<channel>} [<key>{,<key>}]
  Errors: ERR_NEEDMOREPARAMS, ERR_BANNEDFROMCHAN, ERR_INVITEONLYCHAN, ERR_CHANNELISFULL,
          ERR_BADCHANNELKEY, ERR_BADCHANMASK, ERR_NOSUCHCHANNEL, ERR_TOOMANYCHANNELS
  Reply: RPL_TOPIC

* PART <channel>{,<channel>}
  Errors: ERR_NEEDMOREPARAMS, ERR_NOSUCHCHANNEL, ERR_NOTONCHANNEL

* MODE <channel> {[+|-]o|p|s|i|t|n|b|v} [<limit>] [<user>] [<ban mask>]
  Errors: ERR_NEEDMOREPARAMS, ERR_CHANOPRIVSNEEDED, ERR_NOTONCHANNEL, ERR_UNKNOWNMODE,
          ERR_NOSUCHNICK, ERR_KEYSET, ERR_NOSUCHCHANNEL
  Reply: RPL_CHANNELMODEIS, RPL_BANLIST, RPL_ENDOFBANLIST

* TOPIC <channel> [<:topic>]
  Errors: ERR_NEEDMOREPARAMS, ERR_NOTONCHANNEL, ERR_CHANOPRIVSNEEDED
  Reply: RPL_NOTOPIC, RPL_TOPIC

* NAMES [<channel>{,<channel>}]
  Reply: RPL_NAMREPLY, RPL_ENDOFNAMES

* LIST [<channel>{,<channel>} [<server>]]
  Errors: ERR_NOSUCHSERVER
  Reply: RPL_LISTSTART, RPL_LIST, RPL_LISTEND

* INVITE <nickname> <channel>
  Errors: ERR_NEEDMOREPARAMS, ERR_NOSUCHNICK, ERR_NOTONCHANNEL, ERR_USERONCHANNEL,
          ERR_CHANOPRIVSNEEDED
  Reply: RPL_INVITING, RPL_AWAY

* KICK <channel> <user> [<:comment>]
  Errors: ERR_NEEDMOREPARAMS, ERR_NOSUCHCHANNEL, ERR_BADCHANMASK, ERR_CHANOPRIVSNEEDED,
          ERR_NOTONCHANNEL

### User Operations
* MODE <nickname> {[+|-]i|w|s|o}
  Errors: ERR_USERSDONTMATCH, ERR_UMODEUNKNOWNFLAG
  Reply: RPL_UMODEIS

### Server Queries and Commands
* VERSION [<server>]
* STATS [<query> [<server>]]
* LINKS [[<remote server>] <server mask>]
* TIME [<server>]
* CONNECT <target server> [<port> [<remote server>]]
* TRACE [<server>]
* ADMIN [<server>]
* INFO [<server>]

### Sending Messages
* PRIVMSG <receiver>{,<receiver>} <:text to be sent>
* NOTICE <nickname> <:text>

### User Based Queries
* WHO [<name> [o]]
* WHOIS [<server>] <nickmask>[,<nickmask>[,...]]
* WHOWAS <nickname> [<count> [<server>]]

### Miscellaneous Messages
* KILL <nickname> <:comment>
* PING <server1> [<server2>]
* PONG <daemon> [<daemon2>]
* ERROR <:error message>

### Optional Messages
* AWAY [<:message>]
* REHASH
* RESTART
* SUMMON <user> [<server>]
* USERS [<server>]
* WALLOPS <:text for opers>
* USERHOST <nickname>{ <nickname>}
* ISON <nickname>{ <nickname>}