Documentation
¶
Overview ¶
Package wire formats and parses the line-based JaWS WebSocket protocol.
The package has two message layers. Message is an in-process dispatch record routed through Message.Dest. WsMsg is one browser protocol record; WsMsg.Append serializes it and Parse recovers it.
ReadLoop and WriteLoop deliver records over a WebSocket. See github.com/linkdata/jaws/lib/what for commands and events, and github.com/linkdata/jaws/lib/tag for destination tags.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendJSONQuote ¶ added in v0.500.0
AppendJSONQuote appends s to b as a JSON string literal accepted by JSON.parse.
It uses JSON escapes, preserves '<', '>', and '&', and replaces invalid UTF-8 with U+FFFD.
func ReadLoop ¶
func ReadLoop(ctx context.Context, ccf context.CancelCauseFunc, doneCh <-chan struct{}, incomingMsgCh chan<- WsMsg, idleInterval, pingTimeout time.Duration, ws *websocket.Conn)
ReadLoop reads WebSocket text messages and sends each valid protocol record on incomingMsgCh.
Records are LF-terminated and delivered in order. A text message may contain multiple records; malformed records are skipped independently.
A WebSocket read that remains pending for idleInterval triggers a ping bounded by pingTimeout. Incoming data or a successful ping restarts the idle interval. Time spent parsing or delivering an already-read message does not count toward it. If a message is processed while a ping is pending, that ping's failure is ignored. idleInterval and pingTimeout must be positive.
Closes incomingMsgCh on exit.
Canceling ctx or closing doneCh interrupts reads and pings in progress and is not reported through ccf.
ccf may be nil, in which case errors are not reported and only the loop exits.
func WriteLoop ¶
func WriteLoop(ctx context.Context, ccf context.CancelCauseFunc, doneCh <-chan struct{}, outboundMsgCh <-chan WsMsg, writeTimeout time.Duration, ws *websocket.Conn)
WriteLoop formats messages read from outboundMsgCh and writes them to the WebSocket.
Consecutive queued records may be coalesced into one text message.
Each WebSocket write has its own writeTimeout deadline; writeTimeout must be positive.
Closes the WebSocket on exit.
Canceling ctx or closing doneCh interrupts writes in progress and is not reported through ccf.
ccf may be nil, in which case errors are not reported and only the loop exits.
Types ¶
type Message ¶
type Message struct {
// Dest selects recipients among active Requests: nil targets every active
// Request, a nonzero request key targets the matching active Request, and any
// other value is expanded into a tag or tag list. Plain strings and Jid values
// are illegal destinations.
Dest any
What what.What // command to perform
Data string // payload: inner HTML content or a tag list
}
Message contains the elements of a message to be sent to requests.
func (*Message) String ¶
String returns the Message in a form suitable for debug output.
Dest is rendered with tag.TagString, so in the default build it shows only its type (and, for a pointer, its address when it can be read safely) and a malformed Dest cannot crash the caller; build with -tags debug or -race for full-value rendering, which is more informative but not crash-safe.
type WsMsg ¶
type WsMsg struct {
Data string // data to send
Jid jid.Jid // non-negative Jid to send
What what.What // command
}
WsMsg is a protocol record sent to or from a WebSocket.
func Parse ¶
Parse parses one LF-terminated protocol record.
For commands other than what.JsVar and what.Call, quote-prefixed Data is decoded as a string; other Data is taken verbatim. A malformed quoted string rejects the record. JsVar and Call Data is always verbatim and ends at the first tab. Accepted Data is sanitized with strings.ToValidUTF8.
func (*WsMsg) Append ¶
Append appends m in wire format to b and returns the extended buffer.
The record is What<TAB>Jid<TAB>Data<LF>, where the Jid field is empty if Jid is zero. The Data field is written verbatim for what.JsVar and what.Call, and JSON-quoted for every other command. Append panics if Jid is negative.
Verbatim Data must contain no tab or newline bytes, which would corrupt the record; ensuring that is the caller's responsibility.