func NetConn(ctxcontext.Context, c *Conn, msgTypeMessageType)net.Conn

type AcceptOptions struct {// Subprotocols lists the WebSocket subprotocols that Accept will negotiate with the client.// The empty subprotocol will always be negotiated as perRFC 6455. If you would like to// reject it, close the connection when c.Subprotocol() == "".Subprotocols []string// InsecureSkipVerify is used to disable Accept's origin verification behaviour.//// You probably want to use OriginPatterns instead.InsecureSkipVerifybool// OriginPatterns lists the host patterns for authorized origins.// The request host is always authorized.// Use this to enable cross origin WebSockets.//// i.e javascript running on example.com wants to access a WebSocket server at chat.example.com.// In such a case, example.com is the origin and chat.example.com is the request host.// One would set this field to []string{"example.com"} to authorize example.com to connect.//// Each pattern is matched case insensitively against the request origin host// with path.Match.// Seehttps://golang.org/pkg/path/#Match//// Please ensure you understand the ramifications of enabling this.// If used incorrectly your WebSocket server will be open to CSRF attacks.//// Do not use * as a pattern to allow any origin, prefer to use InsecureSkipVerify instead// to bring attention to the danger of such a setting.OriginPatterns []string// CompressionMode controls the compression mode.// Defaults to CompressionDisabled.//// See docs on CompressionMode for details.CompressionModeCompressionMode// CompressionThreshold controls the minimum size of a message before compression is applied.//// Defaults to 512 bytes for CompressionNoContextTakeover and 128 bytes// for CompressionContextTakeover.CompressionThresholdint// OnPingReceived is an optional callback invoked synchronously when a ping frame is received.//// The payload contains the application data of the ping frame.// If the callback returns false, the subsequent pong frame will not be sent.// To avoid blocking, any expensive processing should be performed asynchronously using a goroutine.OnPingReceived func(ctxcontext.Context, payload []byte)bool// OnPongReceived is an optional callback invoked synchronously when a pong frame is received.//// The payload contains the application data of the pong frame.// To avoid blocking, any expensive processing should be performed asynchronously using a goroutine.//// Unlike OnPingReceived, this callback does not return a value because a pong frame// is a response to a ping and does not trigger any further frame transmission.OnPongReceived func(ctxcontext.Context, payload []byte)}

type CloseError struct {CodeStatusCodeReasonstring}

func (CloseError)Error¶

func (ceCloseError) Error()string

type CompressionModeint

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

funcAccept¶

func Accept(whttp.ResponseWriter, r *http.Request, opts *AcceptOptions) (*Conn,error)

Accept accepts a WebSocket handshake from a client and upgrades thethe connection to a WebSocket.

Accept will not allow cross origin requests by default.See the InsecureSkipVerify and OriginPatterns options to allow cross origin requests.

Accept will write a response to w on all errors.

Note that using the http.Request Context after Accept returns may lead tounexpected behavior (see http.Hijacker).

package mainimport ("context""log""net/http""time""github.com/coder/websocket""github.com/coder/websocket/wsjson")func main() {// This handler accepts a WebSocket connection, reads a single JSON// message from the client and then closes the connection.fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {c, err := websocket.Accept(w, r, nil)if err != nil {log.Println(err)return}defer c.CloseNow()ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)defer cancel()var v interface{}err = wsjson.Read(ctx, c, &v)if err != nil {log.Println(err)return}c.Close(websocket.StatusNormalClosure, "")})err := http.ListenAndServe("localhost:8080", fn)log.Fatal(err)}

funcDial¶

func Dial(ctxcontext.Context, ustring, opts *DialOptions) (*Conn, *http.Response,error)

Dial performs a WebSocket handshake on url.

The response is the WebSocket handshake response from the server.You never need to close resp.Body yourself.

If an error occurs, the returned response may be non nil.However, you can only read the first 1024 bytes of the body.

This function requires at least Go 1.12 as it uses a new featurein net/http to perform WebSocket handshakes.See docs on the HTTPClient option andhttps://github.com/golang/go/issues/26937#issuecomment-415855861

URLs with http/https schemes will work and are interpreted as ws/wss.

package mainimport ("context""log""time""github.com/coder/websocket""github.com/coder/websocket/wsjson")func main() {// Dials a server, writes a single JSON message and then// closes the connection.ctx, cancel := context.WithTimeout(context.Background(), time.Minute)defer cancel()c, _, err := websocket.Dial(ctx, "ws://localhost:8080", nil)if err != nil {log.Fatal(err)}defer c.CloseNow()err = wsjson.Write(ctx, c, "hi")if err != nil {log.Fatal(err)}c.Close(websocket.StatusNormalClosure, "")}

func (*Conn)Close¶

func (c *Conn) Close(codeStatusCode, reasonstring) (errerror)

Close performs the WebSocket close handshake with the given status code and reason.

It will write a WebSocket close frame with a timeout of 5s and then wait 5s forthe peer to send a close frame.All data messages received from the peer during the close handshake will be discarded.

The connection can only be closed once. Additional calls to Closeare no-ops.

The maximum length of reason must be 125 bytes. Avoid sending a dynamic reason.

Close will unblock all goroutines interacting with the connection oncecomplete.

func (*Conn)CloseNow¶

func (c *Conn) CloseNow() (errerror)

CloseNow closes the WebSocket connection without attempting a close handshake.Use when you do not want the overhead of the close handshake.

func (*Conn)CloseRead¶

func (c *Conn) CloseRead(ctxcontext.Context)context.Context

CloseRead starts a goroutine to read from the connection until it is closedor a data message is received.

Once CloseRead is called you cannot read any messages from the connection.The returned context will be cancelled when the connection is closed.

If a data message is received, the connection will be closed with StatusPolicyViolation.

Call CloseRead when you do not expect to read any more messages.Since it actively reads from the connection, it will ensure that ping, pong and closeframes are responded to. This means c.Ping and c.Close will still work as expected.

This function is idempotent.

func (*Conn)Ping¶

func (c *Conn) Ping(ctxcontext.Context)error

Ping sends a ping to the peer and waits for a pong.Use this to measure latency or ensure the peer is responsive.Ping must be called concurrently with Reader as it doesnot read from the connection but instead waits for a Reader callto read the pong.

TCP Keepalives should suffice for most use cases.

package mainimport ("context""log""time""github.com/coder/websocket")func main() {// Dials a server and pings it 5 times.ctx, cancel := context.WithTimeout(context.Background(), time.Minute)defer cancel()c, _, err := websocket.Dial(ctx, "ws://localhost:8080", nil)if err != nil {log.Fatal(err)}defer c.CloseNow()// Required to read the Pongs from the server.ctx = c.CloseRead(ctx)for i := 0; i < 5; i++ {err = c.Ping(ctx)if err != nil {log.Fatal(err)}}c.Close(websocket.StatusNormalClosure, "")}

func (*Conn)Read¶

func (c *Conn) Read(ctxcontext.Context) (MessageType, []byte,error)

Read is a convenience method around Reader to read a single messagefrom the connection.

func (*Conn)Reader¶

func (c *Conn) Reader(ctxcontext.Context) (MessageType,io.Reader,error)

Reader reads from the connection until there is a WebSocketdata message to be read. It will handle ping, pong and close frames as appropriate.

It returns the type of the message and an io.Reader to read it.The passed context will also bound the reader.Ensure you read to EOF otherwise the connection will hang.

Call CloseRead if you do not expect any data messages from the peer.

Only one Reader may be open at a time.

If you need a separate timeout on the Reader call and the Read itself,use time.AfterFunc to cancel the context passed in.Seehttps://github.com/nhooyr/websocket/issues/87#issue-451703332Most users should not need this.

func (*Conn)SetReadLimit¶

func (c *Conn) SetReadLimit(nint64)

SetReadLimit sets the max number of bytes to read for a single message.It applies to the Reader and Read methods.

By default, the connection has a message read limit of 32768 bytes.

When the limit is hit, the connection will be closed with StatusMessageTooBig.

Set to -1 to disable.

func (*Conn)Subprotocol¶

func (c *Conn) Subprotocol()string

Subprotocol returns the negotiated subprotocol.An empty string means the default protocol.

func (*Conn)Write¶

func (c *Conn) Write(ctxcontext.Context, typMessageType, p []byte)error

Write writes a message to the connection.

See the Writer method if you want to stream a message.

If compression is disabled or the compression threshold is not met, then itwill write the message in a single frame.

func (*Conn)Writer¶

func (c *Conn) Writer(ctxcontext.Context, typMessageType) (io.WriteCloser,error)

Writer returns a writer bounded by the context that will writea WebSocket message of type dataType to the connection.

You must close the writer once you have written the entire message.

Only one writer can be open at a time, multiple calls will block until the previous writeris closed.

type DialOptions struct {// HTTPClient is used for the connection.// Its Transport must return writable bodies for WebSocket handshakes.// http.Transport does beginning with Go 1.12.HTTPClient *http.Client// HTTPHeader specifies the HTTP headers included in the handshake request.HTTPHeaderhttp.Header// Host optionally overrides the Host HTTP header to send. If empty, the value// of URL.Host will be used.Hoststring// Subprotocols lists the WebSocket subprotocols to negotiate with the server.Subprotocols []string// CompressionMode controls the compression mode.// Defaults to CompressionDisabled.//// See docs on CompressionMode for details.CompressionModeCompressionMode// CompressionThreshold controls the minimum size of a message before compression is applied.//// Defaults to 512 bytes for CompressionNoContextTakeover and 128 bytes// for CompressionContextTakeover.CompressionThresholdint// OnPingReceived is an optional callback invoked synchronously when a ping frame is received.//// The payload contains the application data of the ping frame.// If the callback returns false, the subsequent pong frame will not be sent.// To avoid blocking, any expensive processing should be performed asynchronously using a goroutine.OnPingReceived func(ctxcontext.Context, payload []byte)bool// OnPongReceived is an optional callback invoked synchronously when a pong frame is received.//// The payload contains the application data of the pong frame.// To avoid blocking, any expensive processing should be performed asynchronously using a goroutine.//// Unlike OnPingReceived, this callback does not return a value because a pong frame// is a response to a ping and does not trigger any further frame transmission.OnPongReceived func(ctxcontext.Context, payload []byte)}

type MessageTypeint

const (// MessageText is for UTF-8 encoded text messages like JSON.MessageTextMessageType =iota + 1// MessageBinary is for binary messages like protobufs.MessageBinary)

MessageType constants.

func (MessageType)String¶

func (iMessageType) String()string

type StatusCodeint

const (StatusNormalClosureStatusCode = 1000StatusGoingAwayStatusCode = 1001StatusProtocolErrorStatusCode = 1002StatusUnsupportedDataStatusCode = 1003// StatusNoStatusRcvd cannot be sent in a close message.// It is reserved for when a close message is received without// a status code.StatusNoStatusRcvdStatusCode = 1005// StatusAbnormalClosure is exported for use only with Wasm.// In non Wasm Go, the returned error will indicate whether the// connection was closed abnormally.StatusAbnormalClosureStatusCode = 1006StatusInvalidFramePayloadDataStatusCode = 1007StatusPolicyViolationStatusCode = 1008StatusMessageTooBigStatusCode = 1009StatusMandatoryExtensionStatusCode = 1010StatusInternalErrorStatusCode = 1011StatusServiceRestartStatusCode = 1012StatusTryAgainLaterStatusCode = 1013StatusBadGatewayStatusCode = 1014// StatusTLSHandshake is only exported for use with Wasm.// In non Wasm Go, the returned error will indicate whether there was// a TLS handshake failure.StatusTLSHandshakeStatusCode = 1015)

https://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number

These are only the status codes defined by the protocol.

You can define custom codes in the 3000-4999 range.The 3000-3999 range is reserved for use by libraries, frameworks and applications.The 4000-4999 range is reserved for private use.

funcCloseStatus¶

func CloseStatus(errerror)StatusCode

CloseStatus is a convenience wrapper around Go 1.13's errors.As to grabthe status code from a CloseError.

-1 will be returned if the passed error is nil or not a CloseError.

package mainimport ("context""log""time""github.com/coder/websocket")func main() {// Dials a server and then expects to be disconnected with status code// websocket.StatusNormalClosure.ctx, cancel := context.WithTimeout(context.Background(), time.Minute)defer cancel()c, _, err := websocket.Dial(ctx, "ws://localhost:8080", nil)if err != nil {log.Fatal(err)}defer c.CloseNow()_, _, err = c.Reader(ctx)if websocket.CloseStatus(err) != websocket.StatusNormalClosure {log.Fatalf("expected to be disconnected with StatusNormalClosure but got: %v", err)}}

func (StatusCode)String¶

func (iStatusCode) String()string