66 lines
3.1 KiB
Markdown
66 lines
3.1 KiB
Markdown
# Base-server
|
|
## TCP request syntax
|
|
A valid request contains a 4-byte (32-bit) big endian unsigned integer denoting the length of the data in bytes, not including the integer itself, a null-byte (`00000000`), which is also not included in the length, followed by the data. Responses are formed in the same format.
|
|
|
|
# Text-server
|
|
## Command data syntax
|
|
- The server accepts UTF-8/ASCII encoded messages.
|
|
- Each message may be formatted like: `command,argument 1,argument 2,...`
|
|
- The arguments are optional, depending on the command.
|
|
- Spaces between commas are parsed, so to the server, `command ,` would be "command " and `, argument` would be " argument".
|
|
- Commas may be escaped by use of a `\`
|
|
- Sending a `\`, without escaping the next character, can be done with `\\`
|
|
- Responses and other client-messages are formed in the same format.
|
|
- Responses may include UTF-8.
|
|
|
|
## Default commands
|
|
**Legend:** `commands`, `<required aguments>`, `[optional arguments]`
|
|
- **req**
|
|
Execute a command with an associated request ID. Returns with the same ID, and the command's return value(s).
|
|
*Arguments:* `req,<ID>,<command>,[argument 1],[argument 2],[...]`
|
|
*Return:* `req,<ID>,[return value 1],[return value 2],[...]`
|
|
- **register**
|
|
Register a new user on the server.
|
|
*Arguments:* `<user>,<password>`
|
|
- **login**
|
|
Log into an existing server.
|
|
*Arguments:* `<user>,<password>`
|
|
- **whoami**
|
|
Check which user this session is using.
|
|
*Return:* `user,<user>`
|
|
- **send**
|
|
Sends command to another user's clients. The command will arrive as-is, with the user switched to be the sender instead of the receiver. So if you are fier, and you execute `send,fier2,text,hello`, fier2 will get `send,fier,text,hello`
|
|
*Arguments:* `<user>,<command>,[argument 1],[argument 2],[...]`
|
|
- **nop**
|
|
Do (almost) nothing.
|
|
*Return:* An "empty" response (four bytes denoting the message has a length of 0 and no additional data)
|
|
|
|
If a return is not specified, the command will return `ok`. If arguments are not specified, the command does not take any arguments. Any command may return an error if malformed or an exception occurs.
|
|
|
|
The server may add, remove or change commands.
|
|
|
|
## Error responses
|
|
- An error returns as `error,<fatality>,<type>,[info]` or `req,<ID>,<fatality>,<type>,[info]` if `req` was used.
|
|
- `<fatality>` is either `fatal` or `nonfatal`. `fatal` usually results in the connection being dropped.
|
|
- `<type>` is the programmatic name of the error. These are usually lower-case. The types are listed below.
|
|
- `[info]` is additional info, meant to be read by a human.
|
|
|
|
## Error types
|
|
- **unhandled**
|
|
An error occured on the server.
|
|
- **request_too_long**
|
|
The request sent by the client is too long.
|
|
- **timeout**
|
|
The request did not finish in a timely fashion, or the session timed out.
|
|
- **command_not_found**
|
|
The command is not available on this server.
|
|
- **syntax**
|
|
The command's arguments are wrong in some way.
|
|
- **name_too_short**
|
|
The user name is not long enough.
|
|
- **invalid_name**
|
|
The user name contains invalid characters.
|
|
- **wrong_user_or_password**
|
|
The user does not exist, or the password is incorrect.
|
|
- **not_logged_in**
|
|
Action requires the session to log in. |