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 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 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.