User:Narc/Extensible Messaging Protocol
From NarcWiki
Note to self: this thing needs a decent name.
Contents |
Commands
Commands may be sent by either server or client. Commands are case-insensitive. All commands are of one of these forms:
command command: single argument, which may be a comma-separated list command: first argument; second argument; ...
Arguments are optional (commands may have no arguments), and if not present, the colon separator can also be omitted. Arguments are case-insensitive unless otherwise mentioned in the command description. Multiple commands in the same message must be separated by \n (the line feed character, also known as a newline (ASCII character #10)).
If there are multiple arguments, semicolons (ASCII character #59) must be used to separate them from each other.
Arguments may be lists, in which case commas (ASCII character #44) must be used to separate the list elements.
Whitespace is not significant except when in the middle of a command, argument, or list item (i.e. whitespace around punctuation is ignored -- "command: arg" and "command:arg" are the same thing).
Commas, semicolons, newlines and ampersands (ASCII character #38) inside arguments must be escaped as HTML entities:
- commas become ,
- semicolons become ;
- newlines become
- ampersands become &
Other HTML entities may be used as desired, and must be understood by the receiving host (server or client).
Unknown commands must be ignored. Capabilities should be used to determine what commands the remote host can understand.
Base Protocol and Implementation
At its core, the protocol is for communicating between a server and one or more (usually more) clients, with a very small number of required capabilities.
Required Capabilities
- nicknames (client only) -- before interacting with any other clients, clients must first "log in" to the server by specifying a nickname. Clients may remain nickname-less to interact with the server, if the server has any nickname-less capabilities.
- capability capability (client and server) -- clients must be able to send their own capabilities when requested, and must be able to understand the server's capabilities. Clients without this capability will be disconnected automatically after 30 seconds. This capability is required to allow any interaction with the server.
- ask capability (client and server) -- clients and servers must be able to ask each other for various bits of information, which must be implemented as the "what" command, with "tell" used to respond unless a different command (like capa) would be more appropriate.
Required Commands
Required commands for this implementation level:
Example: Hello from: Narc's server
Notes: Sent by server as soon as client connection is accepted.
Example: nickname Narc
Notes: Used to enable interaction with other clients on the same server (most commonly, using the server as text message relay). May also be used to change nickname at any time after interaction has been enabled. This command's argument is case-sensitive.
Example: capa: nick, chat, channel, pm
Notes: Used to specify a client's capabilities.
Example: what: capa, ip?
Notes: Used to ask for information from the remote host (server or client). Requested information may have a question mark at the end, which must be ignored. Requested information may be a list, in which case question marks trailing any list element must be ignored. If asking for an unknown askable, remote must respond with the special value "unknown" (case-insensitive)
Example: tell: ip, 127.0.0.1; nick, narc
Notes: Used in reply to a what command for items that do not have their own command that can be used as reply (as capa does). Multiple keyword-item pairs may be sent, but are not required.
Example: bye: User exited
Notes: Used to notify of closing connection. reason is optional, and may be logged or displayed by the remote end, if appropriate.
Askable information
Questions may be sent by either server or client unless otherwise specified. Responses are in the form of a tell command unless otherwise specified.
- what: ip -- Remote must respond with the IP it believes it is connected to (i.e. server will respond with client's IP, client with server's IP).
- what: capa -- Remote must respond with a capa command containing its capabilities.
- what: connection time -- Remote must respond with the time elapsed since initial connection, in seconds.
Example session
| Client | Server |
|---|---|
| client at 1.2.3.4 connected to server | server listening at 5.6.7.8 accepts connection |
| client waits; may also send capabilities now (see below) | Hello from: Some Server |
| client stores information about server name | server waits for command |
| capa: nick, capa, ask | received data, processing in next tick |
| nick: SomeUser | server recognizes capa command from previous tick and stores information about capabilities |
| what: ip, capa? (client asks for its IP (as seen by remote) and server capabilities) | server recognizes nick command from previous tick and stores information about nickname |
| client waits for response | server recognizes what command from previous tick, sends first response: tell: ip; 1.2.3.4 (server tells client its IP) |
| client displays or stores the IP it just asked for | capa: nick (server tells client what capabilities it has) |
| client stores the server capabilities it just received | server waits for further input |
In this example, the client was lazy and waited to receive and process Hello from from the server before saying anything. It could have also immediately sent the capa command, or all three commands with \n between them all at once. Likewise the server, when responding to the what command could have responded with both tell and capa in one message, \n-separated.
