chore: import upstream snapshot with attribution

Sources/CloudHypervisor/HTTPOverUDS.swift

@@ -0,0 +1,202 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the Containerization project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import AsyncHTTPClient
+import Foundation
+import Logging
+import NIOConcurrencyHelpers
+import NIOCore
+import NIOHTTP1
+
+// MARK: - HTTPResponse
+
+/// An HTTP response received from Cloud Hypervisor's REST API.
+struct HTTPResponse: Sendable {
+    let status: HTTPResponseStatus
+    let headers: HTTPHeaders
+    let body: Data
+}
+
+// MARK: - HTTPOverUDSClient
+
+/// A minimal HTTP/1.1 client that speaks over a Unix Domain Socket. Backed
+/// by `AsyncHTTPClient` so connection lifecycle, timeout handling, and the
+/// head/body/end write race we used to manage manually all live in the
+/// library rather than in this file.
+///
+/// AHC selects UDS via the `http+unix://` URL scheme (the supplied
+/// `URL(httpURLWithSocketPath:uri:)` initializer does the percent-encoding).
+/// Each `HTTPOverUDSClient` owns a fresh `HTTPClient` configured with
+/// `eventLoopGroupProvider: .shared(group)` so the underlying NIO group is
+/// the caller's to shut down — `httpClient.shutdown` only releases the
+/// client's own state.
+final class HTTPOverUDSClient: Sendable {
+    private let socketPath: String
+    private let httpClient: HTTPClient
+    private let logger: Logger
+    private let requestTimeout: TimeAmount
+    // One-shot flag tracking whether shutdown has been initiated, so
+    // explicit `shutdown()` is idempotent and `deinit` skips its fallback
+    // when an explicit shutdown already drained the HTTPClient.
+    private let didShutdown: NIOLockedValueBox<Bool>
+
+    init(
+        socketPath: String,
+        group: any EventLoopGroup,
+        logger: Logger,
+        requestTimeout: TimeAmount = .seconds(30)
+    ) {
+        self.socketPath = socketPath
+        self.httpClient = HTTPClient(
+            eventLoopGroupProvider: .shared(group),
+            configuration: .init()
+        )
+        self.logger = logger
+        self.requestTimeout = requestTimeout
+        self.didShutdown = NIOLockedValueBox(false)
+    }
+
+    /// Drain the underlying HTTPClient and wait for in-flight I/O to
+    /// finish. Idempotent — safe to call multiple times.
+    ///
+    /// MUST be called before the shared event-loop group is torn down.
+    /// AsyncHTTPClient leaves deferred connection-cleanup work parked on
+    /// the group's event loops after a response returns; if the group is
+    /// shut down first, that deferred work fails to schedule and SwiftNIO
+    /// prints "Cannot schedule tasks on an EventLoop that has already
+    /// shut down" (and will upgrade to a forced crash in future NIO
+    /// releases).
+    func shutdown() async throws {
+        let already = didShutdown.withLockedValue { state -> Bool in
+            if state { return true }
+            state = true
+            return false
+        }
+        if already { return }
+        try await httpClient.shutdown()
+    }
+
+    /// Send an HTTP request and return the response.
+    ///
+    /// Translates AHC errors → ``CloudHypervisor/Error/transport(_:)`` so
+    /// callers see a uniform error type regardless of failure mode.
+    func send(
+        method: HTTPMethod,
+        uri: String,
+        body: Data?,
+        headers: HTTPHeaders = [:]
+    ) async throws -> HTTPResponse {
+        // AHC handles the percent-encoding. nil only on a path that can't
+        // be encoded — surface it the same way the public Client init does.
+        guard let url = URL(httpURLWithSocketPath: socketPath, uri: uri) else {
+            throw CloudHypervisor.Error.invalidSocketPath(socketPath)
+        }
+
+        var request = HTTPClientRequest(url: url.absoluteString)
+        request.method = method
+
+        // Preserve all caller-supplied headers verbatim.
+        for (name, value) in headers {
+            request.headers.replaceOrAdd(name: name, value: value)
+        }
+
+        // `Connection: close` is preserved from the previous transport. CH
+        // accepts both close and keep-alive, but close is the safer default
+        // until we have explicit smoke coverage of long-lived per-VM
+        // keep-alive behavior. Each request goes to a different per-VM UDS
+        // anyway so there's nothing to pool.
+        request.headers.replaceOrAdd(name: "Connection", value: "close")
+
+        // Body framing. CH's HTTP parser rejects body-less PUTs unless the
+        // request carries `Content-Length: 0` instead of falling back to
+        // chunked transfer encoding.
+        //
+        // How AHC actually frames the request is subtle:
+        // `RequestValidation.setTransportFraming` strips any manually-set
+        // `Content-Length` and re-derives framing from the body's known
+        // length. Assigning `.bytes(ByteBuffer())` (rather than leaving
+        // body nil) sets `bodyLength == .known(0)`, which AHC then frames
+        // as `Content-Length: 0` for PUT/POST per RFC 7230 §3.3.2. Leaving
+        // body nil would surface as `bodyLength == .unknown`, and AHC may
+        // emit chunked framing or no framing at all, which CH rejects.
+        // The explicit `Content-Length: 0` header set below is documentation
+        // of intent — AHC removes it before deriving framing — but the
+        // wire shape is determined by the empty body assignment.
+        //
+        // Regression test: ClientTests.bodylessPUTSendsContentLengthZero.
+        if let body, !body.isEmpty {
+            if request.headers["Content-Type"].isEmpty {
+                request.headers.add(name: "Content-Type", value: "application/json")
+            }
+            request.body = .bytes(ByteBuffer(bytes: body))
+        } else {
+            request.headers.replaceOrAdd(name: "Content-Length", value: "0")
+            request.body = .bytes(ByteBuffer())
+        }
+
+        let deadline = NIODeadline.now() + requestTimeout
+        logger.debug("HTTPOverUDSClient: \(method) \(uri) → \(socketPath)")
+
+        do {
+            let response = try await httpClient.execute(
+                request,
+                deadline: deadline,
+                logger: logger
+            )
+
+            // 16 MiB is far larger than any CH response we expect — vm.info,
+            // the largest, measures in low-KB even for many-disk VMs. The
+            // cap exists so a wedged server can't OOM us.
+            //
+            // Use `readableBytesView` + the Sequence-based Data init rather
+            // than `Data(buffer: ByteBuffer)`: the latter requires
+            // `NIOFoundationCompat`, which the Linux musl build doesn't
+            // pull in via Foundation by default.
+            let bodyBuffer = try await response.body.collect(upTo: 1 << 24)
+            let bodyData = Data(bodyBuffer.readableBytesView)
+
+            logger.debug("HTTPOverUDSClient: \(method) \(uri) ← \(response.status.code)")
+            return HTTPResponse(
+                status: response.status,
+                headers: response.headers,
+                body: bodyData
+            )
+        } catch let error as CloudHypervisor.Error {
+            throw error
+        } catch {
+            throw CloudHypervisor.Error.transport(error)
+        }
+    }
+
+    deinit {
+        // Fire the callback-based shutdown only when `shutdown()` wasn't
+        // already called. The sync variant would deadlock if deinit
+        // happened to run on one of the HTTPClient's own event loops
+        // (commit fe1c95cf); the callback variant returns immediately at
+        // the cost of any completion signal. If explicit shutdown
+        // already ran, the HTTPClient is drained and a second call would
+        // just return `alreadyShutdown` — but it can still try to
+        // schedule the callback on the (now-dead) event loop, which is
+        // exactly the failure mode this whole flag guards against.
+        let already = didShutdown.withLockedValue { state -> Bool in
+            if state { return true }
+            state = true
+            return false
+        }
+        guard !already else { return }
+        httpClient.shutdown { _ in }
+    }
+}