README ¶
SignalR
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 and MessagePack is fully supported.
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"
"github.com/philippseith/signalr"
)
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(signalr.WithHTTPServeMux(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: JavaScript/TypeScript
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:
-
import the
signalr.js
library (orsignalr.min.js
); -
create a connection object using the
HubConnectionBuilder
; -
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;
- UI event handlers can use
-
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>
Client side: go
To handle callbacks from the server, create a receiver class which gets the server callbacks mapped to its methods:
type receiver struct {
signalr.Hub
}
func (c *receiver) Receive(msg string) {
fmt.Println(msg)
}
Receive
gets called when the server does something like this:
hub.Clients().Caller().Send("receive", message)
The client itself might be used like that:
// Create a Connection (with timeout for the negotiation process)
creationCtx, _ := context.WithTimeout(ctx, 2 * time.Second)
conn, err := signalr.NewHTTPConnection(creationCtx, address)
if err != nil {
return err
}
// Create the client and set a receiver for callbacks from the server
client, err := signalr.NewClient(ctx,
signalr.WithConnection(conn),
signalr.WithReceiver(receiver))
if err != nil {
return err
}
// Start the client loop
c.Start()
// Do some client work
ch := <-c.Invoke("update", data)
// ch gets the result of the update operation
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 totrue
, the logging will be enabled. The tests will log toos.Stderr
. - If
Debug
ist set totrue
, 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 formats Text (JSON) and Binary (MessagePack).
Basics ¶
The SignalR Protocol is a protocol for two-way RPC over any stream- or 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, WithConnection(NewNetConnection(ctx, conn)), TransferFormat("Binary), WithReceiver(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.
// Configurable HTTP connection conn, err := NewHTTPConnection(ctx, "http://example.com/hub", WithHTTPHeaders(..)) // Client with JSON encoding client, err := NewClient(ctx, WithConnection(conn), TransferFormat(TransferFormatText), WithReceiver(receiver)) client.Start()
The object which will receive server callbacks is passed to NewClient() by using the WithReceiver 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 serve 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(signalr.WithHTTPServeMux(router), "/hub") // 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. The methods which return a channel are not supported.
// 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 ¶
- Variables
- func AllowOriginPatterns(origins []string) func(Party) error
- func ChanReceiveTimeout(timeout time.Duration) func(Party) error
- func CtxPipe(ctx context.Context) (*PipeReader, *PipeWriter)
- func EnableDetailedErrors(enable bool) func(Party) error
- func HTTPTransports(transports ...TransportType) func(Party) error
- func HandshakeTimeout(timeout time.Duration) func(Party) error
- func HubFactory(factory func() HubInterface) func(Party) error
- func InsecureSkipVerify(skip bool) func(Party) error
- func KeepAliveInterval(interval time.Duration) func(Party) error
- func Logger(logger StructuredLogger, debug bool) func(Party) error
- func MaximumReceiveMessageSize(sizeInBytes uint) func(Party) error
- func ReadWriteWithContext(ctx context.Context, doRW func() (int, error), unblockRW func()) (int, error)
- func SimpleHubFactory(hubProto HubInterface) func(Party) error
- func StreamBufferCapacity(capacity uint) func(Party) error
- func TimeoutInterval(timeout time.Duration) func(Party) error
- func TransferFormat(format TransferFormatType) func(Party) error
- func UseHub(hub HubInterface) func(Party) error
- func WithBackoff(backoffFactory func() backoff.BackOff) func(party Party) error
- func WithConnection(connection Connection) func(party Party) error
- func WithConnector(connectionFactory func() (Connection, error)) func(Party) error
- func WithHTTPClient(client Doer) func(*httpConnection) error
- func WithHTTPHeaders(headers func() http.Header) func(*httpConnection) error
- func WithHTTPServeMux(serveMux *http.ServeMux) func() MappableRouter
- func WithHttpConnection(ctx context.Context, address string, options ...func(*httpConnection) error) func(Party) error
- func WithReceiver(receiver interface{}) func(Party) error
- func WithTransports(transports ...TransportType) func(*httpConnection) error
- type Client
- type ClientProxy
- type ClientState
- type Connection
- func HttpConnectionFactory(ctx context.Context, address string, options ...func(*httpConnection) error) (Connection, error)
- func NewHTTPConnection(ctx context.Context, address string, options ...func(*httpConnection) error) (Connection, error)
- func NewNetConnection(ctx context.Context, conn net.Conn) Connection
- type ConnectionBase
- type ConnectionWithTransferMode
- type Doer
- type GroupManager
- type Hub
- func (h *Hub) Abort()
- func (h *Hub) Clients() HubClients
- func (h *Hub) ConnectionID() string
- func (h *Hub) Context() context.Context
- func (h *Hub) Groups() GroupManager
- func (h *Hub) Initialize(ctx HubContext)
- func (h *Hub) Items() *sync.Map
- func (h *Hub) Logger() (info StructuredLogger, dbg StructuredLogger)
- func (h *Hub) OnConnected(string)
- func (h *Hub) OnDisconnected(string)
- type HubClients
- type HubContext
- type HubInterface
- type HubLifetimeManager
- type InvokeResult
- type MappableRouter
- type Party
- type PipeReader
- type PipeWriter
- type RWJobResult
- type Receiver
- type ReceiverInterface
- type Server
- type StructuredLogger
- type TransferFormatType
- type TransferMode
- type TransportType
Constants ¶
This section is empty.
Variables ¶
var ErrClosedPipe = errors.New("io: read/write on closed pipe")
ErrClosedPipe is the error used for read or write operations on a closed pipe.
var ErrUnableToConnect = errors.New("neither WithConnection nor WithConnector option was given")
Functions ¶
func AllowOriginPatterns ¶ added in v0.4.0
AllowOriginPatterns lists the host patterns for authorized origins which is used for avoid same origin strategy. See https://pkg.go.dev/nhooyr.io/websocket#AcceptOptions
func ChanReceiveTimeout ¶
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 CtxPipe ¶ added in v0.2.2
func CtxPipe(ctx context.Context) (*PipeReader, *PipeWriter)
CtxPipe creates a synchronous in-memory pipe. It can be used to connect code expecting an io.Reader with code expecting an io.Writer.
By canceling the context, Read and Write can be canceled ¶
Reads and Writes on the pipe are matched one to one except when multiple Reads are needed to consume a single Write. That is, each Write to the PipeWriter blocks until it has satisfied one or more Reads from the PipeReader that fully consume the written data. The data is copied directly from the Write to the corresponding Read (or Reads); there is no internal buffering.
It is safe to call Read and Write in parallel with each other or with Close. Parallel calls to Read and parallel calls to Write are also safe: the individual calls will be gated sequentially.
func EnableDetailedErrors ¶
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 ...TransportType) func(Party) error
HTTPTransports sets the list of available transports for http connections. Allowed transports are "WebSockets", "ServerSentEvents". Default is both transports are available.
func HandshakeTimeout ¶
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(factory func() HubInterface) func(Party) error
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 InsecureSkipVerify ¶ added in v0.4.0
InsecureSkipVerify disables Accepts origin verification behaviour which is used to avoid same origin strategy. See https://pkg.go.dev/nhooyr.io/websocket#AcceptOptions
func KeepAliveInterval ¶
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
Logger sets the logger used by the Party to log info events. If debug is true, debug log event are generated, too
func MaximumReceiveMessageSize ¶
MaximumReceiveMessageSize is the maximum size in bytes of a single incoming hub message. Default is 32768 bytes (32KB)
func ReadWriteWithContext ¶ added in v0.5.0
func ReadWriteWithContext(ctx context.Context, doRW func() (int, error), unblockRW func()) (int, error)
ReadWriteWithContext is a wrapper to make blocking io.Writer / io.Reader cancelable. It can be used to implement cancellation of connections. ReadWriteWithContext will return when either the Read/Write operation has ended or ctx has been canceled.
doRW func() (int, error)
doRW should contain the Read/Write operation.
unblockRW func()
unblockRW should contain the operation to unblock the Read/Write operation. If there is no way to unblock the operation, one goroutine will leak when ctx is canceled. As the standard use case when ReadWriteWithContext is canceled is the cancellation of a connection this leak will be problematic on heavily used servers with uncommon connection types. Luckily, the standard connection types for ServerSentEvents, Websockets and common net.Conn connections can be unblocked.
func SimpleHubFactory ¶
func SimpleHubFactory(hubProto HubInterface) func(Party) error
SimpleHubFactory sets a HubFactory which creates a new hub with the underlying type of hubProto on each hub method invocation.
func StreamBufferCapacity ¶
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 server processes stream items. Default is 10.
func TimeoutInterval ¶
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 TransferFormatType) func(Party) error
TransferFormat sets the transfer format used on the transport. Allowed values are "Text" and "Binary"
func UseHub ¶
func UseHub(hub HubInterface) func(Party) error
UseHub sets the hub instance used by the server
func WithBackoff ¶ added in v0.6.1
WithBackoff sets the backoff.BackOff used for repeated connection attempts in the client. See https://pkg.go.dev/github.com/cenkalti/backoff for configuration options. If the option is not set, backoff.NewExponentialBackOff() without any further configuration will be used.
func WithConnection ¶ added in v0.5.0
func WithConnection(connection Connection) func(party Party) error
WithConnection sets the Connection of the Client
func WithConnector ¶ added in v0.6.0
func WithConnector(connectionFactory func() (Connection, error)) func(Party) error
WithConnector allows the Client to establish a connection using the Connection build by the connectionFactory. It is also used for auto reconnect if the connection is lost.
func WithHTTPClient ¶ added in v0.5.0
WithHTTPClient sets the http client used to connect to the signalR server. The client is only used for http requests. It is not used for the websocket connection.
func WithHTTPHeaders ¶ added in v0.5.0
WithHTTPHeaders sets the function for providing request headers for HTTP and websocket requests
func WithHTTPServeMux ¶ added in v0.5.0
func WithHTTPServeMux(serveMux *http.ServeMux) func() MappableRouter
WithHTTPServeMux is a MappableRouter factory for MapHTTP which converts a http.ServeMux to a MappableRouter. For factories for other routers, see github.com/philippseith/signalr/router
func WithHttpConnection ¶ added in v0.6.3
func WithHttpConnection(ctx context.Context, address string, options ...func(*httpConnection) error) func(Party) error
WithHttpConnection first tries to create a connection with WebSockets (if it is allowed by the HttpConnection options) and if this fails, falls back to a SSE based connection. This strategy is also used for auto reconnect if this option is used. WithHttpConnection is a shortcut for WithConnector(HttpConnectionFactory(...))
func WithReceiver ¶ added in v0.5.0
WithReceiver sets the object which will receive server side calls to client methods (e.g. callbacks)
func WithTransports ¶ added in v0.6.3
func WithTransports(transports ...TransportType) func(*httpConnection) error
Types ¶
type Client ¶
type Client interface { Party Start() Stop() State() ClientState ObserveStateChanged(chan ClientState) context.CancelFunc Err() error WaitForState(ctx context.Context, waitFor ClientState) <-chan error 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 InvokeResult }
Client is the signalR connection used on the client side.
Start()
Start starts the client loop. After starting the client, the interaction with a server can be started. The client loop will run until the server closes the connection. If WithConnector is used, Start will start a new loop. To end the loop from the client side, the context passed to NewClient has to be canceled or the Stop function has to be called.
Stop()
Stop stops the client loop. This is an alternative to using a cancelable context on NewClient.
State() ClientState
State returns the current client state. When WithConnector is set and the server allows reconnection, the client switches to ClientConnecting and tries to reach ClientConnected after the last connection has ended.
ObserveStateChanged(chan ClientState) context.CancelFunc
ObserveStateChanged pushes a new item != nil to the channel when State has changed. The returned CancelFunc ends the observation and closes the channel.
Err() error
Err returns the last error occurred while running the client. When the client goes to ClientConnecting, Err is set to nil.
WaitForState(ctx context.Context, waitFor ClientState) <-chan error
WaitForState returns a channel for waiting on the Client to reach a specific ClientState. The channel either returns an error if ctx or the client has been canceled. or nil if the ClientState waitFor was reached.
Invoke(method string, arguments ...interface{}) <-chan InvokeResult
Invoke invokes a method on the server and returns a channel wich will return the InvokeResult. When failing, InvokeResult.Error contains the client side error.
Send(method string, arguments ...interface{}) <-chan error
Send invokes a method on the server but does not return a result from the server but only a channel, which might contain a client side error occurred while sending.
PullStream(method string, arguments ...interface{}) <-chan InvokeResult
PullStream invokes a streaming method on the server and returns a channel which delivers the stream items. For more info about Streaming see https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md#streaming
PushStreams(method string, arguments ...interface{}) <-chan error
PushStreams pushes all items received from its arguments of type channel to the server (Upload Streaming). PushStreams does not support server methods that return a channel. For more info about Upload Streaming see https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md#upload-streaming
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 ClientState ¶ added in v0.5.0
type ClientState int
ClientState is the state of the client.
const ( ClientCreated ClientState = iota ClientConnecting ClientConnected ClientClosed )
Client states
ClientCreated
The Client has been created and is not started yet.
ClientConnecting
The Client has been started and is negotiating the connection.
ClientConnected
The Client has successfully negotiated the connection and can send and receive messages.
ClientClosed
The Client is not able to send and receive messages anymore and has to be started again to be able to.
type Connection ¶
type Connection interface { io.Reader io.Writer Context() context.Context ConnectionID() string SetConnectionID(id string) }
Connection describes a connection between signalR client and server
func HttpConnectionFactory ¶ added in v0.6.3
func HttpConnectionFactory(ctx context.Context, address string, options ...func(*httpConnection) error) (Connection, error)
HttpConnectionFactory is a connectionFactory for WithConnector which first tries to create a connection with WebSockets (if it is allowed by the HttpConnection options) and if this fails, falls back to a SSE based connection.
func NewHTTPConnection ¶ added in v0.3.0
func NewHTTPConnection(ctx context.Context, address string, options ...func(*httpConnection) error) (Connection, error)
NewHTTPConnection creates a signalR HTTP Connection for usage with a Client. ctx can be used to cancel the SignalR negotiation during the creation of the Connection but not the Connection itself.
func NewNetConnection ¶
func NewNetConnection(ctx context.Context, conn net.Conn) Connection
NewNetConnection wraps net.Conn into a Connection
type ConnectionBase ¶
type ConnectionBase struct {
// contains filtered or unexported fields
}
ConnectionBase is a baseclass for implementers of the Connection interface.
func NewConnectionBase ¶ added in v0.5.0
func NewConnectionBase(ctx context.Context, connectionID string) *ConnectionBase
NewConnectionBase creates a new ConnectionBase
func (*ConnectionBase) ConnectionID ¶
func (cb *ConnectionBase) ConnectionID() string
ConnectionID is the ID of the connection.
func (*ConnectionBase) Context ¶
func (cb *ConnectionBase) Context() context.Context
Context can be used to wait for cancellation of the Connection
func (*ConnectionBase) SetConnectionID ¶
func (cb *ConnectionBase) SetConnectionID(id string)
SetConnectionID sets the ConnectionID
type ConnectionWithTransferMode ¶
type ConnectionWithTransferMode interface { TransferMode() TransferMode SetTransferMode(transferMode TransferMode) }
ConnectionWithTransferMode is a Connection with TransferMode (e.g. Websocket)
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) ConnectionID ¶
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) 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 ¶
OnConnected is called when the hub is connected
func (*Hub) OnDisconnected ¶
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 Context() context.Context 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 PipeReader ¶ added in v0.2.2
type PipeReader struct {
// contains filtered or unexported fields
}
A PipeReader is the read half of a pipe.
func (*PipeReader) Close ¶ added in v0.2.2
func (r *PipeReader) Close() error
Close closes the reader; subsequent writes to the write half of the pipe will return the error ErrClosedPipe.
func (*PipeReader) CloseWithError ¶ added in v0.2.2
func (r *PipeReader) CloseWithError(err error) error
CloseWithError closes the reader; subsequent writes to the write half of the pipe will return the error err.
CloseWithError never overwrites the previous error if it exists and always returns nil.
func (*PipeReader) Read ¶ added in v0.2.2
func (r *PipeReader) Read(data []byte) (n int, err error)
Read implements the standard Read interface: it reads data from the pipe, blocking until a writer arrives or the write end is closed. If the write end is closed with an error, that error is returned as err; otherwise err is EOF.
type PipeWriter ¶ added in v0.2.2
type PipeWriter struct {
// contains filtered or unexported fields
}
A PipeWriter is the write half of a pipe.
func (*PipeWriter) Close ¶ added in v0.2.2
func (w *PipeWriter) Close() error
Close closes the writer; subsequent reads from the read half of the pipe will return no bytes and EOF.
func (*PipeWriter) CloseWithError ¶ added in v0.2.2
func (w *PipeWriter) CloseWithError(err error) error
CloseWithError closes the writer; subsequent reads from the read half of the pipe will return no bytes and the error err, or EOF if err is nil.
CloseWithError never overwrites the previous error if it exists and always returns nil.
func (*PipeWriter) Write ¶ added in v0.2.2
func (w *PipeWriter) Write(data []byte) (n int, err error)
Write implements the standard Write interface: it writes data to the pipe, blocking until one or more readers have consumed all the data or the read end is closed. If the read end is closed with an error, that err is returned as err; otherwise err is ErrClosedPipe.
type RWJobResult ¶ added in v0.5.0
type RWJobResult struct {
// contains filtered or unexported fields
}
RWJobResult can be used to send the result of an io.Writer / io.Reader operation over a channel. Use it for special connection types, where ReadWriteWithContext does not fit all needs.
type Receiver ¶
type Receiver struct {
// contains filtered or unexported fields
}
Receiver is a base class for receivers in the client. It implements ReceiverInterface
type ReceiverInterface ¶ added in v0.5.0
ReceiverInterface allows receivers to interact with the server directly from the receiver methods
Init(Client)
Init is used by the Client to connect the receiver to the server.
Server() Client
Server can be used inside receiver methods to call Client methods, e.g. Client.Send, Client.Invoke, Client.PullStream and Client.PushStreams
type Server ¶
type Server interface { Party MapHTTP(routerFactory func() MappableRouter, path string) Serve(conn Connection) error 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 a path on a 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.
type StructuredLogger ¶
type StructuredLogger interface {
Log(keyVals ...interface{}) error
}
StructuredLogger is the simplest logging interface for structured logging. See github.com/go-kit/log
type TransferFormatType ¶ added in v0.6.3
type TransferFormatType string
var TransferFormatBinary TransferFormatType = "Binary"
var TransferFormatText TransferFormatType = "Text"
type TransferMode ¶
type TransferMode int
TransferMode is either TextTransferMode or BinaryTransferMode
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.
type TransportType ¶ added in v0.6.3
type TransportType string
var TransportServerSentEvents TransportType = "ServerSentEvents"
var TransportWebSockets TransportType = "WebSockets"
Source Files ¶
- Invokeresult.go
- client.go
- clientoptions.go
- clientproxy.go
- clientsseconnection.go
- connection.go
- connectionbase.go
- ctxpipe.go
- doc.go
- groupmanager.go
- httpconnection.go
- httpmux.go
- hub.go
- hubclients.go
- hubconnection.go
- hubcontext.go
- hublifetimemanager.go
- hubprotocol.go
- invokeclient.go
- jsonhubprotocol.go
- loop.go
- messagepackhubprotocol.go
- negotiateresponse.go
- netconnection.go
- options.go
- party.go
- receiver.go
- server.go
- serveroptions.go
- serversseconnection.go
- streamclient.go
- streamer.go
- websocketconnection.go