signalr

README

Azure SignalR Client for Golang

Quickly and easily build real-time communications into your web application

With Azure SignalR Service, adding real-time communications to your web application is as simple as provisioning a service—no need to be a real-time communications guru!

Getting Started

Installing the library

Use go get to acquire and install from source. We recommend using Go modules if you can. For more information on modules, see the Go modules wiki.

With go get:

go get -u github.com/devigned/signalr-go

If you need to install Go, follow the official instructions

Examples

Find up-to-date examples and documentation on godoc.org.

Documentation

Overview

Package signalr provides a simple interface for sending and receiving messages via the Azure SignalR service. For more information about the Azure SignalR service see https://aka.ms/signalr-go.

Index

• type Client
  • func NewClient(connStr string, hubName string, opts ...ClientOption) (*Client, error)
  • func (c *Client) AddUserToGroup(ctx context.Context, groupName string, userID string) error
  • func (c *Client) BroadcastAll(ctx context.Context, msg *InvocationMessage) error
  • func (c *Client) BroadcastGroup(ctx context.Context, msg *InvocationMessage, groupName string) error
  • func (c *Client) GetHub() string
  • func (c *Client) GetName() string
  • func (c *Client) Listen(ctx context.Context, handler Handler) error
  • func (c *Client) RemoveUserFromAllGroups(ctx context.Context, userID string) error
  • func (c *Client) RemoveUserFromGroup(ctx context.Context, groupName string, userID string) error
  • func (c *Client) SendInvocation(ctx context.Context, uri string, msg *InvocationMessage) error
  • func (c *Client) SendToUser(ctx context.Context, msg *InvocationMessage, userID string) error
• type ClientOption
  • func ClientWithName(name string) ClientOption
• type Handler
• type HandlerFunc
  • func (hf HandlerFunc) Default(ctx context.Context, target string, args []json.RawMessage) error
• type InvocationMessage
  • func NewInvocationMessage(target string, args ...interface{}) (*InvocationMessage, error)
• type NotifiedHandler
  • func NewNotifiedHandler(base Handler, onStart func()) NotifiedHandler
• type ParsedConnString
  • func ParseConnectionString(connStr string) (*ParsedConnString, error)
• type SendFailureError
  • func (sfe SendFailureError) Error() string

Examples

• Client.AddUserToGroup
• Client.BroadcastAll
• Client.BroadcastGroup
• Client.Listen
• Client.RemoveUserFromAllGroups
• Client.SendToUser
• ClientWithName
• NewClient

Types

type Client

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

Client represents a bidirectional connection to Azure SignalR

func NewClient

func NewClient(connStr string, hubName string, opts ...ClientOption) (*Client, error)

NewClient constructs a new client given a set of construction options

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := "chat"
client, err := signalr.NewClient(connStr, hubName)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println(client.GetHub())

Output:

chat

func (*Client) AddUserToGroup

func (c *Client) AddUserToGroup(ctx context.Context, groupName string, userID string) error

AddUserToGroup will add a userID to a SignalR group

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
groupName := "someGroup"
clientName := "client42"
client, err := signalr.NewClient(connStr, hubName, signalr.ClientWithName(clientName))
if err != nil {
	fmt.Println(err)
	return
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

if err := client.AddUserToGroup(ctx, groupName, client.GetName()); err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("added user %q to group %q\n", clientName, groupName)

Output:

added user "client42" to group "someGroup"

func (*Client) BroadcastAll

func (c *Client) BroadcastAll(ctx context.Context, msg *InvocationMessage) error

BroadcastAll will send a broadcast `InvocationMessage` to all listening to the hub

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
client, err := signalr.NewClient(connStr, hubName)
if err != nil {
	fmt.Println(err)
	return
}

ctx, cancel := context.WithCancel(context.Background())

started := make(chan struct{}, 1)
mph := &MessagePrinterHandler{
	onStart: func() {
		started <- struct{}{}
	},
	cancel: cancel,
}

go func() {
	err = client.Listen(ctx, mph)
	if err != nil {
		fmt.Println(err)
		started <- struct{}{}
	}
}()
<-started

msg, err := signalr.NewInvocationMessage("Println", "hello world!")
if err != nil {
	fmt.Println(err)
	return
}

err = client.BroadcastAll(ctx, msg)
if err != nil {
	fmt.Println(err)
	return
}

// wait for the `MessagePrinterHandler` to call cancel on the context
<-ctx.Done()

Output:

hello world!

func (*Client) BroadcastGroup

func (c *Client) BroadcastGroup(ctx context.Context, msg *InvocationMessage, groupName string) error

BroadcastGroup will send a broadcast `InvocationMessage` to all listening to the hub group

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
groupName := randomName("group", 5)
client, err := signalr.NewClient(connStr, hubName)
if err != nil {
	fmt.Println(err)
	return
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
if err := client.AddUserToGroup(ctx, groupName, client.GetName()); err != nil {
	fmt.Println(err)
	return
}

started := make(chan struct{}, 1)
mph := &MessagePrinterHandler{
	onStart: func() {
		started <- struct{}{}
	},
	cancel: cancel,
}

go func() {
	err = client.Listen(ctx, mph)
	if err != nil {
		fmt.Println(err)
		started <- struct{}{}
	}
}()
<-started

msg, err := signalr.NewInvocationMessage("Println", "I'm part of the cool group")
if err != nil {
	fmt.Println(err)
	return
}

err = client.BroadcastGroup(ctx, msg, groupName)
if err != nil {
	fmt.Println(err)
	return
}

// wait for the `MessagePrinterHandler` to call cancel on the context
<-ctx.Done()

Output:

I'm part of the cool group

func (*Client) GetHub

func (c *Client) GetHub() string

GetHub returns the name of the SignalR hub the client is targeting

func (*Client) GetName

func (c *Client) GetName() string

GetName returns the name of the client

func (*Client) Listen

func (c *Client) Listen(ctx context.Context, handler Handler) error

Listen will start the WebSocket connection for the client

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
client, err := signalr.NewClient(connStr, hubName)
if err != nil {
	fmt.Println(err)
	return
}

listenCtx, cancel := context.WithCancel(context.Background())

started := make(chan struct{}, 1)
mph := &MessagePrinterHandler{
	onStart: func() {
		fmt.Println("I'm listening")
		started <- struct{}{}
		cancel()
	},
}
// since `MessagePrinterHandler` implements `NotifiedHandler` it will receive a call to `OnStart` when listening

go func() {
	err = client.Listen(listenCtx, mph)
	if err != nil {
		fmt.Println(err)
		started <- struct{}{}
	}
}()
<-started

Output:

I'm listening

func (*Client) RemoveUserFromAllGroups

func (c *Client) RemoveUserFromAllGroups(ctx context.Context, userID string) error

RemoveUserFromAllGroups will remove a user from all groups

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
clientName := "client42"
client, err := signalr.NewClient(connStr, hubName, signalr.ClientWithName(clientName))
if err != nil {
	fmt.Println(err)
	return
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

if err := client.RemoveUserFromAllGroups(ctx, client.GetName()); err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("removed user %q from all groups\n", clientName)

Output:

removed user "client42" from all groups

func (*Client) RemoveUserFromGroup

func (c *Client) RemoveUserFromGroup(ctx context.Context, groupName string, userID string) error

RemoveUserFromGroup will remove a userID from a SignalR group

func (*Client) SendInvocation

func (c *Client) SendInvocation(ctx context.Context, uri string, msg *InvocationMessage) error

SendInvocation will send an `InvocationMessage` to the hub

func (*Client) SendToUser

func (c *Client) SendToUser(ctx context.Context, msg *InvocationMessage, userID string) error

SendToUser will send a `InvocationMessage` to a particular user

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
clientName := randomName("client", 5)
client, err := signalr.NewClient(connStr, hubName, signalr.ClientWithName(clientName))
if err != nil {
	fmt.Println(err)
	return
}

ctx, cancel := context.WithCancel(context.Background())

started := make(chan struct{}, 1)
mph := &MessagePrinterHandler{
	onStart: func() {
		started <- struct{}{}
	},
	cancel: cancel,
}

go func() {
	err = client.Listen(ctx, mph)
	if err != nil {
		fmt.Println(err)
		started <- struct{}{}
	}
}()
<-started

msg, err := signalr.NewInvocationMessage("Println", "hello only to you")
if err != nil {
	fmt.Println(err)
	return
}

err = client.SendToUser(ctx, msg, clientName)
if err != nil {
	fmt.Println(err)
	return
}

// wait for the `MessagePrinterHandler` to call cancel on the context
<-ctx.Done()

Output:

hello only to you

type ClientOption

type ClientOption func(*Client) error

ClientOption provides a way to configure a client at time of construction

func ClientWithName

func ClientWithName(name string) ClientOption

ClientWithName configures a SignalR client to use a specific name for addressing the client individually

If a client name is provided, a random name will be assigned to the client and can be accessed via `client.GetName()`

Example

connStr := os.Getenv("SIGNALR_CONNECTION_STRING")
hubName := randomName("example", 5)
clientName := "myName123"
client, err := signalr.NewClient(connStr, hubName, signalr.ClientWithName(clientName))
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println(client.GetName()) // client can be addressed directly from this name

Output:

myName123

type Handler

type Handler interface {
	Default(ctx context.Context, target string, args []json.RawMessage) error
}

Handler is the default handler implementation for receiving SignalR invocations

type HandlerFunc

type HandlerFunc func(ctx context.Context, target string, args []json.RawMessage) error

HandlerFunc is a type converter that allows a func to be used as a `Handler`

func (HandlerFunc) Default

func (hf HandlerFunc) Default(ctx context.Context, target string, args []json.RawMessage) error

Default redirects this call to the func that was provided

type InvocationMessage

type InvocationMessage struct {
	Type         messageType       `json:"type,omitempty"`
	Headers      map[string]string `json:"headers,omitempty"`
	InvocationID string            `json:"invocationId,omitempty"`
	Target       string            `json:"target"`
	Arguments    []json.RawMessage `json:"arguments"`
	Error        string            `json:"error,omitempty"`
}

InvocationMessage is the structure expected for sending and receiving in the SignalR protocol

func NewInvocationMessage

func NewInvocationMessage(target string, args ...interface{}) (*InvocationMessage, error)

NewInvocationMessage creates a new `InvocationMessage` from a target method name and arguments

type NotifiedHandler

type NotifiedHandler interface {
	Handler
	OnStart()
}

NotifiedHandler is a message handler which also provides an OnStart hook

func NewNotifiedHandler

func NewNotifiedHandler(base Handler, onStart func()) NotifiedHandler

NewNotifiedHandler creates a new `NotifiedHandler` for responding to SignalR invocations

type ParsedConnString

type ParsedConnString struct {
	Endpoint *url.URL
	Key      string
	Version  string
}

ParsedConnString is the structure extracted from a SignalR connection string

func ParseConnectionString

func ParseConnectionString(connStr string) (*ParsedConnString, error)

ParseConnectionString will parse the SignalR connection string from the Azure Portal

type SendFailureError

type SendFailureError struct {
	StatusCode int
	Body       string
}

SendFailureError provides added error information when a send message call fails

func (SendFailureError) Error

func (sfe SendFailureError) Error() string