Documentation
¶
Overview ¶
Package stream reads streaming responses: Server-Sent Events and WebSocket message scripts (docs/decisions/0004-streaming-protocols.md).
Index ¶
- Constants
- func Read(body io.Reader, stop func(), lim Options, protocol exchange.Protocol, ...) (*exchange.Stream, error)
- func ReadSSE(body io.Reader, stop func(), lim Options) (*exchange.Stream, error)
- func SSEStream(body []byte) *exchange.Stream
- func WebSocket(ctx context.Context, u *httpx.Upgrade, steps []Step, lim Options) (*exchange.Response, error)
- type Event
- type Interactive
- type Options
- type SSEParser
- type Step
- type StepError
- type StepKind
Constants ¶
const ( DefaultTimeout = 10 * time.Second DefaultMaxBytes = 10 << 20 )
Default limits of a stream (sonde-stream-timeout, sonde-stream-max-bytes).
Variables ¶
This section is empty.
Functions ¶
func Read ¶
func Read(body io.Reader, stop func(), lim Options, protocol exchange.Protocol, parse func([]byte) ([]exchange.Message, error)) (*exchange.Stream, error)
Read reads the messages of a stream of protocol from body, as ReadSSE does: parse turns each chunk read into the messages it completes. An error from parse ends the stream as a failure.
func ReadSSE ¶
ReadSSE reads an event stream from body until a limit is reached or the server ends it; each limit is a normal stop. stop must interrupt a pending body read (by canceling its request); read errors after stop are the stop, not failures. Only a read error the limits did not cause is returned as an error, with the events read so far.
func SSEStream ¶
SSEStream builds the stream of a body read whole: the sondeStream query of an entry without sonde-stream-* options.
func WebSocket ¶
func WebSocket(ctx context.Context, u *httpx.Upgrade, steps []Step, lim Options) (*exchange.Response, error)
WebSocket performs the handshake prepared by u and runs steps, then closes the connection normally unless a Close step did. The response is the handshake response; it has a Stream when the upgrade succeeded. A refused upgrade (any status but 101) is not an error: the steps do not run and the status asserts report it. The whole exchange after the handshake must end within lim.Timeout; a Receive still waiting then fails. On a failure the response keeps the messages exchanged so far.
Types ¶
type Event ¶
type Event struct {
Type string // "message" when the event has no event field
Data string
ID string // the last event ID at dispatch
Retry *int // this event's valid retry field, if any
}
Event is one dispatched Server-Sent Event.
type Interactive ¶ added in v1.4.0
type Interactive struct {
// Request is the handshake request as sent.
Request exchange.Request
// Response is the handshake response. Its Stream records every
// message sent and received; read it after Done is closed.
Response *exchange.Response
// contains filtered or unexported fields
}
Interactive is a WebSocket connection its caller drives one step at a time (the desktop's live session), dialed exactly like a scripted exchange. Send and Close steps are read from Steps; Receive steps are ignored, since every message received is reported as it arrives. The session ends after a Close step, when the server closes the connection or the connection fails, when a message goes past MaxBytes, or when the context given to DialInteractive ends.
func DialInteractive ¶ added in v1.4.0
DialInteractive performs the handshake prepared by u (bounded by its max-time) and starts a session that lives until ctx ends or the session is closed. lim.OnMessage receives every message, sent and received, serially; it must not block for long, since the session can not end while it runs. lim.MaxBytes limits the bytes received, and lim.Count and lim.Timeout do not apply. A refused upgrade returns the handshake response in a session that is already done, with an error; a failed handshake returns no session. The stream's StopReason is set when the session ends without an error.
func (*Interactive) Done ¶ added in v1.4.0
func (s *Interactive) Done() <-chan struct{}
Done is closed when the session has ended and released its connection.
func (*Interactive) Err ¶ added in v1.4.0
func (s *Interactive) Err() error
Err is why the session ended: nil after a Close step or a normal closure by the server; otherwise the failure, the server's close code, or the context's error. It is final once Done is closed.
func (*Interactive) Steps ¶ added in v1.4.0
func (s *Interactive) Steps() chan<- Step
Steps is where the caller sends Send and Close steps. A send blocks until the previous step is done; select on Done not to block on an ended session.
type Options ¶
type Options struct {
Count int
Timeout time.Duration
MaxBytes int64
OnMessage func(exchange.Message)
}
Options bound a stream: zero fields take their defaults, Count zero means no count limit. OnMessage, when set, is called with each message as it is sent or received.
type SSEParser ¶
type SSEParser struct {
// contains filtered or unexported fields
}
SSEParser parses a text/event-stream incrementally, following the WHATWG HTML "event stream interpretation": one leading BOM is stripped, CRLF, LF and CR end lines, data lines join with LF, an id containing NUL and a retry that is not all ASCII digits are ignored, and an event without data is not dispatched. A partial event at the end of the stream is dropped. The zero value is ready to use.
type Step ¶
type Step struct {
Kind StepKind
// Send: the message, binary or text.
Data []byte
Binary bool
// Receive: how many messages to wait for (at least 1).
Count int
// Close: the status code, 0 for 1000.
Code int
}
Step is one rendered [SondeMessages] step.