Overhaul parser for spec compliance; add reconnecting EventSource client

[zac]

Summary

Closes the functional gaps between this library and the WHATWG server-sent events specification, and adds the missing pieces needed to use it as a complete SSE client.

Critical fixes

• Errors no longer hang the consumer. The parser previously swallowed transport errors with a print and never finished its stream, leaving for await suspended forever on any network drop. Parsing is now iterator-driven and rethrows transport errors to the consumer.
• Cancellation propagates. There is no detached parse task or unbounded AsyncStream buffer anymore; bytes are read only as events are consumed, and cancelling the consuming task stops the parse and releases the connection.
• Invalid UTF-8 can no longer fabricate events. Undecodable bytes previously turned a line into "", which the parser treated as a dispatch boundary — splitting one event in two and dropping data. Decoding now uses U+FFFD replacement per spec.

Spec compliance

• A single leading BOM is stripped.
• Fixed the line splitter emitting a phantom empty line for CR CR sequences.
• The last event ID persists across events and is stamped on every dispatched event (lastEventId), commits at dispatch time (so a truncated final block can't poison the resume ID), and id-only blocks commit without dispatching — all per spec.
• ServerSentEvent.type applies the spec's "message" default when the event field is absent or empty.
• The URLSession helpers now send Accept: text/event-stream and Cache-Control: no-cache, and validate the response (status 200, text/event-stream content type), throwing SSEError instead of parsing an error page as a stream.

New: EventSource

A reconnecting client mirroring the spec's EventSource model:

• automatic reconnection when the server closes the stream or the network drops
• honors the server's retry interval
• resumes with the Last-Event-ID header
• HTTP 204 ends the sequence (the spec's "stop reconnecting" signal); other non-200 responses fail the connection with a thrown error

for try await event in EventSource(url: url) {
    print(event.type, event.data)
}

Structure & cleanup

• The parser is now generic over any AsyncSequence of bytes, decoupling it from URLSession.AsyncBytes — it builds and tests on Linux (the URLSession pieces are Darwin-gated), and CI gains a Linux job.
• Removed dead API: the never-populated Event.comment field, the unused trim() helper, and the unused AsyncSequence.split extensions.
• README rewritten (the previous example called a nonexistent asyncBytes(from:) API) and the feature checklist updated.
• ~15 new tests covering BOM handling, invalid UTF-8, error propagation, last-event-ID persistence and dispatch-time commit, type defaulting, cancellation, and request/response validation.

Breaking changes

• AsyncServerSentEvents.Event is now the top-level ServerSentEvent (a typealias keeps the old spelling reachable); the comment property is gone.
• AsyncServerSentEvents is generic over its byte source and its iteration can now throw, so consumers must use for try await.
• serverSentEvents(from:)/(for:) now throw SSEError for non-200 or non-text/event-stream HTTP responses.

Test plan

• Full suite passes on macOS (Swift 6.0) and the new Linux job (Swift 6.0), including the pre-existing parsing/resilience suites and the new spec-compliance suite.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8971b446b1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".