README
¶
websocket-service 
This service provides WebSocket handling that allows separation of WebSocket connection handling from application servers. Whenever a WebSocket connection is made or a message is received, a message is sent to your application server. Whenever your application server wishes to respond with a message, it can send a message to the WebSocket service cluster.
Why?
Separating WebSocket handling into a separate service has many advantages:
- The service is easy to scale, and it scales independently of your application. You don't need to worry about scaling up your application servers to be able to support the long-lived connections and file descriptors that WebSockets require.
- The service can improve your availability. The service is stateless, so it can trivially be used in multi-region or even multi-cloud deployments.
- As a side-effect of the multi-region capabilities, the service can improve your clients' performance by serving their connections from locations geographically closer to them.
- The service makes your application deployments faster and less disruptive. By decoupling WebSocket handling from your business logic, you don't need to sever or drain WebSocket connections when you deploy application updates.
- Eliminating WebSocket handling from your application may enable your application to be deployed to "serverless" environments.
- The service eliminates a common source of server-to-server traffic within your cluster as you no longer need to worry about routing traffic destined for WebSocket connections.
Architecture
The service itself is very transport-agnostic. The only transport protocol you are required to use is the WebSocket protocol for client connections. The service can communicate with your origin or other nodes within the cluster via any means you'd like. For example, if you're deploying the service to a single AWS VPC, you may use UDP for inter-node communication and SQS for service-origin communication:
Developing
The only external dependency is the Go dependency manager, dep.
After installing dep, you can download the dependencies via dep ensure.
You can then use the standard Go commands (e.g. go test ./...).
Documentation
¶
Index ¶
- type Address
- type Cluster
- type Connection
- type ConnectionHandler
- type ConnectionId
- type Origin
- type OriginFunc
- type OriginRequest
- type OutgoingWebSocketMessage
- type Service
- type ServiceRequest
- type WebSocketEvent
- type WebSocketEventConnectionClosed
- type WebSocketEventConnectionEstablished
- type WebSocketKeepAlive
- type WebSocketMessage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cluster ¶
type Cluster interface {
// Returns the address of the local node. Other nodes in the cluster should be able to send
// messages to this node using this address.
Address() Address
SendServiceRequest(address Address, r *ServiceRequest) error
}
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
func NewConnection ¶
func NewConnection(conn *websocket.Conn, logger logrus.FieldLogger, handler ConnectionHandler) *Connection
func (*Connection) Close ¶
func (c *Connection) Close() error
func (*Connection) Send ¶
func (c *Connection) Send(msg *websocket.PreparedMessage)
type ConnectionHandler ¶
type ConnectionHandler interface {
HandleWebSocketMessage(msg *WebSocketMessage)
HandleClose()
}
type ConnectionId ¶
type ConnectionId []byte
func NewConnectionId ¶
func NewConnectionId(address Address) (ConnectionId, error)
func (ConnectionId) Address ¶
func (id ConnectionId) Address() Address
func (ConnectionId) String ¶
func (id ConnectionId) String() string
type Origin ¶
type Origin interface {
SendOriginRequest(*OriginRequest) error
}
type OriginFunc ¶
type OriginFunc func(*OriginRequest) error
func (OriginFunc) SendOriginRequest ¶
func (f OriginFunc) SendOriginRequest(r *OriginRequest) error
type OriginRequest ¶
type OriginRequest struct {
WebSocketEvent *WebSocketEvent
// The service will periodically send keep-alives, which don't represent actual websocket
// events, but just let you know the connections are still alive and well.
WebSocketKeepAlives []*WebSocketKeepAlive
}
type OutgoingWebSocketMessage ¶
type OutgoingWebSocketMessage struct {
ConnectionIds []ConnectionId
Message *WebSocketMessage
}
type Service ¶
type Service struct {
// The subprotocols to advertise during WebSocket negotiation.
Subprotocols []string
// Origin provides a means of sending messages to the origin server.
Origin Origin
// Cluster provides a means of sending messages to other nodes in the cluster.
Cluster Cluster
// If non-zero, the origin will receive keep-alive events for WebSocket connections. These
// events don't represent any actual WebSockett activity, but indicate that the connection is
// still alive and healthy.
KeepAliveInterval time.Duration
// The logger to use. If nil, the standard logger will be used.
Logger logrus.FieldLogger
// contains filtered or unexported fields
}
func (*Service) CloseConnection ¶
func (s *Service) CloseConnection(id ConnectionId) error
func (*Service) ConnectionCount ¶
func (*Service) HandleServiceRequest ¶
func (s *Service) HandleServiceRequest(r *ServiceRequest)
type ServiceRequest ¶
type ServiceRequest struct {
OutgoingWebSocketMessages []*OutgoingWebSocketMessage
}
type WebSocketEvent ¶
type WebSocketEvent struct {
ConnectionId ConnectionId
ConnectionEstablished *WebSocketEventConnectionEstablished
ConnectionClosed *WebSocketEventConnectionClosed
MessageReceived *WebSocketMessage
}
type WebSocketEventConnectionClosed ¶
type WebSocketEventConnectionClosed struct{}
type WebSocketEventConnectionEstablished ¶
type WebSocketEventConnectionEstablished struct {
Subprotocol string
}
type WebSocketKeepAlive ¶
type WebSocketKeepAlive struct {
ConnectionId ConnectionId
}
type WebSocketMessage ¶
func (*WebSocketMessage) PreparedMessage ¶
func (msg *WebSocketMessage) PreparedMessage() (*websocket.PreparedMessage, error)
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.