Websocket Protocol

Important Note: This documentation is a work-in-progress.
As such, it might have inaccurate or incomplete information.
The protocol is also still in flux so it may change.
Contact TheTechRobo on hackint or Libera.chat IRC for help.

Currently missing from the documentation: logging

The client-server protocol for #burnthetwitch is fairly simple. It uses an architecture very similar to that of Seesaw, which is Archive Team's standard toolkit. I decided not to use Seesaw because it isn't very well documented and I didn't want to have to build an IRC bot around it.

Client and server communicate using a websocket. There is a simple handshake currently consisting of one message (it will be extended later but I'm a lazyass):

Client: {"type": "afternoon", "auth": "", "version": ""}

If you do not authenticate properly, your messages will be ignored. Furthermore, if you provide an invalid authentication token, it will automatically notify the IRC channel.

From then on, pings look like this:

Client-to-server: {"type": "ping"}
Server-to-client: {"type": "godot", "method": "ping"}

If one end of the connection receives a ping, the other end of the connection should respond with one.

Note: The handshake is one thing that I really want to change. Additionally, the ping mechanism will likely be turned into actual WebSocket pings rather than JSON messages.

From then on, the client can request an item:

Client: {"type": "get"}

The server then responds with the item.

Server: {"type": "item", "item": "123456789", "started_by": "TheTechRobo", ...}

Failure conditions:

Generic "can't provide an item" error: {"type": "item", "item": "", "started_by": "", ...}
If more details can be provided:       {"type": "item", "item": "", "started_by": "", ..., "suppl": "Supplemental Information"}

The suppl field will be populated if the tracker can provide more details about the error. If no suppl field is returned, it should output a generic "no items found" error message. If a suppl field is returned but the client does not understand it, the client should either output it or output a generic "no items found" error message.

Current possible suppl values:

• NO_NEW_SERVES: The tracker has been manually paused.
• RATE_LIMITING: The tracker is refusing to provide an item because the global rate-limit has been reached.
• ENHANCE_YOUR_CALM: You have requested a lot of items in a short amount of time.
• TOO_MANY_ERRORS: You have returned a high amount of errors in a short amount of time. The tracker does not want to hand out items to a broken client. This will go away eventually, or if you restart the client, however your error threshold may be temporarily lowered.
• ERROR: Tracker experienced an internal error or database malfunction.

Once the client has received the item, it should process it. A client can feed new items to the tracker:

Client: {"type": "feed", "item": "https://transfer.archivete.am/...", "item_for": "The item identifier responsible for queuing", "user": "Whoever queued the original item", "reason": "Why the item is being queued"}

Note that there is currently no acknowledgement. Also, in future, the user, item_for, and reason fields will likely be ignored and populated by the server.

An item can issue a warning about the item in the IRC channel:

Client: {"type": "warn", "item": "xxx", "person": "TheTechRobo", "message": "You're a loser."}

If a fatal error occurs, the client can report it to the server:

Client: {"type": "error", "item": "", "id": "", "reason": "Short text describing why it happened."}

There is currently no acknowledgement for that.

Uploading

TODO

And now you're all done!