stream

package
v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Sep 28, 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 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