stream

package
v1.4.1 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package stream reads streaming responses: Server-Sent Events and WebSocket message scripts (docs/decisions/0004-streaming-protocols.md).

Index

Constants

View Source
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

func ReadSSE(body io.Reader, stop func(), lim Options) (*exchange.Stream, error)

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

func SSEStream(body []byte) *exchange.Stream

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.

func ParseSSE

func ParseSSE(b []byte) []Event

ParseSSE parses a whole event stream.

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

func DialInteractive(ctx context.Context, u *httpx.Upgrade, lim Options) (*Interactive, error)

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.

func (*SSEParser) Write

func (p *SSEParser) Write(b []byte) []Event

Write feeds b and returns the events it completed.

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.

type StepError

type StepError struct {
	Index int
	Err   error
}

StepError is the failure of a step: Index is its position in the steps.

func (*StepError) Error

func (e *StepError) Error() string

func (*StepError) Unwrap

func (e *StepError) Unwrap() error

type StepKind

type StepKind int

StepKind is the kind of a WebSocket script step.

const (
	Send StepKind = iota
	Receive
	Close
)

Step kinds.

Jump to

Keyboard shortcuts

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