diff --git a/WebSocketLibCommuncationStandard.md b/WebSocketLibCommuncationStandard.md new file mode 100644 index 0000000..5f8ec20 --- /dev/null +++ b/WebSocketLibCommuncationStandard.md @@ -0,0 +1,107 @@ +# Getiyo WebSocket Bridge + +Document that describes the messaging standard that Getiyo uses for WebSocket communication with external software and tools. + +## Connection + +Connect with a WebSocket client to the address of the Getiyo instance, use the port that is specified in your Getiyo config (default 4081). + +## Authentication + +Once you're connected to the WebSocket server it is very important you immediately send an `AUTH` message. If you are unable to authenticate within 5 seconds you'll be automatically disconnected. For authentication feedback see [errors](#message-type-error), if the authentication is succesful you'll receive the `SYSTEM` message `authOk` + +```JSON +{ + "packet": "AUTH", + "channelId": "fakeChannelId123", + "moduleIds": [ + "fakeModuleId1", + "fadeModuleId2" + ], + "apiKey": "fakeApiKey" +} +``` + +## Message Encoding/Decoding + +Messages are encoded as stringified JSON. Each message **always** includes a `packet` attributes. This attributes specifies the packet type, see the types below. This format applies to both directions of communication. + +## Message type `NORMAL` + +Normal messaging from module to external service. + +```typescript +api.Libs.getWebSocket().broadcast('setScore', 'fakePlayerId123', 10); +``` + +```JSON +{ + "packet": "NORMAL", + "header": "setScore", + "args": [ + "fakePlayerId123", + 10 + ] +} +``` + +Messaging from external service to module. + +```JSON +{ + "packet": "NORMAL", + "moduleId": "fakeTargetModuleId", + "header": "setScore", + "args": [ + "fakePlayerId123", + 10 + ] +} +``` + +## Message type `ERROR` + +There are a messages that can only be send by Getiyo and contain server-side errors. The system message packet **always** contains a `type` attribute which specifies the system message type and a `message` attribute that has the actual error. + +```JSON +{ + "packet": "SYSTEM", + "type": "auth", + "message": "An error message." +} +``` + +### `auth` + +Invalid authentication. + +### `notExist` + +Channel/Module/WebSocket Listeners + +## Message type `SYSTEM` + +There are a messages that can only be send by Getiyo and contain general data. The system message packet **always** contains a `type` attribute which specifies the system message type. + +### `id` + +The id of the socket client once authentication was completed. + +```JSON +{ + "packet": "SYSTEM", + "type": "id", + "id": "fakeSocketClientId123" +} +``` + +### `authOk` + +Triggered when the authentication was completed. + +```JSON +{ + "packet": "SYSTEM", + "type": "authOk", +} +``` diff --git a/_Sidebar.md b/_Sidebar.md index ee5e361..2908fa8 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -32,6 +32,7 @@ - [Important Principals](./ModuleServerAPIPrincipals) - [Libs](./ModuleServerAPILibs) - [LibWebSocket](./ModuleServerAPILibsWebSocketLib) + - [Communication Standard](./WebSocketLibCommuncationStandard) - [Axios](https://axios-http.com/docs/instance) ### [ModuleServerAPI GameLib](./ModuleServerAPIGameLibIntroduction)