Message

Overview

After a handshake is performed, messages can be sent.

Types

Assume all strings have a limit of 10,000 characters by default because of DF.

type SendMessage = {
    type: "s"
    // Websocket message id
    id: number
    // Plot id of sender
    from: number
    // Plot id to send to
    to_plot: number
    // Plot mailbox's key to send to
    to_key: string

    // Unix time
    sent_at: number
    // Either a string or an array of list of strings
    // The max length of the array is determined by the "hello" part of the handshake
    // This is found with `protocol.send_max_length`
    data: string | string[]
}

All responses have "type": "r"

type ResponseMessage = {
    type: "r"
    // This must match the id that this message is responding to
    id: number
} & ... // all the responses

Standard Response types

You MUST NOT add any more properties to these messages other than specified. If you need to, use a non standard response

Ok

type Success = {
    ok: "success"
}

Allowlist

The sender isn't part of the allowlist

type AllowlistError = {
    err: "allowlist"
    allowed?: number[]
}

Blacklist

The sender is part of the blocklist

type BlocklistError = {
    err: "blocklist"
}

Format Error

The receiver expected a different format. For example, the sender sent plain text while the receiver expected JSON.

type FormatError = {
    err: "format"
    desc?: string
}

Internal error

There was an internal error processing the message

type InternalError = {
    err: "internal"
}

Nonstandard Responses

Non standard responses exist to accommodate for some implementation specific features and scripting. Non standard responses must follow these simple rules.

1. The response still must be a ResponseMessage meaning it has a type indicator and a websocket message id
2. A successful response must have an ok key
3. A non-successful response must have an err key
4. ok and err must follow the regex: ^(?:[A-Za-z_][A-Za-z0-9_]*)(?::[A-Za-z_][A-Za-z0-9_]*)?$
   • This does mean you SHOULD add a namespace

Examples

{
    "type": "r",
    "id": 55,
    "ok": "cool_db:insert_success",
    "rows_inserted": 4
}

{
    "type": "r",
    "id": 42,
    "err": "mace:even_number_plot_id",
    "msg": "Your plot id is even, I don't like it"
}