Server-Sent Events (SSE)¶

OxideHTTP supports Server-Sent Events (SSE) through OxideHTTP.sse(). Events are parsed incrementally and yielded as SSEEvent instances.

Basic Usage¶

from oxidehttp import OxideHTTP

async with OxideHTTP() as client:
    async for event in client.sse('GET', 'https://example.com/events'):
        print(event.data)

The client automatically configures the following headers if they are not already provided:

Accept: text/event-stream
Cache-Control: no-cache

Event Structure¶

Each event is represented by an SSEEvent:

Attribute	Type	Description
`data`	`str`	Event data
`event`	`str \\| None`	Event type
`event_id`	`str \\| None`	Event identifier
`retry`	`int \\| None`	Parsed retry interval in seconds (integer conversion)

Example¶

async with OxideHTTP() as client:
    async for event in client.sse('GET', 'https://example.com/events'):
        print(f'Event: {event.event}')
        print(f'ID: {event.event_id}')
        print(f'Data: {event.data}')
        print(f'Retry: {event.retry}')

Request Options¶

sse() accepts the same request options as stream():

async for event in client.sse(
    'GET',
    'https://example.com/events',
    params={'channel': 'general'},
    headers={'Authorization': 'Bearer token'},
):
    print(event.data)

You can also specify a request body using json, body_text, body_bytes, or form, depending on the HTTP method.

Automatic Reconnection¶

Automatic reconnection can be enabled with auto_reconnect=True.

async with OxideHTTP() as client:
    async for event in client.sse(
        'GET',
        'https://example.com/events',
        auto_reconnect=True,
        reconnect_delay=3.0,
        max_reconnects=10,
    ):
        print(event.data)

Parameter	Default	Description
`auto_reconnect`	`False`	Reconnect after connection failures or stream completion
`reconnect_delay`	`3.0`	Default delay between reconnects, in seconds
`max_reconnects`	`None`	Maximum reconnect attempts; `None` allows unlimited attempts

Reconnection Behavior¶

When automatic reconnection is enabled:

The client reconnects after connection failures.
The client also reconnects when the stream ends normally.
The most recently received event ID is sent through the Last-Event-ID header.
If the server provides a retry interval, it takes precedence over reconnect_delay.
CancelledError is propagated without attempting reconnection.

The server's retry field is specified in milliseconds. The parser converts it to seconds for reconnect scheduling. The SSEParser.retry property exposes that value as a float in seconds; the SSEEvent.retry field currently converts it to an integer, so it may lose fractional seconds.

Event Parsing¶

The SSE parser supports the standard fields:

data: accumulated into the event payload. Multiple data lines are joined with newline characters.
event: sets the event type.
id: sets the event identifier unless the value contains a null character.
retry: accepts non-negative integers and updates the reconnection interval.
Comments: lines starting with : are ignored.

Events are dispatched when an empty line is encountered. Any remaining buffered data is processed when the stream finishes.

Error Handling¶

When automatic reconnection is disabled, request failures are translated into OxideHTTP exceptions and propagated to the caller.

When automatic reconnection is enabled, connection errors trigger another connection attempt according to the configured reconnect policy.

See Exceptions for available exception classes and Types for the event type.