signalr

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2021 License: MIT Imports: 26 Imported by: 23

README

SignalR

Actions Status codecov PkgGoDev

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/philippseith/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) Abort 

func (h *Hub) Abort()

Abort aborts the current connection

func (*Hub) Clients 

func (h *Hub) Clients() HubClients

Clients returns the clients of this hub

func (*Hub) ConnectionID 

func (h *Hub) ConnectionID() string

ConnectionID gets the ID of the current connection

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)
	HubClients() HubClients
	// 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.

HubClients() allows to call all HubClients of the server from server-side, non-hub code. Note that HubClients.Caller() returns nil, because there is no real caller which can be reached over a HubConnection.

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.

Source Files

View all Source files

Directories

Path Synopsis
middleware
public
mux module
router module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.