https://github.com/chancehudson/especial
Websocket based communication protocol
https://github.com/chancehudson/especial
Last synced: over 1 year ago
JSON representation
Websocket based communication protocol
- Host: GitHub
- URL: https://github.com/chancehudson/especial
- Owner: chancehudson
- Created: 2020-08-01T01:21:33.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-08-07T13:11:29.000Z (almost 4 years ago)
- Last Synced: 2025-03-10T12:53:31.096Z (over 1 year ago)
- Language: JavaScript
- Size: 271 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# especial  
A websocket based communication protocol.
## Usage
`npm install especial`
### Server
```js
const especial = require('especial')
const app = especial()
app.handle('utils.ping', (data, send, next) => {
send('pong')
})
const server = app.listen(4000, () => {
console.log(`Listening on port 4000`)
})
```
### Client
```js
const EspecialClient = require('especial/client')
const client = new EspecialClient('ws://localhost:4000')
const { data, message, status } = await client.send('utils.ping')
console.log(message) // "pong"
```
## Protocol
Especial communicates across websockets using JSON encoded payloads. Clients emit a payload with a unique id and the server is expected to respond with a single message with the same id.
### Request
Requests are structured like this:
```json
{
"_rid": "jki7uo9XsOEJkel3PrF_T",
"route": "utils.ping",
"data": {}
}
```
The fields are as follows:
- `_rid`: A unique identifier for the request
- `route`: A string indicating the function to execute
- `data`: An object containing arbitrary data for the function
### Response
Responses are structured like this:
```json
{
"_rid": "jki7uo9XsOEJkel3PrF_T",
"route": "utils.ping",
"data": {},
"message": "pong",
"status": 0
}
```
- `_rid`: The same \_rid emitted in the matching request
- `route`: The route requested
- `data`: Arbitrary data returned from the function
- `message`: String info about function execution
- `status`: Integer representing execution result, `0` indicates success
### Broadcast
In addition to simple request/response communication servers may send data to clients without a request being made. This can be used to update data or provide new information.
The structure of such a message is the same as a response, with the `_rid` being a simple string the client may subscribe to.