README
Project moved
This project has moved here. This repository is deprecated.
ws-promise-server
ws-promise-server
is a tiny framework that builds a request-response model onto HTML5 WebSockets using ES2015 Promises. You can use this with ES2017's await
/async
to simplify your WebSocket API.
The official client to use with this server is available at kdex/ws-promise-client.
The protocol that servers and clients carry out is kdex/ws-rpc-client, a minimal RPC protocol.
Getting started
The following code creates a WebSocket server and allows you to reply to a specific message sent by a client without you needing to put any kind of message ID anywhere.
import WS from "ws-promise-server";
const server = new WS({
port: 8080
});
(async () => {
await server.open();
server.on("connection", rpc => {
rpc.on("computePrimes", async message => {
try {
const primes = await computePrimes();
await message.reply(...primes);
/* In this line, the client will have received the reply */
}
catch (e) {
/* In this line, the client might have disconnected */
}
});
});
})();
API reference
WS.constructor(options)
Constructs a new ws-promise-server
instance. The options
argument will be passed to the constructor of ws
once you open the connection.
async WS.prototype.open()
Starts listening. The entire options
object will be passed to the constructor of ws
. Once the server is listening, the Promise
will resolve. If there is an error, the Promise
will reject.
async WS.prototype.close()
Closes the server by disconnecting all clients and closing the TCP socket. Once the port is free for use again, the Promise
will resolve. If there is an error while closing, the Promise
will reject.
Events
The following standard WebSocket server events can be handled with on(event, handler)
:
- error
- headers
- connection
For a list of client events you can handle, check out the RPC protocol that defines them.