Skip to content

Commit

Permalink
docs: Deprecate all symbols
Browse files Browse the repository at this point in the history
nhooyr committed Aug 10, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent fac7867 commit 4a3ee3f
Showing 9 changed files with 45 additions and 0 deletions.
4 changes: 4 additions & 0 deletions accept.go
Original file line number Diff line number Diff line change
@@ -21,6 +21,8 @@ import (
)

// AcceptOptions represents Accept's options.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
type AcceptOptions struct {
// Subprotocols lists the WebSocket subprotocols that Accept will negotiate with the client.
// The empty subprotocol will always be negotiated as per RFC 6455. If you would like to
@@ -75,6 +77,8 @@ func (opts *AcceptOptions) cloneWithDefaults() *AcceptOptions {
// Accept accepts a WebSocket handshake from a client and upgrades the
// the connection to a WebSocket.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// Accept will not allow cross origin requests by default.
// See the InsecureSkipVerify and OriginPatterns options to allow cross origin requests.
//
11 changes: 11 additions & 0 deletions close.go
Original file line number Diff line number Diff line change
@@ -16,6 +16,8 @@ import (

// StatusCode represents a WebSocket status code.
// https://tools.ietf.org/html/rfc6455#section-7.4
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
type StatusCode int

// https://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number
@@ -61,20 +63,25 @@ const (

// CloseError is returned when the connection is closed with a status and reason.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// Use Go 1.13's errors.As to check for this error.
// Also see the CloseStatus helper.
type CloseError struct {
Code StatusCode
Reason string
}

// Deprecated: coder now maintains this library at github.com/coder/websocket.
func (ce CloseError) Error() string {
return fmt.Sprintf("status = %v and reason = %q", ce.Code, ce.Reason)
}

// CloseStatus is a convenience wrapper around Go 1.13's errors.As to grab
// the status code from a CloseError.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// -1 will be returned if the passed error is nil or not a CloseError.
func CloseStatus(err error) StatusCode {
var ce CloseError
@@ -86,6 +93,8 @@ func CloseStatus(err error) StatusCode {

// Close performs the WebSocket close handshake with the given status code and reason.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// It will write a WebSocket close frame with a timeout of 5s and then wait 5s for
// the peer to send a close frame.
// All data messages received from the peer during the close handshake will be discarded.
@@ -130,6 +139,8 @@ func (c *Conn) Close(code StatusCode, reason string) (err error) {

// CloseNow closes the WebSocket connection without attempting a close handshake.
// Use when you do not want the overhead of the close handshake.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
func (c *Conn) CloseNow() (err error) {
defer errd.Wrap(&err, "failed to immediately close WebSocket")

2 changes: 2 additions & 0 deletions compress.go
Original file line number Diff line number Diff line change
@@ -12,6 +12,8 @@ import (
// CompressionMode represents the modes available to the permessage-deflate extension.
// See https://tools.ietf.org/html/rfc7692
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// Works in all modern browsers except Safari which does not implement the permessage-deflate extension.
//
// Compression is only used if the peer supports the mode selected.
8 changes: 8 additions & 0 deletions conn.go
Original file line number Diff line number Diff line change
@@ -17,6 +17,8 @@ import (

// MessageType represents the type of a WebSocket message.
// See https://tools.ietf.org/html/rfc6455#section-5.6
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
type MessageType int

// MessageType constants.
@@ -30,6 +32,8 @@ const (
// Conn represents a WebSocket connection.
// All methods may be called concurrently except for Reader and Read.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// You must always read from the connection. Otherwise control
// frames will not be handled. See Reader and CloseRead.
//
@@ -140,6 +144,8 @@ func newConn(cfg connConfig) *Conn {

// Subprotocol returns the negotiated subprotocol.
// An empty string means the default protocol.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
func (c *Conn) Subprotocol() string {
return c.subprotocol
}
@@ -198,6 +204,8 @@ func (c *Conn) flate() bool {
// not read from the connection but instead waits for a Reader call
// to read the pong.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// TCP Keepalives should suffice for most use cases.
func (c *Conn) Ping(ctx context.Context) error {
p := atomic.AddInt32(&c.pingCounter, 1)
4 changes: 4 additions & 0 deletions dial.go
Original file line number Diff line number Diff line change
@@ -21,6 +21,8 @@ import (
)

// DialOptions represents Dial's options.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
type DialOptions struct {
// HTTPClient is used for the connection.
// Its Transport must return writable bodies for WebSocket handshakes.
@@ -91,6 +93,8 @@ func (opts *DialOptions) cloneWithDefaults(ctx context.Context) (context.Context

// Dial performs a WebSocket handshake on url.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// The response is the WebSocket handshake response from the server.
// You never need to close resp.Body yourself.
//
2 changes: 2 additions & 0 deletions netconn.go
Original file line number Diff line number Diff line change
@@ -12,6 +12,8 @@ import (

// NetConn converts a *websocket.Conn into a net.Conn.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// It's for tunneling arbitrary protocols over WebSockets.
// Few users of the library will need this but it's tricky to implement
// correctly and so provided in the library.
8 changes: 8 additions & 0 deletions read.go
Original file line number Diff line number Diff line change
@@ -21,6 +21,8 @@ import (
// Reader reads from the connection until there is a WebSocket
// data message to be read. It will handle ping, pong and close frames as appropriate.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// 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.
@@ -39,6 +41,8 @@ func (c *Conn) Reader(ctx context.Context) (MessageType, io.Reader, error) {

// Read is a convenience method around Reader to read a single message
// from the connection.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
func (c *Conn) Read(ctx context.Context) (MessageType, []byte, error) {
typ, r, err := c.Reader(ctx)
if err != nil {
@@ -52,6 +56,8 @@ func (c *Conn) Read(ctx context.Context) (MessageType, []byte, error) {
// CloseRead starts a goroutine to read from the connection until it is closed
// or a data message is received.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// Once CloseRead is called you cannot read any messages from the connection.
// The returned context will be cancelled when the connection is closed.
//
@@ -89,6 +95,8 @@ func (c *Conn) CloseRead(ctx context.Context) context.Context {
// SetReadLimit sets the max number of bytes to read for a single message.
// It applies to the Reader and Read methods.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// By default, the connection has a message read limit of 32768 bytes.
//
// When the limit is hit, the connection will be closed with StatusMessageTooBig.
2 changes: 2 additions & 0 deletions stringer.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions write.go
Original file line number Diff line number Diff line change
@@ -23,6 +23,8 @@ import (
// Writer returns a writer bounded by the context that will write
// a WebSocket message of type dataType to the connection.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// 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 writer
@@ -37,6 +39,8 @@ func (c *Conn) Writer(ctx context.Context, typ MessageType) (io.WriteCloser, err

// Write writes a message to the connection.
//
// Deprecated: coder now maintains this library at github.com/coder/websocket.
//
// See the Writer method if you want to stream a message.
//
// If compression is disabled or the compression threshold is not met, then it

0 comments on commit 4a3ee3f

Please sign in to comment.