BinarySocket - Binary Web Sockets
BinarySocket is a real-time bidirectional binary socket library for the web. It offers a clean, robust and efficient solution to connect webbrowsers with a go-backend in a simple way. It automatically detects supported socket layers and chooses the most suitable one. This library offers a net.Conn interface on the go-backend site and a similar net.Conn interface on the client javascript site. That's awesome, right?
You already have a Go application using a TCP connection? Just drop in the BinarySocket package, fire up a HTTP server and that's it. No further adaptions are required in the backend. Instead of writing one backend which is responsible to communicate with web-application and another backend which communicates with other go programs, BinarySocket eliminates this duplication.
In a normal scenario a high-level communication protocol is stacked on top of BinarySocket. Example: PAKT Project
Socket layers
Two socket layers are supported:
- WebSockets - This is the primary option. They are used if the webbrowser supports WebSockets defined by RFC 6455.
- AjaxSockets - This socket layer is used as a fallback mode.
Introduction
Golang Backend
// Create a new binarysocket server.
server := binarysocket.NewServer()
// Set the binarysocket server handler.
http.Handle("/binsocket", server)
// Setup your http server.
// ...
// Start accepting net.Conn connections.
conn, err := server.Accept()
// ...Javascript Frontend
var socket = BinarySocket.open("/binsocket");
socket.onOpen = function() {
console.log("opened");
socket.write(BinarySocket.stringToBytes("Hello World!"));
};
socket.onClose = function() {
console.log("closed");
};
socket.onError = function(msg) {
console.log("error:", msg);
};
socket.onRead = function(data) {
console.log("read:", BinarySocket.bytesToString(data));
};Sample
Check the sample directory for a simple server and client example.
Installation
Javascript
The client javascript library is located in client/dist/binarysocket.min.js.
You can use bower to install the client library:
bower install --save binarysocket
Golang
Get the source and start hacking.
go get -u github.com/desertbit/binarysocket
Import it with:
import "github.com/desertbit/binarysocket"Byte Encoding
BinarySocket takes care about the byte order (endianness). The default byte encoding is in network order (big endian). BinarySocket includes a simple javascript byte handling library. For more information check the ByteBuffer project.
var bb = BinarySocket.newByteBuffer(data)
var st = BinarySocket.bytesToString(bytes)
var bs = BinarySocket.stringToBytes(str)API
Golang
For more information please check the Go Documentation.
Javascript
BinarySocket
// Open and return a new BinarySocket.
// The first argument is required. It defines a host which has to start with
// http:// or https:// or / for an absolute path using the current host.
// The second argument defines optional options.
BinarySocket.open(host, options)
// Create a new ByteBuffer.
// Optionally set the implicitGrowth boolean.
// Wrapper for JavaScript's ArrayBuffer/DataView maintaining index and default endianness.
// More information: https://github.com/desertbit/byte-buffer
BinarySocket.newByteBuffer(data, implicitGrowth)
// Convert an ArrayBuffer to a string.
BinarySocket.bytesToString(b)
// Convert a string to an ArrayBuffer.
BinarySocket.stringToBytes(s)Open Options
var options = {
// Force a socket type.
// Values: false, "WebSocket", "AjaxSocket"
forceSocketType: false,
// Kill the connect attempt after the timeout.
connectTimeout: 10000
};Socket
// Return the current socket type.
// Values: "WebSocket", "AjaxSocket"
socket.socketType()
// Close the socket connection.
socket.close()
// Returns a boolean whenever the socket is closed.
socket.isClosed()
// Write the ArrayBuffer to the socket.
socket.write(data)
// Function which is triggered as soon as the connection is established.
socket.onOpen = function() {}
// Function which is triggered as soon as the connection closes.
socket.onClose = function() {}
// Function which is triggered as soon as the connection closes with an error.
// An optional error message is passed.
// onClose is also triggered afterwards.
socket.onError = function(msg) {}
// Function which is triggered as soon as new bytes are received.
// The passed data is an ArrayBuffer.
socket.onRead = function(data) {}Author
Roland Singer
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent