4.4 KiB
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).
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.
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.