5.7 KiB
The Forst API
A client communicates with a Forst server using JSON packets over one or more WebSocket connections. While a single connection should usually suffice, some clients may prefer multiple connections (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.
Packets
The server and client communicate using packets. A packet is a textual WebSocket message containing a JSON object.
There are three types of packets: Events, commands, and replies.
- An event is sent from the server to the client whenever something happens that the client should know about.
- A command is sent from the client to the server. It instructs the server to perform an action on behalf of the client.
- The server must respond to a command with a reply. It describes the result of executing the command.
Every packet has a type field that describes the type of the packet. It must
have one of the following values:
"event"if the packet is an event"command"if the packet is a command"reply"if the packet is a reply
Every packet has a name field and a data field. The name field contains
the name of the event or command. The data field contains a json object that
is the payload of the event, command, or reply.
Command and reply packets have an optional field id of type string
that can be used by the client to associate replies with commands. When the
client sends a command, it may include an arbitrary id. In its reply to the
command, the server must include the exact same id. If the client omitted the
id, the server must omit it as well.
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.