diff --git a/README.md b/README.md index e69de29..ace2857 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,60 @@ +# 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, 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`, ``, `[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,,,[argument 1],[argument 2],[...]` +*Return:* `,,[return value 1],[return value 2],[...]` +- **register** +Register a new user on the server. +*Arguments:* `,` +- **login** +Log into an existing server. +*Arguments:* `,` +- **whoami** +Check which user this session is using. +*Return:* `` + +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,,,[info]` or `req,,,,[info]` if `req` was used. +- `` is either `fatal` or `nonfatal`. `fatal` usually results in the connection being dropped. +- `` 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. \ No newline at end of file