Skip to content

Latest commit

 

History

History
332 lines (281 loc) · 7.21 KB

PROTOCOL.md

File metadata and controls

332 lines (281 loc) · 7.21 KB

The AxoChat protocol

The AxoChat protocol is based on websockets. All packets are sent to the /ws endpoint.

Table of Contents

Packets

Packets are sent in websocket text messages encoded as JSON objects. They all have a structure like that, with c being optional:

{
    "m": "Name",
    "c": {
        "...": "...",
        "...": false
    }
}

Not every packet has a body:

{
    "m": "Name"
}

Client

Client Packets are received by the client.

Error

This packet may be sent at any time, but is usually a response to a failed action of the client.

Example

{
    "m": "Error",
    "c": {
        "message": "LoginFailed"
    }
}

Message

This packet will be sent to every authenticated client, if another client successfully sent a message to the server.

  • author_info is just the name and uuid of the user that sent the message.
  • content is any message fitting the validation scheme of the server.

Example

{
    "m": "Message",
    "c": {
        "author_info": {
            "name": "Notch",
            "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
        },
        "content": "Hello, World!"
    }
}

MojangInfo

After the client sent the server a RequestMojangInfo packet, the server will provide the client with a session_hash. A session hash is synonymous with a server id in the context of authentication with mojang. The client has to send a LoginMojang packet to the server after authenticating itself with mojang.

Example

{
    "m": "MojangInfo",
    "c": {
        "session_hash": "88e16a1019277b15d58faf0541e11910eb756f6"
    }
}

NewJWT

After the client sent the server a RequestJWT packet, the server will provide the client with json web token. This token can be used in the LoginJWT packet.

Example

{
    "m": "NewJWT",
    "c": {
        "token": "VGhpcyBjb3VsZCBiZSBhIGpzb24gd2ViIHRva2VuLCBidXQgaXQgaXNuJ3QK"
    }
}

PrivateMessage

The content of this packet will be sent to a authenticated client with allow_messages turned on, if another client successfully sent a private message.

  • author_info is just the name and uuid of the user that sent the message.
  • content is any message fitting the validation scheme of the server.

Example

{
    "m": "PrivateMessage",
    "c": {
        "author_info": {
            "name": "Notch",
            "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
        },
        "content": "Hello, User!"
    }
}

Success

This packet is sent after either LoginMojang, LoginJWT, BanUser or UnbanUser were processed successfully.

  • reason is the reason for the success; it is one of the following possible values:
    • Login
    • Ban
    • Unban

Example

{
    "m": "Success",
    "c": {
        "reason": "Login"
    }
}

UserCount

This packet is sent after RequestUserCount was received.

  • connections is the amount of connections this server has open
  • logged_in is the amount of authenticated connections this server has open

Example

{
    "m": "UserCount",
    "c": {
        "connections": 623,
        "logged_in": 531,
    }
}

Server

Server Packets are received by the server.

BanUser

A client can send this packet to ban other users from using this chat.

  • user is the uuid of the user to ban.

Example

{
    "m": "BanUser",
    "c": {
        "user": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    }
}

LoginJWT

To login using a json web token, the client has to send a LoginJWT packet. it will send Success if the login was successful.

  • token can be retrieved by sending RequestJWT on an already
  • authenticated connection.
  • If allow_messages is true, other clients may send private messages to this client.

Example

{
    "m": "LoginJWT",
    "c": {
        "token": "VGhpcyBjb3VsZCBiZSBhIGpzb24gd2ViIHRva2VuLCBidXQgaXQgaXNuJ3QK",
        "allow_messages": true,
    }
}

LoginMojang

After the client received a MojangInfo packet and authenticating itself with mojang, it has to send a LoginMojang packet to the server. After the server receives a LoginMojang packet, it will send Success if the login was successful.

  • name needs to be associated with the uuid.
  • uuid is not guaranteed to be hyphenated.
  • If allow_messages is true, other clients may send private messages to this client.

Example

{
    "m": "LoginMojang",
    "c": {
        "name": "Notch",
        "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
        "allow_messages": true
   }
}

Message

The content of this packet will be sent to every client as Message if it fits the validation scheme.

Example

{
    "m": "Message",
    "c": {
        "content": "Hello, World!"
    }
}

PrivateMessage

The content of this packet will be sent to the specified client as PrivateMessage if it fits the validation scheme.

  • receiver is the name of the receiver.

Example

{
    "m": "PrivateMessage",
    "c": {
        "content": "Hello, Notch!",
        "receiver": "Notch"
    }
}

RequestJWT

To login using LoginJWT, a client needs to own a json web token. This token can be retrieved by sending RequestJWT as an already authenticated client to the server. The server will send a NewJWT packet to the client.

This packet has no body.

Example

{
    "m": "RequestJWT"
}

RequestMojangInfo

To login via mojang, the client has to send a RequestMojangInfo packet. The server will then send a MojangInfo to the client.

This packet has no body.

Example

{
    "m": "RequestMojangInfo"
}

RequestUserCount

After receiving this packet, the server will then send a UserCount packet to the client.

This packet has no body.

Example

{
    "m": "RequestUserCount"
}

UnbanUser

A client can send this packet to unban other users.

  • user is the uuid of the user to unban.

Example

{
    "m": "UnbanUser",
    "c": {
        "user": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    }
}