wsutilx

package
v0.16.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 8 Imported by: 0

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

func SetReadDeadline(conn net.Conn, timeout time.Duration)

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

func SetWriteDeadline(conn net.Conn, timeout time.Duration)

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

func WatchCancel(ctx context.Context, conn net.Conn) func()

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

func WithBuffered(conn net.Conn, br *bufio.Reader) net.Conn

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址