Skip to content

messaging.md

Latest commit

 

History

History
559 lines (505 loc) · 15.4 KB

messaging.md

File metadata and controls

559 lines (505 loc) · 15.4 KB

Messaging

All things about messages, typically chats between players.

Sending a message is done with the messaging/send request. When the sender gets a successful response that means the message has been acked by the server and it'll do its best to send it to the recipient(s).

There is no guarantee that the message has been actually received by the other player, if, for example, the recipient disconnects at the same time the message is received. A message can only be sent to online players. There is no support to store messages to be then delivered later. In short, we're not building whatsapp or discord.

Message are received through an event messaging/received. This means the server has no way to guarantee a client acked a message. Each message contains a special marker to allow some form of history seeking.

To receive messages, a client first has to subsribe to a given source. For now the only supported source is player and means direct message from other players. The argument since is there as an option to ask the server some historical events. There will be sent as regular messaging/received event straight after the response. If since is not provided, the default is latest.

  • from_start means the server will send its entire buffer.
  • latest means the server will not send any potentially stored messages, only messages delivered after the subscription will be sent.
  • marker with a corresponding value means the server will deliver all stored messages that have been sent after the message designated by the marker. This marker should be treated as an opaque value. This should typically used by clients when they reconnect after a crash to make sure they are not missing any messages.

Received

Notify the player a message has been received

  • Endpoint Type: Event
  • Source: Server
  • Target: User
  • Required Scopes: tachyon.lobby

Event

JSONSchema 
{
    "title": "MessagingReceivedEvent",
    "tachyon": {
        "source": "server",
        "target": "user",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "event" },
        "messageId": { "type": "string" },
        "commandId": { "const": "messaging/received" },
        "data": {
            "title": "MessagingReceivedEventData",
            "type": "object",
            "properties": {
                "message": { "type": "string" },
                "source": {
                    "anyOf": [
                        {
                            "type": "object",
                            "properties": {
                                "type": { "const": "player" },
                                "userId": { "$ref": "#/definitions/userId" }
                            },
                            "required": ["type", "userId"]
                        },
                        {
                            "type": "object",
                            "properties": {
                                "type": { "const": "party" },
                                "partyId": { "$ref": "#/definitions/partyId" },
                                "userId": { "$ref": "#/definitions/userId" }
                            },
                            "required": ["type", "partyId", "userId"]
                        },
                        {
                            "type": "object",
                            "properties": {
                                "type": { "const": "lobby" },
                                "lobbyId": { "$ref": "#/definitions/lobbyId" },
                                "userId": { "$ref": "#/definitions/userId" }
                            },
                            "required": ["type", "lobbyId", "userId"]
                        }
                    ]
                },
                "timestamp": {
                    "$ref": "#/definitions/unixTime",
                    "description": "time at which the message was received by the server"
                },
                "marker": { "$ref": "#/definitions/historyMarker" }
            },
            "required": ["message", "source", "timestamp", "marker"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}
Example 
{
    "type": "event",
    "messageId": "eu",
    "commandId": "messaging/received",
    "data": {
        "message": "cupidatat Ut velit",
        "source": {
            "type": "player",
            "userId": "351"
        },
        "timestamp": 1705432698000000,
        "marker": "-576460745805023"
    }
}

TypeScript Definition

export type UserId = string;
export type PartyId = string;
export type LobbyId = string;
export type HistoryMarker = string;

export interface MessagingReceivedEvent {
    type: "event";
    messageId: string;
    commandId: "messaging/received";
    data: MessagingReceivedEventData;
}
export interface MessagingReceivedEventData {
    message: string;
    source:
        | {
              type: "player";
              userId: UserId;
          }
        | {
              type: "party";
              partyId: PartyId;
              userId: UserId;
          }
        | {
              type: "lobby";
              lobbyId: LobbyId;
              userId: UserId;
          };
    timestamp: number;
    marker: HistoryMarker;
}

Send

Send a simple message to the given target.

  • Endpoint Type: Request -> Response
  • Source: User
  • Target: Server
  • Required Scopes: tachyon.lobby

Request

JSONSchema 
{
    "title": "MessagingSendRequest",
    "tachyon": {
        "source": "user",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "messaging/send" },
        "data": {
            "title": "MessagingSendRequestData",
            "type": "object",
            "properties": {
                "target": {
                    "anyOf": [
                        {
                            "type": "object",
                            "properties": {
                                "type": { "const": "player" },
                                "userId": { "$ref": "#/definitions/userId" }
                            },
                            "required": ["type", "userId"]
                        },
                        {
                            "type": "object",
                            "properties": { "type": { "const": "party" } },
                            "required": ["type"]
                        },
                        {
                            "type": "object",
                            "properties": { "type": { "const": "lobby" } },
                            "required": ["type"]
                        }
                    ]
                },
                "message": { "type": "string", "maxLength": 512 }
            },
            "required": ["target", "message"]
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}
Example 
{
    "type": "request",
    "messageId": "proident ullamco enim ad",
    "commandId": "messaging/send",
    "data": {
        "target": {
            "type": "party"
        },
        "message": "nostrud consectetur cupidatat dolore Lorem"
    }
}

TypeScript Definition

export type UserId = string;

export interface MessagingSendRequest {
    type: "request";
    messageId: string;
    commandId: "messaging/send";
    data: MessagingSendRequestData;
}
export interface MessagingSendRequestData {
    target:
        | {
              type: "player";
              userId: UserId;
          }
        | {
              type: "party";
          }
        | {
              type: "lobby";
          };
    message: string;
}

Response

JSONSchema 
{
    "title": "MessagingSendResponse",
    "tachyon": {
        "source": "server",
        "target": "user",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "MessagingSendOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "messaging/send" },
                "status": { "const": "success" }
            },
            "required": ["type", "messageId", "commandId", "status"]
        },
        {
            "title": "MessagingSendFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "messaging/send" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "message_too_long",
                        "invalid_target",
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}
Example 
{
    "type": "response",
    "messageId": "Duis dolore labore",
    "commandId": "messaging/send",
    "status": "success"
}

TypeScript Definition

export interface MessagingSendOkResponse {
    type: "response";
    messageId: string;
    commandId: "messaging/send";
    status: "success";
}

Possible Failed Reasons: message_too_long, invalid_target, internal_error, unauthorized, invalid_request, command_unimplemented

SubscribeReceived

Ask the server to send events for relevant messages

  • Endpoint Type: Request -> Response
  • Source: User
  • Target: Server
  • Required Scopes: tachyon.lobby

Request

JSONSchema 
{
    "title": "MessagingSubscribeReceivedRequest",
    "tachyon": {
        "source": "user",
        "target": "server",
        "scopes": ["tachyon.lobby"]
    },
    "type": "object",
    "properties": {
        "type": { "const": "request" },
        "messageId": { "type": "string" },
        "commandId": { "const": "messaging/subscribeReceived" },
        "data": {
            "title": "MessagingSubscribeReceivedRequestData",
            "type": "object",
            "properties": {
                "since": {
                    "anyOf": [
                        {
                            "type": "object",
                            "properties": { "type": { "const": "from_start" } },
                            "required": ["type"]
                        },
                        {
                            "type": "object",
                            "properties": { "type": { "const": "latest" } },
                            "required": ["type"]
                        },
                        {
                            "type": "object",
                            "properties": {
                                "type": { "const": "marker" },
                                "value": {
                                    "$ref": "#/definitions/historyMarker"
                                }
                            },
                            "required": ["type", "value"]
                        }
                    ],
                    "default": { "type": "latest" }
                }
            }
        }
    },
    "required": ["type", "messageId", "commandId", "data"]
}
Example 
{
    "type": "request",
    "messageId": "nostrud dolore elit reprehenderit",
    "commandId": "messaging/subscribeReceived",
    "data": {
        "ut_9ee": -81368696.68960571,
        "fugiat_b": 26924455
    }
}

TypeScript Definition

export type HistoryMarker = string;

export interface MessagingSubscribeReceivedRequest {
    type: "request";
    messageId: string;
    commandId: "messaging/subscribeReceived";
    data: MessagingSubscribeReceivedRequestData;
}
export interface MessagingSubscribeReceivedRequestData {
    since?:
        | {
              type: "from_start";
          }
        | {
              type: "latest";
          }
        | {
              type: "marker";
              value: HistoryMarker;
          };
}

Response

JSONSchema 
{
    "title": "MessagingSubscribeReceivedResponse",
    "tachyon": {
        "source": "server",
        "target": "user",
        "scopes": ["tachyon.lobby"]
    },
    "anyOf": [
        {
            "title": "MessagingSubscribeReceivedOkResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "messaging/subscribeReceived" },
                "status": { "const": "success" },
                "data": {
                    "title": "MessagingSubscribeReceivedOkResponseData",
                    "type": "object",
                    "properties": {
                        "hasMissedMessages": {
                            "description": "set to true when the marker sent doesn't match any message stored by the server.",
                            "type": "boolean"
                        }
                    },
                    "required": ["hasMissedMessages"]
                }
            },
            "required": ["type", "messageId", "commandId", "status", "data"]
        },
        {
            "title": "MessagingSubscribeReceivedFailResponse",
            "type": "object",
            "properties": {
                "type": { "const": "response" },
                "messageId": { "type": "string" },
                "commandId": { "const": "messaging/subscribeReceived" },
                "status": { "const": "failed" },
                "reason": {
                    "enum": [
                        "internal_error",
                        "unauthorized",
                        "invalid_request",
                        "command_unimplemented"
                    ]
                },
                "details": { "type": "string" }
            },
            "required": ["type", "messageId", "commandId", "status", "reason"]
        }
    ]
}
Example 
{
    "type": "response",
    "messageId": "qui ut Excepteur mollit",
    "commandId": "messaging/subscribeReceived",
    "status": "success",
    "data": {
        "hasMissedMessages": false
    }
}

TypeScript Definition

export interface MessagingSubscribeReceivedOkResponse {
    type: "response";
    messageId: string;
    commandId: "messaging/subscribeReceived";
    status: "success";
    data: MessagingSubscribeReceivedOkResponseData;
}
export interface MessagingSubscribeReceivedOkResponseData {
    hasMissedMessages: boolean;
}

Possible Failed Reasons: internal_error, unauthorized, invalid_request, command_unimplemented