pipes-irc-server/notes.md

356 lines
10 KiB
Markdown

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