sse

Documentation

Overview

Package sse parses provider-neutral Server-Sent Event frames.

Parse understands comments, event names, ids, repeated data fields, LF/CRLF endings, EOF-final dispatch, and the OpenAI-style [DONE] sentinel. JSON decoding and provider-specific event handling belong to callers.

Parse bounds individual lines and accumulated event frames. Callers may override those limits with WithMaxLineBytes and WithMaxEventBytes.

Context cancellation is checked between reads. If a caller needs cancellation to interrupt a blocked network read immediately, wrap the response body with CloseOnContextDone or otherwise close the reader when the context is done.

Index

• Variables
• func CloseOnContextDone(ctx context.Context, body io.ReadCloser) io.ReadCloser
• func Parse(ctx context.Context, r io.Reader, handle Handler, opts ...Option) error
• type Event
• type Handler
• type Line
• type LineError
  • func (e *LineError) Error() string
  • func (e *LineError) Unwrap() error
• type Option
  • func WithMaxEventBytes(n int) Option
  • func WithMaxLineBytes(n int) Option

Variables

var (
	// ErrStop lets a handler stop parsing without treating the stop as failure.
	ErrStop = errors.New("sse: stop parsing")
	// ErrMalformedLine reports an event-stream line that is not field formatted.
	ErrMalformedLine = errors.New("sse: malformed line")
	// ErrLineTooLarge reports a line exceeding the configured line limit.
	ErrLineTooLarge = errors.New("sse: line too large")
	// ErrEventTooLarge reports an event frame exceeding the configured event limit.
	ErrEventTooLarge = errors.New("sse: event too large")
)

Functions

func CloseOnContextDone

func CloseOnContextDone(ctx context.Context, body io.ReadCloser) io.ReadCloser

CloseOnContextDone closes body when ctx is canceled so a blocked SSE read can unblock promptly. Callers still own the returned ReadCloser and should close it.

func Parse

func Parse(ctx context.Context, r io.Reader, handle Handler, opts ...Option) error

Parse reads an SSE stream from r and calls handle for each completed event.

Parse understands comments, data, event, and id fields. Repeated data fields are joined with "\n". Provider-specific JSON decoding belongs in callers. Parse enforces default line and event size limits; use WithMaxLineBytes and WithMaxEventBytes when a provider needs tighter bounds. Context cancellation is returned once ctx is canceled or the underlying reader returns that error.

Types

type Event

type Event struct {
	Event string
	Data  string
	ID    string
	Done  bool
	Lines []Line
}

Event is a provider-neutral Server-Sent Event frame.

type Handler

type Handler func(Event) error

Handler receives parsed events. Return ErrStop to end parsing successfully.

type Line

type Line struct {
	Number  int
	Raw     string
	Field   string
	Value   string
	Comment bool
}

Line records one parsed event-stream line without its line ending.

type LineError

type LineError struct {
	Line int
	Raw  string
	Err  error
}

LineError describes a parse failure at a specific stream line.

func (*LineError) Error

func (e *LineError) Error() string

func (*LineError) Unwrap

func (e *LineError) Unwrap() error

type Option

type Option func(*config)

Option configures Parse.

func WithMaxEventBytes

func WithMaxEventBytes(n int) Option

WithMaxEventBytes sets the maximum accumulated event frame size accepted by Parse.

func WithMaxLineBytes

func WithMaxLineBytes(n int) Option

WithMaxLineBytes sets the maximum line size accepted by Parse.