sockjs

Documentation

Index

• Variables
• func DefaultJSessionID(rw http.ResponseWriter, req *http.Request)
• type Handler
  • func NewHandler(prefix string, opts Options, handlerFunc func(Session)) *Handler
  • func (h *Handler) Prefix() string
  • func (h *Handler) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type Options
• type ReceiverType
• type Session
  • func (s Session) Close(status uint32, reason string) error
  • func (s Session) Context() context.Context
  • func (s Session) GetSessionState() SessionState
  • func (s Session) ID() string
  • func (s Session) ReceiverType() ReceiverType
  • func (s Session) Recv() (string, error)
  • func (s Session) RecvCtx(ctx context.Context) (string, error)
  • func (s Session) Request() *http.Request
  • func (s Session) Send(msg string) error
• type SessionState

Examples

• NewHandler (DefaultMux)
• NewHandler (Simple)

Variables

var DefaultOptions = Options{
	Websocket:           true,
	RawWebsocket:        false,
	JSessionID:          nil,
	SockJSURL:           "//cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js",
	HeartbeatDelay:      25 * time.Second,
	DisconnectDelay:     5 * time.Second,
	ResponseLimit:       128 * 1024,
	WebsocketUpgrader:   &websocket.Upgrader{},
	DisableXHR:          false,
	DisableXHRStreaming: false,
	DisableEventSource:  false,
	DisableHtmlFile:     false,
	DisableJSONP:        false,
}

DefaultOptions is a convenient set of options to be used for sockjs

var (
	// ErrSessionNotOpen error is used to denote session not in open state.
	// Recv() and Send() operations are not supported if session is closed.
	ErrSessionNotOpen = errors.New("sockjs: session not in open state")
)

Functions

func DefaultJSessionID

func DefaultJSessionID(rw http.ResponseWriter, req *http.Request)

DefaultJSessionID is a default behaviour function to be used in options for JSessionID if JSESSIONID is needed

Types

type Handler

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

func NewHandler

func NewHandler(prefix string, opts Options, handlerFunc func(Session)) *Handler

NewHandler creates new HTTP handler that conforms to the basic net/http.Handler interface. It takes path prefix, options and sockjs handler function as parameters

Example (DefaultMux)

package main

import (
	"net/http"

	"github.com/igm/sockjs-go/v3/sockjs"
)

func main() {
	handler := sockjs.NewHandler("/echo", sockjs.DefaultOptions, func(session sockjs.Session) {
		for {
			if msg, err := session.Recv(); err == nil {
				if session.Send(msg) != nil {
					break
				}
			} else {
				break
			}
		}
	})
	// need to provide path prefix for http.Mux
	http.Handle("/echo/", handler)
	_ = http.ListenAndServe(":8080", nil)
}

Example (Simple)

package main

import (
	"net/http"

	"github.com/igm/sockjs-go/v3/sockjs"
)

func main() {
	handler := sockjs.NewHandler("/echo", sockjs.DefaultOptions, func(session sockjs.Session) {
		for {
			if msg, err := session.Recv(); err == nil {
				if session.Send(msg) != nil {
					break
				}
			} else {
				break
			}
		}
	})
	_ = http.ListenAndServe(":8080", handler)
}

func (*Handler) Prefix

func (h *Handler) Prefix() string

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type Options

type Options struct {
	// Transports which don't support cross-domain communication natively ('eventsource' to name one) use an iframe trick.
	// A simple page is served from the SockJS server (using its foreign domain) and is placed in an invisible iframe.
	// Code run from this iframe doesn't need to worry about cross-domain issues, as it's being run from domain local to the SockJS server.
	// This iframe also does need to load SockJS javascript client library, and this option lets you specify its url (if you're unsure,
	// point it to the latest minified SockJS client release, this is the default). You must explicitly specify this url on the server
	// side for security reasons - we don't want the possibility of running any foreign javascript within the SockJS domain (aka cross site scripting attack).
	// Also, sockjs javascript library is probably already cached by the browser - it makes sense to reuse the sockjs url you're using in normally.
	SockJSURL string
	// Most streaming transports save responses on the client side and don't free memory used by delivered messages.
	// Such transports need to be garbage-collected once in a while. `response_limit` sets a minimum number of bytes that can be send
	// over a single http streaming request before it will be closed. After that client needs to open new request.
	// Setting this value to one effectively disables streaming and will make streaming transports to behave like polling transports.
	// The default value is 128K.
	ResponseLimit uint32
	// Some load balancers don't support websockets. This option can be used to disable websockets support by the server. By default websockets are enabled.
	Websocket bool
	// This option can be used to enable raw websockets support by the server. By default raw websockets are disabled.
	RawWebsocket bool
	// Provide a custom Upgrader for Websocket connections to enable features like compression.
	// See https://godoc.org/github.com/gorilla/websocket#Upgrader for more details.
	WebsocketUpgrader *websocket.Upgrader
	// WebsocketWriteTimeout is a custom write timeout for Websocket underlying network connection.
	// A zero value means writes will not time out.
	WebsocketWriteTimeout time.Duration
	// In order to keep proxies and load balancers from closing long running http requests we need to pretend that the connection is active
	// and send a heartbeat packet once in a while. This setting controls how often this is done.
	// By default a heartbeat packet is sent every 25 seconds.
	HeartbeatDelay time.Duration
	// The server closes a session when a client receiving connection have not been seen for a while.
	// This delay is configured by this setting.
	// By default the session is closed when a receiving connection wasn't seen for 5 seconds.
	DisconnectDelay time.Duration
	// Some hosting providers enable sticky sessions only to requests that have JSessionID cookie set.
	// This setting controls if the server should set this cookie to a dummy value.
	// By default setting JSessionID cookie is disabled. More sophisticated behaviour can be achieved by supplying a function.
	JSessionID func(http.ResponseWriter, *http.Request)
	// CORS origin to be set on outgoing responses. If set to the empty string, it will default to the
	// incoming `Origin` header, or "*" if the Origin header isn't set.
	Origin string
	// CheckOrigin allows to dynamically decide whether server should set CORS
	// headers or not in case of XHR requests. When true returned CORS will be
	// configured with allowed origin equal to incoming `Origin` header, or "*"
	// if the request Origin header isn't set. When false returned CORS headers
	// won't be set at all. If this function is nil then Origin option above will
	// be taken into account.
	CheckOrigin func(*http.Request) bool

	// DisableXHR This option can be used to restrict handler to use XHR method. By default, DisableXHR is false, meaning that handler is allowed to use XHR
	DisableXHR bool

	// DisableXHRStreaming This option can be used to restrict handler to use XHRStreaming method. By default, DisableXHRStreaming is false, meaning that handler is allowed to use XHRStreaming
	DisableXHRStreaming bool

	// DisableEventSource This option can be used to restrict handler to use EventSource method. By default, DisableEventSource is false, meaning that handler is allowed to use EventSource
	DisableEventSource bool

	DisableHtmlFile bool

	// DisableJSONP is option can be used to restrict handler to use JSONP  method. By default, DisableJSONP is false, meaning that handler is allowed to use JSONP
	DisableJSONP bool
}

Options type is used for defining various sockjs options

type ReceiverType

type ReceiverType int

const (
	ReceiverTypeNone ReceiverType = iota
	ReceiverTypeXHR
	ReceiverTypeEventSource
	ReceiverTypeHtmlFile
	ReceiverTypeJSONP
	ReceiverTypeXHRStreaming
	ReceiverTypeRawWebsocket
	ReceiverTypeWebsocket
)

type Session

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

func (Session) Close

func (s Session) Close(status uint32, reason string) error

Close closes the session with provided code and reason.

func (Session) Context

func (s Session) Context() context.Context

Context returns session context, the context is cancelled whenever the session gets into closing or closed state

func (Session) GetSessionState

func (s Session) GetSessionState() SessionState

GetSessionState returns the current state of the session

func (Session) ID

func (s Session) ID() string

ID returns a session id

func (Session) ReceiverType

func (s Session) ReceiverType() ReceiverType

ReceiverType returns receiver used in session

func (Session) Recv

func (s Session) Recv() (string, error)

Recv reads one text frame from session

func (Session) RecvCtx

func (s Session) RecvCtx(ctx context.Context) (string, error)

RecvCtx reads one text frame from session

func (Session) Request

func (s Session) Request() *http.Request

Request returns the first http request

func (Session) Send

func (s Session) Send(msg string) error

Send sends one text frame to session

type SessionState

type SessionState uint32

SessionState defines the current state of the session

const (
	// brand new session, need to send "h" to receiver
	SessionOpening SessionState = iota
	// active session
	SessionActive
	// session being closed, sending "closeFrame" to receivers
	SessionClosing
	// closed session, no activity at all, should be removed from handler completely and not reused
	SessionClosed
)