README
¶
Documentation
¶
Overview ¶
Package wschannel implements the jrpc2 Channel interface over a websocket.
For jrpc2, see https://godoc.org/github.com/creachadair/jrpc2. For websockets see https://datatracker.ietf.org/doc/html/rfc6455. This package uses the nhooyr.io/websocket library.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrListenerClosed = errors.New("listener is closed")
ErrListenerClosed is the error reported for a closed listener.
Functions ¶
This section is empty.
Types ¶
type Channel ¶
type Channel struct {
// contains filtered or unexported fields
}
Channel implements the jrpc2 Channel interface over a websocket.
On the client side, use the Dial function to connect to a websocket endpoint and negotiate a connection.
On the server side, you can either use NewListener to create a listener that plugs in to the http.Handler interface automatically, or handle the upgrade negotation explicitly and call New to construct a Channel.
func Dial ¶
func Dial(url string, opts *DialOptions) (*Channel, error)
Dial is a shorthand for DialContext with a background context.
func DialContext ¶
DialContext dials the specified websocket URL ("ws://....") with the given options and negotiates a client channel with the server.
func (*Channel) Close ¶
Close shuts down the websocket. The first Close triggers a websocket close handshake, but does not block for its completion.
func (*Channel) Done ¶
func (c *Channel) Done() <-chan struct{}
Done returns a channel that is closed when c is closed.
type DialOptions ¶
type DialOptions struct {
// If non-nil, use this HTTP client instead of the default.
HTTPClient *http.Client
// If set, send these HTTP headers during the websocket handshake.
Header http.Header
}
DialOptions are settings for a client channel. A nil *DialOptions is ready for use and provides default values as described.
type ListenOptions ¶
type ListenOptions struct {
// The maximum number of unaccepted (pending) connections that will be
// admitted by the listener. Connections in excess of this will be rejected.
// If MaxPending ≤ 0, the default limit is 1.
MaxPending int
// If set, this function is called on each HTTP request received by the
// listener, before attempting to upgrade.
//
// If CheckAccept reports an error, no upgrade is attempted, and the error
// is returned to the caller. If an error is being reported, the int value
// is used as the HTTP status code if it is greater than 0; otherwise the
// handler reports code 500 (server internal error).
//
// If CheckAccept is not set, all requests are upgraded.
CheckAccept func(req *http.Request) (int, error)
// If set, include these HTTP headers when negotiating a connection upgrade.
Header http.Header
}
ListenOptions are settings for a listener. A nil *ListenOptions is ready for use and provides default values as described.
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
A Listener implements the http.Handler interface to bridge websocket requests to channels. Each connection served to the listener is made available to the Accept method, and its corresponding handler remains open until the channel is closed.
After the listener is closed, no further connections will be admitted and any unaccepted pending connections are discarded.
func NewListener ¶
func NewListener(opts *ListenOptions) *Listener
NewListener constructs a new listener with the given options. Use opts == nil for default settings (see ListenOptions). A Listener implements the http.Handler interface, and the caller can use the Accept method to obtain connected channels served by the handler.
func (*Listener) Accept ¶
Accept blocks until a channel is available or ctx ends. Accept returns ErrListenerClosed if the listener has closed. The caller must ensure the returned channel is closed. The concrete type of the channel returned is *wschannel.Channel.
func (*Listener) Close ¶
Close closes the listener, after which no further connections will be admitted, and any connections admitted but not yet accepted will be closed and discarded.
func (*Listener) ServeHTTP ¶
func (lst *Listener) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP implements the http.Handler interface. It upgrades the connection to a websocket, if possible, and enqueues a channel on the listener using the upgraded connection. Each invocation of the handler blocks until the corresponding channel closes.
Source Files