Documentation
¶
Overview ¶
Package wsutilx provides shared helpers for both halves of a WebSocket client: recv loops and the write path.
gobwas/ws's NextFrame ignores ctx cancellation; read deadlines bound the wait so half-open sockets can't pin goroutines indefinitely. Writes have the mirror-image problem: a peer that stops draining its receive window wedges conn.Write forever, so every write is deadline-bounded too.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetReadDeadline ¶
SetReadDeadline pushes the read deadline forward on conn. Call before each blocking read inside a recv loop; pass timeout <= 0 to skip (e.g. when the caller manages deadlines explicitly). Errors are intentionally ignored: if the conn is already broken, the next read will surface it.
func SetWriteDeadline ¶ added in v0.12.0
SetWriteDeadline pushes the write deadline forward on conn. Call before each blocking write; pass timeout <= 0 to skip (e.g. when the caller manages deadlines explicitly). Errors are intentionally ignored: if the conn is already broken, the write itself will surface it.
func WatchCancel ¶
WatchCancel spawns a single goroutine that pushes conn's read deadline to the past when ctx is cancelled, breaking any in-flight blocking read so the caller's loop can observe the cancellation and return. The returned stop function MUST be called when the loop exits (typically via defer) to terminate the watcher; failing to call it leaks the watcher goroutine until ctx is cancelled.
Pass a nil ctx (or one with no Done channel) for a no-op — returns a no-op stop fn. This keeps callers simple in places where ctx isn't readily available.
func WithBuffered ¶ added in v0.16.0
WithBuffered returns conn with reads served from br first. ws.Dial puts any bytes the server sent alongside its handshake response into br; a server that speaks first loses its opening frame if br is dropped.
Types ¶
type DurationVar ¶
type DurationVar struct {
// contains filtered or unexported fields
}
DurationVar is an atomic time.Duration suitable for package-level configuration knobs that may be read concurrently by recv loops while tests mutate them.
var DefaultReadTimeout DurationVar
DefaultReadTimeout caps inter-frame idle on application WebSockets. 60s = 30s ping interval + 1 missed ping + margin. Tests may override.
var DefaultWriteTimeout DurationVar
DefaultWriteTimeout caps how long a single WebSocket frame write may block on a peer that has stopped draining. 5s matches wsmedia's DefaultWriteTimeout — a legitimate 640-byte audio frame never takes that long. Tests may override.
func (*DurationVar) Load ¶
func (v *DurationVar) Load() time.Duration
Load returns the current value.
func (*DurationVar) Store ¶
func (v *DurationVar) Store(d time.Duration)
Store atomically replaces the value.
type LockedWriter ¶ added in v0.12.0
type LockedWriter struct {
// contains filtered or unexported fields
}
LockedWriter serializes WebSocket frame writes to a net.Conn and bounds each one with a write deadline. The state field selects masked client frames or unmasked server frames; everything else is identical, so both halves of the codebase share one writer.
Serialization is required for correctness, not merely for safety: a WebSocket frame is a header write followed by a payload write (gobwas ws.WriteFrame issues them as two separate conn.Write calls), so two unsynchronized writers interleave and corrupt the stream. Any endpoint with both a send loop and a read path that answers pings therefore needs a single writer shared by both halves.
The mutex is deliberately held across the gobwas write call. That is the only way to make the header+payload pair atomic, and it is safe precisely because the deadline set immediately beforehand bounds how long the write — and therefore the lock hold — can last. Do not "fix" this by dropping the lock before the write.
A write that fails on the deadline leaves the stream mid-frame and unrecoverable, so the first failure is latched: every later write returns it without touching the conn. Callers must tear the connection down, or supply an onFail hook that does it for them.
func NewLockedWriter ¶ added in v0.12.0
func NewLockedWriter(conn net.Conn) *LockedWriter
NewLockedWriter returns a LockedWriter writing client-side (masked) frames to conn.
func NewServerLockedWriter ¶ added in v0.12.0
func NewServerLockedWriter(conn net.Conn, onFail func()) *LockedWriter
NewServerLockedWriter returns a LockedWriter writing server-side (unmasked) frames to conn. onFail, when non-nil, runs once after the first write failure and outside the mutex — typically conn.Close, which is what wakes a recv loop parked in a blocking read so its handler can unwind instead of serving on a stream carrying a truncated frame.
func (*LockedWriter) Err ¶ added in v0.12.0
func (lw *LockedWriter) Err() error
Err returns the latched write failure, or nil while the stream is intact.
func (*LockedWriter) WriteBinary ¶ added in v0.12.0
func (lw *LockedWriter) WriteBinary(data []byte) error
WriteBinary writes data as a single binary frame.
func (*LockedWriter) WriteControl ¶ added in v0.12.0
func (lw *LockedWriter) WriteControl(op ws.OpCode, payload []byte) error
WriteControl writes a control frame (typically ws.OpPong) with payload.
func (*LockedWriter) WriteText ¶ added in v0.12.0
func (lw *LockedWriter) WriteText(data []byte) error
WriteText writes data as a single text frame.