README

SignalR

Actions Status codecov PkgGoDev Go Report Card HitCount

SignalR is an open-source library that simplifies adding real-time web functionality to apps. Real-time web functionality enables server-side code to push content to clients instantly.

Historically it was tied to ASP.NET Core but the protocol is open and implementable in any language.

This repository contains an implementation of a SignalR server and a SignalR client in go. The implementation is based on the work of David Fowler at https://github.com/davidfowl/signalr-ports. Client and server support transport over WebSockets, Server Sent Events and raw TCP. Protocol encoding in JSON is fully supported, and there is MessagePack support for basic types.

Install

With a correctly configured Go toolchain:

go get -u github.com/philippeseith/signalr

Getting Started

SignalR uses a signalr.HubInterface instance to anchor the connection on the server and a javascript HubConnection object to anchor the connection on the client.

Server side
Implement the HubInterface

The easiest way to implement the signalr.HubInterface in your project is to declare your own type and embed signalr.Hub which implements that interface and will take care of all the signalr plumbing. You can call your custom type anything you want so long as it implements the signalr.HubInterface interface.

package main

import "github.com/philippseith/signalr"

type AppHub struct {
    signalr.Hub
}

Add functions with your custom hub type as a receiver.

func (h *AppHub) SendChatMessage(message string) {
    h.Clients().All().Send("chatMessageReceived", message)
}

These functions must be public so that they can be seen by the signalr server package but can be invoked client-side as lowercase message names. We'll explain setting up the client side in a moment, but as a preview, here's an example of calling our AppHub.SendChatMessage(...) method from the client:

    // javascript snippet invoking that AppHub.Send method from the client
    connection.invoke('sendChatMessage', val);

The signalr.HubInterface contains a pair of methods you can implement to handle connection and disconnection events. signalr.Hub contains empty implementations of them to satisfy the interface, but you can "override" those defaults by implementing your own functions with your custom hub type as a receiver:

func (c *chat) OnConnected(connectionID string) {
    fmt.Printf("%s connected\n", connectionID)
}

func (c *chat) OnDisconnected(connectionID string) {
   fmt.Printf("%s disconnected\n", connectionID)
}
Serve with http.ServeMux
import "net/http"

func runHTTPServer() {
    address := 'localhost:8080'
    
    // create an instance of your hub
    hub := AppHub{}
	
    // build a signalr.Server using your hub
    // and any server options you may need
    server, _ := signalr.NewServer(context.TODO(),
        signalr.SimpleHubFactory(hub)
        signalr.KeepAliveInterval(2*time.Second),
        signalr.Logger(kitlog.NewLogfmtLogger(os.Stderr), true))
    )
    
    // create a new http.ServerMux to handle your app's http requests
    router := http.NewServeMux()
    
    // ask the signalr server to map it's server
    // api routes to your custom baseurl
    server.MapHTTP(router, "/chat")

    // in addition to mapping the signalr routes
    // your mux will need to serve the static files
    // which make up your client-side app, including
    // the signalr javascript files. here is an example
    // of doing that using a local `public` package
    // which was created with the go:embed directive
    // 
    // fmt.Printf("Serving static content from the embedded filesystem\n")
    // router.Handle("/", http.FileServer(http.FS(public.FS)))
    
    // bind your mux to a given address and start handling requests
    fmt.Printf("Listening for websocket connections on http://%s\n", address)
    if err := http.ListenAndServe(address, router); err != nil {
        log.Fatal("ListenAndServe:", err)
    }
}
Client side
Grab copies of the signalr scripts

Microsoft has published the client-side libraries as a node package with embedded typescript annotations: @microsoft/signalr.

You can install @microsoft/signalr through any node package manager:

package manager command
npm npm install @microsoft/signalr@latest
yarn yarn add @microsoft/signalr@latest
LibMan libman install @microsoft/signalr@latest -p unpkg -d wwwroot/js/signalr --files dist/browser/signalr.js --files dist/browser/signalr.min.js --files dist/browser/signalr.map.js
none you can download the version we are using in our chatsample from here (the minified version is here)
Use a HubConnection to connect to your server Hub

How you format your client UI is going to depend on your application use case but here is a simple example. It illustrates the basic steps of connecting to your server hub:

  1. import the signalr.js library (or signalr.min.js);

  2. create a connection object using the HubConnectionBuilder;

  3. bind events

    • UI event handlers can use connection.invoke(targetMethod, payload) to send invoke functions on the server hub;
    • connection event handlers can react to the messages sent from the server hub;
  4. start your connection

<html>
<body>
    <!-- you may want the content you send to be dynamic -->
    <input type="text" id="message" />
    
    <!-- you may need a trigger to initiate the send -->
    <input type="button" value="Send" id="send" />
    
    <!-- you may want some container to display received messages -->
    <ul id="messages">
    </ul>

    <!-- 1. you need to import the signalr script which provides
            the HubConnectionBuilder and handles the connection
            plumbing.
    -->
    <script src="js/signalr.js"></script>
    <script>
    (async function () {
        // 2. use the signalr.HubConnectionBuilder to build a hub connection
        //    and point it at the baseurl which you configured in your mux
        const connection = new signalR.HubConnectionBuilder()
                .withUrl('/chat')
                .build();

        // 3. bind events:
        //    - UI events can invoke (i.e. dispatch to) functions on the server hub
        document.getElementById('send').addEventListener('click', sendClicked);
        //    - connection events can handle messages received from the server hub
        connection.on('chatMessageReceived', onChatMessageReceived);

        // 4. call start to initiate the connection and start streaming events
        //    between your server hub and your client connection
        connection.start();
        
        // that's it! your server and client should be able to communicate
        // through the signalr.Hub <--> connection pipeline managed by the
        // signalr package and client-side library.
        
        // --------------------------------------------------------------------
       
        // example UI event handler
        function sendClicked() {
            // prepare your target payload
            const msg = document.getElementById('message').value;
            if (msg) {
                // call invoke on your connection object to dispatch
                // messages to the server hub with two arguments:
                // -  target: name of the hub func to invoke
                // - payload: the message body
                // 
                const target = 'sendChatMessage';
                connection.invoke(target, msg);
            }
        }

        // example server event handler
        function onChatMessageReceived(payload) {
            // the payload is whatever was passed to the inner
            // clients' `Send(...)` method in your server-side
            // hub function.
           
            const li = document.createElement('li');
            li.innerText = payload;
            document.getElementById('messages').appendChild(li);
        }
    })();
    </script>
</body>
</html>
Debugging

Server, Client and the protocol implementations are able to log most of their operations. The logging option is disabled by default in all tests. To configure logging, edit the testLogConf.json file:

{
  "Enabled": false,
  "Debug": false
}
  • If Enabled is set to true, the logging will be enabled. The tests will log to os.Stderr.
  • If Debug ist set to true, the logging will be more detailed.

Documentation

Overview

package signalr contains a SignalR client and a SignalR server. Both support the transport types Websockets and Server-Sent Events and the transfer format Text (JSON). Rudimentary support for binary transfer format (MessagePack) is available.

Basics

The SignalR Protocol is a protocol for two-way RPC over any Message-based transport. Either party in the connection may invoke procedures on the other party, and procedures can return zero or more results or an error. Typically, SignalR connections are HTTP-based, but it is dead simple to implement a signalr.Connection on any transport that supports io.Reader and io.Writer.

Client

A Client can be used in client side code to access server methods. From an existing connection, it can be created with NewClient().

// NewClient with raw TCP connection and MessagePack encoding
conn, err := net.Dial("tcp", "example.com:6502")
client := NewClient(ctx, NewNetConnection(ctx, conn), TransferFormat("Binary), Receiver(receiver))
client.Start()

A special case is NewHTTPClient(), which creates a Client from a server address and negotiates with the server which kind of connection (Websockets, Server-Sent Events) will be used.

// NewHTTPClient with JSON encoding
client := NewHTTPClient(ctx, "http://example.com", TransferFormat("Text"), Receiver(receiver))
client.Start()

The object which will receive server callbacks is passed to NewClient() / NewHTTPClient() by using the Receiver option. After calling client.Start(), the client is ready to call server methods or to receive callbacks.

Server

A Server provides the public methods of a server side class over signalr to the client. Such a server side class is called a hub and must implement HubInterface. It is reasonable to derive your hubs from the Hub struct type, which already implements HubInterface. Servers for arbitrary connection types can be created with NewServer().

// Typical server with log level debug to Stderr
server, err := NewServer(ctx, SimpleHubFactory(hub), Logger(log.NewLogfmtLogger(os.Stderr), true))

To serve a connection, call server.Serve(connection) in a goroutine. Serve ends when the connection is closed or the servers context is canceled.

// Serving over TCP, accepting client who use MessagePack or JSON
addr, _ := net.ResolveTCPAddr("tcp", "localhost:6502")
listener, _ := net.ListenTCP("tcp", addr)
tcpConn, _ := listener.Accept()
go server.Serve(NewNetConnection(conn))

To server a HTTP connection, use server.MapHTTP(), which connects the server with a path in an http.ServeMux. The server then automatically negotiates which kind of connection (Websockets, Server-Sent Events) will be used.

// build a signalr.Server using your hub
// and any server options you may need
server, _ := signalr.NewServer(ctx,
    signalr.SimpleHubFactory(&AppHub{})
    signalr.KeepAliveInterval(2*time.Second),
    signalr.Logger(kitlog.NewLogfmtLogger(os.Stderr), true))
)

// create a new http.ServerMux to handle your app's http requests
router := http.NewServeMux()

// ask the signalr server to map it's server
// api routes to your custom baseurl
server.MapHTTP(router, "/chat")

// in addition to mapping the signalr routes
// your mux will need to serve the static files
// which make up your client-side app, including
// the signalr javascript files. here is an example
// of doing that using a local `public` package
// which was created with the go:embed directive
//
// fmt.Printf("Serving static content from the embedded filesystem\n")
// router.Handle("/", http.FileServer(http.FS(public.FS)))

// bind your mux to a given address and start handling requests
fmt.Printf("Listening for websocket connections on http://%s\n", address)
if err := http.ListenAndServe(address, router); err != nil {
    log.Fatal("ListenAndServe:", err)
}

Supported method signatures

The SignalR protocol constrains the signature of hub or receiver methods that can be used over SignalR. All methods with serializable types as parameters and return types are supported. Methods with multiple return values are not generally supported, but returning one or no value and an optional error is supported.

// Simple signatures for hub/receiver methods
func (mh *MathHub) Divide(a, b float64) (float64, error) // error on division by zero
func (ah *AlgoHub) Sort(values []string) []string
func (ah *AlgoHub) FindKey(value []string, dict map[int][]string) (int, error) // error on not found
func (receiver *View) DisplayServerValue(value interface{}) // will work for every serializable value

Methods which return a single sending channel (<-chan), and optionally an error, are used to initiate callee side streaming. The caller will receive the contents of the channel as stream. When the returned channel is closed, the stream will be completed.

// Streaming methods
func (n *Netflix) Stream(show string, season, episode int) (<-chan []byte, error) // error on password shared

Methods with one or multiple receiving channels (chan<-) as parameters are used as receivers for caller side streaming. The caller invokes this method and pushes one or multiple streams to the callee. The method should end when all channels are closed. A channel is closed by the server when the assigned stream is completed.

// Caller side streaming
func (mh *MathHub) MultiplyAndSum(a, b chan<- float64) float64

In most cases, the caller will be the client and the callee the server. But the vice versa case is also possible.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ChanReceiveTimeout

func ChanReceiveTimeout(timeout time.Duration) func(Party) error

    The Party option ChanReceiveTimeout is the timeout for processing stream items from the client, after StreamBufferCapacity was reached If the hub method is not able to process a stream item during the timeout duration, the server will send a completion with error. Default is 5 seconds.

    func EnableDetailedErrors

    func EnableDetailedErrors(enable bool) func(Party) error

      The Party option EnableDetailedErrors: If true, detailed exception messages are returned to the other Party when an exception is thrown in a Hub method. The default is false, as these exception messages can contain sensitive information.

      func HTTPTransports

      func HTTPTransports(transports ...string) func(Party) error

        The Server option HTTPTransports sets the list of available transports for http connections. Allowed transports are "WebSockets", "ServerSentEvents". Default is both transports are available.

        func HandshakeTimeout

        func HandshakeTimeout(timeout time.Duration) func(Party) error

          The Party option HandshakeTimeout is the interval if the other Party doesn't send an initial handshake message within, the connection is closed. This is an advanced setting that should only be modified if handshake timeout errors are occurring due to severe network latency. For more detail on the handshake process, see https://github.com/dotnet/aspnetcore/blob/master/src/SignalR/docs/specs/HubProtocol.md

          func HubFactory

          func HubFactory(factoryFunc func() HubInterface) func(Party) error

            The Server option HubFactory sets the function which returns the hub instance for every hub method invocation The function might create a new hub instance on every invocation. If hub instances should be created and initialized by a DI framework, the frameworks factory method can be called here.

            func KeepAliveInterval

            func KeepAliveInterval(interval time.Duration) func(Party) error

              The Party option KeepAliveInterval is the interval if the Party hasn't sent a message within, a ping message is sent automatically to keep the connection open. When changing KeepAliveInterval, change the Timeout setting on the other Party. The recommended Timeout value is double the KeepAliveInterval value. Default is 15 seconds.

              func Logger

              func Logger(logger StructuredLogger, debug bool) func(Party) error

                The Party option Logger sets the logger used by the Party to log info events. If debug is true, debug log event are generated, too

                func MaximumReceiveMessageSize

                func MaximumReceiveMessageSize(size uint) func(Party) error

                  The Party option MaximumReceiveMessageSize is the maximum size of a single incoming hub message. Default is 32KB

                  func NewNetConnection

                  func NewNetConnection(ctx context.Context, conn net.Conn) *netConnection

                  func Receiver

                  func Receiver(receiver interface{}) func(Party) error

                    The Client option Receiver sets the object which will receive server side calls to client methods (e.g. callbacks)

                    func SimpleHubFactory

                    func SimpleHubFactory(hubProto HubInterface) func(Party) error

                      The Server option SimpleHubFactory sets a HubFactory which creates a new hub with the underlying type of hubProto on each hub method invocation.

                      func StreamBufferCapacity

                      func StreamBufferCapacity(capacity uint) func(Party) error

                        The Party option StreamBufferCapacity is the maximum number of items that can be buffered for client upload streams. If this limit is reached, the processing of invocations is blocked until the the server processes stream items. Default is 10.

                        func TimeoutInterval

                        func TimeoutInterval(timeout time.Duration) func(Party) error

                          The Party option TimeoutInterval is the interval one Party will consider the other Party disconnected if it hasn't received a message (including keep-alive) in it. The recommended value is double the KeepAliveInterval value. Default is 30 seconds.

                          func TransferFormat

                          func TransferFormat(format string) func(Party) error

                            The Client option TransferFormat sets the transfer format used on the transport. Allowed values are "Text" and "Binary"

                            func UseHub

                            func UseHub(hub HubInterface) func(Party) error

                              The Server option UseHub sets the hub instance used by the server

                              Types

                              type Client

                              type Client interface {
                              	Party
                              	Start() error
                              	Stop() error
                              	// Closed() <-chan error TODO Define connection state
                              	Invoke(method string, arguments ...interface{}) <-chan InvokeResult
                              	Send(method string, arguments ...interface{}) <-chan error
                              	PullStream(method string, arguments ...interface{}) <-chan InvokeResult
                              	PushStreams(method string, arguments ...interface{}) <-chan error
                              }

                                Client is the signalR connection used on the client side

                                func NewClient

                                func NewClient(ctx context.Context, conn Connection, options ...func(Party) error) (Client, error)

                                  NewClient builds a new Client.

                                  func NewHTTPClient

                                  func NewHTTPClient(ctx context.Context, address string, options ...func(Party) error) (Client, error)

                                    NewHTTPClient creates a signalR Client which tries to connect over http to the given address

                                    type ClientProxy

                                    type ClientProxy interface {
                                    	Send(target string, args ...interface{})
                                    }

                                      ClientProxy allows the hub to send messages to one or more of its clients

                                      type Connection

                                      type Connection interface {
                                      	io.Reader
                                      	io.Writer
                                      	Context() context.Context
                                      	ConnectionID() string
                                      	SetConnectionID(id string)
                                      	Timeout() time.Duration
                                      	SetTimeout(duration time.Duration)
                                      }

                                        Connection describes a connection between signalR client and server

                                        type ConnectionBase

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

                                          ConnectionBase is a baseclass for implementers of the Connection interface.

                                          func (*ConnectionBase) ConnectionID

                                          func (cb *ConnectionBase) ConnectionID() string

                                          func (*ConnectionBase) Context

                                          func (cb *ConnectionBase) Context() context.Context

                                          func (*ConnectionBase) SetConnectionID

                                          func (cb *ConnectionBase) SetConnectionID(id string)

                                          func (*ConnectionBase) SetTimeout

                                          func (cb *ConnectionBase) SetTimeout(duration time.Duration)

                                          func (*ConnectionBase) Timeout

                                          func (cb *ConnectionBase) Timeout() time.Duration

                                          type ConnectionWithTransferMode

                                          type ConnectionWithTransferMode interface {
                                          	TransferMode() TransferMode
                                          	SetTransferMode(transferMode TransferMode)
                                          }

                                          type GroupManager

                                          type GroupManager interface {
                                          	AddToGroup(groupName string, connectionID string)
                                          	RemoveFromGroup(groupName string, connectionID string)
                                          }

                                            GroupManager manages the client groups of the hub

                                            type Hub

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

                                              Hub is a base class for hubs

                                              func (*Hub) Clients

                                              func (h *Hub) Clients() HubClients

                                                Clients returns the clients of this hub

                                                func (*Hub) Groups

                                                func (h *Hub) Groups() GroupManager

                                                  Groups returns the client groups of this hub

                                                  func (*Hub) Initialize

                                                  func (h *Hub) Initialize(ctx HubContext)

                                                    Initialize initializes a hub with a HubContext

                                                    func (*Hub) Items

                                                    func (h *Hub) Items() *sync.Map

                                                      Items returns the items for this connection

                                                      func (*Hub) Logger

                                                      func (h *Hub) Logger() (info StructuredLogger, dbg StructuredLogger)

                                                        Logger returns the loggers used in this server. By this, derived hubs can use the same loggers as the server.

                                                        func (*Hub) OnConnected

                                                        func (h *Hub) OnConnected(string)

                                                          OnConnected is called when the hub is connected

                                                          func (*Hub) OnDisconnected

                                                          func (h *Hub) OnDisconnected(string)

                                                            OnDisconnected is called when the hub is disconnected

                                                            type HubClients

                                                            type HubClients interface {
                                                            	All() ClientProxy
                                                            	Caller() ClientProxy
                                                            	Client(connectionID string) ClientProxy
                                                            	Group(groupName string) ClientProxy
                                                            }

                                                              HubClients gives the hub access to various client groups All() gets a ClientProxy that can be used to invoke methods on all clients connected to the hub Caller() gets a ClientProxy that can be used to invoke methods of the current calling client Client() gets a ClientProxy that can be used to invoke methods on the specified client connection Group() gets a ClientProxy that can be used to invoke methods on all connections in the specified group

                                                              type HubContext

                                                              type HubContext interface {
                                                              	Clients() HubClients
                                                              	Groups() GroupManager
                                                              	Items() *sync.Map
                                                              	ConnectionID() string
                                                              	Abort()
                                                              	Logger() (info StructuredLogger, dbg StructuredLogger)
                                                              }

                                                                HubContext is a context abstraction for a hub Clients() gets a HubClients that can be used to invoke methods on clients connected to the hub Groups() gets a GroupManager that can be used to add and remove connections to named groups Items() holds key/value pairs scoped to the hubs connection ConnectionID() gets the ID of the current connection Abort() aborts the current connection Logger() returns the logger used in this server

                                                                type HubInterface

                                                                type HubInterface interface {
                                                                	Initialize(hubContext HubContext)
                                                                	OnConnected(connectionID string)
                                                                	OnDisconnected(connectionID string)
                                                                }

                                                                  HubInterface is a hubs interface

                                                                  type HubLifetimeManager

                                                                  type HubLifetimeManager interface {
                                                                  	OnConnected(conn hubConnection)
                                                                  	OnDisconnected(conn hubConnection)
                                                                  	InvokeAll(target string, args []interface{})
                                                                  	InvokeClient(connectionID string, target string, args []interface{})
                                                                  	InvokeGroup(groupName string, target string, args []interface{})
                                                                  	AddToGroup(groupName, connectionID string)
                                                                  	RemoveFromGroup(groupName, connectionID string)
                                                                  }

                                                                    HubLifetimeManager is a lifetime manager abstraction for hub instances OnConnected() is called when a connection is started OnDisconnected() is called when a connection is finished InvokeAll() sends an invocation message to all hub connections InvokeClient() sends an invocation message to a specified hub connection InvokeGroup() sends an invocation message to a specified group of hub connections AddToGroup() adds a connection to the specified group RemoveFromGroup() removes a connection from the specified group

                                                                    type InvokeResult

                                                                    type InvokeResult struct {
                                                                    	Value interface{}
                                                                    	Error error
                                                                    }

                                                                      InvokeResult is the combined value/error result for async invocations. Used as channel type.

                                                                      type MappableRouter

                                                                      type MappableRouter interface {
                                                                      	HandleFunc(string, func(w http.ResponseWriter, r *http.Request))
                                                                      	Handle(string, http.Handler)
                                                                      }

                                                                        MappableRouter encapsulates the methods used by server.MapHTTP to configure the handlers required by the signalr protocol. this abstraction removes the explicit binding to http.ServerMux and allows use of any mux which implements those basic Handle and HandleFunc methods.

                                                                        type Party

                                                                        type Party interface {
                                                                        	// contains filtered or unexported methods
                                                                        }

                                                                          Party is the common base of Server and Client. The Party methods are only used internally, but the interface is public to allow using Options on Party as parameters for external functions

                                                                          type Server

                                                                          type Server interface {
                                                                          	Party
                                                                          	MapHTTP(mux MappableRouter, path string)
                                                                          	Serve(conn Connection)
                                                                          	// contains filtered or unexported methods
                                                                          }

                                                                            Server is a SignalR server for one type of hub.

                                                                            MapHTTP(mux *http.ServeMux, path string)
                                                                            

                                                                            maps the servers hub to an path on an http.ServeMux.

                                                                            Serve(conn Connection)
                                                                            

                                                                            serves the hub of the server on one connection. The same server might serve different connections in parallel. Serve does not return until the connection is closed or the servers context is canceled.

                                                                            func NewServer

                                                                            func NewServer(ctx context.Context, options ...func(Party) error) (Server, error)

                                                                              NewServer creates a new server for one type of hub. The hub type is set by one of the options UseHub, HubFactory or SimpleHubFactory

                                                                              type StructuredLogger

                                                                              type StructuredLogger interface {
                                                                              	Log(keyVals ...interface{}) error
                                                                              }

                                                                                StructuredLogger is the simplest logging interface for structured logging. See github.com/go-kit/kit/log

                                                                                type TransferMode

                                                                                type TransferMode int
                                                                                const (
                                                                                	// TextTransferMode is for UTF-8 encoded text messages like JSON.
                                                                                	TextTransferMode TransferMode = iota + 1
                                                                                	// BinaryTransferMode is for binary messages like MessagePack.
                                                                                	BinaryTransferMode
                                                                                )

                                                                                  MessageType constants.

                                                                                  Directories

                                                                                  Path Synopsis