wsclient

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

type Config struct {
	// URL is the full endpoint, e.g. wss://backhaul.example.com/ws/servers/backhaul/.
	// http and https are accepted and mapped to ws and wss.
	//
	// It must come from trusted configuration. The credential below is sent
	// to whatever host it names, and nothing here pins that host, so a URL
	// taken from a server response or from user input hands the agent's key
	// to that host. A ws:// or http:// URL sends the credential in the
	// clear, which is for a local endpoint or a mesh that supplies its own
	// transport security, never the open internet.
	URL string

	// ID and Key are sent as Authorization: id="<ID>", key="<Key>".
	ID  string
	Key string

	// Origin, when non-empty, is sent as the Origin header.
	Origin string

	// UserAgent is sent as the User-Agent header. Empty means
	// "alpamon/<version>", which is only right for alpamon itself: any other
	// agent should name itself here.
	UserAgent string

	// Header carries extra request headers. Authorization and User-Agent
	// always come from the fields above, as does Origin when it is set.
	Header http.Header

	// Dialer opens the connection. Nil means DefaultDialer(). A non-nil
	// dialer is used as given except for four things. A zero
	// HandshakeTimeout becomes DefaultHandshakeTimeout, because
	// gorilla/websocket stops watching the context once the socket is up and
	// an unbounded handshake would hang with no signal at all; a negative one
	// is rejected. TLSClientConfig and Subprotocols are copied, so that a
	// later edit to the tls.Config's own fields, InsecureSkipVerify above
	// all, cannot change how a running client verifies certificates, and a
	// later edit to the subprotocol list cannot change what it negotiates.
	// That copy is one level deep: RootCAs, ClientCAs, Certificates and the
	// verification callbacks are pointers the caller keeps a hold of, so
	// adding a certificate to a pool still reaches the next reconnect. That
	// is left as it is on purpose, since snapshotting a pool would quietly
	// stop a caller who rotates trust through one, but it means those are
	// edits to a running client rather than to a copy of its config. Start
	// from DefaultDialer() to keep its proxy settings.
	//
	// The fourth is the dial hooks, which are wrapped so that Shutdown and a
	// done context can free a socket the handshake is still waiting on. A
	// hook has to return that socket first: NetDialContext is handed a
	// context that ends with the client's, but NetDial takes none and is
	// adapted to the wrapper, so nothing can interrupt it before it returns.
	// Prefer NetDialContext, and give a NetDial a timeout of its own.
	Dialer *websocket.Dialer

	// ReadLimit is the largest inbound message accepted, in bytes: its
	// frames' payloads summed as they arrive, before any decompression. Zero
	// means DefaultReadLimit; a negative value removes the limit.
	//
	// It bounds memory only while compression is off, which is the default:
	// gorilla/websocket counts the compressed bytes against the limit and
	// then reads the decompressed stream whole, so a caller who sets
	// EnableCompression on their own Dialer is bounding the frame, not the
	// allocation it expands into. Nothing here can bound the second.
	ReadLimit int64

	// ReadTimeout is re-armed before every read. Zero means DefaultReadTimeout.
	ReadTimeout time.Duration

	// WriteTimeout bounds each WriteMessage and WriteJSON call. Control frames
	// the client sends itself, pongs and close frames, have a short fixed
	// bound of their own. Zero means DefaultWriteTimeout.
	WriteTimeout time.Duration

	// MinBackoff and MaxBackoff bound the wait between reconnect attempts.
	// Each wait is drawn uniformly from the doubling base up to half again
	// as much, or up to MaxBackoff where that would pass it. Zero means
	// DefaultMinBackoff and DefaultMaxBackoff.
	//
	// The two ends are not symmetric. MinBackoff is a floor that waits
	// actually sit on, while MaxBackoff is one they approach: the base stops
	// at two thirds of it so the jitter still has somewhere to go, which is
	// what keeps a fleet that has been retrying for a while from redialing
	// on a single tick. A settled schedule lands in [2/3 MaxBackoff,
	// MaxBackoff), not on MaxBackoff itself. Setting the two equal asks for
	// a fixed wait and gets one.
	MinBackoff time.Duration
	MaxBackoff time.Duration

	// Rand returns the value in [0, 1) the jitter factor is drawn from. Nil
	// means math/rand/v2. It is here for a caller that wants its own
	// reconnect timing to be reproducible in its own tests, which a module
	// outside this repository cannot arrange any other way.
	Rand func() float64

	// OnConnect runs after every successful dial. OnDisconnect runs once for
	// every connection that OnConnect announced; err is nil when the client
	// closed a healthy connection because Shutdown, Reconnect or the Run
	// context asked it to, and is otherwise what ended the connection: a
	// failed read or write, the peer's close, or the handler's error. OnRetry
	// runs before each wait between connection attempts, whether the last dial
	// failed or a connection ended before it proved itself; err is what caused
	// the wait, and attempt counts from 1, restarting after a connection that
	// worked. All three run on the Run goroutine, so a slow hook delays
	// reading and reconnecting. They may call any Client method except Run.
	OnConnect    func()
	OnDisconnect func(err error)
	OnRetry      func(attempt int, delay time.Duration, err error)
}

type Handler func(ctx context.Context, messageType int, payload []byte) error