rpep-websockets

This is a Websocket transport for rpep.js using theturtle32/WebSocket-Node. RPEP is a simple, light-weight protocol for request-response and stream-event style communication between peers.

Install

yarn install rpep-websockets

Usage

Accessing rpep websockets:

// node.js
var rpepWebsockets = require('rpep-websockets')

// node.js style for the browser (eg webpack)
var rpepWebsockets = require('rpep-websockets/ws.browser')

// amd
require.config({paths: {rpepWebsockets: '../dist/rpep-websockets.umd.js'}})
require(['rpepWebsockets'], function(rpepWebsockets) { /* your code */ })

// global variable
<script src="rpep-websockets.umd.js"></script>
rpepWebsockets; // rpep-websockets.umd.js can define rpepWebsockets globally if you really
             //   want to shun module-based design

API:

• var transport = rpepWebsockets() - Creates a new instance of the transport (to be passed into rpep's constructor).

• transport.connect(host, port, [connectionOptions,] rpepOptions) - Connects to a websocket host. These arguments will be passed through to this method from a call to rpep.connect.

  • connectionOptions for node.js - These are theturtle32/WebSocket-Node WebSocketClient options. Important ones being:
    • protocol - (Default: 'ws') Either 'wss' or 'ws'
    • wsProtocols - A string or array of strings representing the websocket-protocols to request.
    • origin
    • headers
    • requestOptions
  • connectionOptions for the browser:
    • binaryType - The binaryType property of a websocket connection. Defaults to "arraybuffer", which is what the theturtle32/WebSocket-Node library used for node.js requires.
    • protocol - (Default: 'ws') Either 'wss' or 'ws'.
  • rpepOptions are pass through arguments that don't affect the operation of this transport.

• transport.listen(port, [listenerOptions,] rpepOptions, requestHandler) - Listens for websocket connections. These arguments will be passed through to this method from a call to rpep.listen. This method only exists for the node.js version. You can't listen for websocket connections from a browser.

  • port - Optional if listenerOptions.httpServer is passed.
  • listenerOptions- These are theturtle32/WebSocket-Node WebSocketServer options. Important ones being:
    • secure - (Default:false) If true and transportOptions.httpServer is undefined, will create an https server. If transportOptions.httpServer is defined, this is ignored.
    • secureOptions - The options to pass into https.createServer if secure is true.
    • httpServer - If this is defined, uses this server instead of creating a new one. The passed port won't be used. If no http/https server is passed, one will be created internally (http or https is determined by arguments passed to listen). For the browser, there are no transportOptions so none need be passed.
    • httpHandler(request, response) - If this is defined, it is a callback that's called when a normal http/https request comes through.
  • rpepOptions are pass through arguments that don't affect the operation of this transport.

How to Test

• Test for node: node test/test.node
• Test for browsers: node test/testServer

License

Released under the MIT license: http://opensource.org/licenses/MIT