The CloudLink Protocol

Work in progress!

The CloudLink Protocol

This page outlines CLPv4.1. Packets within CLPv4.1 are compliant with UPLv2.2.

Uniform Packet Layout 2.2

UPLv2.2 is a formatting scheme that simplifies the protocol, and has existed since CLPv3.

In short, each packet that is UPL compliant is a JSON encoded text frame.

Each JSON message will have no more than these root keys:

{
    "cmd": String, // Required for all commands, The CL Protocol command to execute.
    "val": [ // Command-specific. Not required for some commands.
        String,
        Integer,
        Boolean,
        Object, // Dictionary in Python terms
        Float
    ],
    "mode": String, // Only used for server to client ulist command
    "name": String, // Required for variable-related commands.
    "id": String, // Required for direct or private message commands.
    "relay": String, // Optional, same as id, but will relay the entire packet instead. UPLv2.2 specific.
    "listener": String // Optional, attach to message to get a response.
    "rooms": [ // Optional for client to server messages, required for server to client messages if a client is linked to rooms
        String,
        List // List of strings
    ]
}

handshake: Starting up connections

When a client connects to a CloudLink server, it is recommended that the first message to be sent client to server is the handshake command.

Request

{
    "cmd": "handshake",
    "listener": String // Optional
}

Responses

1. The server will return the detected IP address of the client.

{
    "cmd": "client_ip",
    "val": String
}

2. The server will report what version it's running.

{
    "cmd": "server_version",
    "val": String
}

3. If enabled, the server will provide its "Message of the Day".

{
    "cmd": "motd",
    "val": String
}

4. The server will provide the client it's user object info.

{
    "cmd": "client_obj",
    "val": {
        "id": String, // Snowflake ID
        "uuid": String // UUID
    }
}

5. The server will report the current userlist of the default room.

{
    "cmd": "ulist",
    "mode": "set",
    "val": [], // List of user objects, following the same format as client_obj
    "rooms": "default"
}

6. The server will return a status code (and a listener, if specified).

{
    "cmd": "statuscode",
    "code": "I:100 | OK",
    "code_id": 100,
    "listener": String
}

Afterwards, the client does not need to send the handshake command during the remainder of the websocket connection.

setid: Setting a username and enabling private/direct messages

Before you can utilize link, unlink, pmsg, pvar, direct, or relay commands, you will need to set a username for your client.

Request

{
    "cmd": "setid",
    "val": String // Username
}

Response

1. The server will broadcast a ulist add command to other clients. This message does not get sent to your client.

{
    "cmd": "ulist",
    "mode": "add",
    "val": {
        "id": String, // Your Snowflake ID
        "username": String, // Your Username
        "uuid": String // Your UUID
    },
    "rooms": "default"
}

2. The server will return to you with a ulist set command.

{
    "cmd": "ulist",
    "mode": "set",
    "val": [] // List of user objects, which will include your updated user object
    "rooms": "default"
}

3. The server will return a status code (and a listener, if specified).

{
    "cmd": "statuscode",
    "code": "I:100 | OK",
    "code_id": 100,
    "listener": String
}