xenofem/transbeam
1
0
Fork 0
Code Issues 6 Pull requests Projects Releases Wiki Activity
transbeam/API.md

2.7 KiB
Raw Blame History

transbeam websocket api

  • After opening the connection, the client sends an upload manifest to the server. This is a JSON object containing the following keys:

    • files: a list of metadata objects for all the files to be uploaded, in the exact order they will be sent. This list must contain at least 1 file and at most 256 files. Each file metadata object has the following keys, all required:
      • name: The name of the file. This will be sanitised on the server side, but the sanitisation library isn't especially restrictive; most Unicode code points will be allowed through as-is.
      • size: The exact size of the file, in bytes.
      • modtime: The modification time of the file, as milliseconds since the Unix epoch.
    • lifetime: an integer number of days the files should be kept for.

  • Once the server receives the metadata, it will respond with a JSON-encoded object containing at least the field type, and possibly other fields as well. The types of message, and their associated extra fields if any, are as follows:

    • ready: The server will accept the upload and is ready to receive data.
      • code: A code string that can be used to download the files, starting now.
    • too_big: The upload is rejected because the total size of the files is bigger than the server is willing to accept.
      • max_size: The maximum total upload size the server will accept. This is subject to change if the admin changes the config, or if the server's storage space is filling up.
    • too_long: The upload is rejected because the requested lifetime is longer than the server will allow.
      • max_days: The maximum number of days the client can request files be kept for.
    • error: A miscellaneous error has occurred.
      • details: A string with more information about the error.

    If the message type is anything other than ready, the connection will be closed by the server.

  • If the server is ready to receive files, the client begins sending chunks of data from the files, as raw binary blobs. The client must transmit each file's data in order from start to finish, and must transmit the files in the same order they were listed in the metadata. The size of the chunks isn't currently specified, and it's fine for a chunk to span the end of one file and the start of the next. After sending each chunk (that is, each complete websocket message), the client must wait for the server to acknowledge the chunk by sending back the string "ack", and then send the next chunk if there is one. Once all chunks have been sent and acknowledged, or once the server has sent a message other than "ack" to indicate an error, the connection will be closed.