gw

README

NATS <-> websocket gateway

A websocket gateway for NATS, usable as a backend for elm-nats and websocket-nats.

Features:

• TLS support
• Each NATS command is sent as a separate websocket message
• Provides a hook to change the CONNECT phase, allowing the http server to handle the connection itself (for example based on a cookie of the http request)
• Easily embeddable in a bigger http server
• Supports both text (default) and binary (by adding '?mode=binary' to the url) messages

Basic usage

Fetch the source:

go get -u github.com/orus-io/nats-websocket-gw

Install and run the default binary

go install github.com/orus-io/nats-websocket-gw/cmd/nats-websocket-gw
nats-websocket-gw --no-origin-check

and/or integrate it in your http server:

package main

import (
	"net/http"

	"github.com/orus-io/nats-websocket-gw"
)

func main() {
	gateway := gw.NewGateway(gw.Settings{
		NatsAddr: "localhost:4222",
	})
	http.HandleFunc("/nats", gateway.Handler)
	http.ListenAndServe("0.0.0.0:8910", nil)
}

How does it differ from other nats-websocket servers ?

• Rest to NATS Proxy provides a websocket based implementation. The approach is pretty different though, as the websockets do not transport the whole NATS protocol, but only the data of the messages (websockets are opened for each subscribed subject).

• ws-tcp-relay, which the proposed backend for websocket-nats is a generic ws-tcp gateway. As such, it:

  • does not allow for TLS connections to NATS because the TLS negociation cannot be done immediately (the NATS protocol has a clear text 'INFO' exchange before TLS handshake)
  • send websocket messages that may contain several NATS commands.

Documentation

Index

• type CommandsReader
  • func NewCommandsReader(src io.Reader) CommandsReader
  • func (cr CommandsReader) NextCommand() ([]byte, error)
• type ConnectHandler
• type ErrorHandler
• type Gateway
  • func NewGateway(settings Settings) *Gateway
  • func (gw *Gateway) Handler(w http.ResponseWriter, r *http.Request)
• type NatsConn
• type NatsServerInfo
• type Settings

Types

type CommandsReader

type CommandsReader struct {
	io.Reader
	// contains filtered or unexported fields
}

CommandsReader parses a NATS connection input stream into commands

func NewCommandsReader

func NewCommandsReader(src io.Reader) CommandsReader

NewCommandsReader creates a CommandsReader

func (CommandsReader) NextCommand

func (cr CommandsReader) NextCommand() ([]byte, error)

NextCommand returns the next command in the input stream

type ConnectHandler

type ConnectHandler func(*NatsConn, *http.Request, *websocket.Conn) error

ConnectHandler is used in Settings for handling the initial CONNECT of a nats connection

type ErrorHandler

type ErrorHandler func(error)

ErrorHandler is used in Settings for handling errors

type Gateway

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

Gateway is a HTTP handler that acts as a websocket gateway to a NATS server

func NewGateway

func NewGateway(settings Settings) *Gateway

NewGateway instanciates a Gateway

func (*Gateway) Handler

func (gw *Gateway) Handler(w http.ResponseWriter, r *http.Request)

Handler is a HTTP handler function

type NatsConn

type NatsConn struct {
	Conn       net.Conn
	CmdReader  CommandsReader
	ServerInfo NatsServerInfo
}

NatsConn holds a NATS TCP connection

type NatsServerInfo

type NatsServerInfo string

NatsServerInfo is the information returned by the INFO nats message

type Settings

type Settings struct {
	NatsAddr       string
	EnableTLS      bool
	TLSConfig      *tls.Config
	ConnectHandler ConnectHandler
	ErrorHandler   ErrorHandler
	WSUpgrader     *websocket.Upgrader
	Trace          bool
}

Settings configures a Gateway