Add APIs for reading/writing HTTP Datagrams by aryan-25 · Pull Request #106 · swift-server/swift-http-server

aryan-25 · 2026-07-31T09:25:49Z

Motivation

Users may wish to send/receive HTTP Datagrams (RFC 9297) using NIOHTTPServer. This PR introduces reader and writer APIs for unreliable datagrams.

Note that the underlying support is yet to be provided by swift-nio-http3. The read/write source is not wired up, and we currently throw an error when attempting to read or write to/from the unreliable datagram stream.

Modifications

Added an UnstableHTTPDatagrams trait, disabled by default. All new APIs are behind that trait (note that the HTTP3 trait must also be enabled as unreliable datagrams are currently only supported over QUIC).
Added a withDatagramReader method on NIOHTTPServer.Reader and a withDatagramWriter method on NIOHTTPServer.ResponseSender.Writer. Both methods are consuming and take a closure that receive the reliable request/response body reader/writer and optionally the unreliable datagram reader/writer as arguments.
- In both methods, the readers/writers are passed as consuming sending, so callers can run the readers/writers separately in concurrent tasks.
Added ConnectUDPExample.swift to show the proposed shape end to end.

Result

APIs for sending/receiving unreliable HTTP Datagrams added.

### Motivation Users may wish to send/receive HTTP Datagrams ([RFC 9297](https://datatracker.ietf.org/doc/html/rfc9297)) using NIOHTTPServer. This PR introduces reader and writer APIs for unreliable datagrams. Note that the underlying support is yet to be provided by `swift-nio-http3`. The read/write source is not wired up, and we currently throw an error when attempting to read or write to/from the unreliable datagram stream. ### Modifications - Added an `UnstableHTTPDatagrams` trait, disabled by default. All new APIs are behind that trait (note that the `HTTP3` trait must also be enabled as unreliable datagrams are currently only supported over QUIC). - Added a `withDatagramReader` method on `NIOHTTPServer.Reader` and a `withDatagramWriter` method on `NIOHTTPServer.ResponseSender.Writer`. Both methods are `consuming` and take a closure that receive the reliable request/response body reader/writer and optionally the unreliable datagram reader/writer as arguments. - In both methods, the readers/writers are passed as `consuming sending`, so callers can run the readers/writers separately in concurrent tasks. - Added `ConnectUDPExample.swift` to show the proposed shape end to end. ### Result APIs for sending/receiving unreliable HTTP Datagrams added.

gjcairo · 2026-07-31T10:15:20Z

+        #if HTTP3 && UnstableHTTPDatagrams
+        /// The unreliable datagram reader, present when the underlying transport is capable of reading/writing
+        /// unreliable datagrams.
+        private var datagramReader: Disconnected<NIOHTTPServer.DatagramReader>?


Do we need Disconnected?

Yes, without this, the datagramReader can't be vended out as sending in withDatagramReader.

I see.

I am quite unconvinced about storing this reader inside the stream reader to be honest - I think it would make more sense to have this somewhere else, like the request context. But I'm also aware this will likely be temporary until we can come up with a more general solution to CONNECT.

gjcairo · 2026-07-31T10:47:07Z

+        public consuming func withDatagramWriter(
+            _ body: (consuming sending Self, consuming sending NIOHTTPServer.DatagramWriter?) async throws -> Void
+        ) async throws {
+            let streamFinish = NIOHTTPServer.StreamFinish(writer: self.writer, state: self.writerState)


I think this type is a bit unnecessary and adds some indirection which makes things harder to follow, IMO. I'd just finish both streams inline in this func, like we do elsewhere.

We unfortunately need this indirection because we pass the stream writer (and the datagram writer) as consuming sending to the body closure, which means we can't call finish on either after the body closure.

This is actually making me doubt we need to have a with-style method (also on the reader). I don't think we should finish the writers implicitly - we don't do this for the normal stream writer: we just expose write and finish. Why not return a tuple with both writers (and readers) instead of having a closure?

Regardless of whether we should automatically finish or not

Why not return a tuple with both writers (and readers) instead of having a closure?

This won't work because tuples with non-Copyable elements aren't supported yet.

I think the closure shape is the only shape that allows both the readers/writers to be run in concurrent tasks.

gjcairo · 2026-08-05T14:08:20Z

+        #if HTTP3 && UnstableHTTPDatagrams
+        /// The unreliable datagram reader, present when the underlying transport is capable of reading/writing
+        /// unreliable datagrams.
+        private var datagramReader: Disconnected<NIOHTTPServer.DatagramReader>?


I see.

I am quite unconvinced about storing this reader inside the stream reader to be honest - I think it would make more sense to have this somewhere else, like the request context. But I'm also aware this will likely be temporary until we can come up with a more general solution to CONNECT.

gjcairo · 2026-08-05T14:10:52Z

+    ///
+    /// - Note: Both readers are passed as `consuming sending`. This means that `body` can use both readers in separate
+    ///   tasks.
+    public consuming func withDatagramReader(


Related to my last comment, some things about this function I'm not sure about. The fact we need to create a new Reader isn't great. Users would also be able to call withDatagramReader again on the streamReader that's returned (since it's the same type), which is a bit weird. Again, perhaps it's fine since this will be temporary, but I thought I'd point them out.

gjcairo · 2026-08-05T14:21:23Z

+        public consuming func withDatagramWriter(
+            _ body: (consuming sending Self, consuming sending NIOHTTPServer.DatagramWriter?) async throws -> Void
+        ) async throws {
+            let streamFinish = NIOHTTPServer.StreamFinish(writer: self.writer, state: self.writerState)


This is actually making me doubt we need to have a with-style method (also on the reader). I don't think we should finish the writers implicitly - we don't do this for the normal stream writer: we just expose write and finish. Why not return a tuple with both writers (and readers) instead of having a closure?

aryan-25

The revised shape looks good. Just some small comments. Thanks for driving this forward @gjcairo!

aryan-25 · 2026-08-13T15:27:39Z

LGTM, thank you!

guoye-zhang · 2026-08-13T16:59:58Z

+extension NIOHTTPServer {
+    /// A reader for the unreliable datagram stream.
+    public struct DatagramReader: AsyncReader, ~Copyable {
+        public typealias ReadElement = UInt8


Should the element be a datagram instead of a byte?

aryan-25 requested review from ehaydenr and gjcairo July 31, 2026 09:25

aryan-25 added the 🆕 semver/minor Adds new public API. label Jul 31, 2026

aryan-25 mentioned this pull request Jul 31, 2026

WebSocket support to the HTTP server #100

Open

gjcairo requested changes Jul 31, 2026

View reviewed changes

Explicitly spell out ambiguous .inits

5986cd4

aryan-25 requested a review from gjcairo July 31, 2026 12:25

gjcairo reviewed Aug 5, 2026

View reviewed changes

Replace with-style reader and writer APIs

0afc478

aryan-25 commented Aug 13, 2026

View reviewed changes

ehaydenr approved these changes Aug 13, 2026

View reviewed changes

PR changes

5d5cad2

Format

b2e5e93

gjcairo enabled auto-merge (squash) August 13, 2026 15:35

guoye-zhang reviewed Aug 13, 2026

View reviewed changes

Uh oh!

Conversation

aryan-25 commented Jul 31, 2026

Motivation

Modifications

Result

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aryan-25 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aryan-25 commented Aug 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants