From 48906512cbd2b38326af4b8732860bcfb9296f44 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 01:50:55 +0000 Subject: [PATCH] Move iOS to swift-nio-http3 and add HTTP/3 datagram sessions The iOS bridge now runs on swift-nio-http3 and swift-nio-quic instead of URLSession, which has no HTTP datagram API. It keeps the method and event channel protocol, reports failures in NSURLErrorDomain codes, and adds openDatagrams / sendDatagram / datagram events: an Extended CONNECT (RFC 9220) stream carrying HTTP datagrams (RFC 9297). - Dart: NativeHttpClient.openDatagramSession returning a DatagramSession; Android (Cronet) throws UnsupportedError. NativeHttpConfig gains connectTimeout (iOS), and quicIdleTimeout now applies on iOS too. - iOS now needs iOS 27 (the libraries' availability) and speaks HTTP/3 only: no HTTP/2 fallback. A rejected certificate is reported as -1200 (notSent), since the QUIC stack doesn't say why a TLS handshake failed. Writes have no backpressure: swift-nio-quic completes them once buffered. - Request streams set halfCloseOnStopSending: without it, a server's STOP_SENDING closes the whole stream and swift-nio-http3 asserts. - The Swift core builds on Linux; CI runs its tests in swift:6.4.2 against the Go test server, which gains a /datagrams/echo endpoint. - Removed the Connect end-stream detector and URLSession header fixups, which only URLSession needed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BqmpXUbxP9wUhn1EyGGpc6 --- .github/workflows/ci.yaml | 19 +- .gitignore | 3 + README.md | 241 +++-- example/integration_test/eliza_test.dart | 63 +- .../integration_test/public_server_test.dart | 18 +- example/ios/Runner.xcodeproj/project.pbxproj | 6 +- ios/connect_native_http/Package.swift | 52 +- .../ConnectNativeHttpCore/HTTP3Bridge.swift | 884 ++++++++++++++++++ .../URLSessionBridge.swift | 410 -------- .../ConnectNativeHttpPlugin.swift | 8 +- .../HTTP3BridgeTests.swift | 470 ++++++++++ .../URLSessionBridgeTests.swift | 276 ------ lib/connect_native_http.dart | 3 +- lib/src/channel/channel_http_client.dart | 159 +++- lib/src/channel/connect_end_stream.dart | 54 -- lib/src/datagram_session.dart | 54 ++ lib/src/native_http_client.dart | 28 +- lib/src/native_http_config.dart | 27 +- lib/src/nio_http3/nio_http3_client.dart | 52 ++ .../ns_url_error.dart | 0 lib/src/url_session/response_headers.dart | 21 - .../url_session/url_session_http_client.dart | 50 - pubspec.yaml | 6 +- test/connect_end_stream_test.dart | 75 -- test/error_classification_test.dart | 2 +- test/nio_http3_client_test.dart | 173 ++++ test/url_session_headers_test.dart | 29 - test_server/datagrams.go | 63 ++ test_server/datagrams_test.go | 99 ++ test_server/main.go | 3 + 30 files changed, 2256 insertions(+), 1092 deletions(-) create mode 100644 ios/connect_native_http/Sources/ConnectNativeHttpCore/HTTP3Bridge.swift delete mode 100644 ios/connect_native_http/Sources/ConnectNativeHttpCore/URLSessionBridge.swift create mode 100644 ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/HTTP3BridgeTests.swift delete mode 100644 ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/URLSessionBridgeTests.swift delete mode 100644 lib/src/channel/connect_end_stream.dart create mode 100644 lib/src/datagram_session.dart create mode 100644 lib/src/nio_http3/nio_http3_client.dart rename lib/src/{url_session => nio_http3}/ns_url_error.dart (100%) delete mode 100644 lib/src/url_session/response_headers.dart delete mode 100644 lib/src/url_session/url_session_http_client.dart delete mode 100644 test/connect_end_stream_test.dart create mode 100644 test/nio_http3_client_test.dart delete mode 100644 test/url_session_headers_test.dart create mode 100644 test_server/datagrams.go create mode 100644 test_server/datagrams_test.go diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1eea565..fa0867f 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -69,13 +69,24 @@ jobs: timeout-minutes: 5 run: go test ./... + # The core needs no Apple SDK, and swift-nio-http3 needs Swift 6.4 and, on Apple platforms, macOS 27, so it is tested + # on Linux. swift-core: - name: Swift core tests (macOS) - runs-on: macos-latest - timeout-minutes: 10 + name: Swift core tests (Linux) + runs-on: ubuntu-latest + container: swift:6.4.2-noble + timeout-minutes: 20 steps: - uses: actions/checkout@v7 timeout-minutes: 5 + # The SwiftPM build of swift-nio-http3 and its dependencies, which takes minutes from cold. + - name: Cache SwiftPM build + uses: actions/cache@v6 + timeout-minutes: 5 + with: + path: ios/connect_native_http/.build + key: swift-core-${{ hashFiles('ios/connect_native_http/Package.swift') }} + restore-keys: swift-core- - uses: actions/setup-go@v7 timeout-minutes: 5 with: @@ -96,7 +107,7 @@ jobs: cat server.log >&2 exit 1 - name: Swift tests - timeout-minutes: 5 + timeout-minutes: 15 working-directory: ios/connect_native_http env: CONNECT_NATIVE_HTTP_CORE_ONLY: "1" diff --git a/.gitignore b/.gitignore index 6ed774e..1906314 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,6 @@ ios/connect_native_http/.swiftpm/ # Test server build output and the certificates it writes test_server/connect-native-http-test-server test_server/certs/ + +# SwiftPM: the core package resolves its own dependencies; Flutter resolves the app's. +ios/connect_native_http/Package.resolved diff --git a/README.md b/README.md index 57eb01a..b4b8a57 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,21 @@ # connect_native_http -connect-dart `HttpClient`s that run on the platform's own HTTP stack: URLSession on iOS, and Cronet on Android. The platform negotiates HTTP/3 (QUIC) or HTTP/2 itself, falls back to HTTP/2 over TCP when QUIC fails, and -carries full-duplex streams, so all four Connect RPC kinds work, bidi included. +connect-dart `HttpClient`s that carry full-duplex streams over HTTP/3, so all four Connect RPC kinds work, bidi +included, plus HTTP/3 datagram sessions on iOS: -Status: experimental. +- **iOS 27+:** [swift-nio-http3](https://github.com/apple/swift-nio-http3) on + [swift-nio-quic](https://github.com/apple/swift-nio-quic). Every call goes over HTTP/3; there is no HTTP/2 fallback. + Datagram sessions (Extended CONNECT with HTTP datagrams, RFC 9220 and RFC 9297) are available. +- **Android:** Cronet, which negotiates HTTP/3 (QUIC) or HTTP/2 itself and falls back to HTTP/2 over TCP when QUIC + fails. No datagram sessions. + +Status: experimental. swift-nio-http3 and swift-nio-quic are pre-1.0 and say their APIs are not stable; see "iOS: +swift-nio-http3" below for what that means here. ## Use -Pair it with the **Connect protocol**. Neither platform stack exposes HTTP trailers to the app, and the gRPC protocol -carries its status in trailers. +Pair it with the **Connect protocol**. Cronet doesn't expose HTTP trailers to the app, and the gRPC protocol carries +its status in trailers. ```dart final origin = Uri.parse('https://example.com'); @@ -27,23 +34,30 @@ final transport = connect_protocol.Transport( `NativeHttpClient.create` returns `null` on platforms without a native client. -**List every origin that serves HTTP/3 in `http3Origins`.** Without it, URLSession learns HTTP/3 from `Alt-Svc` but -only uses it on a new connection. A session that stays busy keeps reusing its first HTTP/2 connection indefinitely. +**On iOS, the server must serve HTTP/3.** A network that blocks UDP fails every call; there is no TCP to fall back +to. Apps that must work there need a second client (for example connect-dart's HTTP/2 transport) and their own +fallback. + +**On Android, list every origin that serves HTTP/3 in `http3Origins`,** so Cronet tries QUIC from the first request +rather than waiting for an `Alt-Svc` header. iOS ignores the list. A failed request throws a `ConnectException` with code `unavailable`. Its `cause` is a `NativeHttpException` that says whether the request provably never left the device (`requestNeverSent`), which makes re-sending it safe: | Failure | iOS (`NSURLErrorDomain` code) | Android (Cronet) | |---|---|---| -| `notSent` | Cannot find or connect to host, DNS failure, offline, TLS handshake failure | Failed before `onStreamReady`; the bridge writes no request body before it | -| `untrusted` | -1201 to -1204, certificate rejected | `net::` certificate errors -200 to -299, or a pin mismatch (-150) | -| `other` | Everything else, timeouts and dropped connections included | Any failure after `onStreamReady` | +| `notSent` | Cannot find host (-1003), no QUIC handshake within the connect timeout (-1004), TLS handshake failure, certificate rejections included (-1200) | Failed before `onStreamReady`; the bridge writes no request body before it | +| `untrusted` | Never: the QUIC stack reports a rejected certificate like any other TLS failure, so it is `notSent` (-1200) | `net::` certificate errors -200 to -299, or a pin mismatch (-150) | +| `other` | Everything else, read-idle timeouts (-1001) and dropped connections or streams (-1005) included | Any failure after `onStreamReady` | + +The iOS bridge reports its failures in `NSURLErrorDomain` codes, as URLSession would, so code that inspects +`platformCode` keeps working. No exception in the package should crash the app or leave a call hanging. Failures end the one call they concern: - **A request the platform stack rejects** fails that call as `notSent`. For example, Cronet throws on a header value with a line break. -- **A method call the plugin can't parse** gets an error reply instead of a force-unwrap (iOS) or an uncaught +- **A method call the plugin can't parse** gets an error reply instead of a crash (iOS) or an uncaught exception (Android). Uncaught exceptions on the Android bridge's thread would otherwise kill the process. - **A malformed event** fails its own call with `internal`. - **An exception from `onResponse`** goes to `FlutterError.onError`, like other errors that have no caller. The call @@ -52,6 +66,40 @@ No exception in the package should crash the app or leave a call hanging. Failur `NativeHttpClient.create` throws a `PlatformException` if the platform can't create a client, for example when Cronet's native library fails to load. +### Datagram sessions (iOS) + +A datagram session is an Extended CONNECT request (RFC 9220) whose stream stays open. Both sides can send HTTP +datagrams (RFC 9297) on it: unreliable, unordered messages that each fit in one QUIC packet. It shares its QUIC +connection with the client's RPCs to the same origin. + +```dart +final session = await native.openDatagramSession( + Uri.parse('https://example.com/telemetry'), + protocol: 'my-datagrams', // the :protocol pseudo-header; the server routes on it + headers: {'authorization': 'Bearer …'}, +); +session.datagrams.listen((datagram) => handle(datagram)); +await session.send(Uint8List.fromList(payload)); +// … +await session.close(); // finishes the request stream; `done` completes when the server ends the session +await session.done; +``` + +- **Opening** waits for the server's HTTP/3 SETTINGS. If the server doesn't offer both `SETTINGS_H3_DATAGRAM` and + `SETTINGS_ENABLE_CONNECT_PROTOCOL`, it fails with a `ConnectException` (`unavailable`, `NativeHttpException` cause) + without sending anything. A server that answers with a status other than 2xx gets `DatagramSessionRejected`. +- **`send`** completes once QUIC has taken the datagram, which says nothing about delivery. It throws a + `NativeHttpException` if the session has ended or the datagram is too large for the connection. +- **`datagrams`** buffers what arrives while nothing listens, and ends with the session, with the session's error if + it failed. **`data`** carries anything the server writes on the stream itself, such as capsules. +- **Ending:** `close()` finishes the request stream and the server is expected to end its side; `cancel()` resets the + stream at once. The connection's QUIC idle timeout and the client's `readIdleTimeout` apply as they do to calls. + Datagrams count as received for the read-idle timeout. +- **Android:** `openDatagramSession` throws `UnsupportedError`. Cronet has no HTTP datagram API. + +The test server's `/datagrams/echo` (`test_server/datagrams.go`) shows the server side in quic-go: set +`http3.Server.EnableDatagrams`, accept the CONNECT with `WriteHeader(200)`, take the stream over with +`http3.HTTPStreamer`, and use `ReceiveDatagram` and `SendDatagram`. ### Read-idle timeout A client can fail each of its calls once the call has received nothing from the server for a set time. Apart from @@ -68,14 +116,18 @@ that go quiet for long need a client without a read-idle timeout, or periodic me - **What it measures:** time since the call last received anything: headers, a body chunk or trailers. The timer starts when the call does, so it also bounds the wait for the response headers. A unary call the server holds longer than the timeout fails, and so does a stream that goes quiet for longer. -- **iOS:** `URLRequest.timeoutInterval`. URLSession treats a request's 60 s as unset and uses the session's value - instead, so the bridge sends 60.001 s for a 60 s timeout. -- **Android:** a timer in the bridge. +- **iOS and Android:** a timer in the bridge. - **The failure:** `unavailable`, with a `NativeHttpException` whose `platformCode` is `NSURLErrorTimedOut` (-1001) on iOS or `net::ERR_TIMED_OUT` (-7) on Android. On Android a timeout before `onStreamReady` is `notSent`, as with any other failure there. - **The connection:** see "Calls that run out of time" below. +### Connect timeout (iOS) + +`NativeHttpConfig.connectTimeout`, 10 s by default, bounds how long a new connection may take to resolve its host and +finish the QUIC handshake. The calls waiting for it then fail as `notSent` (-1004). QUIC ignores the ICMP error a +closed UDP port answers with, so without this a server that isn't there would hold calls until their deadlines. + ### Calls that run out of time A call that hits its read-idle timeout, or its deadline with `evictOnDeadline`, may be stuck on a dead connection. @@ -102,10 +154,10 @@ NativeHttpConfig( - **Without a step,** the server enforces the same deadline, but its clock starts later. On a healthy connection the client's deadline usually fires first, and with `evictOnDeadline` alone the connection would be evicted for nothing. -- **A dead connection is evicted.** Neither stack can close a single connection, so the client moves its new calls to - a fresh `URLSession` or `CronetEngine`, which dials its own connections. Calls already on the old one are not - canceled. They finish there, and it is released after the last one ends. Several calls that run out of time on the - same connection evict it once. +- **A dead connection is evicted.** On iOS the client takes the QUIC connection out of its pool, so new calls dial a + new one. Cronet can't close a single connection, so on Android the client moves its new calls to a fresh + `CronetEngine`. Calls already on the old connection are not canceled. They finish there, and it is closed or released + after the last one ends. Several calls that run out of time on the same connection evict it once. ## Server and infrastructure requirements @@ -116,11 +168,8 @@ found or verified with the tests in this package. - **The server speaks the Connect protocol.** connect-go serves it on the same handler as gRPC, with no configuration. Clients send `application/proto` (unary) and `application/connect+proto` (streams). -- **The server ends every Connect stream with an end-stream message.** connect-go always does. On iOS the client - relies on it to end a bidi call the server finishes first, because URLSession over HTTP/3 does not complete a task - while the request body is open. -**The HTTP/2 path (TCP, and the fallback when UDP is blocked)** +**The HTTP/2 path (Android: TCP, and the fallback when UDP is blocked)** - **Bidi needs HTTP/2 from end to end.** Every proxy or load balancer on the way must forward HTTP/2 to the server. An AWS ALB HTTP/1.1 target group breaks bidi. HTTP/2 and gRPC target groups carry it, and AWS documents that an @@ -138,39 +187,46 @@ found or verified with the tests in this package. - **QUIC version 1 on UDP.** For the client's own fallback to work, the endpoint should use the same host and port as HTTP/2 over TCP. For example, an AWS NLB `TCP_QUIC` listener, which needs TCP and UDP on the same target port. -- **The certificate must chain to a public root.** Cronet refuses QUIC otherwise (`ERR_QUIC_CERT_ROOT_NOT_KNOWN`, +- **The certificate must chain to a public root on Android.** Cronet refuses QUIC otherwise (`ERR_QUIC_CERT_ROOT_NOT_KNOWN`, `net/quic/crypto/proof_verifier_chromium.cc` in Chromium) and has no override. With a private CA, Android always stays on HTTP/2. ACM certificates (Amazon roots) qualify. -- **Clients must dial the HTTP/3 host directly and list it in `http3Origins`.** Don't rely on `Alt-Svc` to move - them: - - URLSession only acts on `Alt-Svc` for a new connection, and a busy session never opens one. - - An `Alt-Svc` that names a different host is followed only if the certificate also covers that host. +- **Clients must dial the HTTP/3 host directly.** iOS speaks HTTP/3 to whatever host the URL names and never reads + `Alt-Svc`. On Android, list the host in `http3Origins` rather than relying on `Alt-Svc`, which Cronet follows to a + different host only if the certificate also covers that host. - **QUIC idle timeout about 6–10 s, with pings every 2–3 s** (in quic-go: `MaxIdleTimeout`, `KeepAlivePeriod`). Keep the ping interval at most half the idle timeout. - - The idle timeout sets how fast clients notice a dead path, and it is the only control iOS has. See "Dead - connections" and "QUIC idle timeout vs HTTP/2 keepalive pings". + - The idle timeout sets how fast clients notice a dead path, unless the client sets a shorter one + (`quicIdleTimeout`). See "Dead connections" and "QUIC idle timeout vs HTTP/2 keepalive pings". - The pings keep healthy connections open, and they keep UDP flows alive through NATs and load balancers. An AWS NLB, for example, drops a UDP flow after 120 s of silence. -- **Send `Alt-Svc` on HTTP/2 responses** (`h3=":"`) for clients that weren't configured with the origin. +- **Send `Alt-Svc` on HTTP/2 responses** (`h3=":"`) for Android clients that weren't configured with the + origin. +- **For datagram sessions, offer HTTP datagrams and Extended CONNECT** in the server's SETTINGS. In quic-go, + `http3.Server.EnableDatagrams` does both (the server always offers Extended CONNECT). DATAGRAM frames travel inside + ordinary QUIC packets, so a QUIC passthrough load balancer such as an AWS NLB QUIC listener carries them; this has + not been tested here. **Observability** -- **Count requests by protocol on the server.** In Go that's `http.Request.Proto`. iOS doesn't report the protocol - it negotiated, so the server is the only place to see how often clients fall back to HTTP/2. The test server echoes - it in `X-Proto`. +- **Count requests by protocol on the server.** In Go that's `http.Request.Proto`. It shows how often Android clients + fall back to HTTP/2. The test server echoes it in `X-Proto`. ## Platform behavior | | iOS | Android | |---|---|---| -| Stack | URLSession, through the Swift plugin in `ios/` (Swift Package Manager only) | Cronet `BidirectionalStream`, through the Kotlin plugin in `android/` | -| HTTP/3 | From the first request for `http3Origins`; otherwise learned from `Alt-Svc` | Same | -| Certificates | System trust store | System trust store; QUIC only with certificates that chain to a public root | -| Negotiated protocol | Not exposed (`NativeHttpResponseInfo.protocol` is `null`) | `h2` or `quic/1+spdy/3` (HTTP/3) | -| QUIC idle timeout | No setting; the server's advertised value applies | `NativeHttpConfig.quicIdleTimeout`, in whole seconds | -| Read-idle timeout | `NativeHttpConfig.readIdleTimeout`, through `URLRequest.timeoutInterval`. Without one, a task that receives nothing for a day fails | `NativeHttpConfig.readIdleTimeout`, through a timer in the bridge. None without one | -| HTTP/1.1 and `http://` | Left to URLSession; not tested | Not carried: Cronet's `BidirectionalStream` fails a call unless HTTP/2 or HTTP/3 is negotiated (`net::ERR_FAILED`), and takes only `https://` URLs (`net::ERR_DISALLOWED_URL_SCHEME`) | -| Redirects | Followed only for requests without a body; otherwise the 3xx response is returned, since a streamed body can't be resent | Not tested | +| Stack | swift-nio-http3 and swift-nio-quic, through the Swift plugin in `ios/` (Swift Package Manager only), iOS 27+ | Cronet `BidirectionalStream`, through the Kotlin plugin in `android/` | +| HTTP/3 | Always, to any origin; no HTTP/2 fallback | From the first request for `http3Origins`; otherwise learned from `Alt-Svc`; HTTP/2 fallback | +| Connections | One QUIC connection per origin per client, on its own UDP socket, shared by calls and datagram sessions | Cronet's pool | +| Certificates | System trust store, through Security.framework | System trust store; QUIC only with certificates that chain to a public root | +| Negotiated protocol | `h3` | `h2` or `quic/1+spdy/3` (HTTP/3) | +| QUIC idle timeout | `NativeHttpConfig.quicIdleTimeout`, in milliseconds; 30 s otherwise, or the server's value if smaller | `NativeHttpConfig.quicIdleTimeout`, in whole seconds | +| Connect timeout | `NativeHttpConfig.connectTimeout`, 10 s by default | None; use deadlines | +| Read-idle timeout | `NativeHttpConfig.readIdleTimeout`, through a timer in the bridge. None without one | Same | +| Datagram sessions | `openDatagramSession` | Not supported | +| HTTP/1.1 and `http://` | Not carried: `http://` URLs fail as -1002 | Not carried: Cronet's `BidirectionalStream` fails a call unless HTTP/2 or HTTP/3 is negotiated (`net::ERR_FAILED`), and takes only `https://` URLs (`net::ERR_DISALLOWED_URL_SCHEME`) | +| Redirects | Never followed; the 3xx response is returned | Not tested | +| Request body backpressure | None: a write completes once swift-nio-quic has buffered it, so a server that stops reading leaves the rest in memory | A write completes once Cronet has sent it | ### Dead connections @@ -180,13 +236,15 @@ connection on its own, so nothing has to reset anything. Two settings make this connections: - **Server: a short idle timeout and frequent pings.** For example `MaxIdleTimeout` 6–10 s and `KeepAlivePeriod` - 2–3 s. The pings keep a quiet but healthy connection alive. The idle timeout is what iOS gets, since URLSession has - no setting of its own. -- **Android: optionally `quicIdleTimeout`.** Detection then doesn't depend on the server's value. + 2–3 s. The pings keep a quiet but healthy connection alive. +- **Client: optionally `quicIdleTimeout`.** Detection then doesn't depend on the server's value. The iOS client sends + no pings of its own, so its idle timeout is only safe with a server that pings more often. The integration tests measure both: -- With the server advertising 3 s, a frozen path failed an open iOS stream after 2.98 s. +- With the server advertising 3 s, a frozen path failed an open iOS stream after 2.98 s (measured with URLSession, + before the move to swift-nio-http3; the integration test still checks the bound). With `quicIdleTimeout: 1s`, the + Swift core tests fail a call on a frozen path in about 1 s, and the next call dials a new connection. - With pings every second, a quiet stream outlived twice the idle timeout. - On Android, `quicIdleTimeout: 3s` ended a quiet stream within the bound, and the same stream without the setting was still open after 8 s. @@ -194,8 +252,8 @@ The integration tests measure both: Clients may enforce a floor on the peer's value. quic-go's client raises anything under 5 s to 5 s (`protocol.MinRemoteIdleTimeout`), so measure any other client before relying on a short server value. -None of this works on the **HTTP/2 fallback** used where UDP is blocked. Neither stack exposes HTTP/2 pings, so a TCP -connection that dies without the interface going down goes unnoticed until a call on it runs out of time: a read-idle +None of this works on Android's **HTTP/2 fallback** used where UDP is blocked. Cronet doesn't expose HTTP/2 pings, so a +TCP connection that dies without the interface going down goes unnoticed until a call on it runs out of time: a read-idle timeout, or a deadline with `evictOnDeadline` (see "Calls that run out of time"). The integration tests check this: - Over a frozen HTTP/2 connection nothing arrives for 3 s, and a new call on the same client waits on it until its @@ -216,7 +274,7 @@ not over HTTP/2. | Who sets it | Both advertise a value; the connection uses the smaller (RFC 9000 §10.1) | Each side sets its own pings | | Can a server setting make the client notice? | Yes. A short server value becomes the client's timeout, and the server's pings stop arriving once the path dies. | No. A server that detects a dead connection can't tell the client, because nothing gets through. | | Through a load balancer | NLB QUIC passthrough is end to end, so the client sees the server's pings | An ALB ends HTTP/2 on each side, so the server's pings stop at the ALB. AWS doesn't document the ALB pinging clients, and nothing here relies on it. | -| Client control here | Android: `quicIdleTimeout`. iOS: none. Both: a read-idle timeout, and `evictOnDeadline`. | No pings: neither URLSession nor Cronet exposes HTTP/2 ping settings. Both: a read-idle timeout, and `evictOnDeadline`. | +| Client control here | `quicIdleTimeout`, a read-idle timeout, and `evictOnDeadline` | Android only. No pings: Cronet doesn't expose HTTP/2 ping settings. A read-idle timeout, and `evictOnDeadline`. | | What a client that sends its own pings gets, for comparison | — | `package:http2` with 3 s pings and a 3 s timeout notices in about 6 s | So for servers: @@ -233,23 +291,40 @@ So for servers: ### When the server ends a bidi call first -Neither platform finishes a stream on its own while the client still has its request side open: - -- **Cronet** reports `onSucceeded` only once both sides are closed. The bridge ends the call as soon as it has read - the whole response, and closes the request side itself. -- **URLSession over HTTP/3** never completes the task while the request body is open. This holds even after the - server sends `STOP_SENDING`, and Apple's own bound streams behave the same way. Over HTTP/2 the task completes. - For Connect streaming responses (`application/connect+…`), the client therefore watches for the end-stream message - and ends the call when it arrives. +Both bridges end the call as soon as they have read the whole response, and close the request side themselves: + +- **Cronet** reports `onSucceeded` only once both sides are closed, so the bridge doesn't wait for it. +- **iOS** ends the call on the response's end. A server that has its answer typically also stops reading the request + (`STOP_SENDING`; quic-go sends it whenever a handler returns before reading the whole body). swift-nio-quic would + close the whole stream on that, response included, so the bridge sets swift-nio-quic's `halfCloseOnStopSending` + option on every request stream, which closes only the request side. + +### iOS: swift-nio-http3 + +The iOS client used URLSession until it moved to swift-nio-http3, for HTTP datagrams, which URLSession doesn't offer. +What changed with it: + +- **iOS 27 and Swift 6.4.** swift-nio-http3 and swift-nio-quic mark their APIs `@available(iOS 27, macOS 27, …)`, so + the plugin's minimum is iOS 27, and apps that use it need Xcode 27. +- **HTTP/3 only.** URLSession raced QUIC against TCP and fell back to HTTP/2 on its own. swift-nio-http3 has no HTTP/2, + so where UDP is blocked calls fail as `notSent`. +- **Pre-1.0 dependencies.** swift-nio-http3 has no release yet and is pinned to a commit in + `ios/connect_native_http/Package.swift`; swift-nio-quic is taken `.upToNextMinor(from: "0.6.0")`. Both say their APIs + aren't stable. Moving the pin is a deliberate change to test. +- **A QUIC stack in Swift, on BSD sockets.** swift-nio-quic implements QUIC itself (swift-network-evolution, SwiftTLS) + on NIO's POSIX sockets, not Network.framework. System proxy settings and Wi-Fi Assist don't apply, and moving between + networks has not been tested; expect a dropped connection, which the next call redials. +- **Logging.** swift-nio-quic logs through swift-log. With no logging backend set up, swift-log prints to stdout, + which includes notices for every stream reset and TLS failure. An app can call `LoggingSystem.bootstrap` to route or + silence it. +- **Write backpressure** and the **TLS failure detail** are lost; see the platform table and the error table above. ### Design notes -- Both platforms use a small native plugin behind the same method and event channel protocol, and one Dart adapter +- Both platforms use a small native plugin behind the same method and event channel protocol (iOS adds the datagram + methods and events), and one Dart adapter (`lib/src/channel/`) turns it into a connect-dart `HttpClient`. The package depends only on `connectrpc` and Flutter, so it can't conflict with an app over shared native-interop packages. -- `package:cupertino_http` isn't used: it builds its URLSession delegate in Dart through `package:objective_c`, which - every package in an app must share. `objective_c` 9.6.3, for example, fails every session creation in iOS 18 debug - builds. - Cronet is bundled (`org.chromium.net:cronet-embedded`), not Google Play services Cronet. Every device runs the same version, and devices without Play services work. It costs about 6.5 MB uncompressed on arm64. - `package:cronet_http` can't do this job: it uses Cronet's `UrlRequest`, which reads the whole request body before @@ -257,8 +332,8 @@ Neither platform finishes a stream on its own while the client still has its req ## Tests -- **`test/`:** host unit tests, runnable on Linux CI. They cover error classification, Connect end-stream detection, - URLSession response headers, and the shared channel adapter against a fake plugin. +- **`test/`:** host unit tests, runnable on Linux CI. They cover error classification, and the shared channel adapter + and datagram sessions against fake plugins. - **`test_server/`:** a Go server for `connectrpc.eliza.v1.ElizaService` over HTTP/2 and HTTP/3, scripted for tests (see `eliza.go`). - `-max-idle` and `-keepalive` set its QUIC idle timeout and ping interval. @@ -268,8 +343,10 @@ Neither platform finishes a stream on its own while the client still has its req clients already have. It drops what they send and what the server writes, then closes them. Connections opened later work, so a client that dials again gets through. - `POST /unfreeze` ends both. - - Its own tests (`go test ./...`) check it over HTTP/3, including the idle timeout, pings and freezing, and check - the TCP freeze over HTTP/2. + - `/datagrams/echo` accepts Extended CONNECT with `:protocol` `datagram-echo` and echoes every HTTP datagram. A + datagram `close` ends the session from the server's side. + - Its own tests (`go test ./...`) check it over HTTP/3, including the idle timeout, pings, freezing and the datagram + echo, and check the TCP freeze over HTTP/2. - It creates a CA in `test_server/certs/` on first start and reuses it, so a device only has to trust it once. - With `QLOGDIR` set, it writes a qlog trace of each QUIC connection there, which shows the server's side of a handshake. @@ -288,17 +365,16 @@ Neither platform finishes a stream on its own while the client still has its req Output also goes to `build/integration_test__.log`. It covers unary calls, errors, deadlines, server streaming, and full-duplex bidi where the server speaks first and - finishes first. It also checks the failure classes (`notSent`, `untrusted`) and the negotiated protocol: HTTP/3 on - iOS, and HTTP/2 on Android, since the server's private CA keeps Cronet off QUIC. On iOS a fresh client's first call, - before any Alt-Svc, must reach HTTP/3 within a few fresh clients. A loaded simulator sometimes lets TCP win - URLSession's race even locally, so a single fallback is logged rather than failed. + finishes first. It also checks the failure classes (`notSent`, and `untrusted` on Android) and the negotiated + protocol: HTTP/3 on iOS, and HTTP/2 on Android, since the server's private CA keeps Cronet off QUIC. On iOS a + datagram session echoes datagrams; on Android it is refused. The script starts the server with a 3 s idle timeout and 1 s pings. Over HTTP/3 (iOS) the tests also check two things: a quiet stream outlives the idle timeout, and a frozen path fails an open stream within it. - The read-idle timeout is tested over HTTP/2 on both platforms. On iOS each of these cases freezes the server's UDP - first, so URLSession falls back to TCP as it would where UDP is blocked. The server reports each call's client - address in `X-Remote-Addr`, which shows whether two calls shared a connection. The cases check five things: + The read-idle timeout and eviction are tested over HTTP/2 on Android; iOS, which has no HTTP/2, skips these cases + and has the same behavior covered by the Swift core tests. The server reports each call's client address in + `X-Remote-Addr`, which shows whether two calls shared a connection. The cases check five things: - A quiet stream fails at its timeout. - A stream that keeps receiving outlives its timeout. - A frozen connection draws no error, and new calls go to it until one hits its deadline. With `evictOnDeadline`, @@ -307,14 +383,19 @@ Neither platform finishes a stream on its own while the client still has its req - With `deadlineStep`, the server answers a deadline a step before the client's, and the client stays on the same connection. - **Native bridge tests:** the same script runs them after the Dart tests, against the same server. Each platform's - bridge (`URLSessionBridge`, `CronetBridge`) has no Flutter dependency, and the tests call it directly, for behavior + bridge (`HTTP3Bridge`, `CronetBridge`) has no Flutter dependency, and the tests call it directly, for behavior Dart can't reach: - - **iOS (`ios/connect_native_http/Tests`, XCTest):** a write stuck on a full buffer returns once the call is - canceled or its connection fails; a redirect of a request with a body is returned, not followed; shutting a - session down lets its calls finish and refuses new ones; a read-idle timeout fails a quiet call with - `NSURLErrorTimedOut`, and the engine's next call works; a call canceled at its deadline ends at once, and the - engine's next call works. The script runs them on the simulator. For a quick loop on the Mac, against a running - test server: + - **iOS (`ios/connect_native_http/Tests`, XCTest):** unary calls go over HTTP/3 and share one connection; a call + ends with its response while its request side is still open (after the server's `STOP_SENDING`); writes waiting + for a connection return once it fails, as `notSent`; a certificate from another CA fails the handshake; a redirect + is returned, not followed; shutting an engine down lets its calls finish and refuses new ones; a read-idle + timeout fails a quiet call with `NSURLErrorTimedOut`, and the engine's next call works; a call canceled at its + deadline ends at once; the QUIC idle timeout fails a call on a frozen path, and the next call reconnects. Datagram + sessions echo datagrams, may send before the server answers, end when the server ends them, share a connection + with calls and other sessions, and refuse an oversized datagram without ending. + + The core builds without Apple's SDKs, so CI runs these on Linux in the `swift:6.4.2` image; the script also runs + them on the simulator. Locally, with Swift 6.4 on macOS 27 or Linux, against a running test server: ```bash cd ios/connect_native_http && CONNECT_NATIVE_HTTP_CORE_ONLY=1 SERVER_URL=https://localhost:8443 \ @@ -327,8 +408,8 @@ Neither platform finishes a stream on its own while the client still has its req read-idle timeout fails a quiet call with -7, once, and the engine's next call works; data arriving resets the timer; a call canceled at its deadline ends at once, and the engine's next call works. - Both platforms' suites also check that malformed method calls get an error reply and leave the bridge working. -- **`example/integration_test/public_server_test.dart`:** HTTP/3 on Android against a server with a public - certificate. It also checks that `quicIdleTimeout` ends a quiet connection, against a control without it. It is +- **`example/integration_test/public_server_test.dart`:** HTTP/3 against a server with a public certificate, which + Android needs for QUIC. It also checks that `quicIdleTimeout` ends a quiet connection, against a control without it. It is opt-in because it needs the internet: ```bash diff --git a/example/integration_test/eliza_test.dart b/example/integration_test/eliza_test.dart index b446fef..af42839 100644 --- a/example/integration_test/eliza_test.dart +++ b/example/integration_test/eliza_test.dart @@ -42,6 +42,7 @@ final class Harness { String baseUrl, { Set http3Origins = const {}, Duration? readIdleTimeout, + Duration? connectTimeout, Duration? deadlineStep, bool evictOnDeadline = false, bool useHttpGet = false, @@ -51,6 +52,7 @@ final class Harness { NativeHttpConfig( http3Origins: http3Origins, readIdleTimeout: readIdleTimeout, + connectTimeout: connectTimeout, deadlineStep: deadlineStep, evictOnDeadline: evictOnDeadline, onResponse: (info) => harness.platformProtocols.add(info.protocol), @@ -112,10 +114,10 @@ Future<(StreamController, StreamIterator)> op /// A client whose pooled connection to the server negotiated [protocol], such as `HTTP/3.0`. /// -/// URLSession races QUIC against TCP for each new connection and keeps whichever connects first, so on a loaded -/// device a connection sometimes lands on HTTP/2 even for an HTTP/3 origin. A client keeps reusing the connection it -/// has, so each attempt uses a fresh client, closing the ones that got another protocol. Each attempt is that -/// client's first call, before any Alt-Svc: reaching HTTP/3 shows the client tried QUIC because of http3Origins. +/// iOS only speaks HTTP/3, so its first attempt gets it. Cronet may race QUIC against TCP for a new connection and +/// keep whichever connects first, and a client keeps reusing the connection it has, so each attempt uses a fresh +/// client, closing the ones that got another protocol. Each attempt is that client's first call, before any Alt-Svc: +/// reaching HTTP/3 shows the client tried QUIC because of http3Origins. Future harnessNegotiating(String protocol) async { final deadline = DateTime.now().add(const Duration(seconds: 5)); final protocols = []; @@ -139,8 +141,8 @@ Future harnessNegotiating(String protocol) async { } } -/// A client on HTTP/2, with the server's UDP frozen for the rest of the case so that QUIC can't connect: URLSession -/// then falls back to TCP, as on a network that blocks UDP. Android is on HTTP/2 with this server anyway. +/// A client on HTTP/2, with the server's UDP frozen for the rest of the case so that QUIC can't connect, as on a +/// network that blocks UDP. Android is on HTTP/2 with this server anyway. Not on iOS, which has no HTTP/2. Future harnessOverHttp2({ Duration? readIdleTimeout, Duration? deadlineStep, @@ -187,8 +189,8 @@ void main() { // One call on a throwaway client before any case. Right after the app launches, the simulator and the test server // on the same CI runner are both slow (a QUIC connection took 66 ms to set up, and the server answered its first - // packet 130 ms after it was sent), so the first call's QUIC attempt loses URLSession's race to TCP. The cases then - // start on a warm app and server. The protocol it got is logged, not checked. + // packet 130 ms after it was sent). The cases then start on a warm app and server. The protocol it got is logged, + // not checked. // // A few attempts, each on a fresh client whose call a deadline cancels: on a freshly booted simulator, trustd can // stall every certificate check for a while (once while it updated its pinning database from a trust data update). @@ -311,19 +313,26 @@ void main() { testCase('a refused connection is reported as never sent', (_) async { expect(unreachableUrl, isNotEmpty, reason: 'run with --dart-define=UNREACHABLE_URL=...'); - final unreachable = await Harness.create(unreachableUrl); + // QUIC ignores the ICMP error a closed UDP port answers with, so on iOS only the connect timeout notices. + final unreachable = await Harness.create(unreachableUrl, connectTimeout: const Duration(seconds: 3)); addTearDown(unreachable.native.close); final cause = await nativeCause(unreachable.eliza.say(SayRequest(sentence: 'hi'))); expect(cause.failure, NativeHttpFailure.notSent, reason: '$cause'); expect(cause.requestNeverSent, isTrue); }); - testCase('a certificate for another name is rejected as untrusted', (_) async { + testCase('a certificate for another name is rejected, and the request never sent', (_) async { expect(untrustedUrl, isNotEmpty, reason: 'run with --dart-define=UNTRUSTED_URL=...'); final untrusted = await Harness.create(untrustedUrl); addTearDown(untrusted.native.close); final cause = await nativeCause(untrusted.eliza.say(SayRequest(sentence: 'hi'))); - expect(cause.failure, NativeHttpFailure.untrusted, reason: '$cause'); + // The QUIC stack on iOS reports every failed TLS handshake alike: NSURLErrorSecureConnectionFailed (-1200). + expect( + cause.failure, + io.Platform.isIOS ? NativeHttpFailure.notSent : NativeHttpFailure.untrusted, + reason: '$cause', + ); + expect(cause.requestNeverSent, isTrue); }); testCase('negotiates the expected protocol', (_) async { @@ -380,8 +389,13 @@ void main() { expect(h3.serverProtocols.last, 'HTTP/3.0'); }, timeout: http3CaseTimeout); - // Over HTTP/2 neither platform notices a dead connection (no pings), so a read-idle timeout is what does. + // Over HTTP/2 Cronet doesn't notice a dead connection (no pings), so a read-idle timeout is what does. iOS has no + // HTTP/2. bool skipUnlessAdmin() { + if (io.Platform.isIOS) { + markTestSkipped('iOS speaks HTTP/3 only'); + return true; + } if (adminUrl.isEmpty) { markTestSkipped('needs ADMIN_URL'); return true; @@ -557,4 +571,29 @@ void main() { expect(stopwatch.elapsed, lessThan(serverMaxIdle + const Duration(seconds: 2))); await requests.close(); }, timeout: http3CaseTimeout); + + testCase('a datagram session echoes datagrams', (_) async { + final url = Uri.parse('$serverUrl/datagrams/echo'); + if (!io.Platform.isIOS) { + expect(() => harness.native.openDatagramSession(url, protocol: 'datagram-echo'), throwsUnsupportedError); + return; + } + final session = await harness.native.openDatagramSession(url, protocol: 'datagram-echo'); + expect(session.status, 200); + final echoes = StreamIterator(session.datagrams); + // Datagrams may be lost, even locally; resend until each comes back. + for (final text in ['one', 'two']) { + final payload = Uint8List.fromList(text.codeUnits); + var echoed = false; + for (var attempt = 0; attempt < 5 && !echoed; attempt++) { + await session.send(payload); + echoed = await echoes.moveNext().timeout(const Duration(seconds: 1), onTimeout: () => false); + } + expect(echoed, isTrue, reason: 'no echo of $text'); + expect(String.fromCharCodes(echoes.current), text); + } + await session.close(); + await session.done; + expect(await echoes.moveNext(), isFalse); + }); } diff --git a/example/integration_test/public_server_test.dart b/example/integration_test/public_server_test.dart index 0eef1f2..d47c7f3 100644 --- a/example/integration_test/public_server_test.dart +++ b/example/integration_test/public_server_test.dart @@ -17,7 +17,7 @@ import 'package:integration_test/integration_test.dart'; /// A real ELIZA, such as Connect's demo server. const publicElizaUrl = String.fromEnvironment('PUBLIC_ELIZA_URL'); -/// What Cronet reports for HTTP/3. URLSession reports nothing, so the check only applies on Android. +/// What Cronet reports for HTTP/3. iOS reports `h3`, and speaks nothing else. const cronetHttp3 = 'quic/1+spdy/3'; void main() { @@ -40,10 +40,8 @@ void main() { }); void expectHttp3() { - if (Platform.isAndroid) { - expect(protocols, isNotEmpty); - expect(protocols, everyElement(cronetHttp3)); - } + expect(protocols, isNotEmpty); + expect(protocols, everyElement(Platform.isAndroid ? cronetHttp3 : 'h3')); } testWidgets('unary over HTTP/3', (_) async { @@ -101,16 +99,16 @@ void main() { return (client, requests, responses); } - bool skipUnlessAndroid() { - if (publicElizaUrl.isEmpty || !Platform.isAndroid) { - markTestSkipped('PUBLIC_ELIZA_URL not set, or not Android: URLSession has no idle timeout setting'); + bool skipUnlessPublicServer() { + if (publicElizaUrl.isEmpty) { + markTestSkipped('PUBLIC_ELIZA_URL not set'); return true; } return false; } testWidgets('the client QUIC idle timeout ends a quiet connection', (_) async { - if (skipUnlessAndroid()) { + if (skipUnlessPublicServer()) { return; } final (client, requests, responses) = await quietConverse(quicIdle); @@ -123,7 +121,7 @@ void main() { testWidgets('without the setting the same quiet connection survives', (_) async { // The control for the previous case: the server keeps a quiet stream open, so the setting is what closed it. - if (skipUnlessAndroid()) { + if (skipUnlessPublicServer()) { return; } final (client, requests, responses) = await quietConverse(null); diff --git a/example/ios/Runner.xcodeproj/project.pbxproj b/example/ios/Runner.xcodeproj/project.pbxproj index eb2f895..f60f27a 100644 --- a/example/ios/Runner.xcodeproj/project.pbxproj +++ b/example/ios/Runner.xcodeproj/project.pbxproj @@ -364,7 +364,7 @@ GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; GCC_WARN_UNUSED_FUNCTION = YES; GCC_WARN_UNUSED_VARIABLE = YES; - IPHONEOS_DEPLOYMENT_TARGET = 15.0; + IPHONEOS_DEPLOYMENT_TARGET = 27.0; MTL_ENABLE_DEBUG_INFO = NO; SDKROOT = iphoneos; STRING_CATALOG_GENERATE_SYMBOLS = YES; @@ -491,7 +491,7 @@ GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; GCC_WARN_UNUSED_FUNCTION = YES; GCC_WARN_UNUSED_VARIABLE = YES; - IPHONEOS_DEPLOYMENT_TARGET = 15.0; + IPHONEOS_DEPLOYMENT_TARGET = 27.0; MTL_ENABLE_DEBUG_INFO = YES; ONLY_ACTIVE_ARCH = YES; SDKROOT = iphoneos; @@ -543,7 +543,7 @@ GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; GCC_WARN_UNUSED_FUNCTION = YES; GCC_WARN_UNUSED_VARIABLE = YES; - IPHONEOS_DEPLOYMENT_TARGET = 15.0; + IPHONEOS_DEPLOYMENT_TARGET = 27.0; MTL_ENABLE_DEBUG_INFO = NO; SDKROOT = iphoneos; STRING_CATALOG_GENERATE_SYMBOLS = YES; diff --git a/ios/connect_native_http/Package.swift b/ios/connect_native_http/Package.swift index d868605..b316bea 100644 --- a/ios/connect_native_http/Package.swift +++ b/ios/connect_native_http/Package.swift @@ -1,14 +1,37 @@ -// swift-tools-version: 5.9 +// swift-tools-version: 6.0 import PackageDescription // Flutter builds this package next to the FlutterFramework package it generates for the app. The Flutter-free core -// and its tests also build on their own, without it: +// and its tests also build on their own, without it, on macOS or Linux: // CONNECT_NATIVE_HTTP_CORE_ONLY=1 swift test +// +// swift-nio-http3 and swift-nio-quic need Swift 6.4 and, on Apple platforms, iOS or macOS 27. let coreOnly = Context.environment["CONNECT_NATIVE_HTTP_CORE_ONLY"] != nil -let core = Target.target(name: "ConnectNativeHttpCore") -let coreTests = Target.testTarget(name: "ConnectNativeHttpCoreTests", dependencies: ["ConnectNativeHttpCore"]) +let core = Target.target( + name: "ConnectNativeHttpCore", + dependencies: [ + .product(name: "NIOCore", package: "swift-nio"), + .product(name: "NIOPosix", package: "swift-nio"), + .product(name: "HTTP3", package: "swift-nio-http3"), + .product(name: "NIOHTTP3", package: "swift-nio-http3"), + .product(name: "NIOQUIC", package: "swift-nio-quic"), + .product(name: "NIOQUICHelpers", package: "swift-nio-quic-helpers"), + .product(name: "HTTPTypes", package: "swift-http-types"), + .product(name: "NIOHTTPTypes", package: "swift-nio-extras"), + .product(name: "Logging", package: "swift-log"), + .product(name: "X509", package: "swift-certificates"), + ], + swiftSettings: [.enableExperimentalFeature("AnyAppleOSAvailability")] +) +let coreTests = Target.testTarget( + name: "ConnectNativeHttpCoreTests", + dependencies: [ + "ConnectNativeHttpCore", + .product(name: "X509", package: "swift-certificates"), + ] +) let plugin = Target.target( name: "connect_native_http", dependencies: [ @@ -20,14 +43,23 @@ let plugin = Target.target( let package = Package( name: "connect_native_http", platforms: [ - .iOS("15.0"), - .macOS("12.0"), + .iOS("27.0"), + .macOS("27.0"), ], products: coreOnly ? [] : [ .library(name: "connect-native-http", targets: ["connect_native_http"]) ], - dependencies: coreOnly ? [] : [ - .package(name: "FlutterFramework", path: "../FlutterFramework") - ], - targets: coreOnly ? [core, coreTests] : [core, plugin, coreTests] + dependencies: [ + .package(url: "https://github.com/apple/swift-nio.git", from: "2.104.0"), + // swift-nio-http3 has no release yet, so it is pinned to a commit. + .package(url: "https://github.com/apple/swift-nio-http3.git", revision: "58ba11baee89b43ca1adeafe6bb976f17c9a86f3"), + .package(url: "https://github.com/apple/swift-nio-quic.git", .upToNextMinor(from: "0.6.0")), + .package(url: "https://github.com/apple/swift-nio-quic-helpers.git", .upToNextMinor(from: "0.1.2")), + .package(url: "https://github.com/apple/swift-http-types.git", from: "1.8.0"), + .package(url: "https://github.com/apple/swift-nio-extras.git", from: "1.22.0"), + .package(url: "https://github.com/apple/swift-log.git", from: "1.12.1"), + .package(url: "https://github.com/apple/swift-certificates.git", from: "1.21.0"), + ] + (coreOnly ? [] : [.package(name: "FlutterFramework", path: "../FlutterFramework")]), + targets: coreOnly ? [core, coreTests] : [core, plugin, coreTests], + swiftLanguageModes: [.v5] ) diff --git a/ios/connect_native_http/Sources/ConnectNativeHttpCore/HTTP3Bridge.swift b/ios/connect_native_http/Sources/ConnectNativeHttpCore/HTTP3Bridge.swift new file mode 100644 index 0000000..8e61c41 --- /dev/null +++ b/ios/connect_native_http/Sources/ConnectNativeHttpCore/HTTP3Bridge.swift @@ -0,0 +1,884 @@ +import Foundation +import HTTP3 +import HTTPTypes +import Logging +import NIOCore +import NIOHTTP3 +import NIOHTTPTypes +import NIOPosix +import NIOQUIC +import NIOQUICHelpers +import X509 + +// Bridges swift-nio-http3 to lib/src/nio_http3/nio_http3_client.dart, one HTTP/3 request stream per call, +// with the same channel protocol as the Android bridge. Dart sends request chunks as method calls; response headers, +// body chunks and the outcome go to `emit`. Kept free of Flutter so it can be tested without a Flutter app, on macOS +// or Linux. +// +// Datagram sessions add to that protocol: `openDatagrams` opens an Extended CONNECT (RFC 9220) request stream, and +// `sendDatagram` sends an HTTP datagram (RFC 9297) on it. Datagrams from the server arrive as `datagram` events. The +// session is otherwise a call like any other: `headers` with the server's answer, `data` with anything it writes on +// the stream, `end` and `cancel` to close it, and `done`, `failed` or `canceled` when it ends. +// +// Failures are reported in `NSURLErrorDomain` codes, which lib/src/nio_http3/ns_url_error.dart already classifies. +// +// Everything runs on one event loop, `loop`: the bridge's state, and every channel of every connection. +public final class HTTP3Bridge: @unchecked Sendable { + public enum Reply { + case success(Any?) + /// The call's arguments were not what the method takes. Refused rather than force-unwrapped, which would crash the + /// app. + case error(code: String, message: String) + case notImplemented + } + + struct BadArgument: Error { + let name: String + } + + private let emit: ([String: Any]) -> Void + /// When set, replaces the system trust store; tests use it for their own CA. + private let trustRoots: [Certificate]? + let loop: any EventLoop + private let logger: Logger + + /// How long a new connection may take to resolve and finish its QUIC handshake, unless its engine sets its own. QUIC + /// itself waits out its idle timeout before giving up on a server that never answers, and ignores ICMP errors. + var connectTimeout: TimeAmount = .seconds(10) + + private var engines: [Int: Engine] = [:] + private var calls: [Int: Call] = [:] + private var nextEngineId = 1 + + public convenience init(emit: @escaping ([String: Any]) -> Void) { + self.init(trustRoots: nil, emit: emit) + } + + init(trustRoots: [Certificate]?, emit: @escaping ([String: Any]) -> Void) { + self.trustRoots = trustRoots + self.emit = emit + self.loop = MultiThreadedEventLoopGroup.singleton.next() + var logger = Logger(label: "connect_native_http") + logger.logLevel = .critical + self.logger = logger + } + + /// Handles one method call. `reply` may be called on any thread. + public func handle(_ method: String, _ args: [String: Any], reply: @escaping (Reply) -> Void) { + do { + try dispatch(method, args, reply: reply) + } catch let bad as BadArgument { + reply(.error(code: "badArguments", message: "\(method): missing or mistyped argument \(bad.name)")) + } catch { + reply(.error(code: "badArguments", message: "\(method): \(error)")) + } + } + + private func arg(_ args: [String: Any], _ name: String) throws -> T { + guard let value = args[name] as? T else { throw BadArgument(name: name) } + return value + } + + /// An optional argument that must be a positive integer when present; absent or null for none. + private func optionalPositiveInt(_ args: [String: Any], _ name: String) throws -> Int? { + guard let value = args[name], !(value is NSNull) else { return nil } + guard let n = value as? Int, n > 0 else { throw BadArgument(name: name) } + return n + } + + private func headerList(_ args: [String: Any]) throws -> [[String]] { + let headers: [[String]] = try arg(args, "headers") + guard headers.allSatisfy({ $0.count == 2 }) else { throw BadArgument(name: "headers") } + return headers + } + + private func dispatch(_ method: String, _ args: [String: Any], reply: @escaping (Reply) -> Void) throws { + switch method { + case "createEngine": + // Every call goes over HTTP/3, so the origins that serve it need no list. Still checked, as the Dart client + // sends it. + let origins = args["http3Origins"] as? [[Any]] ?? [] + guard origins.allSatisfy({ $0.count == 2 }) else { throw BadArgument(name: "http3Origins") } + let quicIdleTimeoutMs = try optionalPositiveInt(args, "quicIdleTimeoutMs") + let connectTimeoutMs = try optionalPositiveInt(args, "connectTimeoutMs") + loop.execute { + let id = self.nextEngineId + self.nextEngineId += 1 + self.engines[id] = Engine( + id: id, quicIdleTimeoutMs: quicIdleTimeoutMs, connectTimeout: connectTimeoutMs.map { .milliseconds(Int64($0)) }) + reply(.success(id)) + } + case "shutdownEngine": + let engineId: Int = try arg(args, "engineId") + loop.execute { + // Calls in flight finish on their connections, which close once they have none left. + guard let engine = self.engines.removeValue(forKey: engineId) else { return } + for connection in engine.connections.values { + self.retire(connection) + } + engine.connections = [:] + } + reply(.success(nil)) + case "open", "openDatagrams": + let engineId: Int = try arg(args, "engineId") + let callId: Int = try arg(args, "callId") + let url: String = try arg(args, "url") + let headers = try headerList(args) + let readIdleTimeoutMs = try optionalPositiveInt(args, "readIdleTimeoutMs") + let kind: Call.Kind + if method == "open" { + let httpMethod: String = try arg(args, "method") + kind = .request(method: httpMethod) + } else { + let proto: String = try arg(args, "protocol") + kind = .datagrams(protocol: proto) + } + loop.execute { self.open(engineId, callId, url, kind, headers, readIdleTimeoutMs) } + reply(.success(nil)) + case "write": + let callId: Int = try arg(args, "callId") + let data: Data = try arg(args, "data") + // Replies once the bytes are written to the stream, so a fast producer waits for the network. + loop.execute { + guard let call = self.calls[callId] else { + reply(.success(nil)) + return + } + call.write(.body(ByteBuffer(bytes: data))) { reply(.success(nil)) } + } + case "end": + let callId: Int = try arg(args, "callId") + loop.execute { + self.calls[callId]?.write(.end(nil)) {} + } + reply(.success(nil)) + case "sendDatagram": + let callId: Int = try arg(args, "callId") + let data: Data = try arg(args, "data") + loop.execute { self.sendDatagram(callId, data, reply: reply) } + case "cancel": + let callId: Int = try arg(args, "callId") + // Set when the call hit its deadline. The server was given a deadline a step earlier, so on a live connection + // its deadline_exceeded would have ended the call first. + let value = args["evictConnection"] + guard value == nil || value is NSNull || value is Bool else { throw BadArgument(name: "evictConnection") } + let evict = value as? Bool ?? false + loop.execute { + guard let call = self.calls[callId] else { return } + if evict { + self.evictConnection(of: call) + } + self.finish(call, ["callId": callId, "type": "canceled"]) + } + reply(.success(nil)) + default: + reply(.notImplemented) + } + } + + static func now() -> UInt64 { + DispatchTime.now().uptimeNanoseconds + } + + // MARK: Engines and connections + + private final class Engine { + let id: Int + let quicIdleTimeoutMs: Int? + let connectTimeout: TimeAmount? + // The connection new calls to each origin ("host:port") go to. + var connections: [String: Connection] = [:] + + init(id: Int, quicIdleTimeoutMs: Int?, connectTimeout: TimeAmount?) { + self.id = id + self.quicIdleTimeoutMs = quicIdleTimeoutMs + self.connectTimeout = connectTimeout + } + } + + /// One QUIC connection to an origin, on a UDP socket of its own, so closing that socket ends everything on it. + final class Connection { + let origin: String + let host: String + let port: Int + var udp: (any Channel)? + var channel: (any Channel)? + var h3: HTTP3ClientConnection? + /// Succeeds once the connection can carry requests; fails if it can't be set up. + let ready: EventLoopPromise + /// Succeeds with the server's SETTINGS, which an Extended CONNECT has to wait for (RFC 9220 § 3). + let settings: EventLoopPromise + var calls: [Int: Call] = [:] + var datagramSessions: [QUICStreamID: Call] = [:] + var isReady = false + /// Taken out of its engine's pool: it closes once its last call ends. + var retired = false + var closed = false + /// When this connection last received anything, in uptime nanoseconds. + var lastReceived: UInt64 = 0 + + init(origin: String, host: String, port: Int, loop: any EventLoop) { + self.origin = origin + self.host = host + self.port = port + self.ready = loop.makePromise() + self.settings = loop.makePromise() + } + } + + private func connection(for engine: Engine, host: String, port: Int) -> Connection { + let origin = "\(host.lowercased()):\(port)" + if let existing = engine.connections[origin], !existing.closed { + return existing + } + let connection = Connection(origin: origin, host: host, port: port, loop: loop) + engine.connections[origin] = connection + connect(connection, quicIdleTimeoutMs: engine.quicIdleTimeoutMs) + let timeout = engine.connectTimeout ?? connectTimeout + loop.scheduleTask(in: timeout) { + if !connection.isReady && !connection.closed { + self.connectionFailed(connection, ConnectError.timedOut(timeout)) + } + } + return connection + } + + private func connect(_ connection: Connection, quicIdleTimeoutMs: Int?) { + let loop = self.loop + let host = connection.host + let port = connection.port + // getaddrinfo blocks, so it runs on NIO's thread pool. + let resolved = NIOThreadPool.singleton.runIfActive(eventLoop: loop) { + try SocketAddress.makeAddressResolvingHost(host, port: port) + } + resolved.whenFailure { error in + self.connectionFailed(connection, ConnectError.resolve(error)) + } + resolved.whenSuccess { address in + do { + try self.dial(connection, address: address, quicIdleTimeoutMs: quicIdleTimeoutMs) + } catch { + self.connectionFailed(connection, ConnectError.connect(error)) + } + } + } + + enum ConnectError: Error { + case resolve(any Error) + case connect(any Error) + case timedOut(TimeAmount) + } + + private func quicConfiguration(quicIdleTimeoutMs: Int?) -> QUICConfiguration { + var configuration = QUICConfiguration.forClient( + verificationConfiguration: .x509Certificates(trustRootsFilePath: nil), + applicationProtocols: ["h3"] + ) + if let ms = quicIdleTimeoutMs { + configuration.maxIdleTimeout = .milliseconds(ms) + } + return configuration + } + + private func dial(_ connection: Connection, address: SocketAddress, quicIdleTimeoutMs: Int?) throws { + let configuration = quicConfiguration(quicIdleTimeoutMs: quicIdleTimeoutMs) + let verifier = + if let trustRoots { + try AsyncVerifier(trustRoots: trustRoots, eventLoop: loop) + } else { + AsyncVerifier(eventLoop: loop) + } + let logger = self.logger + let bindHost = address.protocol == .inet6 ? "::" : "0.0.0.0" + let serverName = connection.host + DatagramBootstrap(group: loop) + .channelInitializer { udp in + udp.eventLoop.makeCompletedFuture { + let quic = QUICHandler( + channel: udp, + quicConfiguration: configuration, + asyncVerifier: verifier, + authenticator: nil, + logger: logger, + inboundConnectionInitializer: { _, _ in + udp.eventLoop.makeFailedFuture(ChannelError.operationUnsupported) + }, + inboundStreamInitializer: Self.inboundStream, + noMoreConnections: {} + ) + try udp.pipeline.syncOperations.addHandler(quic) + } + } + .bind(host: bindHost, port: 0) + .whenComplete { result in + switch result { + case .failure(let error): + self.connectionFailed(connection, ConnectError.connect(error)) + case .success(let udp): + connection.udp = udp + if connection.closed { + // Retired, or its engine shut down, while it was dialing. + udp.close(promise: nil) + return + } + self.handshake(connection, udp: udp, serverName: serverName, address: address) + } + } + } + + // Unidirectional streams the server opens (control, QPACK) go to the connection's HTTP/3 handler. + private static let inboundStream: @Sendable (any Channel) -> EventLoopFuture = { stream in + stream.parent!.pipeline.handler( + type: HTTP3ConnectionHandler.self + ).flatMap { $0.inboundStreamReceived(stream) } + } + + private func handshake(_ connection: Connection, udp: any Channel, serverName: String, address: SocketAddress) { + let logger = self.logger + let handler = ConnectionHandler(bridge: self, connection: connection) + let quic: QUICHandler + do { + quic = try udp.pipeline.syncOperations.handler(type: QUICHandler.self) + } catch { + connectionFailed(connection, ConnectError.connect(error)) + return + } + let established = quic.createOutboundConnection( + serverName: serverName, + remoteAddress: address, + connectionInitializer: { channel, streamCreator in + channel.eventLoop.makeCompletedFuture { + let h3: HTTP3ClientConnection = try channel.pipeline.syncOperations + .configureAsyncHTTP3ClientPipeline( + settings: HTTP3Settings(h3Datagram: true), + streamCreator: streamCreator, + logger: logger, + inboundPushStreamInitializer: { _ in } + ) + try channel.pipeline.syncOperations.addHandler(handler) + connection.h3 = h3 + } + }, + inboundStreamInitializer: Self.inboundStream + ) + established.whenComplete { result in + switch result { + case .failure(let error): + self.connectionFailed(connection, ConnectError.connect(error)) + case .success(let (channel, _)): + connection.channel = channel + connection.lastReceived = Self.now() + channel.closeFuture.whenComplete { _ in self.connectionClosed(connection) } + if connection.closed { + channel.close(promise: nil) + return + } + connection.isReady = true + connection.ready.succeed(()) + } + } + } + + private func connectionFailed(_ connection: Connection, _ error: any Error) { + connection.ready.fail(error) + connection.settings.fail(error) + connectionClosed(connection) + } + + /// The connection ended, by either side or because it could not be set up. Its calls fail as their streams close. + fileprivate func connectionClosed(_ connection: Connection) { + connection.ready.fail(ChannelError.ioOnClosedChannel) + connection.settings.fail(ChannelError.ioOnClosedChannel) + if !connection.closed { + connection.closed = true + for engine in engines.values where engine.connections[connection.origin] === connection { + engine.connections.removeValue(forKey: connection.origin) + } + } + connection.udp?.close(promise: nil) + for call in connection.calls.values where call.stream == nil { + // Still waiting for the connection; those with a stream fail when it closes. + fail(call, connection.channel == nil ? .cannotConnectToHost : .networkConnectionLost, "connection closed") + } + } + + /// Takes `connection` out of new calls' way. It closes once the calls on it have ended. + private func retire(_ connection: Connection) { + connection.retired = true + for engine in engines.values where engine.connections[connection.origin] === connection { + engine.connections.removeValue(forKey: connection.origin) + } + closeIfIdle(connection) + } + + private func closeIfIdle(_ connection: Connection) { + guard connection.retired, connection.calls.isEmpty, !connection.closed else { return } + connection.closed = true + if let channel = connection.channel { + // Closing the QUIC connection channel sends CONNECTION_CLOSE; the UDP socket follows in connectionClosed. + channel.close(promise: nil) + } else { + connection.udp?.close(promise: nil) + } + } + + // A call that ran out of time (its read-idle timeout, or its deadline) may be stuck on a dead connection. It is + // taken to be if nothing has arrived on the call's connection, on any call, since the call last received anything; + // otherwise only that call was slow. The engine's new calls then go to a new connection, and the old one closes once + // the calls still on it have ended. Calls that time out together on the same dead connection replace it once. + private func evictConnection(of call: Call) { + guard let connection = call.connection, !connection.retired, !connection.closed else { return } + if connection.lastReceived > call.lastReceived { + return + } + retire(connection) + } + + // MARK: Calls + + final class Call { + enum Kind { + case request(method: String) + case datagrams(protocol: String) + } + + let callId: Int + let kind: Kind + var connection: Connection? + var stream: (any Channel)? + var streamID: QUICStreamID? + /// Request parts written before the stream existed, sent once it does. + var pending: [(HTTPRequestPart, () -> Void)] = [] + var ended = false + var finished = false + /// When the call last received anything, or started, in uptime nanoseconds. + var lastReceived = HTTP3Bridge.now() + var readIdleTimeoutMs: Int? + var idleTimer: Scheduled? + /// Why the stream failed, when it reports an error before it closes. + var streamError: (any Error)? + + init(callId: Int, kind: Kind) { + self.callId = callId + self.kind = kind + } + + var isDatagramSession: Bool { + if case .datagrams = kind { return true } + return false + } + + /// Writes `part` to the stream, or queues it until the stream exists. `done` runs once it is written, or the call + /// has ended, so a caller waiting on it never hangs. + func write(_ part: HTTPRequestPart, done: @escaping () -> Void) { + if finished || ended { + done() + return + } + if case .end = part { + ended = true + } + guard let stream else { + pending.append((part, done)) + return + } + stream.writeAndFlush(part).whenComplete { _ in done() } + } + + func flushPending() { + guard let stream else { return } + let parts = pending + pending = [] + for (part, done) in parts { + stream.write(part).whenComplete { _ in done() } + } + stream.flush() + } + + func releasePending() { + let parts = pending + pending = [] + for (_, done) in parts { + done() + } + } + } + + private func failure(_ callId: Int, domain: String, code: Int, message: String) -> [String: Any] { + ["callId": callId, "type": "failed", "domain": domain, "code": code, "message": message] + } + + private func open( + _ engineId: Int, _ callId: Int, _ url: String, _ kind: Call.Kind, _ headers: [[String]], _ readIdleTimeoutMs: Int? + ) { + guard let engine = engines[engineId], let components = URLComponents(string: url), let host = components.host, + !host.isEmpty + else { + emit(failure( + callId, domain: "ConnectNativeHttp", code: 0, message: "engine \(engineId) is shut down or \(url) is invalid")) + return + } + guard components.scheme?.lowercased() == "https" else { + emit(failure( + callId, domain: NSURLErrorDomainName, code: URLError.unsupportedURL.rawValue, + message: "\(url): only https is served, over HTTP/3")) + return + } + let request: HTTPRequest + do { + request = try Self.request(kind, components: components, host: host, headers: headers) + } catch { + // As Cronet does, a request the stack can't send fails without being sent. + emit(failure( + callId, domain: NSURLErrorDomainName, code: URLError.badURL.rawValue, message: "\(url): \(error)")) + return + } + + let call = Call(callId: callId, kind: kind) + call.readIdleTimeoutMs = readIdleTimeoutMs + calls[callId] = call + scheduleIdleCheck(call) + let connection = self.connection(for: engine, host: host, port: components.port ?? 443) + attach(call, to: connection, request: request, engine: engine, retried: false) + } + + private func attach(_ call: Call, to connection: Connection, request: HTTPRequest, engine: Engine, retried: Bool) { + call.connection = connection + connection.calls[call.callId] = call + var ready = connection.ready.futureResult + if call.isDatagramSession { + ready = ready.flatMap { connection.settings.futureResult }.flatMapThrowing { settings in + guard settings.extendedConnectSupported, settings.datagramsSupported else { + throw DatagramsUnsupported(settings: settings) + } + } + } + ready.whenComplete { result in + guard !call.finished else { return } + switch result { + case .failure(let error as DatagramsUnsupported): + self.fail(call, domain: "ConnectNativeHttp", code: -2, error.description) + case .failure(let error): + let (code, message) = Self.connectFailure(error) + self.fail(call, code, message) + case .success: + self.startStream(call, on: connection, request: request, engine: engine, retried: retried) + } + } + } + + struct DatagramsUnsupported: Error, CustomStringConvertible { + let settings: ReceivedSettings + var description: String { + "the server does not support HTTP datagrams over Extended CONNECT (SETTINGS_H3_DATAGRAM " + + "\(settings.datagramsSupported), SETTINGS_ENABLE_CONNECT_PROTOCOL \(settings.extendedConnectSupported))" + } + } + + private func startStream( + _ call: Call, on connection: Connection, request: HTTPRequest, engine: Engine, retried: Bool + ) { + guard let h3 = connection.h3 else { + fail(call, .cannotConnectToHost, "connection closed") + return + } + let handler = StreamHandler(bridge: self, call: call) + let loop = self.loop + let created = loop.makeFutureWithTask { + try await h3.createRequestStream { parameters in + // A server that has its answer may stop reading the request (STOP_SENDING, which quic-go sends whenever a + // handler returns before reading the whole body). Without this option, that closes the whole stream, response + // and all; with it, only the request side. + parameters.channel.setOption(.halfCloseOnStopSending, value: true).flatMapThrowing { + try parameters.channel.pipeline.syncOperations.addHandler(handler) + return (parameters.channel, parameters.streamID) + } + } + } + created.whenComplete { result in + switch result { + case .failure(let error): + guard !call.finished else { return } + connection.calls.removeValue(forKey: call.callId) + // The server sent GOAWAY, or the connection is going away: no stream was opened, so nothing was sent. One + // retry on a new connection. + if !retried, engine === self.engines[engine.id] { + self.retire(connection) + let fresh = self.connection(for: engine, host: connection.host, port: connection.port) + self.attach(call, to: fresh, request: request, engine: engine, retried: true) + } else { + self.fail(call, .cannotConnectToHost, "could not open a request stream: \(error)") + self.closeIfIdle(connection) + } + case .success(let (stream, streamID)): + if call.finished { + stream.close(promise: nil) + return + } + call.stream = stream + call.streamID = streamID + if call.isDatagramSession { + connection.datagramSessions[streamID] = call + } + // The head first, then anything Dart wrote meanwhile. + call.pending.insert((.head(request), {}), at: 0) + call.flushPending() + } + } + } + + static func request(_ kind: Call.Kind, components: URLComponents, host: String, headers: [[String]]) throws + -> HTTPRequest + { + var authority = host.contains(":") ? "[\(host)]" : host + if let port = components.port, port != 443 { + authority += ":\(port)" + } + var path = components.percentEncodedPath.isEmpty ? "/" : components.percentEncodedPath + if let query = components.percentEncodedQuery { + path += "?\(query)" + } + var fields = HTTPFields() + for header in headers { + let lower = header[0].lowercased() + // Connection-specific fields are not allowed in HTTP/3 (RFC 9114 § 4.2), and the authority is :authority. + if Self.connectionSpecific.contains(lower) || (lower == "te" && header[1].lowercased() != "trailers") { + continue + } + guard let name = HTTPField.Name(header[0]) else { + throw InvalidHeader(name: header[0]) + } + guard HTTPField.isValidValue(header[1]) else { + throw InvalidHeader(name: header[0]) + } + fields.append(HTTPField(name: name, value: header[1])) + } + switch kind { + case .request(let method): + guard let method = HTTPRequest.Method(method) else { throw InvalidHeader(name: ":method") } + return HTTPRequest(method: method, scheme: "https", authority: authority, path: path, headerFields: fields) + case .datagrams(let proto): + var request = HTTPRequest(method: .connect, scheme: "https", authority: authority, path: path, headerFields: fields) + request.extendedConnectProtocol = proto + return request + } + } + + struct InvalidHeader: Error, CustomStringConvertible { + let name: String + var description: String { "invalid header \(name)" } + } + + private static let connectionSpecific: Set = [ + "host", "connection", "keep-alive", "proxy-connection", "transfer-encoding", "upgrade", + ] + + // MARK: Stream events, on `loop` + + fileprivate func received(_ call: Call) { + let now = Self.now() + call.lastReceived = now + call.connection?.lastReceived = now + } + + fileprivate func didReceive(_ part: HTTPResponsePart, for call: Call) { + guard !call.finished else { return } + received(call) + switch part { + case .head(let response): + // Interim responses (1xx) carry nothing the caller needs. + if response.status.kind == .informational { + return + } + let headers = response.headerFields.map { [$0.name.canonicalName, $0.value] } + emit([ + "callId": call.callId, "type": "headers", "status": response.status.code, "protocol": "h3", + "headers": headers, + ]) + case .body(let buffer): + emit(["callId": call.callId, "type": "data", "data": Data(buffer.readableBytesView)]) + case .end(let trailers): + if let trailers, !trailers.isEmpty { + emit([ + "callId": call.callId, "type": "trailers", "headers": trailers.map { [$0.name.canonicalName, $0.value] }, + ]) + } + // The whole response is in, so the call is over, even while its request body is still open. + finish(call, ["callId": call.callId, "type": "done"]) + } + } + + fileprivate func streamClosed(_ call: Call) { + guard !call.finished else { return } + let message = call.streamError.map { "stream closed: \($0)" } ?? "stream closed before the response ended" + fail(call, .networkConnectionLost, message) + } + + fileprivate func didReceive(_ datagram: HTTP3Datagram, on connection: Connection) { + connection.lastReceived = Self.now() + guard let call = connection.datagramSessions[datagram.streamID], !call.finished else { return } + received(call) + emit(["callId": call.callId, "type": "datagram", "data": Data(datagram.payload.readableBytesView)]) + } + + fileprivate func didReceive(_ settings: ReceivedSettings, on connection: Connection) { + connection.lastReceived = Self.now() + connection.settings.succeed(settings) + } + + private func sendDatagram(_ callId: Int, _ data: Data, reply: @escaping (Reply) -> Void) { + guard let call = calls[callId], call.isDatagramSession else { + reply(.error(code: "datagramFailed", message: "no open datagram session \(callId)")) + return + } + guard let channel = call.connection?.channel, let streamID = call.streamID else { + reply(.error(code: "datagramFailed", message: "datagram session \(callId) is not open yet")) + return + } + let datagram = HTTP3Datagram(streamID: streamID, payload: ByteBuffer(bytes: data)) + channel.writeAndFlush(datagram).whenComplete { result in + switch result { + case .success: + reply(.success(nil)) + case .failure(let error): + reply(.error(code: "datagramFailed", message: "\(error)")) + } + } + } + + // MARK: Ending calls + + private func fail(_ call: Call, _ code: URLError.Code, _ message: String) { + fail(call, domain: NSURLErrorDomainName, code: code.rawValue, message) + } + + private func fail(_ call: Call, domain: String, code: Int, _ message: String) { + finish(call, failure(call.callId, domain: domain, code: code, message: message)) + } + + /// Ends `call` with `event`, its last, and releases everything it holds. + private func finish(_ call: Call, _ event: [String: Any]) { + guard !call.finished else { return } + call.finished = true + calls.removeValue(forKey: call.callId) + call.idleTimer?.cancel() + call.idleTimer = nil + call.releasePending() + if let stream = call.stream { + // Resets the stream if it is still open either way. + stream.close(promise: nil) + } + if let connection = call.connection { + connection.calls.removeValue(forKey: call.callId) + if let streamID = call.streamID { + connection.datagramSessions.removeValue(forKey: streamID) + } + closeIfIdle(connection) + } + emit(event) + } + + // MARK: Read-idle timeout + + private func scheduleIdleCheck(_ call: Call) { + guard let ms = call.readIdleTimeoutMs else { return } + let timeout = UInt64(ms) * 1_000_000 + let elapsed = Self.now() &- call.lastReceived + let remaining = elapsed >= timeout ? 0 : timeout - elapsed + call.idleTimer = loop.scheduleTask(in: .nanoseconds(Int64(remaining))) { + guard !call.finished else { return } + if Self.now() &- call.lastReceived >= timeout { + self.evictConnection(of: call) + self.fail(call, .timedOut, "received nothing for \(ms) ms") + } else { + self.scheduleIdleCheck(call) + } + } + } + + // MARK: Error mapping + + /// The `NSURLErrorDomain` code and message for a connection that could not be set up. None of these sent the + /// request. + static func connectFailure(_ error: any Error) -> (URLError.Code, String) { + switch error { + case ConnectError.resolve(let cause): + return (.cannotFindHost, "\(cause)") + case ConnectError.timedOut(let timeout): + return (.cannotConnectToHost, "no QUIC handshake within \(timeout.nanoseconds / 1_000_000) ms") + case ConnectError.connect(let cause): + // The QUIC stack closes a connection whose TLS handshake failed with CRYPTO_ERROR 0x100 and nothing more, so a + // certificate it rejected can't be told apart from other TLS failures. URLSession reports those as + // NSURLErrorSecureConnectionFailed. + if let error = cause as? QUICConnectionError, !error.isApplication, (0x100...0x1FF).contains(error.code) { + return (.secureConnectionFailed, "TLS handshake failed: \(error.reason) (CRYPTO_ERROR \(error.code))") + } + return (.cannotConnectToHost, "\(cause)") + default: + return (.cannotConnectToHost, "\(error)") + } + } +} + +/// `NSURLErrorDomain`, spelled out: swift-corelibs-foundation names the constant differently. +let NSURLErrorDomainName = "NSURLErrorDomain" + +// MARK: Channel handlers + +/// On a connection channel, after its HTTP/3 handler: routes the connection's datagrams and SETTINGS to the bridge. +private final class ConnectionHandler: ChannelInboundHandler, @unchecked Sendable { + typealias InboundIn = HTTP3Datagram + + private let bridge: HTTP3Bridge + private let connection: HTTP3Bridge.Connection + + init(bridge: HTTP3Bridge, connection: HTTP3Bridge.Connection) { + self.bridge = bridge + self.connection = connection + } + + func channelRead(context: ChannelHandlerContext, data: NIOAny) { + bridge.didReceive(unwrapInboundIn(data), on: connection) + } + + func userInboundEventTriggered(context: ChannelHandlerContext, event: Any) { + if let settings = event as? ReceivedSettings { + bridge.didReceive(settings, on: connection) + } + context.fireUserInboundEventTriggered(event) + } + + func errorCaught(context: ChannelHandlerContext, error: any Error) { + // The connection closes after a connection error; its calls fail as their streams close. + context.fireErrorCaught(error) + } +} + +/// On a request stream channel: hands the response to the bridge. +private final class StreamHandler: ChannelInboundHandler, @unchecked Sendable { + typealias InboundIn = HTTPResponsePart + typealias OutboundOut = HTTPRequestPart + + private let bridge: HTTP3Bridge + private let call: HTTP3Bridge.Call + + init(bridge: HTTP3Bridge, call: HTTP3Bridge.Call) { + self.bridge = bridge + self.call = call + } + + func channelRead(context: ChannelHandlerContext, data: NIOAny) { + bridge.didReceive(unwrapInboundIn(data), for: call) + } + + // The stream closes after an error that ends it; it reports that error first. Others, such as the server's + // STOP_SENDING once it has its answer, leave the response to be read. + func errorCaught(context: ChannelHandlerContext, error: any Error) { + call.streamError = error + } + + func channelInactive(context: ChannelHandlerContext) { + bridge.streamClosed(call) + context.fireChannelInactive() + } +} diff --git a/ios/connect_native_http/Sources/ConnectNativeHttpCore/URLSessionBridge.swift b/ios/connect_native_http/Sources/ConnectNativeHttpCore/URLSessionBridge.swift deleted file mode 100644 index f0d1772..0000000 --- a/ios/connect_native_http/Sources/ConnectNativeHttpCore/URLSessionBridge.swift +++ /dev/null @@ -1,410 +0,0 @@ -import Foundation - -// Bridges URLSession to lib/src/url_session/url_session_http_client.dart, one task per call, with the same protocol -// as the Android bridge. Dart sends request chunks as method calls; response headers, body chunks and the outcome go -// to `emit`, from the bridge's own queue. Kept free of Flutter so it can be tested without a Flutter app. -public final class URLSessionBridge { - public enum Reply { - case success(Any?) - /// The call's arguments were not what the method takes. Refused rather than force-unwrapped, which would crash the - /// app. - case error(code: String, message: String) - case notImplemented - } - - private struct BadArgument: Error { - let name: String - } - - private let emit: ([String: Any]) -> Void - private let trustedRoots: [SecCertificate] - - // URLSession delegate callbacks and all state below run on this queue, so none of it needs locking. - private let queue = DispatchQueue(label: "connect_native_http") - private lazy var delegateQueue: OperationQueue = { - let q = OperationQueue() - q.underlyingQueue = queue - q.maxConcurrentOperationCount = 1 - return q - }() - private var sessions: [Int: Session] = [:] - private var calls: [Int: Call] = [:] - private var callsByTask: [URLSessionTask: Call] = [:] - private var nextSessionId = 1 - - private final class Session { - // Replaced after a call times out, so new calls dial a fresh connection; see `evictConnection`. - var urlSession: URLSession - let http3Origins: Set - // When `urlSession` last received anything from each origin ("host:port"), in uptime nanoseconds. - var lastReceived: [String: UInt64] = [:] - - init(urlSession: URLSession, http3Origins: Set) { - self.urlSession = urlSession - self.http3Origins = http3Origins - } - } - - private final class Call { - let callId: Int - var engineId = 0 - // The URLSession the call's task runs in. - var urlSession: URLSession? - var origin = "" - // When the call last received anything, or started, in uptime nanoseconds. - var lastReceived = URLSessionBridge.now() - var task: URLSessionTask! - var input: InputStream? - var output: OutputStream? - var bodyStreamTaken = false - // Writes to the bound stream pair block while its buffer is full, so they run here rather than on `queue`. - let writer = DispatchQueue(label: "connect_native_http.writer") - - init(callId: Int) { - self.callId = callId - } - } - - public convenience init(emit: @escaping ([String: Any]) -> Void) { - self.init(trustedRoots: [], emit: emit) - } - - /// `trustedRoots`, when not empty, replaces the system trust store; tests use it for their own CA. - init(trustedRoots: [SecCertificate], emit: @escaping ([String: Any]) -> Void) { - self.trustedRoots = trustedRoots - self.emit = emit - } - - /// Handles one method call. `reply` may be called on any thread. - public func handle(_ method: String, _ args: [String: Any], reply: @escaping (Reply) -> Void) { - do { - try dispatch(method, args, reply: reply) - } catch let bad as BadArgument { - reply(.error(code: "badArguments", message: "\(method): missing or mistyped argument \(bad.name)")) - } catch { - reply(.error(code: "badArguments", message: "\(method): \(error)")) - } - } - - private func arg(_ args: [String: Any], _ name: String) throws -> T { - guard let value = args[name] as? T else { throw BadArgument(name: name) } - return value - } - - private func dispatch(_ method: String, _ args: [String: Any], reply: @escaping (Reply) -> Void) throws { - switch method { - case "createEngine": - let origins = try (args["http3Origins"] as? [[Any]] ?? []).map { origin -> String in - guard origin.count == 2 else { throw BadArgument(name: "http3Origins") } - return "\(origin[0])".lowercased() + ":\(origin[1])" - } - queue.async { - let id = self.nextSessionId - self.nextSessionId += 1 - self.sessions[id] = Session(urlSession: self.makeURLSession(), http3Origins: Set(origins)) - reply(.success(id)) - } - case "shutdownEngine": - let engineId: Int = try arg(args, "engineId") - queue.async { - self.sessions.removeValue(forKey: engineId)?.urlSession.finishTasksAndInvalidate() - } - reply(.success(nil)) - case "open": - let engineId: Int = try arg(args, "engineId") - let callId: Int = try arg(args, "callId") - let url: String = try arg(args, "url") - let method: String = try arg(args, "method") - let headers: [[String]] = try arg(args, "headers") - guard headers.allSatisfy({ $0.count == 2 }) else { throw BadArgument(name: "headers") } - let hasBody: Bool = try arg(args, "hasBody") - let readIdleTimeoutMs = try optionalPositiveInt(args, "readIdleTimeoutMs") - queue.async { self.open(engineId, callId, url, method, headers, hasBody, readIdleTimeoutMs) } - reply(.success(nil)) - case "write": - let callId: Int = try arg(args, "callId") - let data: Data = try arg(args, "data") - // Reply once the bytes are in the stream buffer, so a fast producer waits for URLSession to read them. - queue.async { - guard let c = self.calls[callId], let output = c.output else { - reply(.success(nil)) - return - } - c.writer.async { - Self.writeAll(data, to: output) - reply(.success(nil)) - } - } - case "end": - let callId: Int = try arg(args, "callId") - queue.async { - guard let c = self.calls[callId], let output = c.output else { return } - c.writer.async { output.close() } - } - reply(.success(nil)) - case "cancel": - let callId: Int = try arg(args, "callId") - // Set when the call hit its deadline. The server was given a deadline a step earlier, so on a live connection - // its deadline_exceeded would have ended the call first. - let value = args["evictConnection"] - guard value == nil || value is NSNull || value is Bool else { throw BadArgument(name: "evictConnection") } - let evict = value as? Bool ?? false - queue.async { - guard let c = self.calls[callId] else { return } - if evict { - self.evictConnection(of: c) - } - c.task.cancel() - } - reply(.success(nil)) - default: - reply(.notImplemented) - } - } - - /// An optional argument that must be a positive integer when present; absent or null for none. - private func optionalPositiveInt(_ args: [String: Any], _ name: String) throws -> Int? { - guard let value = args[name], !(value is NSNull) else { return nil } - guard let n = value as? Int, n > 0 else { throw BadArgument(name: name) } - return n - } - - static func now() -> UInt64 { - DispatchTime.now().uptimeNanoseconds - } - - private func failure(_ callId: Int, domain: String, code: Int, message: String) -> [String: Any] { - ["callId": callId, "type": "failed", "domain": domain, "code": code, "message": message] - } - - private func makeURLSession() -> URLSession { - let configuration = URLSessionConfiguration.ephemeral - // URLSession fails a task that receives nothing for this long. Its default of 60 s would end a quiet stream or a - // long-running unary call; callers bound calls with deadlines, or set the client's read-idle timeout. - configuration.timeoutIntervalForRequest = Self.sessionIdleTimeout - // Only a bridge with its own roots implements the trust challenge. With the system's roots there is nothing for - // the delegate to decide, so certificate checks are left entirely to the network stack. - let delegate = trustedRoots.isEmpty ? Delegate(bridge: self) : TrustingDelegate(bridge: self) - return URLSession(configuration: configuration, delegate: delegate, delegateQueue: delegateQueue) - } - - /// The `URLRequest.timeoutInterval` for a read-idle timeout of `ms` milliseconds, or nil for the session's. - static func requestTimeoutInterval(readIdleTimeoutMs ms: Int?) -> TimeInterval? { - guard let ms else { return nil } - let interval = TimeInterval(ms) / 1000 - // URLSession takes a request's 60 s, URLRequest's default, to mean "not set" and applies the session's value - // instead, however the request got it. One millisecond more is still honored. - return interval == 60 ? 60.001 : interval - } - - private func open( - _ engineId: Int, _ callId: Int, _ url: String, _ method: String, _ headers: [[String]], _ hasBody: Bool, - _ readIdleTimeoutMs: Int? - ) { - guard let session = sessions[engineId], let target = URL(string: url) else { - emit(failure( - callId, domain: "ConnectNativeHttp", code: 0, message: "engine \(engineId) is shut down or \(url) is invalid")) - return - } - var request = URLRequest(url: target) - request.httpMethod = method - for h in headers { - // URLRequest holds one value per name; addValue joins repeated headers with commas, as RFC 9110 allows. - request.addValue(h[1], forHTTPHeaderField: h[0]) - } - let port = target.port ?? (target.scheme == "http" ? 80 : 443) - // Lowercased, as Dart's Uri gives the hosts in http3Origins; URL keeps the case the caller wrote. - let origin = "\((target.host ?? "").lowercased()):\(port)" - request.assumesHTTP3Capable = session.http3Origins.contains(origin) - // The request's read-idle timeout: URLSession fails the task once it has received nothing for this long, with - // NSURLErrorTimedOut. - if let interval = Self.requestTimeoutInterval(readIdleTimeoutMs: readIdleTimeoutMs) { - request.timeoutInterval = interval - } - - let c = Call(callId: callId) - c.engineId = engineId - c.urlSession = session.urlSession - c.origin = origin - if hasBody { - var input: InputStream? - var output: OutputStream? - Stream.getBoundStreams(withBufferSize: Self.bodyBufferBytes, inputStream: &input, outputStream: &output) - output!.open() - c.input = input - c.output = output - c.task = session.urlSession.uploadTask(withStreamedRequest: request) - } else { - c.task = session.urlSession.dataTask(with: request) - } - calls[callId] = c - callsByTask[c.task] = c - c.task.resume() - } - - private static func writeAll(_ data: Data, to output: OutputStream) { - data.withUnsafeBytes { (raw: UnsafeRawBufferPointer) in - guard let base = raw.bindMemory(to: UInt8.self).baseAddress else { return } - var offset = 0 - while offset < data.count { - let n = output.write(base + offset, maxLength: data.count - offset) - // The task finished and closed its end of the pair; the call's outcome is reported elsewhere. - if n <= 0 { return } - offset += n - } - } - } - - // MARK: URLSession callbacks, on `queue`. - - fileprivate func bodyStream(for task: URLSessionTask) -> InputStream? { - guard let c = callsByTask[task], !c.bodyStreamTaken else { - // A second request for the body means URLSession wants to resend it, which a stream that has already been - // read cannot do. - return nil - } - c.bodyStreamTaken = true - return c.input - } - - // A redirect would resend the request body, which has already been streamed; over HTTP/3 URLSession then waits - // indefinitely for a body nobody can give it. Refusing hands the redirect response itself to the caller. - fileprivate func followsRedirect(_ task: URLSessionTask) -> Bool { - callsByTask[task]?.input == nil - } - - // Anything from the server shows the call's connection is alive. - private func received(_ c: Call) { - let now = Self.now() - c.lastReceived = now - if let session = sessions[c.engineId], session.urlSession === c.urlSession { - session.lastReceived[c.origin] = now - } - } - - fileprivate func didReceive(_ response: URLResponse, for task: URLSessionTask) { - guard let c = callsByTask[task] else { return } - received(c) - guard let http = response as? HTTPURLResponse else { return } - let headers = http.allHeaderFields.map { [String(describing: $0.key), String(describing: $0.value)] } - emit(["callId": c.callId, "type": "headers", "status": http.statusCode, "protocol": NSNull(), "headers": headers]) - } - - fileprivate func didReceive(_ data: Data, for task: URLSessionTask) { - guard let c = callsByTask[task] else { return } - received(c) - emit(["callId": c.callId, "type": "data", "data": data]) - } - - fileprivate func didComplete(_ task: URLSessionTask, error: Error?) { - guard let c = callsByTask.removeValue(forKey: task) else { return } - calls.removeValue(forKey: c.callId) - // Closing the reading end unblocks a write still waiting on a full buffer, but only once it has been opened, - // which URLSession skips when the connection fails first. - if let input = c.input { - if input.streamStatus == .notOpen { - input.open() - } - input.close() - } - guard let error = error as NSError? else { - emit(["callId": c.callId, "type": "done"]) - return - } - if error.domain == NSURLErrorDomain && error.code == NSURLErrorCancelled { - emit(["callId": c.callId, "type": "canceled"]) - return - } - if error.domain == NSURLErrorDomain && error.code == NSURLErrorTimedOut { - evictConnection(of: c) - } - emit(failure(c.callId, domain: error.domain, code: error.code, message: error.localizedDescription)) - } - - // A call that ran out of time (its read-idle timeout, or its deadline) may be stuck on a dead connection. - // It is taken to be if nothing has arrived from the call's origin, on any call, since the call last received - // anything; otherwise only that call was slow. URLSession pools connections per session and has no call that closes - // one, so the engine's new calls go to a fresh URLSession, which dials its own connections. The old one finishes the - // tasks it still has, and is then released. Calls that time out together on the same dead connection replace it - // once. - private func evictConnection(of c: Call) { - guard let session = sessions[c.engineId], let old = c.urlSession, session.urlSession === old else { return } - if let heard = session.lastReceived[c.origin], heard > c.lastReceived { - return - } - session.urlSession = makeURLSession() - session.lastReceived = [:] - old.finishTasksAndInvalidate() - } - - fileprivate func serverTrust(_ challenge: URLAuthenticationChallenge) -> ( - URLSession.AuthChallengeDisposition, URLCredential? - ) { - guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust, - let trust = challenge.protectionSpace.serverTrust - else { - return (.performDefaultHandling, nil) - } - SecTrustSetAnchorCertificates(trust, trustedRoots as CFArray) - SecTrustSetAnchorCertificatesOnly(trust, true) - return SecTrustEvaluateWithError(trust, nil) - ? (.useCredential, URLCredential(trust: trust)) : (.cancelAuthenticationChallenge, nil) - } - - // 64 KiB, the bound pair's buffer: how much request body may wait for URLSession to read it. - private static let bodyBufferBytes = 64 * 1024 - - // A day: in effect no read-idle timeout, for requests that don't set one. - private static let sessionIdleTimeout: TimeInterval = 24 * 60 * 60 -} - -// URLSession keeps its delegate until the session is invalidated, so this holds the bridge weakly. -private class Delegate: NSObject, URLSessionDataDelegate { - weak var bridge: URLSessionBridge? - - init(bridge: URLSessionBridge) { - self.bridge = bridge - } - - func urlSession( - _ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse, - newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void - ) { - completionHandler(bridge?.followsRedirect(task) == true ? request : nil) - } - - func urlSession( - _ session: URLSession, task: URLSessionTask, needNewBodyStream completionHandler: @escaping (InputStream?) -> Void - ) { - completionHandler(bridge?.bodyStream(for: task)) - } - - func urlSession( - _ session: URLSession, dataTask: URLSessionDataTask, didReceive response: URLResponse, - completionHandler: @escaping (URLSession.ResponseDisposition) -> Void - ) { - bridge?.didReceive(response, for: dataTask) - completionHandler(.allow) - } - - func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) { - bridge?.didReceive(data, for: dataTask) - } - - func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) { - bridge?.didComplete(task, error: error) - } -} - -// A Delegate that also checks server certificates against the bridge's own roots. URLSession looks the method up by -// its Objective-C selector, hence the explicit name: a subclass doesn't inherit the protocol's @objc inference. -private final class TrustingDelegate: Delegate { - @objc(URLSession:didReceiveChallenge:completionHandler:) - func urlSession( - _ session: URLSession, didReceive challenge: URLAuthenticationChallenge, - completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void - ) { - let (disposition, credential) = bridge?.serverTrust(challenge) ?? (.performDefaultHandling, nil) - completionHandler(disposition, credential) - } -} diff --git a/ios/connect_native_http/Sources/connect_native_http/ConnectNativeHttpPlugin.swift b/ios/connect_native_http/Sources/connect_native_http/ConnectNativeHttpPlugin.swift index af4daf9..e7b7dcd 100644 --- a/ios/connect_native_http/Sources/connect_native_http/ConnectNativeHttpPlugin.swift +++ b/ios/connect_native_http/Sources/connect_native_http/ConnectNativeHttpPlugin.swift @@ -2,20 +2,20 @@ import ConnectNativeHttpCore import Flutter import Foundation -// Connects a URLSessionBridge to its Flutter channels. +// Connects an HTTP3Bridge to its Flutter channels. public final class ConnectNativeHttpPlugin: NSObject, FlutterPlugin, FlutterStreamHandler { private var sink: FlutterEventSink? - private lazy var bridge = URLSessionBridge { [weak self] event in + private lazy var bridge = HTTP3Bridge { [weak self] event in let payload = event.mapValues { $0 is Data ? FlutterStandardTypedData(bytes: $0 as! Data) : $0 } DispatchQueue.main.async { self?.sink?(payload) } } public static func register(with registrar: FlutterPluginRegistrar) { let instance = ConnectNativeHttpPlugin() - let methods = FlutterMethodChannel(name: "connect_native_http/urlsession", binaryMessenger: registrar.messenger()) + let methods = FlutterMethodChannel(name: "connect_native_http/http3", binaryMessenger: registrar.messenger()) registrar.addMethodCallDelegate(instance, channel: methods) let events = FlutterEventChannel( - name: "connect_native_http/urlsession/events", binaryMessenger: registrar.messenger()) + name: "connect_native_http/http3/events", binaryMessenger: registrar.messenger()) events.setStreamHandler(instance) } diff --git a/ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/HTTP3BridgeTests.swift b/ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/HTTP3BridgeTests.swift new file mode 100644 index 0000000..a31c395 --- /dev/null +++ b/ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/HTTP3BridgeTests.swift @@ -0,0 +1,470 @@ +import Foundation +import X509 +import XCTest + +@testable import ConnectNativeHttpCore + +#if canImport(FoundationNetworking) + import FoundationNetworking +#endif + +// Bridge behavior the Dart integration tests can't reach, on macOS or Linux,, against test_server/. run_integration_tests.sh starts the +// server and passes its URL as SERVER_URL and its CA certificate (DER) as SERVER_CA. +final class HTTP3BridgeTests: XCTestCase { + private static let converse = "/connectrpc.eliza.v1.ElizaService/Converse" + private static let say = "/connectrpc.eliza.v1.ElizaService/Say" + private static let datagramEcho = "/datagrams/echo" + + private var serverURL = "" + private var bridge: HTTP3Bridge! + private let lock = NSLock() + private var events: [[String: Any]] = [] + private var writeReturned = false + + override func setUpWithError() throws { + let env = ProcessInfo.processInfo.environment + guard let url = env["SERVER_URL"], let caPath = env["SERVER_CA"] else { + throw XCTSkip("SERVER_URL and SERVER_CA are not set; run these through run_integration_tests.sh") + } + serverURL = url + let ca = try Certificate(derEncoded: Array(try Data(contentsOf: URL(fileURLWithPath: caPath)))) + bridge = HTTP3Bridge(trustRoots: [ca]) { [weak self] event in + guard let self else { return } + lock.withLock { self.events.append(event) } + } + } + + // Writes before the connection is up wait for it, and return once it fails. + func testWritesWaitingForTheConnectionReturnWhenItFails() async throws { + let engine = try await invoke("createEngine", ["connectTimeoutMs": 500]) as! Int + // Nothing listens on the discard port, so the QUIC handshake never completes and no stream is opened. + let unreachable = try XCTUnwrap(URLComponents(string: serverURL)).with(port: 9) + try await invoke("open", [ + "engineId": engine, "callId": 1, "url": unreachable + Self.say, "method": "POST", + "headers": [["content-type", "application/proto"]], "hasBody": true, + ]) + Task { + try await self.write(1, Data(count: 1 << 20)) + self.lock.withLock { self.writeReturned = true } + } + try await waitUntil("the call failed") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "failed") + XCTAssertEqual(outcome(1)?["code"] as? Int, -1004, "\(String(describing: outcome(1)))") + try await waitUntil("the write returned", timeout: 2) { self.lock.withLock { self.writeReturned } } + } + + func testRedirectOfARequestWithABodyIsReturnedInsteadOfFollowed() async throws { + let engine = try await createEngine() + try await open(engine, callId: 1, path: "/redirect" + Self.say, contentType: "application/proto") + try await write(1, sentence("hi")) + try await invoke("end", ["callId": 1]) + try await waitUntil("the call ended") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + XCTAssertEqual(event(1, "headers")?["status"] as? Int, 307) + } + + func testShutdownLetsACallInFlightFinishAndRefusesNewOnes() async throws { + let engine = try await createEngine() + try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") + try await invoke("shutdownEngine", ["engineId": engine]) + try await write(1, envelope(sentence("bye"))) + try await invoke("end", ["callId": 1]) + try await waitUntil("the call ended") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + XCTAssertTrue(received(1).contains("echo: bye")) + + try await open(engine, callId: 2, path: Self.converse, contentType: "application/connect+proto") + try await waitUntil("the second call ended") { self.outcome(2) != nil } + XCTAssertEqual(outcome(2)?["type"] as? String, "failed") + XCTAssertEqual(outcome(2)?["domain"] as? String, "ConnectNativeHttp") + } + + func testReadIdleTimeoutFailsAQuietCallAndTheEngineCarriesOn() async throws { + let engine = try await createEngine() + // The timeout also covers setting up the connection, which can outlast it on a loaded simulator. A call first + // leaves a connection for the timed one to reuse. + try await open(engine, callId: 10, path: Self.say, contentType: "application/proto") + try await write(10, sentence("warm up")) + try await invoke("end", ["callId": 10]) + try await waitUntil("the warm-up call ended", timeout: 10) { self.outcome(10) != nil } + try await open( + engine, callId: 1, path: Self.converse, contentType: "application/connect+proto", readIdleTimeoutMs: 500) + try await waitUntil("the greeting arrived") { self.received(1).contains("hello") } + let start = Date() + try await waitUntil("the call timed out") { self.outcome(1) != nil } + let elapsed = Date().timeIntervalSince(start) + XCTAssertEqual(outcome(1)?["type"] as? String, "failed", "\(String(describing: outcome(1)))") + XCTAssertEqual(outcome(1)?["code"] as? Int, NSURLErrorTimedOut) + XCTAssertLessThan(elapsed, 2, "a 500 ms read-idle timeout took \(elapsed) s") + + // New calls go to a new connection. + try await open(engine, callId: 2, path: Self.say, contentType: "application/proto") + try await write(2, sentence("after")) + try await invoke("end", ["callId": 2]) + try await waitUntil("the next call ended") { self.outcome(2) != nil } + XCTAssertEqual(outcome(2)?["type"] as? String, "done", "\(String(describing: outcome(2)))") + XCTAssertTrue(received(2).contains("say: after")) + } + + // A call that hit its deadline is canceled at once, and moves the engine's new calls to a new connection. + func testADeadlineCancelEndsTheCallAndTheEngineCarriesOn() async throws { + let engine = try await createEngine() + try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") + try await waitUntil("the greeting arrived", timeout: 10) { self.received(1).contains("hello") } + try await invoke("cancel", ["callId": 1, "evictConnection": true]) + try await waitUntil("the call was canceled") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "canceled", "\(String(describing: outcome(1)))") + + try await open(engine, callId: 2, path: Self.say, contentType: "application/proto") + try await write(2, sentence("after")) + try await invoke("end", ["callId": 2]) + try await waitUntil("the next call ended", timeout: 10) { self.outcome(2) != nil } + XCTAssertEqual(outcome(2)?["type"] as? String, "done", "\(String(describing: outcome(2)))") + } + + func testMalformedArgumentsAreRefusedInsteadOfCrashing() async throws { + let malformed: [(String, [String: Any])] = [ + ("open", [:]), + ("open", ["engineId": "1", "callId": 1, "url": serverURL, "method": "POST", "headers": [[String]](), "hasBody": true]), + ("open", ["engineId": 1, "callId": 1, "url": serverURL, "method": "POST", "headers": [["one"]], "hasBody": true]), + ("open", [ + "engineId": 1, "callId": 1, "url": serverURL, "method": "POST", "headers": [[String]](), "hasBody": true, + "readIdleTimeoutMs": "soon", + ]), + ("open", [ + "engineId": 1, "callId": 1, "url": serverURL, "method": "POST", "headers": [[String]](), "hasBody": true, + "readIdleTimeoutMs": 0, + ]), + ("write", ["callId": 1, "data": "not bytes"]), + ("end", ["callId": "1"]), + ("cancel", [:]), + ("cancel", ["callId": 1, "evictConnection": "yes"]), + ("shutdownEngine", ["engineId": NSNull()]), + ("createEngine", ["http3Origins": [["localhost"]]]), + ("createEngine", ["quicIdleTimeoutMs": "soon"]), + ("createEngine", ["connectTimeoutMs": 0]), + ("openDatagrams", ["engineId": 1, "callId": 1, "url": serverURL, "headers": [[String]]()]), + ("openDatagrams", ["engineId": 1, "callId": 1, "url": serverURL, "protocol": 1, "headers": [[String]]()]), + ("sendDatagram", ["callId": 1]), + ("sendDatagram", ["callId": 1, "data": "not bytes"]), + ] + for (method, arguments) in malformed { + let result = await reply(method, arguments) + guard case .error(let code, _) = result else { + XCTFail("\(method) \(arguments): \(result)") + continue + } + XCTAssertEqual(code, "badArguments") + } + // The bridge still works afterwards. + let engine = try await createEngine() + try await open(engine, callId: 1, path: Self.say, contentType: "application/proto") + try await write(1, sentence("hi")) + try await invoke("end", ["callId": 1]) + try await waitUntil("the call ended") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + } + + func testUnaryCallGoesOverHTTP3() async throws { + let engine = try await createEngine() + try await open(engine, callId: 1, path: Self.say, contentType: "application/proto") + try await write(1, sentence("hi")) + try await invoke("end", ["callId": 1]) + try await waitUntil("the call ended", timeout: 10) { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + let headers = try XCTUnwrap(event(1, "headers")) + XCTAssertEqual(headers["status"] as? Int, 200) + XCTAssertEqual(headers["protocol"] as? String, "h3") + let fields = try XCTUnwrap(headers["headers"] as? [[String]]) + XCTAssertTrue(fields.contains(["x-proto", "HTTP/3.0"]), "\(fields)") + XCTAssertTrue(received(1).contains("say: hi")) + } + + // The server ends Converse after "bye" while the client's side is still open. The call ends with the response. + func testACallEndsWithItsResponseWhileTheRequestIsStillOpen() async throws { + let engine = try await createEngine() + try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") + try await write(1, envelope(sentence("bye"))) + try await waitUntil("the call ended", timeout: 10) { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + XCTAssertTrue(received(1).contains("hello")) + XCTAssertTrue(received(1).contains("echo: bye")) + } + + func testCallsShareOneConnection() async throws { + let engine = try await createEngine() + for id in 1...3 { + try await open(engine, callId: id, path: Self.say, contentType: "application/proto") + try await write(id, sentence("call \(id)")) + try await invoke("end", ["callId": id]) + } + try await waitUntil("the calls ended", timeout: 10) { (1...3).allSatisfy { self.outcome($0) != nil } } + let addresses = Set((1...3).compactMap { id in + (event(id, "headers")?["headers"] as? [[String]])?.first { $0[0] == "x-remote-addr" }?[1] + }) + XCTAssertEqual(addresses.count, 1, "\(addresses)") + } + + // The QUIC stack doesn't say why a TLS handshake failed, so a rejected certificate is a failed secure connection, + // which was not sent, rather than NSURLErrorServerCertificateUntrusted. + func testAServerCertificateFromAnotherCAFailsTheSecureConnection() async throws { + // The system's roots, which don't include the test server's CA. + let untrusting = HTTP3Bridge { [weak self] event in + guard let self else { return } + lock.withLock { self.events.append(event) } + } + let engine = try await reply(untrusting, "createEngine", [:]) as! Int + _ = try await reply(untrusting, "open", [ + "engineId": engine, "callId": 1, "url": serverURL + Self.say, "method": "POST", + "headers": [["content-type", "application/proto"]], "hasBody": true, + ]) + try await waitUntil("the call failed", timeout: 10) { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "failed", "\(String(describing: outcome(1)))") + XCTAssertEqual(outcome(1)?["domain"] as? String, "NSURLErrorDomain") + XCTAssertEqual(outcome(1)?["code"] as? Int, -1200, "\(String(describing: outcome(1)))") + } + + // The client's QUIC idle timeout is what notices a dead path: with the server's UDP frozen, a quiet call fails within + // it, and the next call dials a new connection. + func testTheQUICIdleTimeoutEndsCallsOnADeadPath() async throws { + let admin = ProcessInfo.processInfo.environment["ADMIN_URL"] ?? "http://localhost:8081" + let engine = try await invoke("createEngine", ["quicIdleTimeoutMs": 1000]) as! Int + try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") + try await waitUntil("the greeting arrived", timeout: 10) { self.received(1).contains("hello") } + try await post(admin + "/freeze?for=10s") + defer { Task { try? await self.post(admin + "/unfreeze") } } + let start = Date() + try await waitUntil("the call failed", timeout: 5) { self.outcome(1) != nil } + let elapsed = Date().timeIntervalSince(start) + XCTAssertEqual(outcome(1)?["type"] as? String, "failed", "\(String(describing: outcome(1)))") + XCTAssertEqual(outcome(1)?["code"] as? Int, -1005, "\(String(describing: outcome(1)))") + XCTAssertLessThan(elapsed, 3, "a 1 s QUIC idle timeout took \(elapsed) s") + + try await post(admin + "/unfreeze") + try await open(engine, callId: 2, path: Self.say, contentType: "application/proto") + try await write(2, sentence("after")) + try await invoke("end", ["callId": 2]) + try await waitUntil("the next call ended", timeout: 10) { self.outcome(2) != nil } + XCTAssertEqual(outcome(2)?["type"] as? String, "done", "\(String(describing: outcome(2)))") + } + + private func post(_ url: String) async throws { + var request = URLRequest(url: try XCTUnwrap(URL(string: url))) + request.httpMethod = "POST" + let (_, response) = try await URLSession.shared.data(for: request) + XCTAssertEqual((response as? HTTPURLResponse)?.statusCode, 200, url) + } + + // MARK: Datagram sessions + + func testDatagramsEchoOnAnExtendedConnectSession() async throws { + let engine = try await createEngine() + try await openDatagrams(engine, callId: 1) + try await waitUntil("the session was accepted", timeout: 10) { self.event(1, "headers") != nil } + XCTAssertEqual(event(1, "headers")?["status"] as? Int, 200) + XCTAssertEqual(event(1, "headers")?["protocol"] as? String, "h3") + + for text in ["one", "two", "three"] { + try await invoke("sendDatagram", ["callId": 1, "data": Data(text.utf8)]) + } + // Datagrams are unreliable, but nothing is lost on loopback. + try await waitUntil("the echoes arrived") { self.datagrams(1).count == 3 } + XCTAssertEqual(Set(datagrams(1)), ["one", "two", "three"]) + + // Finishing the request stream ends the session; the server then closes its side. + try await invoke("end", ["callId": 1]) + try await waitUntil("the session ended") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + } + + func testDatagramsCanBeSentBeforeTheServerAnswers() async throws { + let engine = try await createEngine() + try await openDatagrams(engine, callId: 1) + // The stream exists once the reply to sendDatagram is a success; until then it is refused. + try await waitUntil("a datagram was taken", timeout: 10) { + if case .success = await self.reply("sendDatagram", ["callId": 1, "data": Data("early".utf8)]) { + return true + } + return false + } + try await waitUntil("the echo arrived") { self.datagrams(1).contains("early") } + } + + func testTheServerEndsADatagramSession() async throws { + let engine = try await createEngine() + try await openDatagrams(engine, callId: 1) + try await waitUntil("the session was accepted", timeout: 10) { self.event(1, "headers") != nil } + try await invoke("sendDatagram", ["callId": 1, "data": Data("close".utf8)]) + try await waitUntil("the session ended") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") + + if case .success = await reply("sendDatagram", ["callId": 1, "data": Data("late".utf8)]) { + XCTFail("a datagram was taken for an ended session") + } + } + + func testDatagramSessionsAndCallsShareAConnection() async throws { + let engine = try await createEngine() + try await openDatagrams(engine, callId: 1) + try await openDatagrams(engine, callId: 2) + try await open(engine, callId: 3, path: Self.say, contentType: "application/proto") + try await write(3, sentence("alongside")) + try await invoke("end", ["callId": 3]) + try await waitUntil("both sessions were accepted", timeout: 10) { + self.event(1, "headers") != nil && self.event(2, "headers") != nil + } + try await invoke("sendDatagram", ["callId": 1, "data": Data("for one".utf8)]) + try await invoke("sendDatagram", ["callId": 2, "data": Data("for two".utf8)]) + try await waitUntil("the echoes arrived") { !self.datagrams(1).isEmpty && !self.datagrams(2).isEmpty } + XCTAssertEqual(datagrams(1), ["for one"]) + XCTAssertEqual(datagrams(2), ["for two"]) + try await waitUntil("the call ended") { self.outcome(3) != nil } + XCTAssertEqual(outcome(3)?["type"] as? String, "done", "\(String(describing: outcome(3)))") + + try await invoke("cancel", ["callId": 1]) + try await waitUntil("the session was canceled") { self.outcome(1) != nil } + XCTAssertEqual(outcome(1)?["type"] as? String, "canceled") + // The other session is unaffected. + try await invoke("sendDatagram", ["callId": 2, "data": Data("still".utf8)]) + try await waitUntil("the echo arrived") { self.datagrams(2).contains("still") } + } + + func testATooLargeDatagramIsRefused() async throws { + let engine = try await createEngine() + try await openDatagrams(engine, callId: 1) + try await waitUntil("the session was accepted", timeout: 10) { self.event(1, "headers") != nil } + let result = await reply("sendDatagram", ["callId": 1, "data": Data(count: 64 * 1024)]) + guard case .error(let code, _) = result else { + XCTFail("a 64 KiB datagram was taken: \(result)") + return + } + XCTAssertEqual(code, "datagramFailed") + // The session carries on. + try await invoke("sendDatagram", ["callId": 1, "data": Data("small".utf8)]) + try await waitUntil("the echo arrived") { self.datagrams(1).contains("small") } + } + + // MARK: Bridge calls + + private func reply(_ method: String, _ arguments: [String: Any]) async -> HTTP3Bridge.Reply { + await withCheckedContinuation { (done: CheckedContinuation) in + bridge.handle(method, arguments) { done.resume(returning: $0) } + } + } + + private func reply(_ bridge: HTTP3Bridge, _ method: String, _ arguments: [String: Any]) async throws -> Any? { + let result = await withCheckedContinuation { (done: CheckedContinuation) in + bridge.handle(method, arguments) { done.resume(returning: $0) } + } + guard case .success(let value) = result else { + XCTFail("\(method): \(result)") + throw CancellationError() + } + return value + } + + private func openDatagrams(_ engine: Int, callId: Int) async throws { + try await invoke("openDatagrams", [ + "engineId": engine, "callId": callId, "url": serverURL + Self.datagramEcho, "protocol": "datagram-echo", + "headers": [["user-agent", "connect_native_http tests"]], + ]) + } + + @discardableResult + private func invoke(_ method: String, _ arguments: [String: Any]) async throws -> Any? { + switch await reply(method, arguments) { + case .success(let value): + return value + case .error(let code, let message): + XCTFail("\(method): \(code): \(message)") + throw CancellationError() + case .notImplemented: + throw XCTSkip("\(method) is not implemented") + } + } + + private func createEngine() async throws -> Int { + let url = try XCTUnwrap(URL(string: serverURL)) + let origin: [Any] = [url.host!, url.port ?? 443] + return try await invoke("createEngine", ["http3Origins": [origin]]) as! Int + } + + private func open( + _ engine: Int, callId: Int, path: String, contentType: String, readIdleTimeoutMs: Int? = nil + ) async throws { + var arguments: [String: Any] = [ + "engineId": engine, "callId": callId, "url": serverURL + path, "method": "POST", + "headers": [["content-type", contentType], ["connect-protocol-version", "1"]], "hasBody": true, + ] + arguments["readIdleTimeoutMs"] = readIdleTimeoutMs + try await invoke("open", arguments) + } + + private func write(_ callId: Int, _ data: Data) async throws { + try await invoke("write", ["callId": callId, "data": data]) + } + + // MARK: Events + + private func snapshot() -> [[String: Any]] { + lock.withLock { events } + } + + private func event(_ callId: Int, _ type: String) -> [String: Any]? { + snapshot().first { $0["callId"] as? Int == callId && $0["type"] as? String == type } + } + + private func outcome(_ callId: Int) -> [String: Any]? { + snapshot().first { + $0["callId"] as? Int == callId && ["done", "failed", "canceled"].contains($0["type"] as? String ?? "") + } + } + + /// The datagrams received on a session so far, as text. + private func datagrams(_ callId: Int) -> [String] { + snapshot().filter { $0["callId"] as? Int == callId && $0["type"] as? String == "datagram" }.map { + String(decoding: $0["data"] as! Data, as: UTF8.self) + } + } + + /// The response body so far, as text; Connect framing and protobuf leave the sentences readable. + private func received(_ callId: Int) -> String { + var body = Data() + for e in snapshot() where e["callId"] as? Int == callId && e["type"] as? String == "data" { + body.append(e["data"] as! Data) + } + return String(decoding: body, as: UTF8.self) + } + + private func waitUntil(_ what: String, timeout: TimeInterval = 3, _ condition: () async -> Bool) async throws { + let deadline = Date().addingTimeInterval(timeout) + while !(await condition()) { + if Date() > deadline { + XCTFail("timed out after \(timeout) s waiting until \(what); events: \(snapshot())") + throw CancellationError() + } + try await Task.sleep(nanoseconds: 20_000_000) + } + } +} + +extension URLComponents { + fileprivate func with(port: Int) -> String { + var copy = self + copy.port = port + return copy.string! + } +} + +/// A `SayRequest` or `ConverseRequest`: field 1, the sentence. +private func sentence(_ text: String) -> Data { + let utf8 = Data(text.utf8) + precondition(utf8.count < 128) + return Data([0x0A, UInt8(utf8.count)]) + utf8 +} + +/// A Connect streaming message: flags, big-endian length, payload. +private func envelope(_ payload: Data) -> Data { + let n = UInt32(payload.count) + return Data([0, UInt8(n >> 24), UInt8(n >> 16 & 0xFF), UInt8(n >> 8 & 0xFF), UInt8(n & 0xFF)]) + payload +} diff --git a/ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/URLSessionBridgeTests.swift b/ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/URLSessionBridgeTests.swift deleted file mode 100644 index 06bb7d5..0000000 --- a/ios/connect_native_http/Tests/ConnectNativeHttpCoreTests/URLSessionBridgeTests.swift +++ /dev/null @@ -1,276 +0,0 @@ -import Foundation -import XCTest - -@testable import ConnectNativeHttpCore - -// Bridge behavior the Dart integration tests can't reach, against test_server/. run_integration_tests.sh starts the -// server and passes its URL as SERVER_URL and its CA certificate (DER) as SERVER_CA. -final class URLSessionBridgeTests: XCTestCase { - private static let converse = "/connectrpc.eliza.v1.ElizaService/Converse" - private static let say = "/connectrpc.eliza.v1.ElizaService/Say" - - private var serverURL = "" - private var bridge: URLSessionBridge! - private let lock = NSLock() - private var events: [[String: Any]] = [] - private var writeReturned = false - - override func setUpWithError() throws { - let env = ProcessInfo.processInfo.environment - guard let url = env["SERVER_URL"], let caPath = env["SERVER_CA"] else { - throw XCTSkip("SERVER_URL and SERVER_CA are not set; run these through run_integration_tests.sh") - } - serverURL = url - let ca = try XCTUnwrap(SecCertificateCreateWithData(nil, try Data(contentsOf: URL(fileURLWithPath: caPath)) as CFData)) - bridge = URLSessionBridge(trustedRoots: [ca]) { [weak self] event in - guard let self else { return } - lock.withLock { self.events.append(event) } - } - } - - func testWriteWaitingOnAFullBufferReturnsOnceTheCallIsCanceled() async throws { - let engine = try await createEngine() - try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") - try await write(1, envelope(sentence("stall"))) - try await waitUntil("the server stopped reading") { self.received(1).contains("echo: stall") } - - Task { - try await self.write(1, Data(count: 32 << 20)) - self.lock.withLock { self.writeReturned = true } - } - try await Task.sleep(nanoseconds: 1_000_000_000) - XCTAssertFalse(lock.withLock { writeReturned }, "32 MiB fit in the buffers before a server that stopped reading") - - try await invoke("cancel", ["callId": 1]) - try await waitUntil("the call was canceled") { self.event(1, "canceled") != nil } - try await waitUntil("the write returned", timeout: 2) { self.lock.withLock { self.writeReturned } } - } - - func testWriteWaitingOnAFullBufferReturnsWhenTheConnectionFails() async throws { - let engine = try await createEngine() - // Nothing listens on the discard port, so URLSession fails the task without ever opening the body stream. - let unreachable = try XCTUnwrap(URLComponents(string: serverURL)).with(port: 9) - try await invoke("open", [ - "engineId": engine, "callId": 1, "url": unreachable + Self.say, "method": "POST", - "headers": [["content-type", "application/proto"]], "hasBody": true, - ]) - Task { - try await self.write(1, Data(count: 1 << 20)) - self.lock.withLock { self.writeReturned = true } - } - try await waitUntil("the call failed") { self.outcome(1) != nil } - XCTAssertEqual(outcome(1)?["type"] as? String, "failed") - try await waitUntil("the write returned", timeout: 2) { self.lock.withLock { self.writeReturned } } - } - - func testRedirectOfARequestWithABodyIsReturnedInsteadOfFollowed() async throws { - let engine = try await createEngine() - try await open(engine, callId: 1, path: "/redirect" + Self.say, contentType: "application/proto") - try await write(1, sentence("hi")) - try await invoke("end", ["callId": 1]) - try await waitUntil("the call ended") { self.outcome(1) != nil } - XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") - XCTAssertEqual(event(1, "headers")?["status"] as? Int, 307) - } - - func testShutdownLetsACallInFlightFinishAndRefusesNewOnes() async throws { - let engine = try await createEngine() - try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") - try await invoke("shutdownEngine", ["engineId": engine]) - try await write(1, envelope(sentence("bye"))) - try await invoke("end", ["callId": 1]) - try await waitUntil("the call ended") { self.outcome(1) != nil } - XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") - XCTAssertTrue(received(1).contains("echo: bye")) - - try await open(engine, callId: 2, path: Self.converse, contentType: "application/connect+proto") - try await waitUntil("the second call ended") { self.outcome(2) != nil } - XCTAssertEqual(outcome(2)?["type"] as? String, "failed") - XCTAssertEqual(outcome(2)?["domain"] as? String, "ConnectNativeHttp") - } - - func testReadIdleTimeoutFailsAQuietCallAndTheEngineCarriesOn() async throws { - let engine = try await createEngine() - // The timeout also covers setting up the connection, which can outlast it on a loaded simulator. A call first - // leaves a connection for the timed one to reuse. - try await open(engine, callId: 10, path: Self.say, contentType: "application/proto") - try await write(10, sentence("warm up")) - try await invoke("end", ["callId": 10]) - try await waitUntil("the warm-up call ended", timeout: 10) { self.outcome(10) != nil } - try await open( - engine, callId: 1, path: Self.converse, contentType: "application/connect+proto", readIdleTimeoutMs: 500) - try await waitUntil("the greeting arrived") { self.received(1).contains("hello") } - let start = Date() - try await waitUntil("the call timed out") { self.outcome(1) != nil } - let elapsed = Date().timeIntervalSince(start) - XCTAssertEqual(outcome(1)?["type"] as? String, "failed", "\(String(describing: outcome(1)))") - XCTAssertEqual(outcome(1)?["code"] as? Int, NSURLErrorTimedOut) - XCTAssertLessThan(elapsed, 2, "a 500 ms read-idle timeout took \(elapsed) s") - - // New calls go to a fresh URLSession. - try await open(engine, callId: 2, path: Self.say, contentType: "application/proto") - try await write(2, sentence("after")) - try await invoke("end", ["callId": 2]) - try await waitUntil("the next call ended") { self.outcome(2) != nil } - XCTAssertEqual(outcome(2)?["type"] as? String, "done", "\(String(describing: outcome(2)))") - XCTAssertTrue(received(2).contains("say: after")) - } - - // A call that hit its deadline is canceled at once, and moves the engine's new calls to a fresh URLSession. - func testADeadlineCancelEndsTheCallAndTheEngineCarriesOn() async throws { - let engine = try await createEngine() - try await open(engine, callId: 1, path: Self.converse, contentType: "application/connect+proto") - try await waitUntil("the greeting arrived", timeout: 10) { self.received(1).contains("hello") } - try await invoke("cancel", ["callId": 1, "evictConnection": true]) - try await waitUntil("the call was canceled") { self.outcome(1) != nil } - XCTAssertEqual(outcome(1)?["type"] as? String, "canceled", "\(String(describing: outcome(1)))") - - try await open(engine, callId: 2, path: Self.say, contentType: "application/proto") - try await write(2, sentence("after")) - try await invoke("end", ["callId": 2]) - try await waitUntil("the next call ended", timeout: 10) { self.outcome(2) != nil } - XCTAssertEqual(outcome(2)?["type"] as? String, "done", "\(String(describing: outcome(2)))") - } - - func testRequestTimeoutIntervalAvoidsTheValueURLSessionIgnores() { - XCTAssertNil(URLSessionBridge.requestTimeoutInterval(readIdleTimeoutMs: nil)) - XCTAssertEqual(URLSessionBridge.requestTimeoutInterval(readIdleTimeoutMs: 1500), 1.5) - XCTAssertEqual(URLSessionBridge.requestTimeoutInterval(readIdleTimeoutMs: 60_000), 60.001) - } - - func testMalformedArgumentsAreRefusedInsteadOfCrashing() async throws { - let malformed: [(String, [String: Any])] = [ - ("open", [:]), - ("open", ["engineId": "1", "callId": 1, "url": serverURL, "method": "POST", "headers": [[String]](), "hasBody": true]), - ("open", ["engineId": 1, "callId": 1, "url": serverURL, "method": "POST", "headers": [["one"]], "hasBody": true]), - ("open", [ - "engineId": 1, "callId": 1, "url": serverURL, "method": "POST", "headers": [[String]](), "hasBody": true, - "readIdleTimeoutMs": "soon", - ]), - ("open", [ - "engineId": 1, "callId": 1, "url": serverURL, "method": "POST", "headers": [[String]](), "hasBody": true, - "readIdleTimeoutMs": 0, - ]), - ("write", ["callId": 1, "data": "not bytes"]), - ("end", ["callId": "1"]), - ("cancel", [:]), - ("cancel", ["callId": 1, "evictConnection": "yes"]), - ("shutdownEngine", ["engineId": NSNull()]), - ("createEngine", ["http3Origins": [["localhost"]]]), - ] - for (method, arguments) in malformed { - let result = await reply(method, arguments) - guard case .error(let code, _) = result else { - XCTFail("\(method) \(arguments): \(result)") - continue - } - XCTAssertEqual(code, "badArguments") - } - // The bridge still works afterwards. - let engine = try await createEngine() - try await open(engine, callId: 1, path: Self.say, contentType: "application/proto") - try await write(1, sentence("hi")) - try await invoke("end", ["callId": 1]) - try await waitUntil("the call ended") { self.outcome(1) != nil } - XCTAssertEqual(outcome(1)?["type"] as? String, "done", "\(String(describing: outcome(1)))") - } - - // MARK: Bridge calls - - private func reply(_ method: String, _ arguments: [String: Any]) async -> URLSessionBridge.Reply { - await withCheckedContinuation { (done: CheckedContinuation) in - bridge.handle(method, arguments) { done.resume(returning: $0) } - } - } - - @discardableResult - private func invoke(_ method: String, _ arguments: [String: Any]) async throws -> Any? { - switch await reply(method, arguments) { - case .success(let value): - return value - case .error(let code, let message): - XCTFail("\(method): \(code): \(message)") - throw CancellationError() - case .notImplemented: - throw XCTSkip("\(method) is not implemented") - } - } - - private func createEngine() async throws -> Int { - let url = try XCTUnwrap(URL(string: serverURL)) - let origin: [Any] = [url.host!, url.port ?? 443] - return try await invoke("createEngine", ["http3Origins": [origin]]) as! Int - } - - private func open( - _ engine: Int, callId: Int, path: String, contentType: String, readIdleTimeoutMs: Int? = nil - ) async throws { - var arguments: [String: Any] = [ - "engineId": engine, "callId": callId, "url": serverURL + path, "method": "POST", - "headers": [["content-type", contentType], ["connect-protocol-version", "1"]], "hasBody": true, - ] - arguments["readIdleTimeoutMs"] = readIdleTimeoutMs - try await invoke("open", arguments) - } - - private func write(_ callId: Int, _ data: Data) async throws { - try await invoke("write", ["callId": callId, "data": data]) - } - - // MARK: Events - - private func snapshot() -> [[String: Any]] { - lock.withLock { events } - } - - private func event(_ callId: Int, _ type: String) -> [String: Any]? { - snapshot().first { $0["callId"] as? Int == callId && $0["type"] as? String == type } - } - - private func outcome(_ callId: Int) -> [String: Any]? { - snapshot().first { - $0["callId"] as? Int == callId && ["done", "failed", "canceled"].contains($0["type"] as? String ?? "") - } - } - - /// The response body so far, as text; Connect framing and protobuf leave the sentences readable. - private func received(_ callId: Int) -> String { - var body = Data() - for e in snapshot() where e["callId"] as? Int == callId && e["type"] as? String == "data" { - body.append(e["data"] as! Data) - } - return String(decoding: body, as: UTF8.self) - } - - private func waitUntil(_ what: String, timeout: TimeInterval = 3, _ condition: () -> Bool) async throws { - let deadline = Date().addingTimeInterval(timeout) - while !condition() { - if Date() > deadline { - XCTFail("timed out after \(timeout) s waiting until \(what); events: \(snapshot())") - throw CancellationError() - } - try await Task.sleep(nanoseconds: 20_000_000) - } - } -} - -extension URLComponents { - fileprivate func with(port: Int) -> String { - var copy = self - copy.port = port - return copy.string! - } -} - -/// A `SayRequest` or `ConverseRequest`: field 1, the sentence. -private func sentence(_ text: String) -> Data { - let utf8 = Data(text.utf8) - precondition(utf8.count < 128) - return Data([0x0A, UInt8(utf8.count)]) + utf8 -} - -/// A Connect streaming message: flags, big-endian length, payload. -private func envelope(_ payload: Data) -> Data { - let n = UInt32(payload.count) - return Data([0, UInt8(n >> 24), UInt8(n >> 16 & 0xFF), UInt8(n >> 8 & 0xFF), UInt8(n & 0xFF)]) + payload -} diff --git a/lib/connect_native_http.dart b/lib/connect_native_http.dart index a20569e..8396e60 100644 --- a/lib/connect_native_http.dart +++ b/lib/connect_native_http.dart @@ -1,6 +1,7 @@ -/// connect-dart HttpClients on the platform HTTP stacks: URLSession on iOS, Cronet on Android. +/// connect-dart HttpClients over HTTP/3, with HTTP datagram sessions on iOS: swift-nio-http3 on iOS, Cronet on Android. library; +export 'src/datagram_session.dart' show DatagramSession, DatagramSessionRejected; export 'src/native_http_client.dart' show NativeHttpClient; export 'src/native_http_config.dart' show NativeHttpConfig, NativeHttpResponseInfo; export 'src/native_http_exception.dart' show NativeHttpException, NativeHttpFailure; diff --git a/lib/src/channel/channel_http_client.dart b/lib/src/channel/channel_http_client.dart index d3a3844..16da2b0 100644 --- a/lib/src/channel/channel_http_client.dart +++ b/lib/src/channel/channel_http_client.dart @@ -5,14 +5,15 @@ import 'package:connectrpc/connect.dart'; import 'package:flutter/foundation.dart'; import 'package:flutter/services.dart'; +import '../datagram_session.dart'; import '../native_http_client.dart'; import '../native_http_config.dart'; import '../native_http_exception.dart'; -import 'connect_end_stream.dart'; /// A platform plugin that speaks this file's channel protocol: `createEngine`, `shutdownEngine`, `open`, `write`, /// `end` and `cancel` method calls, and `headers`, `data`, `trailers`, `responseComplete`, `done`, `failed` and -/// `canceled` events. +/// `canceled` events. A plugin that [supportsDatagrams] also takes `openDatagrams` and `sendDatagram` calls, and sends +/// `datagram` events. final class PlatformBridge { const PlatformBridge({ required this.name, @@ -20,7 +21,7 @@ final class PlatformBridge { required this.events, required this.failure, this.responseHeaders = plainHeaders, - this.endsStreamsItself = true, + this.supportsDatagrams = false, }); /// Prefixes the plugin's error messages, such as `cronet`. @@ -34,10 +35,8 @@ final class PlatformBridge { /// Builds the response headers connect-dart sees from a `headers` event's name and value pairs. final Headers Function(List<(String, String)> pairs) responseHeaders; - /// Whether the plugin ends a call once the server has sent the whole response, even while the request body is - /// still open. When it does not, the client watches Connect streaming responses for their end-stream message and - /// cancels the call itself once that arrives (see [ConnectEndStreamDetector]). - final bool endsStreamsItself; + /// Whether the plugin opens datagram sessions ([NativeHttpClient.openDatagramSession]). + final bool supportsDatagrams; } Headers plainHeaders(List<(String, String)> pairs) { @@ -49,7 +48,7 @@ Headers plainHeaders(List<(String, String)> pairs) { } final class _Call { - _Call(this.url) { + _Call(this.url, {bool datagramSession = false}) : datagrams = datagramSession ? StreamController() : null { // A failure event can arrive before the `open` reply, so before `_send` has handed this future to its caller. // The caller still gets the error; this keeps it from also being reported as unhandled in the meantime. response.future.ignore(); @@ -58,9 +57,14 @@ final class _Call { final Uri url; final response = Completer(); final body = StreamController(); + + /// A datagram session's incoming datagrams; `null` for other calls. + final StreamController? datagrams; + + /// Completes when the call has ended, with its error if it failed. + final ended = Completer(); final trailer = Headers(); bool finished = false; - ConnectEndStreamDetector? endStream; /// Set when the call's signal fired, so the outcome reports the signal's error rather than the cancellation. Object? abortError; @@ -70,6 +74,17 @@ final class _Call { void fail(Object error) { finished = true; + if (!ended.isCompleted) { + ended.completeError(error); + // Only a datagram session's caller waits on it; others see the error through the response. + ended.future.ignore(); + } + final datagrams = this.datagrams; + if (datagrams != null && !datagrams.isClosed) { + datagrams + ..addError(error) + ..close(); + } if (!response.isCompleted) { response.completeError(error); } @@ -85,6 +100,10 @@ final class _Call { /// The server sent the whole response, so nothing more is sent. void completeResponse(String bridgeName) { finished = true; + if (!ended.isCompleted) { + ended.complete(); + } + datagrams?.close(); if (!response.isCompleted) { response.completeError(ConnectException(Code.internal, '$bridgeName: response ended without headers')); } @@ -188,7 +207,7 @@ final class _Dispatcher { } void _onCallEvent(int id, _Call call, Map e) { - if (const {'headers', 'data', 'trailers'}.contains(e['type'])) { + if (const {'headers', 'data', 'trailers', 'datagram'}.contains(e['type'])) { call.sinceReceived.reset(); } switch (e['type']) { @@ -197,9 +216,6 @@ final class _Dispatcher { for (final pair in (e['headers']! as List).cast>()) (pair[0]! as String, pair[1]! as String), ]); final status = e['status']! as int; - if (!bridge.endsStreamsItself && isConnectStreamingContentType(headers.get('content-type')?.firstOrNull)) { - call.endStream = ConnectEndStreamDetector(); - } final onResponse = _onResponse[id]; if (onResponse != null) { // The caller's own callback: its failure is reported, and doesn't fail the call or leave it hanging. @@ -213,7 +229,14 @@ final class _Dispatcher { call.response.complete(HttpResponse(status, headers, call.body.stream, call.trailer)); } case 'data': - _onData(id, call, e['data']! as Uint8List); + if (!call.finished) { + call.body.add(e['data']! as Uint8List); + } + case 'datagram': + final datagrams = call.datagrams; + if (datagrams != null && !datagrams.isClosed) { + datagrams.add(e['data']! as Uint8List); + } case 'trailers': for (final pair in (e['headers']! as List).cast>()) { call.trailer.add(pair[0]! as String, pair[1]! as String); @@ -232,25 +255,6 @@ final class _Dispatcher { call.fail(call.abortError ?? ConnectException(Code.canceled, '${bridge.name}: stream canceled')); } } - - void _onData(int id, _Call call, Uint8List data) { - if (call.finished) { - return; - } - final detector = call.endStream; - if (detector == null) { - call.body.add(data); - return; - } - final used = detector.add(data); - if (used > 0) { - call.body.add(used == data.length ? data : Uint8List.sublistView(data, 0, used)); - } - if (detector.done) { - call.completeResponse(bridge.name); - unawaited(cancel(id)); - } - } } /// The `connect-timeout-ms` to send for a call whose deadline is [ms] away: [step] less, or half of [ms] when that is @@ -380,6 +384,95 @@ base class ChannelHttpClient implements NativeHttpClient { } } + @override + Future openDatagramSession( + Uri url, { + required String protocol, + Map headers = const {}, + }) async { + if (!_bridge.supportsDatagrams) { + throw UnsupportedError('${_bridge.name}: datagram sessions are not supported on this platform'); + } + final dispatcher = _Dispatcher.of(_bridge); + final call = _Call(url, datagramSession: true); + final id = dispatcher.register(call, _config.onResponse); + try { + await _bridge.methods.invokeMethod('openDatagrams', { + 'engineId': _engineId, + 'callId': id, + 'url': url.toString(), + 'protocol': protocol, + 'headers': [ + for (final MapEntry(:key, :value) in headers.entries) [key, value], + ], + 'readIdleTimeoutMs': _readIdleTimeoutMs, + }); + } catch (error) { + dispatcher.remove(id); + call.finished = true; + final cause = NativeHttpException(NativeHttpFailure.notSent, '${_bridge.name}: open failed: $error'); + throw ConnectException(Code.unavailable, cause.message, cause: cause); + } + final response = await call.response.future; + final session = _DatagramSession(_bridge, dispatcher, id, call, response); + if (response.status < 200 || response.status > 299) { + await session.cancel(); + throw DatagramSessionRejected(response.status, response.header); + } + return session; + } + @override Future close() => _bridge.methods.invokeMethod('shutdownEngine', {'engineId': _engineId}); } + +final class _DatagramSession implements DatagramSession { + _DatagramSession(this._bridge, this._dispatcher, this._id, this._call, this._response); + + final PlatformBridge _bridge; + final _Dispatcher _dispatcher; + final int _id; + final _Call _call; + final HttpResponse _response; + + @override + int get status => _response.status; + + @override + Headers get headers => _response.header; + + @override + Stream get datagrams => _call.datagrams!.stream; + + @override + Stream get data => _response.body; + + @override + Future send(Uint8List datagram) async { + if (_call.finished) { + throw NativeHttpException(NativeHttpFailure.other, '${_bridge.name}: the datagram session has ended'); + } + try { + await _bridge.methods.invokeMethod('sendDatagram', {'callId': _id, 'data': datagram}); + } on PlatformException catch (error) { + throw NativeHttpException(NativeHttpFailure.other, '${_bridge.name}: datagram not sent: ${error.message}'); + } + } + + @override + Future close() async { + if (!_call.finished) { + await _bridge.methods.invokeMethod('end', {'callId': _id}); + } + } + + @override + Future cancel() async { + if (!_call.finished) { + await _dispatcher.cancel(_id); + } + } + + @override + Future get done => _call.ended.future; +} diff --git a/lib/src/channel/connect_end_stream.dart b/lib/src/channel/connect_end_stream.dart deleted file mode 100644 index e7428bb..0000000 --- a/lib/src/channel/connect_end_stream.dart +++ /dev/null @@ -1,54 +0,0 @@ -import 'dart:math'; -import 'dart:typed_data'; - -/// Whether a response with [contentType] is a Connect streaming response, whose body is a sequence of envelopes -/// ending in an end-stream message. -bool isConnectStreamingContentType(String? contentType) => - contentType?.trim().toLowerCase().startsWith('application/connect+') ?? false; - -/// Finds the end of a Connect streaming response body: the envelope with the end-stream flag (`0x02`). -/// -/// Each envelope is a flags byte, a 4-byte big-endian length, then that many bytes. URLSession over HTTP/3 does not -/// complete a task while its request body is still open, even after the server has finished the response, so the -/// end of a bidi call the server ends first is only visible here. -final class ConnectEndStreamDetector { - static const _headerLength = 5; - static const _endStreamFlag = 0x02; - - final _header = Uint8List(_headerLength); - int _headerFilled = 0; - int _payloadRemaining = 0; - bool _inEndStream = false; - bool _done = false; - - /// Whether the end-stream message has been read in full. - bool get done => _done; - - /// Consumes [chunk] and returns how many of its bytes belong to the response, which is all of them unless the - /// end-stream message completes inside [chunk]. Bytes after the end-stream message are not part of any message. - int add(Uint8List chunk) { - var offset = 0; - while (offset < chunk.length && !_done) { - if (_payloadRemaining > 0) { - final take = min(chunk.length - offset, _payloadRemaining); - _payloadRemaining -= take; - offset += take; - if (_payloadRemaining == 0 && _inEndStream) { - _done = true; - } - continue; - } - _header[_headerFilled++] = chunk[offset++]; - if (_headerFilled < _headerLength) { - continue; - } - _headerFilled = 0; - _inEndStream = _header[0] & _endStreamFlag != 0; - _payloadRemaining = ByteData.sublistView(_header).getUint32(1); - if (_payloadRemaining == 0 && _inEndStream) { - _done = true; - } - } - return offset; - } -} diff --git a/lib/src/datagram_session.dart b/lib/src/datagram_session.dart new file mode 100644 index 0000000..7434552 --- /dev/null +++ b/lib/src/datagram_session.dart @@ -0,0 +1,54 @@ +import 'dart:typed_data'; + +import 'package:connectrpc/connect.dart'; + +/// An HTTP/3 Extended CONNECT (RFC 9220) session that carries HTTP datagrams (RFC 9297) to and from the server. Open +/// one with [NativeHttpClient.openDatagramSession]. +/// +/// Datagrams are unreliable and unordered: either side may drop or reorder them, and each must fit in one QUIC +/// packet. The session itself is the request stream that opened it, which ends when either side closes it or the +/// connection fails. It shares its connection with the client's other calls and sessions to the same origin. +abstract interface class DatagramSession { + /// The server's answer to the CONNECT request: a 2xx status, since anything else fails + /// [NativeHttpClient.openDatagramSession]. + int get status; + + /// The headers of the server's answer. + Headers get headers; + + /// The datagrams the server sends on this session, as they arrive. Datagrams that arrive while nothing listens are + /// buffered. The stream ends when the session does, with the session's error if it failed. + Stream get datagrams; + + /// Anything the server writes on the session's request stream, such as capsules (RFC 9297 § 3). Most protocols + /// built on datagrams alone leave it empty. Ends when the session does. + Stream get data; + + /// Sends one datagram. Completes once the datagram is handed to QUIC, which says nothing about delivery. + /// + /// Throws a [NativeHttpException] if the session has ended or the datagram can't be sent, for example because it is + /// larger than the connection's maximum datagram size. + Future send(Uint8List datagram); + + /// Finishes the session's request stream, which asks the server to end the session. [done] completes once it has. + Future close(); + + /// Resets the session's request stream, ending the session at once. + Future cancel(); + + /// Completes when the session ends: normally when the server ends it, after [close] or on its own, or with a + /// [ConnectException] (`unavailable`, with a [NativeHttpException] cause) if it failed, or `canceled` after + /// [cancel]. + Future get done; +} + +/// The server answered a datagram session's CONNECT request with a status other than 2xx. +final class DatagramSessionRejected implements Exception { + const DatagramSessionRejected(this.status, this.headers); + + final int status; + final Headers headers; + + @override + String toString() => 'DatagramSessionRejected: the server answered $status'; +} diff --git a/lib/src/native_http_client.dart b/lib/src/native_http_client.dart index 2c01fb5..b80dad0 100644 --- a/lib/src/native_http_client.dart +++ b/lib/src/native_http_client.dart @@ -3,22 +3,23 @@ import 'dart:io'; import 'package:connectrpc/connect.dart'; import 'cronet/cronet_http_client.dart'; +import 'datagram_session.dart'; import 'native_http_config.dart'; -import 'url_session/url_session_http_client.dart'; +import 'nio_http3/nio_http3_client.dart'; -/// A connect-dart [HttpClient] on the platform's own HTTP stack, which negotiates HTTP/3 or HTTP/2 itself and -/// carries full-duplex streams. Use it with the Connect protocol (`package:connectrpc/protocol/connect.dart`): the -/// platform stacks do not expose HTTP trailers, which the gRPC protocol needs. +/// A connect-dart [HttpClient] for full-duplex streams over HTTP/3: swift-nio-http3 on iOS, which speaks HTTP/3 only, +/// and Cronet on Android, which negotiates HTTP/3 or HTTP/2 itself. Use it with the Connect protocol +/// (`package:connectrpc/protocol/connect.dart`): Cronet does not expose HTTP trailers, which the gRPC protocol needs. /// /// Requests fail with a `ConnectException` of code `unavailable` whose `cause` is a [NativeHttpException]. abstract interface class NativeHttpClient { - /// The client for this platform, or `null` where there is none (anything but iOS and Android). + /// The client for this platform, or `null` where there is none (anything but iOS 27+ and Android). /// /// Throws a `PlatformException` if the platform can't create one, such as when Android fails to load Cronet's native /// library. An app can fall back to another `HttpClient` then. static Future create([NativeHttpConfig config = const NativeHttpConfig()]) async { if (Platform.isIOS) { - return UrlSessionHttpClient.create(config); + return NioHttp3Client.create(config); } if (Platform.isAndroid) { return CronetHttpClient.create(config); @@ -28,6 +29,21 @@ abstract interface class NativeHttpClient { HttpClient get httpClient; + /// Opens an HTTP/3 datagram session: an Extended CONNECT request (RFC 9220) to [url] with `:protocol` [protocol], + /// on which both sides may then send HTTP datagrams (RFC 9297). Completes once the server has accepted it with a 2xx + /// status. + /// + /// Throws a `ConnectException` with code `unavailable` and a [NativeHttpException] cause if the session can't be set + /// up, including when the server's HTTP/3 SETTINGS don't offer datagrams and Extended CONNECT, and + /// [DatagramSessionRejected] if the server answers with another status. + /// + /// iOS only: throws [UnsupportedError] on Android, where Cronet has no HTTP datagrams. + Future openDatagramSession( + Uri url, { + required String protocol, + Map headers = const {}, + }); + /// Lets requests in flight finish and releases the platform resources. Do not send requests after this. Future close(); } diff --git a/lib/src/native_http_config.dart b/lib/src/native_http_config.dart index 32fd8c5..f521e2e 100644 --- a/lib/src/native_http_config.dart +++ b/lib/src/native_http_config.dart @@ -4,8 +4,8 @@ final class NativeHttpResponseInfo { final Uri url; - /// The protocol the platform negotiated, as the platform names it: Cronet reports `h2` or `quic/1+spdy/3` (HTTP/3). - /// `null` when the platform does not expose it, as with URLSession. + /// The protocol the platform negotiated, as the platform names it: Cronet reports `h2` or `quic/1+spdy/3` (HTTP/3), + /// iOS always `h3`. `null` when the platform does not report it. final String? protocol; } @@ -15,6 +15,7 @@ final class NativeHttpConfig { const NativeHttpConfig({ this.http3Origins = const {}, this.quicIdleTimeout, + this.connectTimeout, this.readIdleTimeout, this.deadlineStep, this.evictOnDeadline = false, @@ -22,10 +23,9 @@ final class NativeHttpConfig { }); /// `https://host:port` origins to try HTTP/3 with from the first request, before an `Alt-Svc` response header has - /// advertised it. Both platforms fall back to HTTP/2 over TCP on their own when QUIC fails. + /// advertised it. Cronet falls back to HTTP/2 over TCP on its own when QUIC fails. /// - /// Set this for origins that serve HTTP/3. Without it, URLSession learns HTTP/3 from `Alt-Svc` but uses it only for - /// a new connection, and a busy session keeps reusing its first HTTP/2 connection indefinitely. + /// Android only: on iOS every call goes over HTTP/3, to any origin, with no fallback to TCP. final Set http3Origins; /// The QUIC idle timeout this client advertises, in whole seconds: how long an HTTP/3 connection may go without @@ -33,9 +33,15 @@ final class NativeHttpConfig { /// so this bounds how long a dead network path goes unnoticed, as long as the server pings more often than this. /// `null` keeps the platform default. /// - /// Android only. URLSession exposes no QUIC settings, so on iOS only the server's advertised idle timeout applies. + /// On Android, Cronet takes whole seconds. On iOS any positive duration works, rounded up to the millisecond. final Duration? quicIdleTimeout; + /// How long a new connection may take to resolve its host and finish the QUIC handshake before its calls fail as + /// never sent. `null` means 10 seconds. QUIC ignores ICMP errors, so an unreachable server is only noticed this way. + /// + /// iOS only. Cronet has no setting; bound calls with deadlines instead. + final Duration? connectTimeout; + /// Fails each of this client's calls once it has received nothing from the server for this long. `null` or /// [Duration.zero] means none. Each call has its own timer in the platform client, so it also works on the HTTP/2 /// fallback, where nothing else notices a dead connection. @@ -47,13 +53,13 @@ final class NativeHttpConfig { /// - **What resets it:** anything the call receives. It runs from when the call starts, so it also bounds the wait /// for the response headers, and a unary call the server holds longer than this fails. A server stream that may go /// quiet needs a longer timeout, or periodic messages. - /// - **iOS:** `URLRequest.timeoutInterval`. URLSession fails the task with `NSURLErrorTimedOut` (-1001). + /// - **iOS:** a timer in the bridge, which fails the call with `NSURLErrorTimedOut` (-1001). /// - **Android:** a timer in the bridge, which fails the call with `net::ERR_TIMED_OUT` (-7). /// - **The failure:** a `ConnectException` with code `unavailable`, whose cause is a [NativeHttpException] with /// that `platformCode`. /// - **The connection:** if nothing has arrived from the call's origin, on any call, since the call last received - /// anything, the connection is taken to be dead. The client moves new calls to a fresh `URLSession` or Cronet - /// engine, so they dial a new connection, and lets the calls already on the old one finish there. + /// anything, the connection is taken to be dead. The client moves new calls to a new QUIC connection (iOS) or Cronet + /// engine (Android), and lets the calls already on the old one finish there. final Duration? readIdleTimeout; /// How much shorter a deadline the server gets than the call's own. connect-dart sends a call's deadline in @@ -68,7 +74,8 @@ final class NativeHttpConfig { /// Whether a call that hits its deadline on the client moves new calls off its connection, as a [readIdleTimeout] /// does: if nothing has arrived from the call's origin, on any call, since the call last received anything, new - /// calls go to a fresh `URLSession` or Cronet engine. Calls already on the old connection are not canceled. + /// calls go to a new QUIC connection (iOS) or Cronet engine (Android). Calls already on the old connection are not + /// canceled. /// /// Use it with [deadlineStep]. Without one, the server enforces the same deadline as the client, but its clock /// starts later, so on a healthy connection the client's deadline usually fires before the server's diff --git a/lib/src/nio_http3/nio_http3_client.dart b/lib/src/nio_http3/nio_http3_client.dart new file mode 100644 index 0000000..e9f8f21 --- /dev/null +++ b/lib/src/nio_http3/nio_http3_client.dart @@ -0,0 +1,52 @@ +import 'package:flutter/services.dart'; + +import '../channel/channel_http_client.dart'; +import '../native_http_config.dart'; +import '../native_http_exception.dart'; +import 'ns_url_error.dart'; + +/// Must match `ios/.../ConnectNativeHttpPlugin.swift`. +const nioHttp3MethodChannel = MethodChannel('connect_native_http/http3'); +const nioHttp3EventChannel = EventChannel('connect_native_http/http3/events'); + +const nioHttp3Bridge = PlatformBridge( + name: 'http3', + methods: nioHttp3MethodChannel, + events: nioHttp3EventChannel, + failure: _nioHttp3Failure, + supportsDatagrams: true, +); + +NativeHttpException _nioHttp3Failure(Map event) { + final domain = event['domain']! as String; + final code = event['code']! as int; + return NativeHttpException( + classifyNsUrlError(domain, code), + '${event['message']} ($domain $code)', + platformCode: code, + ); +} + +/// A connect-dart [HttpClient] on swift-nio-http3, driven by the Swift plugin in `ios/`. Every call goes over HTTP/3. +final class NioHttp3Client extends ChannelHttpClient { + NioHttp3Client._(int engineId, NativeHttpConfig config) : super(nioHttp3Bridge, engineId, config); + + static Future create(NativeHttpConfig config) async { + final idle = config.quicIdleTimeout; + if (idle != null && idle <= Duration.zero) { + throw ArgumentError.value(idle, 'quicIdleTimeout', 'must be positive'); + } + final connect = config.connectTimeout; + if (connect != null && connect <= Duration.zero) { + throw ArgumentError.value(connect, 'connectTimeout', 'must be positive'); + } + final engineId = await ChannelHttpClient.createEngine(nioHttp3Bridge, config, { + 'http3Origins': [ + for (final origin in config.http3Origins) [origin.host, origin.port], + ], + 'quicIdleTimeoutMs': idle == null ? null : (idle.inMicroseconds / 1000).ceil(), + 'connectTimeoutMs': connect == null ? null : (connect.inMicroseconds / 1000).ceil(), + }); + return NioHttp3Client._(engineId, config); + } +} diff --git a/lib/src/url_session/ns_url_error.dart b/lib/src/nio_http3/ns_url_error.dart similarity index 100% rename from lib/src/url_session/ns_url_error.dart rename to lib/src/nio_http3/ns_url_error.dart diff --git a/lib/src/url_session/response_headers.dart b/lib/src/url_session/response_headers.dart deleted file mode 100644 index 8e3fcdb..0000000 --- a/lib/src/url_session/response_headers.dart +++ /dev/null @@ -1,21 +0,0 @@ -import 'package:connectrpc/connect.dart'; - -/// Content codings URLSession decodes itself. It advertises them on every request and decodes the response body -/// before handing it over, but leaves `Content-Encoding` in place, which connect-dart would try to decode again. -const _decodedEncodings = {'gzip', 'deflate', 'br'}; - -/// The response headers connect-dart should see, without the encoding headers of a body URLSession already decoded. -Headers responseHeaders(Map allHeaderFields) { - String? field(String name) => - allHeaderFields.entries.where((e) => e.key.toLowerCase() == name).map((e) => e.value).firstOrNull; - final decoded = _decodedEncodings.contains(field('content-encoding')?.trim().toLowerCase()); - final headers = Headers(); - allHeaderFields.forEach((name, value) { - final lower = name.toLowerCase(); - if (decoded && (lower == 'content-encoding' || lower == 'content-length')) { - return; - } - headers.add(lower, value); - }); - return headers; -} diff --git a/lib/src/url_session/url_session_http_client.dart b/lib/src/url_session/url_session_http_client.dart deleted file mode 100644 index 1817181..0000000 --- a/lib/src/url_session/url_session_http_client.dart +++ /dev/null @@ -1,50 +0,0 @@ -import 'package:connectrpc/connect.dart'; -import 'package:flutter/services.dart'; - -import '../channel/channel_http_client.dart'; -import '../native_http_config.dart'; -import '../native_http_exception.dart'; -import 'ns_url_error.dart'; -import 'response_headers.dart'; - -/// Must match `ios/.../ConnectNativeHttpPlugin.swift`. -const urlSessionMethodChannel = MethodChannel('connect_native_http/urlsession'); -const urlSessionEventChannel = EventChannel('connect_native_http/urlsession/events'); - -const urlSessionBridge = PlatformBridge( - name: 'urlsession', - methods: urlSessionMethodChannel, - events: urlSessionEventChannel, - failure: _urlSessionFailure, - responseHeaders: _responseHeaders, - // Over HTTP/3, URLSession does not complete a task while its request body is open, even after the server has - // finished the response and stopped reading. - endsStreamsItself: false, -); - -NativeHttpException _urlSessionFailure(Map event) { - final domain = event['domain']! as String; - final code = event['code']! as int; - return NativeHttpException( - classifyNsUrlError(domain, code), - '${event['message']} ($domain $code)', - platformCode: code, - ); -} - -Headers _responseHeaders(List<(String, String)> pairs) => - responseHeaders({for (final (name, value) in pairs) name: value}); - -/// A connect-dart [HttpClient] on one URLSession, driven by the Swift plugin in `ios/`. -final class UrlSessionHttpClient extends ChannelHttpClient { - UrlSessionHttpClient._(int engineId, NativeHttpConfig config) : super(urlSessionBridge, engineId, config); - - static Future create(NativeHttpConfig config) async { - final engineId = await ChannelHttpClient.createEngine(urlSessionBridge, config, { - 'http3Origins': [ - for (final origin in config.http3Origins) [origin.host, origin.port], - ], - }); - return UrlSessionHttpClient._(engineId, config); - } -} diff --git a/pubspec.yaml b/pubspec.yaml index f409c7b..2344d78 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,8 +1,8 @@ name: connect_native_http description: >- - connect-dart HttpClients on the platform HTTP stacks, URLSession on iOS and Cronet on Android, so Connect calls - can use HTTP/3 with full-duplex streams. -version: 0.1.0 + connect-dart HttpClients over HTTP/3 with full-duplex streams, swift-nio-http3 on iOS and Cronet on Android, plus + HTTP/3 datagram sessions on iOS. +version: 0.2.0 publish_to: none environment: diff --git a/test/connect_end_stream_test.dart b/test/connect_end_stream_test.dart deleted file mode 100644 index 8a7c082..0000000 --- a/test/connect_end_stream_test.dart +++ /dev/null @@ -1,75 +0,0 @@ -import 'dart:typed_data'; - -import 'package:connect_native_http/src/channel/connect_end_stream.dart'; -import 'package:flutter_test/flutter_test.dart'; - -Uint8List envelope(int flags, List payload) { - final header = ByteData(5) - ..setUint8(0, flags) - ..setUint32(1, payload.length); - return Uint8List.fromList([...header.buffer.asUint8List(), ...payload]); -} - -void main() { - test('recognizes Connect streaming content types only', () { - expect(isConnectStreamingContentType('application/connect+proto'), isTrue); - expect(isConnectStreamingContentType('Application/Connect+JSON; charset=utf-8'), isTrue); - expect(isConnectStreamingContentType('application/proto'), isFalse); - expect(isConnectStreamingContentType('application/grpc'), isFalse); - expect(isConnectStreamingContentType(null), isFalse); - }); - - test('data messages do not end the stream', () { - final detector = ConnectEndStreamDetector(); - final chunk = Uint8List.fromList([ - ...envelope(0, [1, 2, 3]), - ...envelope(0x01, [4]), - ]); - expect(detector.add(chunk), chunk.length); - expect(detector.done, isFalse); - }); - - test('finds the end-stream message split across chunks', () { - final detector = ConnectEndStreamDetector(); - final bytes = [ - ...envelope(0, [9, 9]), - ...envelope(0x02, '{}'.codeUnits), - ]; - for (final b in bytes.take(bytes.length - 1)) { - expect(detector.add(Uint8List.fromList([b])), 1); - expect(detector.done, isFalse); - } - expect(detector.add(Uint8List.fromList([bytes.last])), 1); - expect(detector.done, isTrue); - }); - - test('a compressed end-stream message ends the stream', () { - final detector = ConnectEndStreamDetector()..add(envelope(0x03, [7, 7, 7])); - expect(detector.done, isTrue); - }); - - test('an empty end-stream message ends the stream', () { - final detector = ConnectEndStreamDetector()..add(envelope(0x02, [])); - expect(detector.done, isTrue); - }); - - test('reports only the bytes up to the end of the end-stream message', () { - final detector = ConnectEndStreamDetector(); - final end = envelope(0x02, '{}'.codeUnits); - final chunk = Uint8List.fromList([ - ...envelope(0, [1]), - ...end, - 0xff, - 0xff, - ]); - expect(detector.add(chunk), chunk.length - 2); - expect(detector.done, isTrue); - }); - - test('payload bytes that look like an end-stream header do not end the stream', () { - final detector = ConnectEndStreamDetector(); - final payload = envelope(0x02, []); - expect(detector.add(envelope(0, payload)), 5 + payload.length); - expect(detector.done, isFalse); - }); -} diff --git a/test/error_classification_test.dart b/test/error_classification_test.dart index 116be87..73b6098 100644 --- a/test/error_classification_test.dart +++ b/test/error_classification_test.dart @@ -1,6 +1,6 @@ import 'package:connect_native_http/connect_native_http.dart'; import 'package:connect_native_http/src/cronet/cronet_error.dart'; -import 'package:connect_native_http/src/url_session/ns_url_error.dart'; +import 'package:connect_native_http/src/nio_http3/ns_url_error.dart'; import 'package:flutter_test/flutter_test.dart'; void main() { diff --git a/test/nio_http3_client_test.dart b/test/nio_http3_client_test.dart new file mode 100644 index 0000000..c56209d --- /dev/null +++ b/test/nio_http3_client_test.dart @@ -0,0 +1,173 @@ +import 'package:connect_native_http/connect_native_http.dart'; +import 'package:connect_native_http/src/cronet/cronet_http_client.dart'; +import 'package:connect_native_http/src/nio_http3/nio_http3_client.dart'; +import 'package:connectrpc/connect.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; + +/// Stands in for the iOS plugin (HTTP3Bridge): records method calls and lets a test emit the plugin's events. +class FakeHttp3Plugin { + FakeHttp3Plugin() { + _messenger.setMockMethodCallHandler(nioHttp3MethodChannel, (call) async { + calls.add(call); + if (refusing.contains(call.method)) { + throw PlatformException(code: 'datagramFailed', message: '${call.method} refused'); + } + return call.method == 'createEngine' ? 3 : null; + }); + _messenger.setMockMethodCallHandler(MethodChannel(nioHttp3EventChannel.name), (call) async => null); + } + + final calls = []; + final refusing = {}; + + TestDefaultBinaryMessenger get _messenger => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger; + + List callsTo(String method) => calls.where((c) => c.method == method).toList(); + + int get lastSessionId => callsTo('openDatagrams').last.arguments['callId'] as int; + + Future emit(Map event) async { + await _messenger.handlePlatformMessage( + nioHttp3EventChannel.name, + const StandardMethodCodec().encodeSuccessEnvelope(event), + (_) {}, + ); + } + + Future headers(int callId, {int status = 200}) => emit({ + 'callId': callId, + 'type': 'headers', + 'status': status, + 'protocol': 'h3', + 'headers': [ + ['x-session', 'yes'], + ], + }); + + Future datagram(int callId, List bytes) => + emit({'callId': callId, 'type': 'datagram', 'data': Uint8List.fromList(bytes)}); +} + +/// Lets queued microtasks and platform-channel replies run. +Future settle() => Future.delayed(Duration.zero); + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + late FakeHttp3Plugin plugin; + late NioHttp3Client client; + final url = Uri.parse('https://example.test/datagrams/echo'); + + setUp(() async { + plugin = FakeHttp3Plugin(); + client = await NioHttp3Client.create(const NativeHttpConfig(quicIdleTimeout: Duration(milliseconds: 1500))); + }); + + /// Opens a session and lets the fake server accept it with [status]. + Future open({int status = 200}) async { + final session = client.openDatagramSession(url, protocol: 'datagram-echo', headers: {'authorization': 'x'}); + await settle(); + await plugin.headers(plugin.lastSessionId, status: status); + return session; + } + + test('passes the QUIC idle timeout in milliseconds', () { + expect(plugin.callsTo('createEngine').single.arguments['quicIdleTimeoutMs'], 1500); + }); + + test('opens an Extended CONNECT with the protocol and headers, and completes once the server accepts it', () async { + final session = await open(); + final args = plugin.callsTo('openDatagrams').single.arguments as Map; + expect(args['engineId'], 3); + expect(args['url'], url.toString()); + expect(args['protocol'], 'datagram-echo'); + expect(args['headers'], [ + ['authorization', 'x'], + ]); + expect(session.status, 200); + expect(session.headers['x-session'], 'yes'); + }); + + test('delivers datagrams from the server in order, and sends datagrams to the plugin', () async { + final session = await open(); + final received = >[]; + session.datagrams.listen(received.add); + await plugin.datagram(plugin.lastSessionId, [1]); + await plugin.datagram(plugin.lastSessionId, [2, 3]); + await settle(); + expect(received, [ + [1], + [2, 3], + ]); + + await session.send(Uint8List.fromList([9])); + final sent = plugin.callsTo('sendDatagram').single.arguments as Map; + expect(sent['callId'], plugin.lastSessionId); + expect(sent['data'], [9]); + }); + + test('close finishes the request stream, and the session ends with the server', () async { + final session = await open(); + final datagramsDone = session.datagrams.toList(); + await session.close(); + expect(plugin.callsTo('end').single.arguments['callId'], plugin.lastSessionId); + + await plugin.emit({'callId': plugin.lastSessionId, 'type': 'done'}); + await session.done; + expect(await datagramsDone, isEmpty); + await expectLater(session.send(Uint8List(1)), throwsA(isA())); + }); + + test('a failed session fails done and the datagram stream', () async { + final session = await open(); + final datagramsDone = session.datagrams.toList(); + await plugin.emit({ + 'callId': plugin.lastSessionId, + 'type': 'failed', + 'domain': 'NSURLErrorDomain', + 'code': -1005, + 'message': 'connection lost', + }); + await expectLater(session.done, throwsA(isA().having((e) => e.code, 'code', Code.unavailable))); + await expectLater(datagramsDone, throwsA(isA())); + }); + + test('a session the server rejects throws DatagramSessionRejected and is canceled', () async { + await expectLater( + open(status: 404), + throwsA(isA().having((e) => e.status, 'status', 404)), + ); + expect(plugin.callsTo('cancel').single.arguments['callId'], plugin.lastSessionId); + }); + + test('a session that never gets an answer fails with the connection failure', () async { + final session = client.openDatagramSession(url, protocol: 'datagram-echo'); + await settle(); + await plugin.emit({ + 'callId': plugin.lastSessionId, + 'type': 'failed', + 'domain': 'ConnectNativeHttp', + 'code': -2, + 'message': 'the server does not support HTTP datagrams', + }); + await expectLater( + session, + throwsA(isA().having((e) => e.cause, 'cause', isA())), + ); + }); + + test('a datagram the plugin refuses throws a NativeHttpException', () async { + final session = await open(); + plugin.refusing.add('sendDatagram'); + await expectLater(session.send(Uint8List(70000)), throwsA(isA())); + }); + + test('Cronet has no datagram sessions', () async { + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.setMockMethodCallHandler( + cronetMethodChannel, + (call) async => 1, + ); + final cronet = await CronetHttpClient.create(const NativeHttpConfig()); + expect(() => cronet.openDatagramSession(url, protocol: 'datagram-echo'), throwsUnsupportedError); + }); +} diff --git a/test/url_session_headers_test.dart b/test/url_session_headers_test.dart deleted file mode 100644 index 91e719d..0000000 --- a/test/url_session_headers_test.dart +++ /dev/null @@ -1,29 +0,0 @@ -import 'package:connect_native_http/src/url_session/response_headers.dart'; -import 'package:flutter_test/flutter_test.dart'; - -void main() { - group('responseHeaders', () { - test('drops the encoding headers of a body URLSession already decoded', () { - final headers = responseHeaders({ - 'Content-Type': 'application/proto', - 'Content-Encoding': 'gzip', - 'Content-Length': '42', - 'X-Proto': 'HTTP/3.0', - }); - expect(headers.get('content-encoding'), isNull); - expect(headers.get('content-length'), isNull); - expect(headers.get('content-type'), ['application/proto']); - expect(headers.get('x-proto'), ['HTTP/3.0']); - }); - - test('keeps an encoding URLSession does not decode, for connect-dart to handle or reject', () { - final headers = responseHeaders({'Content-Encoding': 'zstd', 'Content-Length': '42'}); - expect(headers.get('content-encoding'), ['zstd']); - expect(headers.get('content-length'), ['42']); - }); - - test('keeps Content-Length of an unencoded body', () { - expect(responseHeaders({'Content-Length': '7'}).get('content-length'), ['7']); - }); - }); -} diff --git a/test_server/datagrams.go b/test_server/datagrams.go new file mode 100644 index 0000000..7e3066f --- /dev/null +++ b/test_server/datagrams.go @@ -0,0 +1,63 @@ +package main + +import ( + "context" + "errors" + "io" + "log" + "net/http" + + "github.com/quic-go/quic-go/http3" +) + +// datagramEchoProtocol is the `:protocol` of the Extended CONNECT (RFC 9220) request that opens a datagram echo +// session. +const datagramEchoProtocol = "datagram-echo" + +// datagramEcho serves Extended CONNECT requests with `:protocol` datagram-echo over HTTP/3: it accepts the request +// with 200 and sends back every HTTP datagram (RFC 9297) the client sends on the request stream, unchanged. The +// session ends when the client finishes or resets the request stream. +// +// A datagram whose payload is "close" ends the session from the server's side instead, by closing the stream. +func datagramEcho(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodConnect || r.Proto != datagramEchoProtocol { + http.Error(w, "want Extended CONNECT with :protocol "+datagramEchoProtocol, http.StatusBadRequest) + return + } + streamer, ok := w.(http3.HTTPStreamer) + if !ok { + http.Error(w, "HTTP/3 only", http.StatusHTTPVersionNotSupported) + return + } + w.WriteHeader(http.StatusOK) + stream, err := streamer.HTTPStream() + if err != nil { + log.Printf("datagram echo: take over stream: %v", err) + return + } + defer stream.Close() + + ctx, cancel := context.WithCancel(r.Context()) + defer cancel() + // The client ends the session by finishing or resetting its side of the stream. + go func() { + defer cancel() + _, _ = io.Copy(io.Discard, stream) + }() + for { + payload, err := stream.ReceiveDatagram(ctx) + if err != nil { + if !errors.Is(err, context.Canceled) { + log.Printf("datagram echo: receive: %v", err) + } + return + } + if string(payload) == "close" { + return + } + if err := stream.SendDatagram(payload); err != nil { + log.Printf("datagram echo: send: %v", err) + return + } + } +} diff --git a/test_server/datagrams_test.go b/test_server/datagrams_test.go new file mode 100644 index 0000000..f844bb9 --- /dev/null +++ b/test_server/datagrams_test.go @@ -0,0 +1,99 @@ +package main + +import ( + "context" + "crypto/tls" + "crypto/x509" + "net" + "net/http" + "net/url" + "os" + "path/filepath" + "testing" + "time" + + "github.com/quic-go/quic-go" + "github.com/quic-go/quic-go/http3" +) + +// An Extended CONNECT with :protocol datagram-echo gets 200, and each HTTP datagram comes back unchanged. +func TestDatagramEcho(t *testing.T) { + dir := t.TempDir() + cert, err := writeCertificates(dir, []string{"localhost", "127.0.0.1"}) + if err != nil { + t.Fatal(err) + } + caDER, err := os.ReadFile(filepath.Join(dir, "ca.der")) + if err != nil { + t.Fatal(err) + } + ca, err := x509.ParseCertificate(caDER) + if err != nil { + t.Fatal(err) + } + roots := x509.NewCertPool() + roots.AddCert(ca) + + udp, err := net.ListenPacket("udp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + server := newHTTP3Server(newElizaMux(), newTLSConfig(cert), quicConfig(30*time.Second, 5*time.Second)) + go func() { _ = server.Serve(udp) }() + t.Cleanup(func() { _ = server.Close() }) + + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + tlsConfig := &tls.Config{RootCAs: roots, ServerName: "localhost", NextProtos: []string{http3.NextProtoH3}} + conn, err := quic.DialAddr(ctx, udp.LocalAddr().String(), tlsConfig, &quic.Config{EnableDatagrams: true}) + if err != nil { + t.Fatal(err) + } + transport := &http3.Transport{EnableDatagrams: true} + client := transport.NewClientConn(conn) + select { + case <-client.ReceivedSettings(): + case <-ctx.Done(): + t.Fatal("no SETTINGS from the server") + } + if settings := client.Settings(); !settings.EnableDatagrams || !settings.EnableExtendedConnect { + t.Fatalf("server SETTINGS %+v: want datagrams and Extended CONNECT", settings) + } + + stream, err := client.OpenRequestStream(ctx) + if err != nil { + t.Fatal(err) + } + req := &http.Request{ + Method: http.MethodConnect, + Proto: datagramEchoProtocol, + Host: "localhost", + URL: &url.URL{Scheme: "https", Host: "localhost", Path: "/datagrams/echo"}, + Header: http.Header{}, + } + if err := stream.SendRequestHeader(req); err != nil { + t.Fatal(err) + } + res, err := stream.ReadResponse() + if err != nil { + t.Fatal(err) + } + if res.StatusCode != http.StatusOK { + t.Fatalf("status %d, want 200", res.StatusCode) + } + for _, payload := range []string{"one", "two"} { + if err := stream.SendDatagram([]byte(payload)); err != nil { + t.Fatal(err) + } + got, err := stream.ReceiveDatagram(ctx) + if err != nil { + t.Fatal(err) + } + if string(got) != payload { + t.Fatalf("echo %q, want %q", got, payload) + } + } + if err := stream.Close(); err != nil { + t.Fatal(err) + } +} diff --git a/test_server/main.go b/test_server/main.go index d23a3fe..a85af86 100644 --- a/test_server/main.go +++ b/test_server/main.go @@ -128,6 +128,8 @@ func newHTTP3Server(handler http.Handler, tlsConfig *tls.Config, quicConfig *qui Handler: handler, TLSConfig: http3.ConfigureTLSConfig(tlsConfig.Clone()), QUICConfig: quicConfig, + // HTTP datagrams (RFC 9297), for datagramEcho. quic-go's server always offers Extended CONNECT. + EnableDatagrams: true, } } @@ -136,6 +138,7 @@ func newElizaMux() *http.ServeMux { elizav1connect.RegisterElizaServiceHandler(server, elizaServer{}) mux := http.NewServeMux() connecthttp.Mount(mux, server) + mux.HandleFunc("/datagrams/echo", datagramEcho) // A 307 makes a client send the same request body again, to the path after /redirect. The body is read first: // answering without it resets the request stream, and the client fails on that instead of the redirect. mux.HandleFunc("/redirect/", func(w http.ResponseWriter, r *http.Request) {