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]

@jkmassel the latest changes worked for the media upload implementation. 🎉

Noting two things:

First, it appears your two commits were pushed to a new pr-367 branch outside of this PR. Was that intentional?

Second, I'll share a few additional thoughts on the new OPTIONS change...

The OPTIONS exemption from auth is necessary for CORS preflight compatibility, but it's only half the solution. A successful CORS preflight also needs avalid response: 204 + Access-Control-Allow-* headers. The library handles the first requirement and leaves the second to the caller.

This creates a hidden obligation. Any caller serving a browser client has to independently discover that they need to handle OPTIONS in their handler, know the correct CORS headers to return, and remember to do so. A handler written naturally — routing on method/path, returning 404 for anything else — will silently break CORS preflight. That's exactly what happened when integrating this.

CORS policy (allowed origins, methods, headers) is application-level and not something the library can own without configuration that arguably falls outside its scope. Instead, should we clearly document this obligation in OPTIONS exception? Possibly noting that callers serving browser clients must handle OPTIONS in their handler and return the appropriate CORS headers.

[jkmassel]

a184a2c adds some documentation about the "handle your own CORS" requirement. I thought about adding a helper that makes it a one-liner for non-relay purposes, but I think that would be better in some future PR if it's really needed.