Add syntax description of MLOCK message to ts6-protocol.txt.

[irc/rqf/shadowircd.git] / doc / technical / ts6.txt

TS6 Proposal (v8)
Written by Lee H <lee@leeh.co.uk>
Ideas borrowed heavily from ircnet (Beeth, jv, Q)

- Changes between v7 and v8 -
-----------------------------

In the v7 specification, the JOIN command included the channel modes of a
channel, and acted on them following TS rules.  In the v8 specification,
JOIN will never send modes.

Desyncs can occur both when they are sent and when they are not.  If they
are sent, then you can have a situation where a user on one side of the
network issues "MODE #channel -l", and a user on another side of the network
issues "JOIN #channel" whilst the +l still exists.  As the JOIN string sent 
server<->server includes the full modes at the time of the user joining, 
this will propagate the +l, but there is a -l crossing in the other
direction.  Desync will occur beyond where they intersect.

If the modes are not sent, then a lower TS JOIN command, or a JOIN command
that creates a channel will cause a desync.

It is judged that the desync with sending the modes is worse than the desync
by not sending them, as such the v8 specification dictates modes are not
sent with a JOIN command server<->server.

The v8 specification also clarifies that servers may issue TMODE.

- Introduction -
----------------

This document aims to fix some of the flaws that are still present in the
current TS system.

Whilst only one person may use a nickname at any one time, they are not
a reliable method of directing commands between servers.  Clients can change
their nicknames, which can create desyncs.  A reliable method of directing
messages between servers is required so that a message will always reach the
intended destination, even if the client changes nicks in between.

UID solves this problem by ensuring that a client has a unique ID for the
duration of his connection.

This document also aims to solve the lack of TS rules to channel 'bans' on
a netburst.  Bans from both sides of a TS war (losing/winning) are kept.
Bursting the bans with a TS solves this problem.

There is also a race condition in the current TS system, where a user can
issue a mode during a netburst and the mode will be set on the server 
we are bursting to.


- Definitions -
---------------

Throughout this document, the following terms are used:

SID	- A servers unique ID.  This is three characters long and must be in
          the form [0-9][A-Z0-9][A-Z0-9]
ID      - A clients unique ID.  This is six characters long and must be in
          the form [A-Z][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9].  The
          numbers [0-9] at the beginning of an ID are legal characters, but
          reserved for future use.
UID     - An ID concateneted to a SID.  This forms the clients UID.
TS6     - The TS version 6.


- Support -
-----------

Support for this document is given by the TS version 6.

Wherever a destination parameter or source parameter is used, it must use
the SID or UID if the server/client has one.  A TS6 capable server must
translate any SIDs/UIDs back into the server/clients name when communicating
with a server that does not support TS6.

A TS6 server must also support the QS (quitstorm) system, and the encap
specification found here:
http://www.leeh.co.uk/ircd/encap.txt

The TS6 protocol does not supports masked entities.


- Nick TS rules -
-----------------

A server receiving a command that requires nick TS rules must check for a
collision between an existing user, and the nick in the received message.
(the "new user").  The collisions must obey the rules specified in Nick TS
collisions.

If the TS received is lower than the TS of the existing user the server will
collide the existing user if the clients user@host are different, if the
clients user@hosts are identical it will collide the new user.

If the TS received is equal to the TS of the existing user both clients are
collided.

If the TS received is higher than the TS of the existing user, the server
will collide the existing user if the user@hosts are identical, if the
clients user@host are different it will collide the new user and drop the 
message.


- Nick TS collisions -
----------------------

If both users are to be collided, we must issue a KILL for the existing 
user to all servers.  If the new user has a UID then we must also issue a 
KILL for that UID back to the server sending us data causing the collision.

If only the existing user is being collided, we must issue a KILL for the
existing user to all servers except the server sending us data.  If the 
existing user has a UID and the server sending us data supports TS6 then 
we must also issue a KILL for the existing users UID to the server sending 
us data.

If only the new user is being collided, we must issue a KILL for the new user 
back to the server sending us data if the new user has a UID.


- Channel TS rules -
--------------------

A server receiving a command that requires normal channel TS rules must 
apply the following rules to the command.

If the TS received is lower than our TS of the channel a TS6 server must
remove status modes (+ov etc) and channel modes (+nt etc).  If the 
originating server is TS6 capable (ie, it has a SID), the server must
also remove any ban modes (+b etc).  The new modes and statuses are then
accepted.

If any bans are removed, the server must send to non-TS6, directly connected 
servers mode changes removing the bans after the command is propagated.
This prevents desync with banlists, and has to be sent after as clients are
still able to send mode changes before the triggering command arrives.

If the TS received is equal to our TS of the channel the server should keep
its current modes and accept the received modes and statuses.

If the TS received is higher than our TS of the channel the server should keep
its current modes and ignore the received modes and statuses.  Any statuses
given in the received message will be removed.  A server must mark clients 
losing their op (+o) status who do not have a UID as 'deopped'.  A server must 
ignore any "MODE" commands from a user marked as 'deopped'.


- Simple channel TS rules -
---------------------------

A server receiving a command that requires simple channel TS rules must
apply the following rules to the command.

If the TS received is lower, or equal to our TS of the channel the modes are
accepted.  If the TS received is higher than our TS of the channel the modes
are ignored and dropped.

Simple channel TS rules do not affect current modes in the channel except
for the modes we are accepting.


- The following commands are defined here as the TS6 protocol -
---------------------------------------------------------------

- PASS -
	PASS <PASSWORD> TS <TS_CURRENT> :<SID>

This command is used for password verification with the server we are
connecting to.

Due to the burst being sent on verification of the "SERVER" command, and
"SVINFO" being sent after "SERVER", we need to be aware of the TS version
earlier to decide whether to send a TS6 burst or not.

The <PASSWORD> field is the password we have stored for this server,
<TS_CURRENT> is our current TS version.  If this field is not present then
the server does not support TS6.  <SID> is the SID of the server.

- UID -
	:<SID> UID <NICK> <HOPS> <TS> +<UMODE> <USERNAME> <HOSTNAME> <IP> <UID> :<GECOS>

This command is used for introducing clients to the network.

The <SID> field is the SID of the server the client is connected to.
The <NICK> field is the nick of the client being introduced.  The <HOPS>
field is the amount of server hops between the server being burst to and
the server the client is on.  The <TS> field is the TS of the client, either
the time they connected or the time they last changed nick.  The <UMODE>
field contains the clients usermodes that need to be transmitted between
servers.  The <USERNAME> field contains the clients username/ident.  The
<HOSTNAME> field contains the clients host.

The <IP> field contains the clients IP.  If the IP is not to be sent
(due to a spoof etc), the field must be sent as "0".  The <UID> field is the 
clients UID.  The <GECOS> field is the clients gecos.

A server receiving a UID command must apply nick TS rules to the nick.

- SID -
	:<SID> SID <SERVERNAME> <HOPS> <SID> :<GECOS>

This command is used for introducing servers to the network.

The first <SID> field is the SID of the new servers uplink.  The
<SERVERNAME> field is the new servers name.  The <HOPS> field is the hops
between the server being introduced nd the server being burst to.

The second <SID> field is the SID of the new server.  The <GECOS> field i
is the new servers gecos.

Upon receiving the SID command servers must check for a SID collision.  
Two servers must not be allowed to link to the network with the same SID.  
If a server detects a SID collision it must drop the link to the directly 
connected server through which the command was received.

Client and servers which do not have a UID/SID must be introduced by old
methods.

- SJOIN -
	:<SID> SJOIN <TS> <CHANNAME> +<CHANMODES> :<UIDS>

This command is used for introducing users to channels.

The <SID> field is the SID of the server introducing users to the channel.
The <TS> field is the channels current TS, <CHANNAME> is the channels
current name, <CHANMODES> are the channels current modes.  <UIDS> is a
space delimited list of clients UIDs to join to the channel.  Each clients
UID is prefixed with their status on the channel, ie "@UID" for an opped
user.  Multiple prefixes are allowed, "peons" (clients without a status) are
not prefixed.

A server receiving an SJOIN must apply normal channel TS rules to the SJOIN.  

A TS6 server must not use the SJOIN command outside of a netburst
to introduce a single user to an existing channel.  It must instead
use the "JOIN" command defined in this specification.  A TS6 server must
still use SJOIN for creating channels.

- JOIN -
	:<UID> JOIN <TS> <CHANNAME> +

This command is used for introducing one user unopped to an existing channel.

The <UID> field is the UID of the client joining the channel.  The
<TS> field is the channels current TS, <CHANNAME> is the channels
current name.

A server receiving a JOIN must apply normal channel TS rules to the JOIN.

No channel modes are sent with the JOIN command.  In previous versions of
this specification, the "+" parameter contained the channels current modes.
A server following this version of the specification must not interpret this
argument and must not propagate any value other than "+" for this parameter.

It should be noted that whilst JOIN would not normally create a 
channel or lower the timestamp, during specific conditions it can.  This 
can create a desync that this specification does not rectify.

- BMASK -
	:<SID> BMASK <TS> <CHANNAME> <TYPE> :<MASKS>

This command is used for bursting channel bans to a network.

The <SID> field is the SID of the server bursting the bans.  The
<TS> field is the channels current TS, <CHANNAME> is the channels
name.  <TYPE> is a single character identifying the mode type (ie,
for a ban 'b').  <MASKS> is a space delimited list of masks of the 
given mode,limited only in length to the size of the buffer as defined 
by RFC1459.

A server receiving a BMASK must apply simple channel TS rules to the BMASK.

A TS6 server must translate BMASKs into raw modes for non-TS6 
capable servers.  This command must be used only after SJOIN has
been sent for the given channel.

It should be noted however, that a BMASK with a lower TS should
not be possible without a desync, due to it being sent after
SJOIN.

- TMODE -
	:<SID|UID> TMODE <TS> <CHANNAME> <MODESTRING>

This command is used for clients issuing modes on a channel.

<SID|UID> is either the UID of the client setting the mode, or the SID of
the server setting the mode.  <TS> is the current TS of the channel, 
<CHANNAME> is the channels name. <MODESTRING> is the raw mode the client is 
setting.

A server receiving a TMODE must apply simple channel TS rules to the TMODE.

A TS6 server must translate MODEs issued by a local client, or received from
a server into TMODE to send to other TS6 capable servers.