[IRC-DEV] Borrador 1 de API TCP/IP 0 de Olimpo

[Jesus Cea Avion]

Este documento define el borrador 1 (22/Ene/02) para el nivel CERO del
API TCP/IP de Olimpo.

Este documento define un borrador. Se esperan recibir comentarios y
sugerencias por parte de toda la comunidad de programadores de IRC.

El objetivo de este API es crear un estándar para que los bots y Olimpo
puedan comunicarse a través de TCP/IP. Ello posibilita, por ejemplo, que
los bots puedan residir en cualquier lugar de internet, y que
IRC-Hispano no tenga por qué tener acceso a su código fuente.

Existe interés, también, en que este API sea utilizado en otras redes,
de forma que los bots se puedan utilizar tanto en IRC-Hispano como en la
"competencia".


ESPECIFICACIONES

El API consiste en el intercambio de comandos y respuestas, de forma
asíncrona.

El servidor envía los comandos y las respuestas como texto terminado con
un "\r\n" (retorno de carro y salto de línea, ASCII 13 y 10,
respectivamente). El servidor acepta texto terminado con "\r\n" y "\n".
Es decir, el "\r" es opcional.

Los comandos y respuestas ignoran mayúsculas y minúsculas en su nombre.

El servidor desconectará cualquier bot que utilice un comando no
documentado o utilice una sintaxis ilegal.

La longitud máxima de una línea permitida por el servidor es de 256
bytes. Si un bot intenta enviar líneas más largas, será desconectado.

El servidor puede enviar líneas arbitrariamente largas, y los bots deben
soportarlo.

Solo se admiten comunicaciones con usuario con modo "+r".

COMANDOS y RESPUESTAS

CHALLENGE
Sintaxis: "challenge" mecanismo reto

Este comando es enviado por el servidor para verificar la identidad de
un bot que intenta conectarse. El servidor plantea un reto, que el bot
debe responder correctamente antes de que se le permita conectar y de
que pueda enviar ningún comando al sistema o recibir notificaciones
desde el mismo.

En este momento el único mecanismo definido es "HMAC-MD5".

"reto" es un parámetro proporcionado por el servidor.

CHALLENGE-RESULT
Sintaxis: "challenge-result" nick resultado

Ésta es la respuesta enviada por el bot al comando "challenge-result".

BYE
Sintaxis: "bye" razón

Comando enviado al bot cuando el servidor lo desconecta.

PING
Sintaxis: "ping" token

Envía un "ping" al otro extremo.

PONG
Sintaxis: "pong" token

Responde al "ping". El token *DEBE* ser el mismo del "ping".

COMMANDLIST
Sintaxis: "commandlist" comandos...

Este mensaje comunica al servidor la lista de comandos que acepta el
bot. El servidor sólo enviará al bot los privados de usuarios
conteniendo dichos mensajes. Si un usuario envía un comando inexistente,
el servidor lo ignorará y nunca llegará al bot.

Se ignora mayúsculas y minúsculas.

PRIVMSG
Sintaxis: "privmsg" csesion texto

"csesion" identifica la sesión de conexión que corresponde a ese
usuario.

Cuando lo envía el servidor, indica un privado de un usuario. Si el bot
no tiene constancia de la sesión especificada, se está abriendo una
nueva sesión de conexión de forma implícita.

Cuando lo envía el bot, indica un privado *AL* usuario. Si la sesión de
conexión ya no existe, el servidor responderá con su cierre.

CSESSION
Sintaxis: "csession" comando csesion..

Realiza operaciones sobre una sesión o un grupo de sesiones de conexión.

Los comandos son:

"test": Comprueba si una sesión existe.
"open": Abre una sesión nueva. Este comando lo envía el servidor, y
puede ser implícito.
"closed": Avisa de que una sesión ya no existe o ya no nos interesa.
"exists": Avisa de que una sesión sigue existiendo, como respuesta a
"test".


SINTAXIS pseudoBNF

envio:= (comando | respuesta) ("\n" | "\r\n")
comando:= challenge | bye | ping | privmsg | csession
respuesta:= challenge-result | pong |
challenge:= "challenge" metodo-challenge reto
metodo-challenge:= "HMAC-MD5"
reto:= imprimible
alfanumerico:= ("a"|..|"z"|"A"|..|"Z"|"0"|.."9")..
challenge-result:= "challenge-result" nick respuesta
nick:= alfanumextras
alfanumextras=(alfanumerico | "-" | "_")..
respuesta=hexadecimal
hexadecimal=("A"|..|"F"|"a"|..|"f"|"0".."9")..
imprimible:=cualquier carácter imprimible
bye:= "bye" razón
razón:= imprimible
ping:= "ping" razón
pong:= "pong" razón
commandlist:= "commandlist" listacomando..
listacomando:= imprimible
privmsg:= "privmsg" csesion texto
csesion:= alfanumerico
texto:= (imprimible | " " | "\t")..
csession:= "csession" comando-csesion csesion..
comando-csesion:= "test" | "open" | "closed" | "exists"


SESIONES DE CONEXION

Una sesión de conexion identifica unívocamente a un usuario en una
conexión determinada. Su validez termina cuando:

a) El usuario se desconecta, aunque vuelva a reconectarse.
b) Cuando hay un split en la red.
c) Si el usuario cambia de nick.

-- 
Jesus Cea Avion                         _/_/      _/_/_/        _/_/_/
jcea at argo.es http://www.argo.es/~jcea/ _/_/    _/_/  _/_/    _/_/  _/_/
                                      _/_/    _/_/          _/_/_/_/_/
PGP Key Available at KeyServ   _/_/  _/_/    _/_/          _/_/  _/_/
"Things are not so easy"      _/_/  _/_/    _/_/  _/_/    _/_/  _/_/
"My name is Dump, Core Dump"   _/_/_/        _/_/_/      _/_/  _/_/
"El amor es poner tu felicidad en la felicidad de otro" - Leibniz