Subprocess 0.1

This is the initial release of swift-subprocess.

API Changes Since Initial Proposal

• Introduce preferredBufferSize parameter to allow custom buffer size when streaming subprocess output (#168)

  A new preferredBufferSize parameter was added to the streaming APIs, allowing developers to control the buffer size when reading subprocess output instead of relying on a fixed default.

public func run<Result, Input: InputProtocol, Error: OutputProtocol>(
    _ executable: Executable,
    arguments: Arguments = [],
    environment: Environment = .inherit,
    workingDirectory: FilePath? = nil,
    platformOptions: PlatformOptions = PlatformOptions(),
    input: Input = .none,
    error: Error = .discarded,
    preferredBufferSize: Int? = nil, // New API
    isolation: isolated (any Actor)? = #isolation,
    body: ((Execution, AsyncBufferSequence) async throws -> Result)
) async throws -> ExecutionResult<Result> where Error.OutputType == Void

• Expand API with Configuration-based run() overloads (#164)

  Added new run() overloads that allow subprocesses to be launched using a Configuration, bringing parity with APIs that take individual parameters.

// New Configuration-based APIs

public func run<
    InputElement: BitwiseCopyable,
    Output: OutputProtocol,
    Error: OutputProtocol
>(
    _ configuration: Configuration,
    input: borrowing Span<InputElement>,
    output: Output,
    error: Error = .discarded
) async throws -> CollectedResult<Output, Error>

public func run<Result, Input: InputProtocol, Output: OutputProtocol, Error: OutputProtocol>(
    _ configuration: Configuration,
    input: Input = .none,
    output: Output = .discarded,
    error: Error = .discarded,
    isolation: isolated (any Actor)? = #isolation,
    body: ((Execution) async throws -> Result)
) async throws -> ExecutionResult<Result> where Error.OutputType == Void

public func run<Result, Input: InputProtocol, Error: OutputProtocol>(
    _ configuration: Configuration,
    input: Input = .none,
    error: Error = .discarded,
    isolation: isolated (any Actor)? = #isolation,
    body: ((Execution, AsyncBufferSequence) async throws -> Result)
) async throws -> ExecutionResult<Result> where Error.OutputType == Void

public func run<Result, Input: InputProtocol, Output: OutputProtocol>(
    _ configuration: Configuration,
    input: Input = .none,
    output: Output,
    isolation: isolated (any Actor)? = #isolation,
    body: ((Execution, AsyncBufferSequence) async throws -> Result)
) async throws -> ExecutionResult<Result> where Output.OutputType == Void

public func run<Result, Error: OutputProtocol>(
    _ configuration: Configuration,
    error: Error = .discarded,
    isolation: isolated (any Actor)? = #isolation,
    body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
) async throws -> ExecutionResult<Result> where Error.OutputType == Void

public func run<Result, Output: OutputProtocol>(
    _ configuration: Configuration,
    output: Output,
    isolation: isolated (any Actor)? = #isolation,
    body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
) async throws -> ExecutionResult<Result> where Output.OutputType == Void

• Remove preSpawnProcessConfigurator on Linux

  This property has been removed due to async-signal-safety concerns. It is not possible to offer a safe implementation of this API.

• Remove the default collected output buffer limit and throw an error when the limit is reached (#130)

  The default output buffer has been removed. All run() methods now require developers to explicitly specify the output type and buffer limit. If the limit is reached, an error will be thrown. This change ensures developers choose buffer sizes that best fit their use case.

@@ -9,6 +9,6 @@ public func run<
     workingDirectory: FilePath? = nil,
     platformOptions: PlatformOptions = PlatformOptions(),
     input: Input = .none,
-    output: Output = .string,
+    output: Output,
     error: Error = .discarded
 ) async throws -> CollectedResult<Output, Error>

• Expose platform-specific process file descriptors (#101)

  Linux, FreeBSD, and Windows now expose their respective process descriptors (pidfd on Linux and FreeBSD, HANDLE on Windows). These allow integration with system APIs that require descriptors rather than raw process IDs.

@@ -2,7 +2,7 @@
 public struct ProcessIdentifier: Sendable, Hashable {
     /// The platform-specific process identifier value
     public let value: pid_t
-    internal let processDescriptor: PlatformFileDescriptor
+    public let processDescriptor: PlatformFileDescriptor
 }
 #endif
 
@@ -10,7 +10,7 @@ public struct ProcessIdentifier: Sendable, Hashable {
 public struct ProcessIdentifier: Sendable, Hashable {
     /// Windows-specific process identifier value
     public let value: DWORD
-    internal nonisolated(unsafe) let processDescriptor: HANDLE
-    internal nonisolated(unsafe) let threadHandle: HANDLE
+    public nonisolated(unsafe) let processDescriptor: HANDLE
+    public nonisolated(unsafe) let threadHandle: HANDLE
 }
 #endif

• Remove runDetached API (#95)

  runDetached was originally proposed as the synchronous counterpart to run(). However, since posix_spawn can block, this API could not be implemented synchronously. It has therefore been removed.

• Make Configuration.workingDirectory optional (#74)

  Configuration.workingDirectory is now optional. A nil value means the subprocess will inherit the parent process’s working directory.

@@ -2,6 +2,6 @@ public struct Configuration: Sendable {
     public var executable: Executable
     public var arguments: Arguments
     public var environment: Environment
-    public var workingDirectory: FilePath
+    public var workingDirectory: FilePath?
     public var platformOptions: PlatformOptions
 }

• AsyncBufferSequence.Buffer Improvements (#48)

  Introduced AsyncBufferSequence.LineSequence as the preferred way to stream output as text. This converts the raw Buffer sequence into an asynchronous sequence of lines.

extension AsyncBufferSequence {
    public struct LineSequence<Encoding: _UnicodeEncoding>: AsyncSequence, Sendable {
        public typealias Element = String

        public enum BufferingPolicy: Sendable {
           case unbounded
           case maxLineLength(Int)
       }

        public struct AsyncIterator: AsyncIteratorProtocol {
            public mutating func next() async throws -> String?
        }

        public func makeAsyncIterator() -> AsyncIterator
    }

    public func lines() -> LineSequence<UTF8>

    public func lines<Encoding: _UnicodeEncoding>(
        encoding: Encoding.Type,
        bufferingPolicy: LineSequence<Encoding>.BufferingPolicy = .maxLineLength(128 * 1024)
    ) -> LineSequence<Encoding>
}

• Make Environment keys case-insensitive on Windows (#174)

  Introduced Environment.Key to provide a platform-aware way of accessing environment variables. Keys are now case-insensitive on Windows, while retaining case sensitivity on platforms where that is the convention.

public struct Key: ExpressibleByStringLiteral, Codable, Hashable, RawRepresentable, CustomStringConvertible, Sendable{
    public var rawValue: String

    public init(stringLiteral rawValue: String)
}