Documentation
¶
Overview ¶
Package websocket provides WebSocket connection support for services that use relay for HTTP communication. It applies the same authentication and signing primitives (relay.RequestSigner, custom headers) to the WebSocket upgrade handshake, ensuring a consistent authentication story across HTTP and WebSocket connections.
Basic usage ¶
conn, err := websocket.Dial(ctx, "wss://api.example.com/ws",
websocket.WithSigner(relay.RequestSignerFunc(func(r *http.Request) error {
r.Header.Set("Authorization", "Bearer "+token)
return nil
})),
)
if err != nil { ... }
defer conn.Close()
// Send a message
if err := conn.WriteText("hello"); err != nil { ... }
// Receive a message
msg, err := conn.ReadMessage()
TLS customisation ¶
conn, err := websocket.Dial(ctx, "wss://...",
websocket.WithTLSConfig(&tls.Config{
InsecureSkipVerify: false,
RootCAs: certPool,
}),
)
Index ¶
Constants ¶
const ( // TextMessage denotes a text data message (UTF-8 encoded). TextMessage = gorilla.TextMessage // BinaryMessage denotes a binary data message. BinaryMessage = gorilla.BinaryMessage // CloseMessage denotes a close control message. CloseMessage = gorilla.CloseMessage // PingMessage denotes a ping control message. PingMessage = gorilla.PingMessage // PongMessage denotes a pong control message. PongMessage = gorilla.PongMessage )
MessageType mirrors gorilla/websocket message types for callers that need to distinguish text from binary frames.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is an active WebSocket connection. Call Close or CloseGracefully when done.
func Dial ¶
Dial establishes a WebSocket connection to url. It performs the HTTP upgrade handshake, applying any configured headers and signer before sending.
url must use the "ws://" or "wss://" scheme.
Dial blocks until the handshake completes or ctx is cancelled.
func (*Conn) Close ¶
Close sends a close frame and then closes the underlying connection immediately. For a graceful shutdown, use [CloseGracefully].
func (*Conn) CloseGracefully ¶
CloseGracefully sends a close control message with the given code and reason, then waits up to 5 seconds for the peer to echo a close frame before closing the underlying connection (RFC 6455 §7.1.2).
Use gorilla/websocket close codes (e.g. 1000 for normal closure, 1001 for going away).
func (*Conn) ReadMessage ¶
ReadMessage reads the next message from the peer. It blocks until a message arrives, the connection is closed, or an error occurs.
func (*Conn) Underlying ¶
Underlying returns the underlying gorilla/websocket connection for advanced use cases (setting read/write deadlines, configuring ping handlers, etc.).
func (*Conn) WriteBytes ¶
WriteBytes sends a binary frame to the peer.
type Message ¶
type Message struct {
// Type is the message type (TextMessage or BinaryMessage).
Type int
// Data is the raw message payload.
Data []byte
}
Message is a WebSocket message received from the peer.
type Option ¶
type Option func(*option)
Option configures a WebSocket Dial call.
func WithHeaders ¶
WithHeaders adds static headers to the WebSocket upgrade handshake. Calling WithHeaders multiple times merges all provided headers.
func WithSigner ¶
func WithSigner(s relay.RequestSigner) Option
WithSigner sets a relay.RequestSigner that signs the upgrade HTTP request before the handshake is sent. This mirrors relay.WithSigner so the same signer implementation can be reused for both HTTP and WebSocket connections.
func WithTLSConfig ¶
WithTLSConfig sets a custom TLS configuration for the upgrade connection.
Source Files