166 lines
4.4 KiB
Markdown
166 lines
4.4 KiB
Markdown
# The Forst API
|
|
|
|
A client communicates with a Forst server using JSON packets over one or more
|
|
WebSocket connections. A normal client does not need more than one connection,
|
|
but can still use more if it is more convenient (e.g. multiple browser tabs).
|
|
|
|
<!-- Implementing a client should be easy, especially implementing a bot. -->
|
|
<!-- The API must be usable in the context of a web browser. -->
|
|
<!-- The API should be robust if the connection is unstable (e.g. mobile data). -->
|
|
|
|
## The connection lifecycle
|
|
|
|
A connection has two phases: The **auth phase** and the **roam phase**. In each
|
|
phase, only commands from the respective phase are allowed.
|
|
|
|
A connection starts out in the **auth phase**. Here, the client and server must
|
|
negotiate a client identity. When the client receives its identity, the
|
|
connection switches to the roam phase.
|
|
|
|
The connection now stays in the **roam phase** until it is closed. During this
|
|
phase, the client can enter and exit rooms, as well as interact with other
|
|
clients in entered rooms. The server will also send status updates (events) for
|
|
entered rooms.
|
|
|
|
## Primitive types
|
|
|
|
### EventId
|
|
|
|
A message id is a string matching `e[0-9a-f]{16}`. In other words, it's a 128
|
|
bit hexadecimal integer prefixed by `e`.
|
|
|
|
Sorting events by their id puts them in chronological order.
|
|
|
|
### MessageId
|
|
|
|
A message id is a string matching `m[0-9a-f]{16}`. In other words, it's a 128
|
|
bit hexadecimal integer prefixed by `m`.
|
|
|
|
Sorting messages by their id puts them in chronological order.
|
|
|
|
### SessionId
|
|
|
|
A session id is a string matching `s[0-9a-f]{16}`. In other words, it's a 128
|
|
bit hexadecimal integer prefixed by `s`.
|
|
|
|
### UserId
|
|
|
|
A user id is a string matching `[a-z0-9-]+`. It is usually four characters long
|
|
for accounts and eight characters plus a dash for other sessions, though this is
|
|
not required. A user id uniquely identifies a user.
|
|
|
|
<!-- Dashes are optional and carry no meaning. They can be added and removed at will. -->
|
|
|
|
## Auth phase commands
|
|
|
|
### `c-auth-cookie`
|
|
|
|
Authenticate via the cookies exchanged during the HTTP handshake portion of the
|
|
WebSocket connection. This requires the client to store and present the cookies
|
|
on subsequent connections.
|
|
|
|
### `c-auth-session-id`
|
|
|
|
Authenticate via session id. This requires the client to store the session id
|
|
and present it on subsequent connections via `auth-session-id`.
|
|
|
|
### `c-auth-anon`
|
|
|
|
Don't authenticate and obtain a unique user id for this session.
|
|
|
|
## Roam phase events
|
|
|
|
### `e-goodbye`
|
|
|
|
When the server decides to close the connection, it may send a goodbye event
|
|
explaining the decision beforehand, though this is not required.
|
|
|
|
Possible reasons:
|
|
|
|
- protocol error (e.g. using roam commands during the auth phase)
|
|
- spam (the client is sending too many commands)
|
|
- login (the client has logged into an account on another connection for the same session)
|
|
- logout (the client has logged out of an account on another connection for the same session)
|
|
|
|
## Roam phase commands
|
|
|
|
### `c-enter`
|
|
|
|
Enter a room. This is required for a client to receive room events and send room
|
|
commands. A user that has entered a room in at least one client will be displayed
|
|
in the nick list.
|
|
|
|
As part of the reply to this command, the server will include the client's
|
|
current room nick.
|
|
|
|
### `c-exit`
|
|
|
|
Exit a room. After exiting a room, the server will no longer relay events for
|
|
that room, and the client can no longer issue commands for that room.
|
|
|
|
### `c-login`
|
|
|
|
## Roam phase room events
|
|
|
|
### `e-enter`
|
|
|
|
A user has entered the room.
|
|
|
|
### `e-exit`
|
|
|
|
A user has exited the room.
|
|
|
|
### `e-nick`
|
|
|
|
A user has changed their nick.
|
|
|
|
### `e-send`
|
|
|
|
A new message has been sent.
|
|
|
|
### `e-edit`
|
|
|
|
An existing message has been edited.
|
|
|
|
### `e-delete`
|
|
|
|
An existing message has been deleted.
|
|
|
|
## Roam phase room commands
|
|
|
|
### `c-nick`
|
|
|
|
Change your own nick.
|
|
|
|
### `c-send`
|
|
|
|
Send a new message.
|
|
|
|
### `c-edit`
|
|
|
|
Edit a message.
|
|
|
|
### `c-delete`
|
|
|
|
Delete a message.
|
|
|
|
### `c-get-msg`
|
|
|
|
Request a specific message.
|
|
|
|
This may be useful for clients like bots that don't want to store the entire
|
|
message history.
|
|
|
|
### `c-get-thread`
|
|
|
|
Request one or more threads, optionally starting before a specific message id.
|
|
|
|
If no message id is specified, the latest threads are returned. If a message id
|
|
is specified, the first few threads older than that id are returned.
|
|
|
|
### `c-get-log`
|
|
|
|
Request event log, optionally starting before a specific event id.
|
|
|
|
If no event id is specified, the latest events are returned. If an event id is
|
|
specified, the first few events older than that id are returned.
|