binarysocket

README

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

Documentation

Overview

Package binarysocket is a real-time bidirectional binary socket library for the web. It offers a clean, robust and efficient way 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.

Index

• Variables
• type Options
• type Server
  • func NewServer(opts ...*Options) *Server
  • func (s *Server) Accept() (net.Conn, error)
  • func (s *Server) Close() error
  • func (s *Server) IsClosed() bool
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Variables

var (
	// ErrClosed defines the error if the connection was closed.
	ErrClosed = errors.New("closed")
)

var (
	// Log is the public logrus value used internally.
	Log = logrus.New()
)

Types

type Options

type Options struct {
	// ReadBufferSize and WriteBufferSize specify I/O buffer sizes. If a buffer
	// size is zero, then a default value of 4096 is used. The I/O buffer sizes
	// do not limit the size of the messages that can be sent or received.
	ReadBufferSize, WriteBufferSize int

	// CheckOrigin returns true if the request Origin header is acceptable. If
	// CheckOrigin is nil, the host in the Origin header must not be set or
	// must match the host of the request.
	// This method is used by the backend sockets before establishing connections.
	CheckOrigin func(r *http.Request) bool

	// DisableAjax deactivates the ajax backend.
	DisableAjax bool
}

Options define the BinarySocket optional options.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server implements the web server which handles the websocket and ajax connections.

func NewServer

func NewServer(opts ...*Options) *Server

NewServer creates a new server instance. Optionally pass the BinarySocket options.

func (*Server) Accept

func (s *Server) Accept() (net.Conn, error)

Accept waits for the next client socket connection and returns a generic Conn. Returns ErrClosed if the server is closed.

func (*Server) Close

func (s *Server) Close() error

Close the server by blocking all new incoming connections. This does not close the http server.

func (*Server) IsClosed

func (s *Server) IsClosed() bool

IsClosed returns a boolean indicating if the server is closed. This does not indicate the http server state.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the HTTP Handler interface of the http package.