feat: add cross-platform HTTP/1.1 parser and local proxy server for iOS and Android

[jkmassel]

What?

Adds a hardened, RFC-conformant HTTP/1.1 request parser and local proxy server for both iOS (Swift) and Android (Kotlin), with shared cross-platform test fixtures to guarantee behavioral parity.

Why?

GutenbergKit's native integration embeds a web editor that communicates with native networking through an in-process HTTP server. Because the server is exposed to JavaScript running in the WebView, the parser must be hardened against malformed and adversarial input per RFC 7230/9110/9112 — a lenient parser could enable request smuggling, header injection, or denial-of-service via resource exhaustion.

How?

Swift (iOS)

• GutenbergKitHTTP module — Incremental, stateful parser (HTTPRequestParser) that buffers to a temporary file on disk so memory stays flat regardless of body size. Strict RFC conformance: rejects obs-fold, whitespace before colon, conflicting Content-Length, Transfer-Encoding, invalid UTF-8 (round-trip validated), lone surrogates, overlong encodings.
• HTTPServer — Local HTTP/1.1 server on Network.framework with async handler API, connection limits, read timeouts, and constant-time bearer token authentication.
• Multipart parsing — RFC 7578 multipart/form-data support with lazy body references (file slices, not copies).
• RequestBody — Abstracts over in-memory and file-backed storage with InputStream and async data access.

Kotlin (Android)

• Pure-Kotlin HTTP parser (org.wordpress.gutenberg.http) — Feature-identical port of the Swift parser with no native dependencies. Includes HeaderValue, HTTPRequestSerializer, HTTPRequestParser (with disk-backed buffering via Buffer/TempFileOwner), ParsedHTTPRequest, MultipartPart, and RequestBody.
• HttpServer — Local HTTP/1.1 server with connection limits, read timeouts, pure-Kotlin response serialization, and proper 400 responses on premature connection close.

Shared cross-platform test fixtures

• 163 JSON test fixtures in test-fixtures/http/ covering header value extraction (20 cases), request parsing (58 basic + 42 error + 4 incremental), and multipart parsing (32 field-based + 7 error).
• 8 dedicated UTF-8 edge cases — overlong encodings, lone surrogates, truncated sequences, code points above U+10FFFF.
• 2 whitespace-before-colon cases — space and tab before colon, returning the specific whitespaceBeforeColon error (request smuggling vector per RFC 7230 §3.2.4).
• Both platforms load the same fixture files, guaranteeing identical parse behavior.

Key design decisions

• 64-bit Content-Length on both platforms (Swift Int64, Kotlin Long) with a 4 GB default max body size.
• UTF-8 round-trip validation on both platforms to reject silently-accepted malformed sequences.
• Disk-backed buffering with configurable inMemoryBodyThreshold (512 KB default) — bodies below threshold stay in memory, larger ones reference the temp file directly as a slice.
• Multipart part bodies are lazy file-slice references for file-backed sources, avoiding copies during parsing.

Testing Instructions

Automated (CI runs these on every push)

1. swift test — runs 820+ tests including 163 fixture-based cross-platform tests
2. cd android && ./gradlew :Gutenberg:test — runs all Android unit tests including fixture tests

On-device (manual)

1. iOS: Open ios/Demo-iOS/Gutenberg.xcodeproj in Xcode, run on a device, navigate to the Media Proxy Server screen — it prints the server URL
2. Android: Build and install the demo app, open the Media Proxy Server activity — it prints the server URL
3. Send adversarial requests to verify hardening (all should return appropriate 4xx errors):

   # Missing Host header → 400
   printf "GET / HTTP/1.1\r\n\r\n" | nc -w 3 <device-ip> <port>
   
   # Transfer-Encoding (rejected) → 400
   printf "GET / HTTP/1.1\r\nHost: localhost\r\nTransfer-Encoding: chunked\r\n\r\n" | nc -w 3 <device-ip> <port>
   
   # Oversized headers → 431
   printf "GET / HTTP/1.1\r\nHost: localhost\r\nX-Long: $(python3 -c 'print("X"*70000)')\r\n\r\n" | nc -w 3 <device-ip> <port>
   
   # Conflicting Content-Length → 400
   printf "POST / HTTP/1.1\r\nHost: localhost\r\nContent-Length: 5\r\nContent-Length: 10\r\n\r\nhello" | nc -w 3 <device-ip> <port>
   
   # Whitespace before colon (smuggling vector) → 400
   printf "GET / HTTP/1.1\r\nHost: localhost\r\nContent-Length : 0\r\n\r\n" | nc -w 3 <device-ip> <port>
   
   # Premature connection close → 400
   printf "\r\n\r\n" | nc -w 3 <device-ip> <port>

4. Instrumented tests: cd android && ./gradlew :Gutenberg:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=org.wordpress.gutenberg.http.InstrumentedFixtureTests runs all 163 fixture cases on a connected device

🤖 Generated with Claude Code

[dcalhoun]

@jkmassel the testing instructions succeeded for me.

I also had Claude swiftly rebase #357 atop this work and update it to use the HTTP server library in this work. Good news is that it seems to work. The result of the work is in the feat/leverage-host-media-processing-stacked branch (here is the current diff).

I did encounter a couple of issues that I noted in inline comments below. I worked around them in the feat/leverage-host-media-processing-stacked branch, but we might address them in the library instead. WDYT?

[dcalhoun]

When requiresAuthentication is enabled, auth is checked on every request including OPTIONS. In practice this makes the server incompatible with any browser client using fetch(): browsers send a CORS preflight OPTIONS before the actual request, and the Fetch spec forbids auth headers on preflight — so it always gets rejected before the real request can be made.

Since OPTIONS responses contain no sensitive information (just allowed methods/headers), there's no security value in authenticating them. A simple exemption here would make the built-in auth usable from browser contexts without requiring callers to opt out entirely:

if requiresAuthentication && partial.method.uppercased() != "OPTIONS" {
    guard authenticate(partial, token: token) else {
        throw HTTPServerError.authenticationFailed
    }
}

Without this, callers who need to support browser clients must set requiresAuthentication: false and reimplement auth in their handler, losing the library's constant-time comparison and other protections.

Note: This applies to the Android implementation as well.

[jkmassel]

Ah yep, this is a sensible change. c68a223 skips auth for OPTIONS

[dcalhoun]

The built-in auth uses Proxy-Authorization, which is a forbidden request header in the Fetch spec. WebKit's fetch() (and all standards-compliant browsers) silently strip it before sending — meaning any browser client using the built-in auth will always get a 407, with no error surfaced to the caller.

The RFC 9110 §11.7.1 rationale (keeping Authorization free for upstream credentials) is sound, but Proxy-Authorization is the wrong vehicle when the client is a browser. A custom header like X-GBKit-Token avoids the forbidden-header restriction while preserving the same separation of concerns.

Proposal: change the built-in auth to use a custom header (e.g. X-GBKit-Token) so it works correctly from browser contexts out of the box.

Note: This applies to the Android implementation as well.

[jkmassel]

TIL about forbidden request headers. The reasoning seems sound though! 0f83848 adds the Relay-Authorization header (using X- as a prefix is deprecated).