54 lines
2.7 KiB
Markdown
54 lines
2.7 KiB
Markdown
|
# 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.
|