turnpike

README

turnpike

Go implementation of WAMP - The Websocket Application Messaging Protocol

Turnpike provides a WAMP server and client.

Examples

chat

Very simple chat server and client written in Dart. To run, first install Dart (Dart editor should work as well), then:

cd examples/dart
pub install
./build.sh
go run server.go

Open a browser (or more) to localhost:8080. Type in the textbox and hit enter.

hello

Connect to a Turnpike server with autobahn.js:

cd examples/hello
go run server.go

Open a browser to localhost:8080. You should see a message when autobahn.js connects to Turnpike.

Documentation

Overview

Package turnpike provides a Websocket Application Messaging Protocol (WAMP) server and client

Index

• Variables
• func HandleWebsocket(t Handler) func(*websocket.Conn)
• type CallResult
• type Client
  • func NewClient() *Client
  • func (c *Client) Call(procURI string, args ...interface{}) chan CallResult
  • func (c *Client) Connect(server, origin string) error
  • func (c *Client) Prefix(prefix, URI string) error
  • func (c *Client) Publish(topicURI string, event interface{}, opts ...interface{}) error
  • func (c *Client) PublishExcludeMe(topicURI string, event interface{}) error
  • func (c *Client) SetSessionOpenCallback(f func(string))
  • func (c *Client) Subscribe(topicURI string, f EventHandler) error
  • func (c *Client) Unsubscribe(topicURI string) error
• type ConnectionNotification
• type DisconnectionNotification
• type EventHandler
• type Handler
• type Notification
• type PubHandler
• type RPCError
  • func (e RPCError) Error() string
• type RPCHandler
• type Server
  • func NewServer() *Server
  • func (t *Server) ConnectedClients() []string
  • func (t *Server) HandleWebsocket(conn *websocket.Conn)
  • func (t *Server) RegisterPubHandler(uri string, f PubHandler)
  • func (t *Server) RegisterRPC(uri string, f RPCHandler)
  • func (t *Server) RegisterSubHandler(uri string, f SubHandler)
  • func (t *Server) SendEvent(topic string, event interface{})
  • func (t *Server) SetSessionOpenCallback(f func(string))
  • func (t *Server) UnregisterPubHandler(uri string)
  • func (t *Server) UnregisterRPC(uri string)
  • func (t *Server) UnregisterSubHandler(uri string)
• type SubHandler
• type SubscriptionNotification
• type UnsubscriptionNotification
• type WAMPError
  • func (e *WAMPError) Error() string

Variables

var (
	// An ErrInvalidURI describes an invalid URI.
	ErrInvalidURI = &WAMPError{"invalid URI"}
	// An ErrInvalidNumArgs describes invalid number of arguments in a message.
	ErrInvalidNumArgs = &WAMPError{"invalid number of arguments in message"}
	// An ErrUnsupportedProtocol describes an unsupported WAMP protocol in a welcome message.
	ErrUnsupportedProtocol = &WAMPError{"unsupported protocol"}
)

Functions

func HandleWebsocket

func HandleWebsocket(t Handler) func(*websocket.Conn)

HandleWebsocket is a Go1.0 shim for method values.

Types

type CallResult

type CallResult struct {
	// Result contains the RPC call result returned by the server.
	Result interface{}
	// Error is nil on call success otherwise it contains the RPC error.
	Error error
}

CallResult represents either a sucess or a failure after a RPC call.

type Client

type Client struct {
	// SessionId is a ID of the session in UUID4 format received at the start of the session.
	SessionId string
	// ProtocolVersion is the version of the WAMP protocol received at the start of the session.
	ProtocolVersion int
	// ServerIdent is the server ID (ie "turnpike, autobahn") received at the start of the session.
	ServerIdent string
	// contains filtered or unexported fields
}

Client represents a WAMP client that handles RPC and pub/sub.

func NewClient

func NewClient() *Client

NewClient creates a new WAMP client.

func (*Client) Call

func (c *Client) Call(procURI string, args ...interface{}) chan CallResult

Call makes a RPC call on the server identified by procURI (in either full URI or CURIE format) with zero or more args. Returns a channel that will receive the call result (or error) on completion.

Ref: http://wamp.ws/spec#call_message

func (*Client) Connect

func (c *Client) Connect(server, origin string) error

Connect will connect to server with an optional origin. More details here: http://godoc.org/code.google.com/p/go.net/websocket#Dial

func (*Client) Prefix

func (c *Client) Prefix(prefix, URI string) error

Prefix sets a CURIE prefix at the server for later use when interacting with the server. prefix is the first part of a CURIE (ie "calc") and URI is a full identifier (ie "http://example.com/simple/calc#") that is mapped to the prefix.

Ref: http://wamp.ws/spec#prefix_message

func (*Client) Publish

func (c *Client) Publish(topicURI string, event interface{}, opts ...interface{}) error

Publish publishes an event to the topicURI that gets sent to all subscribers of that topicURI by the server. opts can can be either empty, one boolean that can be used to exclude outself from receiving the event or two lists; the first a list of clients to exclude and the second a list of clients that are eligible to receive the event. Either list can be empty.

Ref: http://wamp.ws/spec#publish_message

func (*Client) PublishExcludeMe

func (c *Client) PublishExcludeMe(topicURI string, event interface{}) error

PublishExcludeMe is a short hand for Publish(tobicURI, event, true) that will not send the event to ourself.

func (*Client) SetSessionOpenCallback

func (c *Client) SetSessionOpenCallback(f func(string))

SetSessionOpenCallback adds a callback function that is run when a new session begins. The callback function must accept a string argument that is the session ID.

func (*Client) Subscribe

func (c *Client) Subscribe(topicURI string, f EventHandler) error

Subscribe adds a subscription at the server for events with topicURI lasting for the session or until Unsubscribe is called.

Ref: http://wamp.ws/spec#subscribe_message

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(topicURI string) error

Unsubscribe removes a previous subscription with topicURI at the server.

Ref: http://wamp.ws/spec#unsubscribe_message

type ConnectionNotification

type ConnectionNotification struct {
	ConnectionId string
}

type DisconnectionNotification

type DisconnectionNotification struct {
	ConnectionId string
}

type EventHandler

type EventHandler func(topicURI string, event interface{})

EventHandler is an interface for handlers to published events. The topicURI is the URI of the event and event is the event centents.

type Handler

type Handler interface {
	HandleWebsocket(*websocket.Conn)
}

Handler is a interface to support Go1.0.

type Notification

type Notification interface {
}

type PubHandler

type PubHandler func(topicURI string, event interface{}) (string, interface{})

PubHandler is an interface that handlers for publishes should implement to get notified on a client publish with the possibility to modify the event. The event that will be published should be returned.

type RPCError

type RPCError struct {
	URI         string
	Description string
	Details     interface{}
}

RPCError represents a call error and is the recommended way to return an error from a RPC handler.

func (RPCError) Error

func (e RPCError) Error() string

Error returns an error description.

type RPCHandler

type RPCHandler func(clientID string, topicURI string, args ...interface{}) (interface{}, error)

RPCHandler is an interface that handlers to RPC calls should implement. The first parameter is the call ID, the second is the proc URI. Last comes all optional arguments to the RPC call. The return can be of any type that can be marshaled to JSON, or a error (preferably RPCError but any error works.) NOTE: this may be broken in v2 if multiple-return is implemented

type Server

type Server struct {
	websocket.Server
	// SubscriptionNotifications
	SubscriptionNotifications chan Notification
	ConnectionNotifications   chan Notification
	// contains filtered or unexported fields
}

Server represents a WAMP server that handles RPC and pub/sub.

func NewServer

func NewServer() *Server

NewServer creates a new WAMP server.

func (*Server) ConnectedClients

func (t *Server) ConnectedClients() []string

ConnectedClients returns a slice of the ids of all connected clients

func (*Server) HandleWebsocket

func (t *Server) HandleWebsocket(conn *websocket.Conn)

HandleWebsocket implements the go.net/websocket.Handler interface.

func (*Server) RegisterPubHandler

func (t *Server) RegisterPubHandler(uri string, f PubHandler)

RegisterPubHandler adds a handler called when a client publishes to URI. The event can be modified in the handler and the returned event is what is published to the other clients.

func (*Server) RegisterRPC

func (t *Server) RegisterRPC(uri string, f RPCHandler)

RegisterRPC adds a handler for the RPC named uri.

func (*Server) RegisterSubHandler

func (t *Server) RegisterSubHandler(uri string, f SubHandler)

RegisterSubHandler adds a handler called when a client subscribes to URI. The subscription can be canceled in the handler by returning false, or approved by returning true.

func (*Server) SendEvent

func (t *Server) SendEvent(topic string, event interface{})

SendEvent sends an event with topic directly (not via Client.Publish())

func (*Server) SetSessionOpenCallback

func (t *Server) SetSessionOpenCallback(f func(string))

SetSessionOpenCallback adds a callback function that is run when a new session begins. The callback function must accept a string argument that is the session ID.

func (*Server) UnregisterPubHandler

func (t *Server) UnregisterPubHandler(uri string)

UnregisterPubHandler removes a publish handler for the URI.

func (*Server) UnregisterRPC

func (t *Server) UnregisterRPC(uri string)

UnregisterRPC removes a handler for the RPC named uri.

func (*Server) UnregisterSubHandler

func (t *Server) UnregisterSubHandler(uri string)

UnregisterSubHandler removes a subscription handler for the URI.

type SubHandler

type SubHandler func(clientID string, topicURI string) bool

SubHandler is an interface that handlers for subscriptions should implement to control with subscriptions are valid. A subscription is allowed by returning true or denied by returning false.

type SubscriptionNotification

type SubscriptionNotification struct {
	SessionId string
	TopicURI  string
}

type UnsubscriptionNotification

type UnsubscriptionNotification struct {
	SessionId string
	TopicURI  string
}

type WAMPError

type WAMPError struct {
	Msg string
}

A WAMPError is returned when attempting to create a message that does not follow the WAMP protocol

func (*WAMPError) Error

func (e *WAMPError) Error() string

Error implements the error interface to provide a message.