tachyon-protocol 0.3.1 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -111
- package/dist/{bot → autohost}/slave/request.json +5 -4
- package/dist/{bot/unslave → autohost/slave}/response.json +8 -7
- package/dist/{bot → autohost}/unslave/request.json +5 -4
- package/dist/autohost/unslave/response.json +107 -0
- package/dist/game/launch/response.json +1 -1
- package/dist/index.d.ts +1054 -179
- package/dist/index.js +147 -25
- package/dist/lobby/close/request.json +1 -1
- package/dist/lobby/close/response.json +1 -1
- package/dist/lobby/create/request.json +1 -1
- package/dist/lobby/create/response.json +1 -1
- package/dist/lobby/join/request.json +1 -1
- package/dist/lobby/join/response.json +1 -1
- package/dist/lobby/joined/response.json +327 -110
- package/dist/lobby/leave/request.json +1 -1
- package/dist/lobby/leave/response.json +1 -1
- package/dist/lobby/left/response.json +1 -1
- package/dist/lobby/list/request.json +1 -1
- package/dist/lobby/list/response.json +475 -119
- package/dist/lobby/receiveMessage/response.json +1 -1
- package/dist/lobby/sendMessage/request.json +1 -1
- package/dist/lobby/sendMessage/response.json +1 -1
- package/dist/lobby/subscribe/request.json +33 -0
- package/dist/{bot/slave → lobby/subscribe}/response.json +6 -7
- package/dist/lobby/unsubscribe/request.json +30 -0
- package/dist/lobby/unsubscribe/response.json +131 -0
- package/dist/lobby/updated/response.json +459 -143
- package/dist/matchmaking/cancel/request.json +1 -1
- package/dist/matchmaking/cancel/response.json +1 -1
- package/dist/matchmaking/found/response.json +1 -1
- package/dist/matchmaking/list/request.json +1 -1
- package/dist/matchmaking/list/response.json +13 -7
- package/dist/matchmaking/lost/response.json +1 -1
- package/dist/matchmaking/queue/request.json +1 -1
- package/dist/matchmaking/queue/response.json +1 -1
- package/dist/matchmaking/queueUpdate/response.json +1 -1
- package/dist/matchmaking/ready/request.json +1 -1
- package/dist/matchmaking/ready/response.json +1 -1
- package/dist/matchmaking/readyUpdate/response.json +1 -1
- package/dist/system/connected/response.json +183 -4
- package/dist/system/disconnect/request.json +12 -1
- package/dist/system/disconnect/response.json +105 -0
- package/dist/system/serverStats/request.json +18 -0
- package/dist/system/serverStats/response.json +117 -0
- package/dist/user/subscribe/request.json +33 -0
- package/dist/user/subscribe/response.json +290 -0
- package/dist/user/unsubscribe/request.json +33 -0
- package/dist/user/unsubscribe/response.json +131 -0
- package/dist/user/updated/response.json +304 -0
- package/package.json +18 -6
- package/dist/meta.json +0 -96
package/README.md
CHANGED
|
@@ -1,123 +1,45 @@
|
|
|
1
1
|
# Tachyon
|
|
2
2
|
|
|
3
|
-
Tachyon is the name of
|
|
4
|
-
|
|
5
|
-
[Schema Reference](docs/README.md)
|
|
6
|
-
|
|
7
|
-
## Authorization
|
|
8
|
-
|
|
9
|
-
See [dedicated authorization documentation page](docs/authorization.md).
|
|
10
|
-
|
|
11
|
-
## Connecting
|
|
12
|
-
|
|
13
|
-
To connect to a Tachyon WebSocket server, the client should add a `tachyonVersion` query parameter which specifies which version of Tachyon they're using, e.g. `wss://tachyon-server.com?tachyonVersion=1.2.3`. The server should send a [`system/version/response`](docs/system.md/#version) command containing the version of the Tachyon protocol that is being served and `versionParity` field stating how it differs to the client's version. Ideally, clients should ensure their implementation is using the same version of the protocol, which can be found in this repo's [`package.json`](package.json). However, it is up to the client to decide how to handle version mismatches, and the server should not terminate clients because of a version disparity.
|
|
3
|
+
Tachyon is the name of this protocol, designed to replace the old [Spring Lobby Protocol](https://springrts.com/dl/LobbyProtocol/ProtocolDescription.html), primarily intended for use in [Beyond All Reason](https://github.com/beyond-all-reason/Beyond-All-Reason). It describes the message schema that clients should use to communicate with the master server and vice-versa. The exchange format is JSON sent over a WebSocket connection. [JSONSchema](https://json-schema.org/) is used to define the structure of commands, which can be found in the [dist](dist) directory. Server and client implementations of this protocol are encouraged to use a [JSONSchema validator](https://json-schema.org/implementations.html#validators) to validate and sanitize message requests and responses.
|
|
14
4
|
|
|
15
5
|
## Terminology
|
|
16
6
|
|
|
17
7
|
| Term | Meaning |
|
|
18
8
|
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
-
|
|
|
20
|
-
| Client Application | E.g. SpringLobby, Chobby, BAR Lobby |
|
|
21
|
-
| Server | The provider of the protocol and what clients connect to. i.e. the master or middleware server |
|
|
22
|
-
| Command | A JSON message relating to a specific endpoint |
|
|
23
|
-
| Command ID | The unique string which represents the message type. E.g. `user/login/request` or `lobby/join/response` |
|
|
24
|
-
| Message ID | A unique identifier for a pair of request/response commands which links them together |
|
|
25
|
-
| Endpoint | E.g. `register`, `login` or `join` |
|
|
26
|
-
| Service | A collection of endpoints that are categorically related, E.g. `user` or `lobby` |
|
|
27
|
-
| UserClient | Specifically a registered user who is online |
|
|
28
|
-
| Bot | An automated UserClient, marked as a bot |
|
|
9
|
+
| AI | User-owned game AI instances, e.g. ScavengersAI or BARbarianAI. Can only exist within lobbies/battles |
|
|
29
10
|
| Autohost | A bot which is specifically intended to host battles |
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
11
|
+
| Battle | Either custom or matchmaking |
|
|
12
|
+
| Bot | An automated UserClient, marked as a bot |
|
|
13
|
+
| Client | A WebSocket client that communicates with the Tachyon server via the Tachyon protocol |
|
|
14
|
+
| Client Application | Top level application that connectsE.g. SpringLobby, Chobby, BAR Lobby |
|
|
15
|
+
| Command | The JSON data sent in a message. The shape of these objects are primarily what this Tachyon schema describes |
|
|
16
|
+
| Command ID | The unique string which represents the command type. E.g. `system/connected/response` or `lobby/join/request` |
|
|
17
|
+
| Endpoint | Represents a request->response command or a single response command E.g. `register`, `login` or `join` |
|
|
34
18
|
| Engine | A version of the engine (Recoil), e.g. `105.1.1-1544-g058c8ea BAR105` |
|
|
35
|
-
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
### Responses
|
|
59
|
-
|
|
60
|
-
Every response command contains these additional properties:
|
|
61
|
-
|
|
62
|
-
| Property | type | Description |
|
|
63
|
-
| -------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
64
|
-
| status | "success" \| "failed" | A object containing data specific to the command. This may be omitted if the command does not require it |
|
|
65
|
-
| data | object | Command-specific data object. Only present for "success" responses |
|
|
66
|
-
| reason | string | An error code only present for "failed" responses |
|
|
67
|
-
|
|
68
|
-
All `failed` responses that are initiated by a request can return one of the following `reason`s, even though not explicitly defined in each command's definition file:
|
|
69
|
-
|
|
70
|
-
| Reason | Description |
|
|
71
|
-
| --------------- | ------------------------------------------------------------------------------------------ |
|
|
72
|
-
| unauthorized | When a client sends a request command of which they do not have the `role` required to use |
|
|
73
|
-
| internal_error | When the server fails to handle the request in some way, typically sent in a `catch` block |
|
|
74
|
-
| invalid_command | When the request command doesn't match the schema |
|
|
19
|
+
| Host | The host of a battle. Typically these users are bots |
|
|
20
|
+
| Game | A version of the core game files, e.g. `Beyond All Reason test-22425-e6c0e37` |
|
|
21
|
+
| Lobby | A room or waiting area from which a Battle can be launched, one Lobby can have multiple Battles over the course of its lifetime |
|
|
22
|
+
| Message | The request/response sent over the network that contains a command |
|
|
23
|
+
| Message ID | A unique identifier for a pair of request/response commands which links them together |
|
|
24
|
+
| Server | The provider of the protocol and what clients connect to. i.e. the master/middleware server |
|
|
25
|
+
| Service | A collection of endpoints that are categorically related, E.g. `user` or `lobby` |
|
|
26
|
+
| User | Syonymous with an account, and strictly represents the data which is stored in the server database |
|
|
27
|
+
| UserClient | A registered user who is online |
|
|
28
|
+
|
|
29
|
+
## Docs
|
|
30
|
+
|
|
31
|
+
- [Authentication and Authorization](docs/authorization.md)
|
|
32
|
+
- [Message Structure](docs/commands.md)
|
|
33
|
+
- Commands
|
|
34
|
+
<!-- COMMAND_SCHEMA_PLACEHOLDER_START_DO_NOT_REMOVE -->
|
|
35
|
+
- [autohost](docs/schema/autohost.md)
|
|
36
|
+
- [game](docs/schema/game.md)
|
|
37
|
+
- [lobby](docs/schema/lobby.md)
|
|
38
|
+
- [matchmaking](docs/schema/matchmaking.md)
|
|
39
|
+
- [system](docs/schema/system.md)
|
|
40
|
+
- [user](docs/schema/user.md)
|
|
41
|
+
<!-- COMMAND_SCHEMA_PLACEHOLDER_END_DO_NOT_REMOVE -->
|
|
75
42
|
|
|
76
43
|
## Contributing
|
|
77
44
|
|
|
78
|
-
The [dist](dist) and [docs](docs) directories are automatically generated based on the files in [src](src). The source files are written in (
|
|
79
|
-
|
|
80
|
-
A schema file looks like this:
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
import { Type } from "@sinclair/typebox";
|
|
84
|
-
|
|
85
|
-
import { defineEndpoint } from "@/helpers";
|
|
86
|
-
|
|
87
|
-
export default defineEndpoint({
|
|
88
|
-
description: "Create a new lobby - intended for player clients to summon a dedicated host.",
|
|
89
|
-
request: {
|
|
90
|
-
data: Type.Object(
|
|
91
|
-
{
|
|
92
|
-
title: Type.String({ minLength: 2, maxLength: 30 }),
|
|
93
|
-
private: Type.Boolean({ default: true }),
|
|
94
|
-
region: Type.String(),
|
|
95
|
-
maxPlayers: Type.Integer({ minimum: 0, default: 16 }),
|
|
96
|
-
},
|
|
97
|
-
{
|
|
98
|
-
examples: [
|
|
99
|
-
{
|
|
100
|
-
title: "8v8 | All Welcome",
|
|
101
|
-
private: false,
|
|
102
|
-
region: "EU",
|
|
103
|
-
maxPlayers: 16,
|
|
104
|
-
},
|
|
105
|
-
],
|
|
106
|
-
}
|
|
107
|
-
),
|
|
108
|
-
},
|
|
109
|
-
response: [{ status: "success" }, { status: "failed", reason: "no_hosts_available" }, { status: "failed", reason: "invalid_region" }],
|
|
110
|
-
});
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### Endpoint Options
|
|
114
|
-
|
|
115
|
-
| Option | Type | Description |
|
|
116
|
-
| ------------- | ------- | ---------------------------------------------------- |
|
|
117
|
-
| request | object | The request schema for this endpoint |
|
|
118
|
-
| response | object | The response schema for this endpoint |
|
|
119
|
-
| description | string | A description of what this endpoint is for |
|
|
120
|
-
| requiresLogin | boolean | Does the endpoint require the client to be logged in |
|
|
121
|
-
| order | number | Determines the order endpoint appears in the docs |
|
|
122
|
-
|
|
123
|
-
If `request` is omitted, then this describes an endpoint of which the server can send a `response` for at any time, and the client should be ready to handle it. Similarly, if `response` is omitted, this describes an endpoint of which the client should not expect a response, however, the server may still send one, typically for failed responses.
|
|
45
|
+
The [dist](dist) and [docs/schema](docs/schema) directories are automatically generated based on the files in [src/schema](src/schema). The source files are written in [TypeScript](https://www.typescriptlang.org/) for [Node.js](https://nodejs.org/en), using the [TypeBox](https://github.com/sinclairzx81/typebox) library for JSONSchema generation.
|
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
{
|
|
2
|
-
"$id": "
|
|
3
|
-
"
|
|
4
|
-
|
|
2
|
+
"$id": "autohost/slave/request",
|
|
3
|
+
"roles": [
|
|
4
|
+
"autohost"
|
|
5
|
+
],
|
|
5
6
|
"type": "object",
|
|
6
7
|
"properties": {
|
|
7
8
|
"messageId": {
|
|
8
9
|
"type": "string"
|
|
9
10
|
},
|
|
10
11
|
"commandId": {
|
|
11
|
-
"const": "
|
|
12
|
+
"const": "autohost/slave/request",
|
|
12
13
|
"type": "string"
|
|
13
14
|
},
|
|
14
15
|
"data": {
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"$id": "
|
|
3
|
-
"
|
|
4
|
-
|
|
2
|
+
"$id": "autohost/slave/response",
|
|
3
|
+
"roles": [
|
|
4
|
+
"autohost"
|
|
5
|
+
],
|
|
5
6
|
"anyOf": [
|
|
6
7
|
{
|
|
7
8
|
"type": "object",
|
|
@@ -10,7 +11,7 @@
|
|
|
10
11
|
"type": "string"
|
|
11
12
|
},
|
|
12
13
|
"commandId": {
|
|
13
|
-
"const": "
|
|
14
|
+
"const": "autohost/slave/response",
|
|
14
15
|
"type": "string"
|
|
15
16
|
},
|
|
16
17
|
"status": {
|
|
@@ -31,7 +32,7 @@
|
|
|
31
32
|
"type": "string"
|
|
32
33
|
},
|
|
33
34
|
"commandId": {
|
|
34
|
-
"const": "
|
|
35
|
+
"const": "autohost/slave/response",
|
|
35
36
|
"type": "string"
|
|
36
37
|
},
|
|
37
38
|
"status": {
|
|
@@ -57,7 +58,7 @@
|
|
|
57
58
|
"type": "string"
|
|
58
59
|
},
|
|
59
60
|
"commandId": {
|
|
60
|
-
"const": "
|
|
61
|
+
"const": "autohost/slave/response",
|
|
61
62
|
"type": "string"
|
|
62
63
|
},
|
|
63
64
|
"status": {
|
|
@@ -83,7 +84,7 @@
|
|
|
83
84
|
"type": "string"
|
|
84
85
|
},
|
|
85
86
|
"commandId": {
|
|
86
|
-
"const": "
|
|
87
|
+
"const": "autohost/slave/response",
|
|
87
88
|
"type": "string"
|
|
88
89
|
},
|
|
89
90
|
"status": {
|
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
{
|
|
2
|
-
"$id": "
|
|
3
|
-
"
|
|
4
|
-
|
|
2
|
+
"$id": "autohost/unslave/request",
|
|
3
|
+
"roles": [
|
|
4
|
+
"autohost"
|
|
5
|
+
],
|
|
5
6
|
"type": "object",
|
|
6
7
|
"properties": {
|
|
7
8
|
"messageId": {
|
|
8
9
|
"type": "string"
|
|
9
10
|
},
|
|
10
11
|
"commandId": {
|
|
11
|
-
"const": "
|
|
12
|
+
"const": "autohost/unslave/request",
|
|
12
13
|
"type": "string"
|
|
13
14
|
}
|
|
14
15
|
},
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "autohost/unslave/response",
|
|
3
|
+
"roles": [
|
|
4
|
+
"autohost"
|
|
5
|
+
],
|
|
6
|
+
"anyOf": [
|
|
7
|
+
{
|
|
8
|
+
"type": "object",
|
|
9
|
+
"properties": {
|
|
10
|
+
"messageId": {
|
|
11
|
+
"type": "string"
|
|
12
|
+
},
|
|
13
|
+
"commandId": {
|
|
14
|
+
"const": "autohost/unslave/response",
|
|
15
|
+
"type": "string"
|
|
16
|
+
},
|
|
17
|
+
"status": {
|
|
18
|
+
"const": "success",
|
|
19
|
+
"type": "string"
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
"required": [
|
|
23
|
+
"messageId",
|
|
24
|
+
"commandId",
|
|
25
|
+
"status"
|
|
26
|
+
]
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"type": "object",
|
|
30
|
+
"properties": {
|
|
31
|
+
"messageId": {
|
|
32
|
+
"type": "string"
|
|
33
|
+
},
|
|
34
|
+
"commandId": {
|
|
35
|
+
"const": "autohost/unslave/response",
|
|
36
|
+
"type": "string"
|
|
37
|
+
},
|
|
38
|
+
"status": {
|
|
39
|
+
"const": "failed",
|
|
40
|
+
"type": "string"
|
|
41
|
+
},
|
|
42
|
+
"reason": {
|
|
43
|
+
"const": "internal_error",
|
|
44
|
+
"type": "string"
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
"required": [
|
|
48
|
+
"messageId",
|
|
49
|
+
"commandId",
|
|
50
|
+
"status",
|
|
51
|
+
"reason"
|
|
52
|
+
]
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
"type": "object",
|
|
56
|
+
"properties": {
|
|
57
|
+
"messageId": {
|
|
58
|
+
"type": "string"
|
|
59
|
+
},
|
|
60
|
+
"commandId": {
|
|
61
|
+
"const": "autohost/unslave/response",
|
|
62
|
+
"type": "string"
|
|
63
|
+
},
|
|
64
|
+
"status": {
|
|
65
|
+
"const": "failed",
|
|
66
|
+
"type": "string"
|
|
67
|
+
},
|
|
68
|
+
"reason": {
|
|
69
|
+
"const": "unauthorized",
|
|
70
|
+
"type": "string"
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
"required": [
|
|
74
|
+
"messageId",
|
|
75
|
+
"commandId",
|
|
76
|
+
"status",
|
|
77
|
+
"reason"
|
|
78
|
+
]
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
"type": "object",
|
|
82
|
+
"properties": {
|
|
83
|
+
"messageId": {
|
|
84
|
+
"type": "string"
|
|
85
|
+
},
|
|
86
|
+
"commandId": {
|
|
87
|
+
"const": "autohost/unslave/response",
|
|
88
|
+
"type": "string"
|
|
89
|
+
},
|
|
90
|
+
"status": {
|
|
91
|
+
"const": "failed",
|
|
92
|
+
"type": "string"
|
|
93
|
+
},
|
|
94
|
+
"reason": {
|
|
95
|
+
"const": "invalid_command",
|
|
96
|
+
"type": "string"
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
"required": [
|
|
100
|
+
"messageId",
|
|
101
|
+
"commandId",
|
|
102
|
+
"status",
|
|
103
|
+
"reason"
|
|
104
|
+
]
|
|
105
|
+
}
|
|
106
|
+
]
|
|
107
|
+
}
|