Configuration.swift

//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//

#if canImport(System)
public import System
#else
public import SystemPackage
#endif

#if canImport(Darwin)
import Darwin
#elseif canImport(Android)
import Android
#elseif canImport(Glibc)
import Glibc
#elseif canImport(Musl)
import Musl
#elseif canImport(WinSDK)
@preconcurrency public import WinSDK
#endif

/// A collection of configuration parameters to use when
/// spawning a subprocess.
public struct Configuration: Sendable {
    /// The executable to run.
    public var executable: Executable
    /// The arguments to pass to the executable.
    public var arguments: Arguments
    /// The environment to use when running the executable.
    public var environment: Environment
    /// The working directory to use when running the executable.
    ///
    /// If this property is `nil`, the subprocess inherits the working
    /// directory from the parent process.
    public var workingDirectory: FilePath?
    /// The platform-specific options to use when
    /// running the subprocess.
    public var platformOptions: PlatformOptions

    /// Creates a configuration with the parameters you provide.
    /// - Parameters:
    ///   - executable: The executable to run.
    ///   - arguments: The arguments to pass to the executable.
    ///   - environment: The environment to use when running the executable.
    ///   - workingDirectory: The working directory to use when running the executable.
    ///   - platformOptions: The platform-specific options to use when running the subprocess.
    public init(
        executable: Executable,
        arguments: Arguments = [],
        environment: Environment = .inherit,
        workingDirectory: FilePath? = nil,
        platformOptions: PlatformOptions = PlatformOptions()
    ) {
        self.executable = executable
        self.arguments = arguments
        self.environment = environment
        self.workingDirectory = workingDirectory
        self.platformOptions = platformOptions
    }

    internal func run<Result, Input: InputProtocol, Output: OutputProtocol, Error: OutputProtocol>(
        input: consuming CreatedPipe,
        as inputType: Input.Type,
        output: consuming CreatedPipe,
        as outputType: Output.Type,
        error: consuming CreatedPipe,
        as errorType: Error.Type,
        _ body: (
            (
                ProcessIdentifier,
                consuming IODescriptor?,
                consuming IODescriptor?,
                consuming IODescriptor?
            ) async throws -> Result
        )
    ) async throws -> ExecutionOutcome<Result> {
        // Built before spawning so it can be attached to spawn failures, where
        // no resolved values exist yet.
        let baseContext = ExecutionContext(self)

        var spawnResults: SpawnResult
        #if os(Windows)
        // `spawn` is `throws(SubprocessError)` on Windows, so `error` is
        // already typed; an `as SubprocessError` pattern is a redundant cast
        // that crashes the 6.2 toolchain's SIL ownership verifier. Elsewhere
        // `spawn` is untyped `throws`, where the cast is meaningful.
        do {
            spawnResults = try await self.spawn(
                withInput: input,
                outputPipe: output,
                errorPipe: error
            )
        } catch {
            throw error.withExecutionContext(baseContext)
        }
        #else
        do {
            spawnResults = try await self.spawn(
                withInput: input,
                outputPipe: output,
                errorPipe: error
            )
        } catch let error as SubprocessError {
            throw error.withExecutionContext(baseContext)
        }
        #endif

        let processIdentifier = spawnResults.processIdentifier

        defer {
            // Close the process file descriptor now that monitoring has finished.
            processIdentifier.close()
        }

        // Spawn succeeded, so resolved values are available. This context is
        // attached to any error surfacing after spawn.
        let executionContext = ExecutionContext(
            self,
            resolvedExecutable: spawnResults.resolvedExecutable,
            resolvedEnvironment: self.environment.resolvedValues(),
            resolvedWorkingDirectory: self.workingDirectory ?? currentWorkingDirectory()
        )

        do {
            return try await withAsyncTaskCleanupHandler { () throws -> ExecutionOutcome<Result> in
                // The counter coordinates a race between two finishers: the body
                // closure and the process-termination monitor. Whichever side
                // increments first observes a value of `1` and owns the response;
                // the other side sees `2` and stays out of the way.
                //
                // If the monitor wins, the child has exited while the body is
                // still reading or writing. The body might be blocked on a pipe
                // that an inherited grandchild keeps open, so the monitor calls
                // `cancelAsyncIO` to unblock it. If the body wins, the I/O
                // already finished cleanly and no cancellation is needed.
                let taskFinishFlag = AtomicCounter()

                let (result, monitorError) = try await withThrowingTaskGroup(
                    of: SubprocessError?.self,
                    returning: (Swift.Result<Result, any Swift.Error>, SubprocessError?).self
                ) { group in
                    group.addTask {
                        do throws(SubprocessError) {
                            try await waitForProcessTermination(for: processIdentifier)
                            if taskFinishFlag.addOne() == 1 {
                                // The body closure hasn't finished but the child
                                // process has terminated. Cancel all active
                                // AsyncIO now.
                                try AsyncIO.shared.cancelAsyncIO(for: processIdentifier)
                            }
                            return nil
                        } catch {
                            try? AsyncIO.shared.cancelAsyncIO(for: processIdentifier)
                            return error
                        }
                    }

                    let inputIO = spawnResults.inputWriteEnd()
                    let outputIO = spawnResults.outputReadEnd()
                    let errorIO = spawnResults.errorReadEnd()

                    let result: Swift.Result<Result, any Swift.Error>
                    do {
                        // Body runs in the same isolation.
                        let bodyResult = try await body(processIdentifier, inputIO, outputIO, errorIO)
                        taskFinishFlag.addOne()
                        result = .success(bodyResult)
                    } catch {
                        let execution = Execution<Input, Output, Error>(
                            processIdentifier: processIdentifier,
                            inputWriter: nil,
                            outputStream: nil,
                            errorStream: nil
                        )
                        // Attempt to terminate the child process when the body throws
                        await execution.teardown(using: self.platformOptions.teardownSequence)
                        result = .failure(error)
                    }

                    // Wait for the monitor child task to finish.
                    let monitorError = try await group.next() ?? nil
                    return (result, monitorError)
                }

                // Drop the cancellation marker before reaping the zombie. After
                // `reapProcess` runs the kernel can immediately reuse this PID,
                // so the marker must be gone first; otherwise a concurrent
                // `run()` that happens to inherit the same PID would see the
                // stale entry and reject its registrations.
                AsyncIO.shared.cleanup(processIdentifier: processIdentifier)

                let terminationStatus = try reapProcess(with: processIdentifier)

                if let monitorError {
                    throw monitorError
                }

                return try ExecutionOutcome(
                    terminationStatus: terminationStatus,
                    value: result.get()
                )
            } onCleanup: {
                let execution = Execution<Input, Output, Error>(
                    processIdentifier: processIdentifier,
                    inputWriter: nil,
                    outputStream: nil,
                    errorStream: nil
                )
                // Attempt to terminate the child process.
                await execution.teardown(using: self.platformOptions.teardownSequence)
            }
        } catch let error as SubprocessError {
            throw error.withExecutionContext(executionContext)
        }
    }
}

extension Configuration: CustomStringConvertible, CustomDebugStringConvertible {
    /// A textual representation of this configuration.
    public var description: String {
        return """
            Configuration(
                executable: \(self.executable.description),
                arguments: \(self.arguments.description),
                environment: \(self.environment.description),
                workingDirectory: \(self.workingDirectory?.string ?? ""),
                platformOptions: \(self.platformOptions.description(withIndent: 1))
            )
            """
    }

    /// A debug-oriented textual representation of this configuration.
    public var debugDescription: String {
        return """
            Configuration(
                executable: \(self.executable.debugDescription),
                arguments: \(self.arguments.debugDescription),
                environment: \(self.environment.debugDescription),
                workingDirectory: \(self.workingDirectory?.string ?? ""),
                platformOptions: \(self.platformOptions.description(withIndent: 1))
            )
            """
    }

}

// MARK: - Cleanup
extension Configuration {
    /// Close each input individually, and throw the first error if there's multiple errors thrown
    @Sendable
    internal func safelyCloseMultiple(
        inputRead: consuming IODescriptor?,
        inputWrite: consuming IODescriptor?,
        outputRead: consuming IODescriptor?,
        outputWrite: consuming IODescriptor?,
        errorRead: consuming IODescriptor?,
        errorWrite: consuming IODescriptor?
    ) throws(SubprocessError) {
        var possibleError: SubprocessError? = nil

        // To avoid closing the same descriptor multiple times,
        // keep track of the list of descriptors that we have
        // already closed. If a `IODescriptor.Descriptor` is
        // already closed, mark that `IODescriptor` as closed
        // as opposed to actually try to close it.
        var remainingSet: Set<IODescriptor.Descriptor> = Set(
            optionalSequence: [
                inputRead?.descriptor(),
                inputWrite?.descriptor(),
                outputRead?.descriptor(),
                outputWrite?.descriptor(),
                errorRead?.descriptor(),
                errorWrite?.descriptor(),
            ]
        )

        do {
            if remainingSet.tryRemove(inputRead?.descriptor()) {
                try inputRead?.safelyClose()
            } else {
                try inputRead?.markAsClosed()
            }
        } catch {
            possibleError = error
        }
        do {
            if remainingSet.tryRemove(inputWrite?.descriptor()) {
                try inputWrite?.safelyClose()
            } else {
                try inputWrite?.markAsClosed()
            }
        } catch {
            possibleError = error
        }
        do {
            if remainingSet.tryRemove(outputRead?.descriptor()) {
                try outputRead?.safelyClose()
            } else {
                try outputRead?.markAsClosed()
            }
        } catch {
            possibleError = error
        }
        do {
            if remainingSet.tryRemove(outputWrite?.descriptor()) {
                try outputWrite?.safelyClose()
            } else {
                try outputWrite?.markAsClosed()
            }
        } catch {
            possibleError = error
        }
        do {
            if remainingSet.tryRemove(errorRead?.descriptor()) {
                try errorRead?.safelyClose()
            } else {
                try errorRead?.markAsClosed()
            }
        } catch {
            possibleError = error
        }
        do {
            if remainingSet.tryRemove(errorWrite?.descriptor()) {
                try errorWrite?.safelyClose()
            } else {
                try errorWrite?.markAsClosed()
            }
        } catch {
            possibleError = error
        }

        if let actualError = possibleError {
            throw actualError
        }
    }
}

// MARK: - Executable

/// A description of how to locate the executable to run.
public struct Executable: Sendable, Hashable {
    internal enum Storage: Sendable, Hashable {
        case executable(String)
        case path(FilePath)
    }

    internal let storage: Storage

    private init(_config: Storage) {
        self.storage = _config
    }

    /// Locates the executable by name.
    /// The subprocess uses the `PATH` value to determine the full path.
    public static func name(_ executableName: String) -> Self {
        return .init(_config: .executable(executableName))
    }
    /// Locates the executable by its full file path.
    /// The subprocess uses this path directly.
    public static func path(_ filePath: FilePath) -> Self {
        return .init(_config: .path(filePath))
    }
    /// Resolves the full executable path using the given environment.
    public func resolveExecutablePath(in environment: Environment) async throws(SubprocessError) -> FilePath {
        try await runOnBackgroundThread { () throws(SubprocessError) -> FilePath in
            let path = try self.resolveExecutablePath(withPathValue: environment.pathValue())
            return FilePath(path)
        }
    }
}

extension Executable: CustomStringConvertible, CustomDebugStringConvertible {
    /// A textual representation of this executable.
    public var description: String {
        switch storage {
        case .executable(let executableName):
            return executableName
        case .path(let filePath):
            return filePath.string
        }
    }

    /// A debug-oriented textual representation of this executable.
    public var debugDescription: String {
        switch storage {
        case .executable(let string):
            return "executable(\(string))"
        case .path(let filePath):
            return "path(\(filePath.string))"
        }
    }
}

// MARK: - Arguments

/// A collection of arguments to pass to the subprocess.
public struct Arguments: Sendable, ExpressibleByArrayLiteral, Hashable {
    /// The type of the elements of an array literal.
    public typealias ArrayLiteralElement = String

    internal let storage: [StringOrRawBytes]
    internal let executablePathOverride: StringOrRawBytes?

    /// Creates an arguments value from the given literal values.
    public init(arrayLiteral elements: String...) {
        self.storage = elements.map { .string($0) }
        self.executablePathOverride = nil
    }
    /// Creates an arguments value from the given array.
    public init(_ array: [String]) {
        self.storage = array.map { .string($0) }
        self.executablePathOverride = nil
    }

    /// Creates an ``Arguments`` value using the given values, but
    /// override the first argument value with `executablePathOverride`.
    /// If `executablePathOverride` is `nil`,
    /// ``Arguments`` automatically uses the executable path
    /// as the first argument.
    /// - Parameters:
    ///   - executablePathOverride: The value to override the first argument.
    ///   - remainingValues: The remaining argument values.
    public init(executablePathOverride: String?, remainingValues: [String]) {
        self.storage = remainingValues.map { .string($0) }
        if let executablePathOverride = executablePathOverride {
            self.executablePathOverride = .string(executablePathOverride)
        } else {
            self.executablePathOverride = nil
        }
    }
    #if !os(Windows) // Windows does not support non-unicode arguments
    /// Creates an ``Arguments`` value using the given values, but
    /// override the first argument value with `executablePathOverride`.
    /// If `executablePathOverride` is `nil`,
    /// ``Arguments`` automatically uses the executable path
    /// as the first argument.
    /// - Parameters:
    ///   - executablePathOverride: The value to override the first argument.
    ///   - remainingValues: The remaining argument values.
    public init(executablePathOverride: [UInt8]?, remainingValues: [[UInt8]]) {
        self.storage = remainingValues.map { .rawBytes($0) }
        if let override = executablePathOverride {
            self.executablePathOverride = .rawBytes(override)
        } else {
            self.executablePathOverride = nil
        }
    }
    /// Creates an arguments value from the array you provide.
    public init(_ array: [[UInt8]]) {
        self.storage = array.map { .rawBytes($0) }
        self.executablePathOverride = nil
    }
    #endif
}

extension Arguments: CustomStringConvertible, CustomDebugStringConvertible {
    /// A textual representation of the arguments.
    public var description: String {
        var result: [String] = self.storage.map(\.description)

        if let override = self.executablePathOverride {
            result.insert("override\(override.description)", at: 0)
        }
        return result.description
    }

    /// A debug-oriented textual representation of the arguments.
    public var debugDescription: String { return self.description }
}

// MARK: - Environment

/// A set of environment variables to use when running the subprocess.
public struct Environment: Sendable, Hashable {
    internal enum Configuration: Sendable, Hashable {
        case inherit([Key: String?])
        case custom([Key: String])
        #if !os(Windows)
        case rawBytes([[UInt8]])
        #endif
    }

    internal let config: Configuration

    init(config: Configuration) {
        self.config = config
    }
    /// Inherits the environment from the current process.
    public static var inherit: Self {
        return .init(config: .inherit([:]))
    }
    /// Returns an updated environment that applies `newValue` to the current configuration.
    ///
    /// Keys with `nil` values in `newValue` remove the corresponding entry
    /// from the environment before passing it to the child process.
    public func updating(_ newValue: [Key: String?]) -> Self {
        switch config {
        case .inherit(var overrides):
            for (key, value) in newValue {
                overrides[key] = value
            }
            return .init(config: .inherit(overrides))
        case .custom(var environment):
            for (key, value) in newValue {
                environment[key] = value
            }
            return .init(config: .custom(environment))
        #if !os(Windows)
        case .rawBytes(var rawBytesArray):
            let overriddenKeys = newValue.keys.map { Array("\($0)=".utf8) }
            rawBytesArray.removeAll {
                overriddenKeys.contains(where: $0.starts)
            }

            for (key, value) in newValue {
                if let value {
                    rawBytesArray.append(Array("\(key)=\(value)\0".utf8))
                }
            }
            return .init(config: .rawBytes(rawBytesArray))
        #endif
        }
    }
    /// Creates an environment with custom variables.
    public static func custom(_ newValue: [Key: String]) -> Self {
        return .init(config: .custom(newValue))
    }

    #if !os(Windows)
    /// Creates an environment with custom variables as raw bytes.
    public static func custom(_ newValue: [[UInt8]]) -> Self {
        return .init(config: .rawBytes(newValue))
    }
    #endif
}

extension Environment: CustomStringConvertible, CustomDebugStringConvertible {
    /// A key used to access values in an ``Environment``.
    ///
    /// This type respects the compiled platform's case sensitivity requirements.
    public struct Key {
        public let rawValue: String

        package init(_ rawValue: String) {
            self.rawValue = rawValue
        }
    }

    /// A textual representation of the environment.
    public var description: String {
        switch self.config {
        case .custom(let customDictionary):
            return """
                Custom environment:
                \(customDictionary)
                """
        case .inherit(let updateValue):
            return """
                Inheriting current environment with updates:
                \(updateValue)
                """
        #if !os(Windows)
        case .rawBytes(let rawBytes):
            return """
                Raw bytes:
                \(rawBytes)
                """
        #endif
        }
    }

    /// A debug-oriented textual representation of the environment.
    public var debugDescription: String {
        return self.description
    }

    internal static func currentEnvironmentValues() -> [Key: String] {
        return self.withCopiedEnv { environments in
            var results: [Key: String] = [:]
            for env in environments {
                let environmentString = String(cString: env)

                #if os(Windows)
                // Windows GetEnvironmentStringsW API can return
                // magic environment variables set by the cmd shell
                // that starts with `=`
                // We should exclude these values
                if environmentString.utf8.first == Character("=").utf8.first {
                    continue
                }
                #endif // os(Windows)

                guard let delimiter = environmentString.firstIndex(of: "=") else {
                    continue
                }

                let key = String(environmentString[environmentString.startIndex..<delimiter])
                let value = String(
                    environmentString[environmentString.index(after: delimiter)..<environmentString.endIndex]
                )
                results[Key(key)] = value
            }
            return results
        }
    }

    /// The concrete environment variables passed to the child process, or
    /// `nil` if they cannot be represented as a `[Key: String]` map.
    ///
    /// This mirrors the environment built by the platform spawn path: for
    /// `.inherit`, the parent's current values with the configured overrides
    /// applied (a `nil` override removes the key); for `.custom`, those values
    /// directly; for raw-byte environments, `nil`. On Windows, `PATH` is
    /// injected from the parent when absent, matching the spawn path's
    /// DLL-resolution behavior.
    internal func resolvedValues() -> [Environment.Key: String]? {
        var values: [Environment.Key: String]
        switch self.config {
        case .custom(let customValues):
            values = customValues
        case .inherit(let overrides):
            values = Self.currentEnvironmentValues()
            for (key, override) in overrides {
                values[key] = override
            }
        #if !os(Windows)
        case .rawBytes:
            return nil
        #endif
        }
        #if os(Windows)
        if values[.path] == nil,
            let parentPath = Self.currentEnvironmentValues()[.path]
        {
            values[.path] = parentPath
        }
        #endif
        return values
    }
}

extension Environment.Key {
    package static let path: Self = "PATH"
}

extension Environment.Key: CodingKeyRepresentable {}

extension Environment.Key: Comparable {
    public static func < (lhs: Self, rhs: Self) -> Bool {
        // Even on windows use a stable sort order.
        lhs.rawValue < rhs.rawValue
    }
}

extension Environment.Key: CustomStringConvertible {
    public var description: String { self.rawValue }
}

extension Environment.Key: Encodable {
    public func encode(to encoder: any Swift.Encoder) throws {
        try self.rawValue.encode(to: encoder)
    }
}

extension Environment.Key: Equatable {
    public static func == (_ lhs: Self, _ rhs: Self) -> Bool {
        #if os(Windows)
        lhs.rawValue.lowercased() == rhs.rawValue.lowercased()
        #else
        lhs.rawValue == rhs.rawValue
        #endif
    }
}

extension Environment.Key: ExpressibleByStringLiteral {
    public init(stringLiteral rawValue: String) {
        self.init(rawValue)
    }
}

extension Environment.Key: Decodable {
    public init(from decoder: any Swift.Decoder) throws {
        self.rawValue = try String(from: decoder)
    }
}

extension Environment.Key: Hashable {
    public func hash(into hasher: inout Hasher) {
        #if os(Windows)
        self.rawValue.lowercased().hash(into: &hasher)
        #else
        self.rawValue.hash(into: &hasher)
        #endif
    }
}

extension Environment.Key: RawRepresentable {
    public init?(rawValue: String) {
        self.rawValue = rawValue
    }
}

extension Environment.Key: Sendable {}

// MARK: - TerminationStatus

/// The exit status of a subprocess.
public enum TerminationStatus: Sendable, Hashable {
    #if os(Windows)
    /// The type of the status code.
    public typealias Code = DWORD
    #else
    /// The type of the status code.
    public typealias Code = CInt
    #endif

    /// The subprocess exited with the given code.
    case exited(Code)
    #if !os(Windows)
    /// The subprocess terminated due to the given signal.
    case signaled(Code)
    #endif
    /// A Boolean value that indicates whether the termination was successful.
    public var isSuccess: Bool {
        switch self {
        case .exited(let exitCode):
            return exitCode == 0
        #if !os(Windows)
        case .signaled(_):
            return false
        #endif
        }
    }
}

extension TerminationStatus: CustomStringConvertible, CustomDebugStringConvertible {
    /// A textual representation of this termination status.
    public var description: String {
        switch self {
        case .exited(let code):
            return "exited(\(code))"
        #if !os(Windows)
        case .signaled(let code):
            return "signaled(\(code))"
        #endif
        }
    }

    /// A debug-oriented textual representation of this termination status.
    public var debugDescription: String {
        return self.description
    }
}

// MARK: - Internal

extension Configuration {
    /// After Spawn finishes, child side file descriptors
    /// (input read, output write, error write) will be closed
    /// by `spawn()`. It returns the parent side file descriptors
    /// via `SpawnResult` to perform actual reads
    internal struct SpawnResult: ~Copyable {
        let processIdentifier: ProcessIdentifier
        let resolvedExecutable: FilePath?
        var _inputWriteEnd: IODescriptor?
        var _outputReadEnd: IODescriptor?
        var _errorReadEnd: IODescriptor?

        init(
            processIdentifier: ProcessIdentifier,
            inputWriteEnd: consuming IODescriptor?,
            outputReadEnd: consuming IODescriptor?,
            errorReadEnd: consuming IODescriptor?,
            resolvedExecutable: FilePath? = nil
        ) {
            self.processIdentifier = processIdentifier
            self._inputWriteEnd = consume inputWriteEnd
            self._outputReadEnd = consume outputReadEnd
            self._errorReadEnd = consume errorReadEnd
            self.resolvedExecutable = resolvedExecutable
        }

        mutating func inputWriteEnd() -> IODescriptor? {
            return self._inputWriteEnd.take()
        }

        mutating func outputReadEnd() -> IODescriptor? {
            return self._outputReadEnd.take()
        }

        mutating func errorReadEnd() -> IODescriptor? {
            return self._errorReadEnd.take()
        }
    }
}

internal enum StringOrRawBytes: Sendable, Hashable {
    case string(String)
    case rawBytes([UInt8])

    // Return value needs to be deallocated manually by callee
    func createRawBytes() -> UnsafeMutablePointer<CChar> {
        switch self {
        case .string(let string):
            #if os(Windows)
            return _strdup(string)
            #else
            return strdup(string)
            #endif
        case .rawBytes(let rawBytes):
            #if os(Windows)
            return _strdup(rawBytes)
            #else
            return strdup(rawBytes)
            #endif
        }
    }

    var stringValue: String? {
        switch self {
        case .string(let string):
            return string
        case .rawBytes(let rawBytes):
            return String(decoding: rawBytes, as: UTF8.self)
        }
    }

    var description: String {
        switch self {
        case .string(let string):
            return string
        case .rawBytes(let bytes):
            return bytes.description
        }
    }

    var count: Int {
        switch self {
        case .string(let string):
            return string.count
        case .rawBytes(let rawBytes):
            return strnlen(rawBytes, Int.max)
        }
    }

    func hash(into hasher: inout Hasher) {
        // If Raw bytes is valid UTF8, hash it as so
        switch self {
        case .string(let string):
            hasher.combine(string)
        case .rawBytes(let bytes):
            if let stringValue = self.stringValue {
                hasher.combine(stringValue)
            } else {
                hasher.combine(bytes)
            }
        }
    }
}

internal enum _CloseTarget {
    #if canImport(WinSDK)
    case handle(HANDLE)
    #else
    case fileDescriptor(FileDescriptor)
    #endif
}

internal func _safelyClose(_ target: _CloseTarget) throws(SubprocessError) {
    switch target {
    #if os(Windows)
    case .handle(let handle):
        /// Windows does not provide a “deregistration” API (the reverse of
        /// `CreateIoCompletionPort`) for handles and it reuses HANDLE
        /// values once they are closed. Since we rely on the handle value
        /// as the completion key for `CreateIoCompletionPort`, we should
        /// remove the registration when the handle is closed to allow
        /// new registration to proceed if the handle is reused.
        AsyncIO.shared.removeRegistration(for: handle)
        guard CloseHandle(handle) else {
            let error = GetLastError()
            // Getting `ERROR_INVALID_HANDLE` suggests that the file descriptor
            // might have been closed unexpectedly. This can pose security risks
            // if another part of the code inadvertently reuses the same HANDLE.
            // We use `fatalError` upon receiving `ERROR_INVALID_HANDLE`
            // to prevent accidentally closing a different HANDLE.
            guard error != ERROR_INVALID_HANDLE else {
                fatalError(
                    "HANDLE \(handle) is already closed"
                )
            }
            let subprocessError: SubprocessError = .asyncIOFailed(
                reason: "Failed to close HANDLE",
                underlyingError: SubprocessError.WindowsError(win32Error: error)
            )

            throw subprocessError
        }
    #else
    case .fileDescriptor(let fileDescriptor):
        do {
            try fileDescriptor.close()
        } catch {
            guard let errno: Errno = error as? Errno else {
                throw .asyncIOFailed(
                    reason: "Failed to close file descriptor \(fileDescriptor.rawValue)"
                )
            }
            // Getting `.badFileDescriptor` suggests that the file descriptor
            // might have been closed unexpectedly. This can pose security risks
            // if another part of the code inadvertently reuses the same file descriptor
            // number. This problem is especially concerning on Unix systems due to POSIX’s
            // guarantee of using the lowest available file descriptor number, making reuse
            // more probable. We use `fatalError` upon receiving `.badFileDescriptor`
            // to prevent accidentally closing a different file descriptor.
            guard errno != .badFileDescriptor else {
                fatalError(
                    "FileDescriptor \(fileDescriptor.rawValue) is already closed"
                )
            }
            // Throw other kinds of errors to allow user to catch them
            throw .asyncIOFailed(
                reason: "Failed to close file descriptor \(fileDescriptor.rawValue)",
                underlyingError: errno
            )
        }
    #endif
    }
}

/// An IO descriptor wraps platform-specific file descriptor, which establishes a
/// connection to the standard input/output (IO) system during the process of
/// spawning a child process.
///
/// Unlike a file descriptor, the `IODescriptor` does not support
/// data read/write operations; its primary function is to facilitate the spawning of
/// child processes by providing a platform-specific file descriptor.
internal struct IODescriptor: ~Copyable {
    #if canImport(WinSDK)
    typealias Descriptor = HANDLE
    #else
    typealias Descriptor = FileDescriptor
    #endif

    internal var closeWhenDone: Bool
    #if canImport(WinSDK)
    internal nonisolated(unsafe) let _descriptor: Descriptor
    #else
    internal let _descriptor: Descriptor
    #endif

    internal init(
        _ descriptor: Descriptor,
        closeWhenDone: Bool
    ) {
        self._descriptor = descriptor
        self.closeWhenDone = closeWhenDone
    }

    internal init?(duplicating ioDescriptor: borrowing IODescriptor?) throws(SubprocessError) {
        let descriptor = try ioDescriptor?.duplicate()
        if let descriptor {
            self = descriptor
        } else {
            return nil
        }
    }

    func duplicate() throws(SubprocessError) -> IODescriptor {
        do throws(any Error) {
            return try IODescriptor(self._descriptor.duplicate(), closeWhenDone: self.closeWhenDone)
        } catch {
            throw SubprocessError.asyncIOFailed(
                reason: "Failed to duplicate file descriptor \(self._descriptor)",
                underlyingError: error as? SubprocessError.UnderlyingError
            )
        }
    }

    internal mutating func safelyClose() throws(SubprocessError) {
        guard self.closeWhenDone else {
            return
        }
        closeWhenDone = false

        #if canImport(WinSDK)
        try _safelyClose(.handle(self._descriptor))
        #else
        try _safelyClose(.fileDescriptor(self._descriptor))
        #endif
    }

    internal mutating func markAsClosed() throws(SubprocessError) {
        self.closeWhenDone = false
    }

    deinit {
        guard self.closeWhenDone else {
            return
        }

        fatalError("FileDescriptor \(self._descriptor) was not closed")
    }

    internal func platformDescriptor() -> PlatformFileDescriptor {
        #if canImport(WinSDK)
        return self._descriptor
        #else
        return self._descriptor.platformDescriptor
        #endif
    }

    internal func descriptor() -> Descriptor {
        return self._descriptor
    }

    internal mutating func consumeDescriptor() -> Descriptor {
        // This Descriptor has been consumed, we don't need to close it anymore
        self.closeWhenDone = false
        return self._descriptor
    }
}

#if canImport(WinSDK)
import Synchronization

internal enum PipeNameCounter {
    private static let value = Atomic<UInt64>(0)

    internal static func nextValue() -> UInt64 {
        return self.value.add(1, ordering: .relaxed).newValue
    }
}
#endif

internal struct CreatedPipe: ~Copyable, Sendable {
    internal enum Purpose: CustomStringConvertible {
        /// This pipe is used for standard input. This option maps to
        /// `PIPE_ACCESS_OUTBOUND` on Windows where child only reads,
        /// parent only writes.
        case input
        /// This pipe is used for standard output and standard error.
        /// This option maps to `PIPE_ACCESS_INBOUND` on Windows where
        /// child only writes, parent only reads.
        case output

        var description: String {
            switch self {
            case .input:
                return "input"
            case .output:
                return "output"
            }
        }
    }

    internal var _readFileDescriptor: IODescriptor?
    internal var _writeFileDescriptor: IODescriptor?

    internal init(
        readFileDescriptor: consuming IODescriptor?,
        writeFileDescriptor: consuming IODescriptor?
    ) {
        self._readFileDescriptor = readFileDescriptor
        self._writeFileDescriptor = writeFileDescriptor
    }

    mutating func readFileDescriptor() -> IODescriptor? {
        return self._readFileDescriptor.take()
    }

    mutating func writeFileDescriptor() -> IODescriptor? {
        return self._writeFileDescriptor.take()
    }

    internal init(duplicating createdPipe: borrowing CreatedPipe) throws(SubprocessError) {
        self.init(
            readFileDescriptor: try IODescriptor(duplicating: createdPipe._readFileDescriptor),
            writeFileDescriptor: try IODescriptor(duplicating: createdPipe._writeFileDescriptor)
        )
    }

    internal init(closeWhenDone: Bool, purpose: Purpose) throws(SubprocessError) {
        #if canImport(WinSDK)
        /// On Windows, we need to create a named pipe.
        /// According to Microsoft documentation:
        /// > Asynchronous (overlapped) read and write operations are
        /// > not supported by anonymous pipes.
        /// See https://learn.microsoft.com/en-us/windows/win32/ipc/anonymous-pipe-operations
        while true {
            /// Windows named pipes are system wide. To avoid creating two pipes with the same
            /// name, create the pipe with `FILE_FLAG_FIRST_PIPE_INSTANCE` such that it will
            /// return error `ERROR_ACCESS_DENIED` if we try to create another pipe with the same name.
            let pipeName = "\\\\.\\pipe\\LOCAL\\subprocess-\(GetCurrentProcessId())-\(purpose)-\(PipeNameCounter.nextValue())"
            var saAttributes: SECURITY_ATTRIBUTES = SECURITY_ATTRIBUTES()
            saAttributes.nLength = DWORD(MemoryLayout<SECURITY_ATTRIBUTES>.size)
            saAttributes.bInheritHandle = true
            saAttributes.lpSecurityDescriptor = nil

            let parentEnd = pipeName.withCString(
                encodedAs: UTF16.self
            ) { pipeNameW in
                // Use OVERLAPPED for async IO
                var openMode: DWORD = DWORD(FILE_FLAG_OVERLAPPED | FILE_FLAG_FIRST_PIPE_INSTANCE)
                switch purpose {
                case .input:
                    openMode |= DWORD(PIPE_ACCESS_OUTBOUND)
                case .output:
                    openMode |= DWORD(PIPE_ACCESS_INBOUND)
                }

                return CreateNamedPipeW(
                    pipeNameW,
                    openMode,
                    DWORD(PIPE_TYPE_BYTE | PIPE_READMODE_BYTE | PIPE_WAIT | PIPE_REJECT_REMOTE_CLIENTS),
                    1, // Max instance,
                    // Both libuv (Node) and Rust std::process use this value
                    DWORD(64 * 1024),
                    DWORD(64 * 1024),
                    0,
                    nil
                )
            }
            guard let parentEnd, parentEnd != INVALID_HANDLE_VALUE else {
                // Since we created the pipe with `FILE_FLAG_FIRST_PIPE_INSTANCE`,
                // if there's already a pipe with the same name, GetLastError()
                // will be set to ERROR_ACCESS_DENIED. In this case,
                // try again with a different name.
                let errorCode = GetLastError()
                guard errorCode != ERROR_ACCESS_DENIED else {
                    continue
                }
                // Throw all other errors
                throw .asyncIOFailed(
                    reason: "CreateNamedPipeW failed",
                    underlyingError: SubprocessError.WindowsError(win32Error: GetLastError())
                )
            }

            let childEnd = pipeName.withCString(
                encodedAs: UTF16.self
            ) { pipeNameW in
                var targetAccess: DWORD = 0
                switch purpose {
                case .input:
                    targetAccess = DWORD(GENERIC_READ)
                case .output:
                    targetAccess = DWORD(GENERIC_WRITE)
                }

                return CreateFileW(
                    pipeNameW,
                    targetAccess,
                    0,
                    &saAttributes,
                    DWORD(OPEN_EXISTING),
                    DWORD(FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OVERLAPPED),
                    nil
                )
            }
            guard let childEnd, childEnd != INVALID_HANDLE_VALUE else {
                throw .asyncIOFailed(
                    reason: "CreateFileW failed",
                    underlyingError: SubprocessError.WindowsError(win32Error: GetLastError())
                )
            }
            switch purpose {
            case .input:
                self._readFileDescriptor = .init(childEnd, closeWhenDone: closeWhenDone)
                self._writeFileDescriptor = .init(parentEnd, closeWhenDone: closeWhenDone)
            case .output:
                self._readFileDescriptor = .init(parentEnd, closeWhenDone: closeWhenDone)
                self._writeFileDescriptor = .init(childEnd, closeWhenDone: closeWhenDone)
            }
            return
        }
        #else
        do {
            let pipe = try FileDescriptor.pipe()
            self._readFileDescriptor = .init(
                pipe.readEnd,
                closeWhenDone: closeWhenDone
            )
            self._writeFileDescriptor = .init(
                pipe.writeEnd,
                closeWhenDone: closeWhenDone
            )
        } catch {
            throw .asyncIOFailed(
                reason: "Failed to create pipe",
                underlyingError: error as? SubprocessError.UnderlyingError
            )
        }
        #endif
    }
}

extension Optional where Wrapped: Collection {
    func withOptionalUnsafeBufferPointer<Result>(
        _ body: ((UnsafeBufferPointer<Wrapped.Element>)?) -> Result
    ) -> Result {
        switch self {
        case .some(let wrapped):
            guard let array: [Wrapped.Element] = wrapped as? Array else {
                return body(nil)
            }
            return array.withUnsafeBufferPointer { ptr in
                return body(ptr)
            }
        case .none:
            return body(nil)
        }
    }
}

extension Optional where Wrapped == String {
    func withOptionalCString<Result>(
        _ body: ((UnsafePointer<Int8>)?) throws(SubprocessError) -> Result
    ) throws(SubprocessError) -> Result {
        switch self {
        case .none:
            return try body(nil)
        case .some(let wrapped):
            return try wrapped._withCString { (str) throws(SubprocessError) in
                return try body(str)
            }
        }
    }

    var stringValue: String {
        return self ?? "nil"
    }
}

/// Runs the body close, then runs the on-cleanup closure if the body closure throws an error
/// or if the parent task is cancelled.
///
/// In the latter case, `onCleanup` may be run concurrently with `body`.
/// The `body` closure is guaranteed to run exactly once.
/// The `onCleanup` closure is guaranteed to run only once, or not at all.
internal func withAsyncTaskCleanupHandler<Result: Sendable>(
    _ body: () async throws -> Result,
    onCleanup handler: @Sendable @escaping () async -> Void,
) async throws -> Result {
    let (runCancellationHandlerStream, runCancellationHandlerContinuation) = AsyncThrowingStream.makeStream(of: Void.self)
    return try await withThrowingTaskGroup(
        of: Void.self,
        returning: Result.self
    ) { group in
        group.addTask {
            // Keep this task sleep indefinitely until the parent task is cancelled.
            // `Task.sleep` throws `CancellationError` when the task is canceled
            // before the time ends. We then run the cancel handler.
            do { while true { try await Task.sleep(nanoseconds: 1_000_000_000) } } catch {}
            // Run task cancel handler
            runCancellationHandlerContinuation.finish(throwing: CancellationError())
        }

        group.addTask {
            // Enumerate the async stream until it completes or throws an error.
            // Since we signal completion of the stream from cancellation or the
            // parent task or the body throwing, this ensures that we run the
            // cleanup handler exactly once in any failure scenario, and also do
            // so _immediately_ if the failure scenario is due to parent task
            // cancellation. We do so in a detached Task to prevent cancellation
            // of the parent task from interrupting enumeration of the stream itself.
            await withUncancelledTask {
                do {
                    var iterator = runCancellationHandlerStream.makeAsyncIterator()
                    while let _ = try await iterator.next() {
                    }
                } catch {
                    await handler()
                }
            }
        }

        defer {
            group.cancelAll()
        }

        do {
            let result = try await body()
            runCancellationHandlerContinuation.finish()
            return result
        } catch {
            runCancellationHandlerContinuation.finish(throwing: error)
            throw error
        }
    }
}

internal struct _OrderedSet<Element: Hashable & Sendable>: Hashable, Sendable {
    private var elements: [Element]
    private var hashValueSet: Set<Int>

    internal init() {
        self.elements = []
        self.hashValueSet = Set()
    }

    internal init(_ arrayValue: [Element]) {
        self.elements = []
        self.hashValueSet = Set()

        for element in arrayValue {
            self.insert(element)
        }
    }

    mutating func insert(_ element: Element) {
        guard !self.hashValueSet.contains(element.hashValue) else {
            return
        }
        self.elements.append(element)
        self.hashValueSet.insert(element.hashValue)
    }
}

extension _OrderedSet: Sequence {
    typealias Iterator = Array<Element>.Iterator

    internal func makeIterator() -> Iterator {
        return self.elements.makeIterator()
    }
}

extension Set {
    init<S>(optionalSequence sequence: S) where S: Sequence, S.Element == Optional<Self.Element> {
        let sequence: [Self.Element] = sequence.compactMap(\.self)
        self.init(sequence)
    }

    mutating func tryRemove(_ element: Self.Element?) -> Bool {
        guard let element else {
            return false
        }
        return self.remove(element) != nil
    }
}

#if canImport(WinSDK)
extension HANDLE {
    func duplicate() throws(SubprocessError) -> HANDLE {
        var handle: HANDLE? = nil
        guard
            DuplicateHandle(
                GetCurrentProcess(),
                self,
                GetCurrentProcess(),
                &handle,
                0, true, DWORD(DUPLICATE_SAME_ACCESS)
            )
        else {
            throw .asyncIOFailed(
                reason: "Failed to create pipe",
                underlyingError: SubprocessError.WindowsError(win32Error: GetLastError())
            )
        }
        guard let handle else {
            throw .asyncIOFailed(
                reason: "Failed to create pipe",
                underlyingError: SubprocessError.WindowsError(win32Error: GetLastError())
            )
        }
        return handle
    }
}
#endif

/// Many standard library functions such as `withCheckedThrowingContinuation`
/// does not support typed throw yet. This method casts `any Error` thrown by
/// those methods back to `SubprocessError`
internal func _castError<Success: Sendable>(
    _ body: () async throws -> Success,
) async throws(SubprocessError) -> Success {
    do {
        return try await body()
    } catch {
        throw (error as! SubprocessError)
    }
}

internal func _castError<Success: Sendable>(
    _ body: () throws -> Success
) throws(SubprocessError) -> Success {
    do {
        return try body()
    } catch {
        throw (error as! SubprocessError)
    }
}

extension StringProtocol {
    func _withCString<Result, Error: Swift.Error>(
        _ body: (UnsafePointer<Int8>) throws(Error) -> Result
    ) throws(Error) -> Result {
        do {
            return try self.withCString(body)
        } catch {
            throw error as! Error
        }
    }

    func _withCString<Result, TargetEncoding, Error: Swift.Error>(
        encodedAs targetEncoding: TargetEncoding.Type,
        _ body: (UnsafePointer<TargetEncoding.CodeUnit>) throws(Error) -> Result
    ) throws(Error) -> Result where TargetEncoding: _UnicodeEncoding {
        do {
            return try self.withCString(encodedAs: targetEncoding, body)
        } catch {
            throw error as! Error
        }
    }
}

/// Best-effort lookup of the parent process's current working directory.
///
/// Returns `nil` on failure; never throws, since it only feeds diagnostics.
internal func currentWorkingDirectory() -> FilePath? {
    #if os(Windows)
    let length = GetCurrentDirectoryW(0, nil)
    guard length > 0 else { return nil }
    let path = try? fillNullTerminatedWideStringBuffer(
        initialSize: length,
        maxSize: DWORD(Int16.max)
    ) {
        GetCurrentDirectoryW(DWORD($0.count), $0.baseAddress)
    }
    guard let path else { return nil }
    return FilePath(path)
    #else
    return withUnsafeTemporaryAllocation(of: CChar.self, capacity: Int(PATH_MAX)) { buffer -> FilePath? in
        guard getcwd(buffer.baseAddress, buffer.count) != nil else {
            return nil
        }
        return FilePath(platformString: buffer.baseAddress!)
    }
    #endif
}