Source code documentation updates

dcantah · dcantah · commit 86378a72e1f8 · 2025-06-04T10:34:42.000-07:00
This change adds documentation to quite a few existing public types
that didn't have a blurb before.

Additionally, this fixes a couple things that I think either didn't make sense
when going to document them:
- Rename ConnectionStream to VsockConnectionStream. This type only functions for
vsock connections.
- Deletes NsLock+Closure. This was not used anywhere.
- Rename ContainerizationOCI/Config.swift to ImageConfig.swift.

Signed-off-by: Danny Canter &lt;danny_canter@apple.com&gt;
diff --git a/Sources/Containerization/DNSConfiguration.swift b/Sources/Containerization/DNSConfiguration.swift
@@ -14,6 +14,8 @@
 // limitations under the License.
 //===----------------------------------------------------------------------===//
 
+/// DNS configuration for a container. The values will be used to
+/// construct /etc/resolv.conf for a given container.
 public struct DNS: Sendable {
     public static let defaultNameservers = ["1.1.1.1"]
 
diff --git a/Sources/Containerization/Image/Image.swift b/Sources/Containerization/Image/Image.swift
@@ -26,6 +26,7 @@ import SystemPackage
 import ContainerizationExtras
 #endif
 
+/// Type representing an OCI container image.
 public struct Image: Sendable {
 
     private let contentStore: ContentStore
diff --git a/Sources/Containerization/Image/InitImage.swift b/Sources/Containerization/Image/InitImage.swift
@@ -18,6 +18,9 @@ import ContainerizationError
 import ContainerizationOCI
 import Foundation
 
+/// Data representing the image to use as the root filesystem for a virtual machine.
+/// Typically this image would contain the guest agent used to facilitate container
+/// workloads, as well as any extras that may be useful to have in the guest.
 public struct InitImage: Sendable {
     public var name: String { image.reference }
 
diff --git a/Sources/Containerization/Kernel.swift b/Sources/Containerization/Kernel.swift
@@ -16,7 +16,9 @@
 
 import Foundation
 
-/// A kernel used to boot a sandbox.
+/// An object representing a Linux kernel used to boot a virtual machine.
+/// In addition to a path to the kernel itself, this type stores relevant
+/// data such as the commandline to pass to the kernel, and init arguments.
 public struct Kernel: Sendable, Codable {
     /// The command line arguments passed to the kernel on boot.
     public struct CommandLine: Sendable, Codable {
diff --git a/Sources/Containerization/LinuxProcess.swift b/Sources/Containerization/LinuxProcess.swift
@@ -163,7 +163,7 @@ public final class LinuxProcess: Sendable {
 }
 
 extension LinuxProcess {
-    func setupIO(streams: [ConnectionStream?]) async throws -> [FileHandle?] {
+    func setupIO(streams: [VsockConnectionStream?]) async throws -> [FileHandle?] {
         let handles = try await Timeout.run(seconds: 3) {
             await withTaskGroup(of: (Int, FileHandle?).self) { group in
                 var results = [FileHandle?](repeating: nil, count: 3)
@@ -231,7 +231,7 @@ extension LinuxProcess {
     public func start() async throws {
         let spec = self.state.withLock { $0.spec }
 
-        var streams = [ConnectionStream?](repeating: nil, count: 3)
+        var streams = [VsockConnectionStream?](repeating: nil, count: 3)
         if let stdin = self.ioSetup.stdin {
             streams[0] = try self.vm.listen(stdin.port)
         }
diff --git a/Sources/Containerization/NATNetworkInterface.swift b/Sources/Containerization/NATNetworkInterface.swift
@@ -22,6 +22,8 @@ import ContainerizationError
 import Foundation
 import Synchronization
 
+/// An interface that uses NAT to provide an IP address for a given
+/// container/virtual machine.
 @available(macOS 16, *)
 public final class NATNetworkInterface: Interface, Sendable {
     public var address: String {
diff --git a/Sources/Containerization/SystemPlatform.swift b/Sources/Containerization/SystemPlatform.swift
@@ -16,6 +16,9 @@
 
 import ContainerizationOCI
 
+/// `SystemPlatform` describes an operating system and architecture pair.
+/// This is primarily used to choose what kind of OCI image to pull from a
+/// registry.
 public struct SystemPlatform: Sendable, Codable {
     public enum OS: String, CaseIterable, Sendable, Codable {
         case linux
diff --git a/Sources/Containerization/VZVirtualMachineInstance.swift b/Sources/Containerization/VZVirtualMachineInstance.swift
@@ -184,8 +184,8 @@ extension VZVirtualMachineInstance {
         ).dupHandle()
     }
 
-    func listen(_ port: UInt32) throws -> ConnectionStream {
-        let stream = ConnectionStream(port: port)
+    func listen(_ port: UInt32) throws -> VsockConnectionStream {
+        let stream = VsockConnectionStream(port: port)
         let listener = VZVirtioSocketListener()
         listener.delegate = stream
 
diff --git a/Sources/Containerization/VirtualMachineInstance.swift b/Sources/Containerization/VirtualMachineInstance.swift
@@ -39,7 +39,7 @@ public protocol VirtualMachineInstance: Sendable {
     /// Dial a vsock port in the guest.
     func dial(_ port: UInt32) async throws -> FileHandle
     /// Listen on a host vsock port.
-    func listen(_ port: UInt32) throws -> ConnectionStream
+    func listen(_ port: UInt32) throws -> VsockConnectionStream
     /// Stop listening on a vsock port.
     func stopListen(_ port: UInt32) throws
     /// Start the virtual machine.
diff --git a/Sources/Containerization/VsockConnectionStream.swift b/Sources/Containerization/VsockConnectionStream.swift
@@ -20,12 +20,14 @@ import Foundation
 import Virtualization
 #endif
 
-public final class ConnectionStream: NSObject, Sendable {
+/// A stream of vsock connections.
+public final class VsockConnectionStream: NSObject, Sendable {
     /// A stream of connections dialed from the remote.
     public let connections: AsyncStream<FileHandle>
+    /// The port the connections are for.
+    public let port: UInt32
 
     private let cont: AsyncStream<FileHandle>.Continuation
-    private let port: UInt32
 
     public init(port: UInt32) {
         self.port = port
@@ -41,7 +43,7 @@ public final class ConnectionStream: NSObject, Sendable {
 
 #if os(macOS)
 
-extension ConnectionStream: VZVirtioSocketListenerDelegate {
+extension VsockConnectionStream: VZVirtioSocketListenerDelegate {
     public func listener(
         _: VZVirtioSocketListener, shouldAcceptNewConnection conn: VZVirtioSocketConnection,
         from _: VZVirtioSocketDevice
diff --git a/Sources/ContainerizationExtras/AsyncLock.swift b/Sources/ContainerizationExtras/AsyncLock.swift
@@ -16,6 +16,10 @@
 
 import Foundation
 
+/// `AsyncLock` provides a familiar locking API, with the main benefit being that it
+/// is safe to call async methods while holding the lock. This is primarily used in spots
+/// where an actor makes sense, but we may need to ensure we don't fall victim to actor
+/// reentrancy issues.
 public actor AsyncLock {
     private var busy = false
     private var queue: ArraySlice<CheckedContinuation<(), Never>> = []
diff --git a/Sources/ContainerizationExtras/Timeout.swift b/Sources/ContainerizationExtras/Timeout.swift
@@ -16,7 +16,11 @@
 
 import Foundation
 
+/// `Timeout` contains helpers to run an operation and error out if
+/// the operation does not finish within a provided time.
 public struct Timeout {
+    /// Performs the passed in `operation` and throws a `CancellationError` if the operation
+    /// doesn't finish in the provided `seconds` amount.
     public static func run<T: Sendable>(
         seconds: UInt32,
         operation: @escaping @Sendable () async -> T
diff --git a/Sources/ContainerizationIO/ReadStream.swift b/Sources/ContainerizationIO/ReadStream.swift
@@ -18,6 +18,8 @@ import ContainerizationOS
 import Foundation
 import NIO
 
+/// `ReadStream` is a utility type for streaming data from a `URL`
+/// or `Data` blob.
 public class ReadStream {
     public static let bufferSize = Int(1.mib())
 
diff --git a/Sources/ContainerizationNetlink/NetlinkSession.swift b/Sources/ContainerizationNetlink/NetlinkSession.swift
@@ -18,6 +18,9 @@ import ContainerizationExtras
 import ContainerizationOS
 import Logging
 
+/// `NetlinkSession` facilitates interacting with netlink via a provided
+/// `NetlinkSocket`. This is the core high level type offered to perform
+/// actions to the netlink surface in the kernel.
 public struct NetlinkSession {
     private static let receiveDataLength = 65536
 
diff --git a/Sources/ContainerizationOCI/Bundle.swift b/Sources/ContainerizationOCI/Bundle.swift
@@ -27,6 +27,8 @@ private let _mount = Glibc.mount
 private let _umount = Glibc.umount2
 #endif
 
+/// `Bundle` represents an OCI runtime spec bundle for running
+/// a container.
 public struct Bundle: Sendable {
     public let path: URL
 
diff --git a/Sources/ContainerizationOCI/ImageConfig.swift b/Sources/ContainerizationOCI/ImageConfig.swift
diff --git a/Sources/ContainerizationOS/AsyncSignalHandler.swift b/Sources/ContainerizationOS/AsyncSignalHandler.swift
@@ -17,6 +17,8 @@
 import Foundation
 import Synchronization
 
+/// Async friendly wrapper around DispatchSourceSignal. Provided an AsyncStream
+/// interface to get notified of received signals.
 public final class AsyncSignalHandler: Sendable {
     /// An async stream that returns the signal that was caught, if ever
     public var signals: AsyncStream<Int32> {
diff --git a/Sources/ContainerizationOS/File.swift b/Sources/ContainerizationOS/File.swift
@@ -16,6 +16,7 @@
 
 import Foundation
 
+/// Trivial type to discover information about a given file (uid, gid, mode...).
 public struct File: Sendable {
     public enum Error: Swift.Error, CustomStringConvertible {
         case errno(_ e: Int32)
diff --git a/Sources/ContainerizationOS/Linux/Epoll.swift b/Sources/ContainerizationOS/Linux/Epoll.swift
@@ -27,7 +27,8 @@ import Glibc
 import Foundation
 import Synchronization
 
-/// Register file descriptors to receive events.
+/// Register file descriptors to receive events via Linux's
+/// epoll syscall surface.
 public final class Epoll: Sendable {
     public typealias Mask = Int32
     public typealias Handler = (@Sendable (Mask) -> Void)
diff --git a/Sources/ContainerizationOS/Mount/Mount.swift b/Sources/ContainerizationOS/Mount/Mount.swift
@@ -30,6 +30,8 @@ private let _umount = Glibc.umount2
 /// Technically, this would be fine in the Linux subdirectory as it's Linux specific for now, but that
 /// might not always be the case.
 
+/// `Mount` models a Linux mount (although potentially could be used on other unix platforms), and
+/// provides a simple interface to mount what the type describes.
 public struct Mount: Sendable {
     // Type specifies the host-specific of the mount.
     public var type: String
@@ -108,6 +110,17 @@ extension Mount {
         return false
     }
 
+    public func mount(root: String, createWithPerms: Int16? = nil) throws {
+        var rootURL = URL(fileURLWithPath: root)
+        rootURL = rootURL.resolvingSymlinksInPath()
+        rootURL = rootURL.appendingPathComponent(self.target)
+        try self.mountToTarget(target: rootURL.path, createWithPerms: createWithPerms)
+    }
+
+    public func mount(createWithPerms: Int16? = nil) throws {
+        try self.mountToTarget(target: self.target, createWithPerms: createWithPerms)
+    }
+
     private func mountToTarget(target: String, createWithPerms: Int16?) throws {
         let pageSize = sysconf(_SC_PAGESIZE)
 
@@ -154,17 +167,6 @@ extension Mount {
         }
     }
 
-    public func mount(root: String, createWithPerms: Int16? = nil) throws {
-        var rootURL = URL(fileURLWithPath: root)
-        rootURL = rootURL.resolvingSymlinksInPath()
-        rootURL = rootURL.appendingPathComponent(self.target)
-        try self.mountToTarget(target: rootURL.path, createWithPerms: createWithPerms)
-    }
-
-    public func mount(createWithPerms: Int16? = nil) throws {
-        try self.mountToTarget(target: self.target, createWithPerms: createWithPerms)
-    }
-
     private func mkdirAll(_ name: String, _ perm: Int16) throws {
         try FileManager.default.createDirectory(
             atPath: name,
diff --git a/Sources/ContainerizationOS/NSLock+Closure.swift b/Sources/ContainerizationOS/NSLock+Closure.swift
diff --git a/Sources/ContainerizationOS/Path.swift b/Sources/ContainerizationOS/Path.swift
@@ -16,6 +16,8 @@
 
 import Foundation
 
+/// `Path` provides utilities to look for binaries in the current PATH,
+/// or to return the current PATH.
 public struct Path {
     /// lookPath looks up an executable's path from $PATH
     public static func lookPath(_ name: String) -> URL? {
diff --git a/Sources/ContainerizationOS/Signals.swift b/Sources/ContainerizationOS/Signals.swift
@@ -16,6 +16,7 @@
 
 import Foundation
 
+/// Helper type with utilities to parse and manipulate unix signals.
 public struct Signals {
     public static func allNumeric() -> [Int32] {
         Array(Signals.all.values)
diff --git a/Sources/ContainerizationOS/Socket/Socket.swift b/Sources/ContainerizationOS/Socket/Socket.swift
@@ -44,6 +44,7 @@ let sysConnect = connect
 let sysIoctl: @convention(c) (CInt, CUnsignedLong, UnsafeMutableRawPointer) -> CInt = ioctl
 #endif
 
+/// Threadsafe socket wrapper.
 public final class Socket: Sendable {
     public enum TimeoutOption {
         case send
diff --git a/Sources/ContainerizationOS/Socket/SocketType.swift b/Sources/ContainerizationOS/Socket/SocketType.swift
@@ -24,6 +24,7 @@ import Darwin
 #error("SocketType not supported on this platform.")
 #endif
 
+/// Protocol used to describe the family of socket to be created with `Socket`.
 public protocol SocketType: Sendable, CustomStringConvertible {
     var domain: Int32 { get }
     var type: Int32 { get }
diff --git a/Sources/ContainerizationOS/Socket/UnixType.swift b/Sources/ContainerizationOS/Socket/UnixType.swift
@@ -27,6 +27,7 @@ let _SOCK_STREAM = SOCK_STREAM
 #error("UnixType not supported on this platform.")
 #endif
 
+/// Unix domain socket variant of `SocketType`.
 public struct UnixType: SocketType, Sendable, CustomStringConvertible {
     public var domain: Int32 { AF_UNIX }
     public var type: Int32 { _SOCK_STREAM }
diff --git a/Sources/ContainerizationOS/Socket/VsockType.swift b/Sources/ContainerizationOS/Socket/VsockType.swift
@@ -26,6 +26,7 @@ import Darwin
 #error("VsockType not supported on this platform.")
 #endif
 
+/// Vsock variant of `SocketType`.
 public struct VsockType: SocketType, Sendable {
     public var domain: Int32 { AF_VSOCK }
     public var type: Int32 { _SOCK_STREAM }
diff --git a/Sources/ContainerizationOS/Syscall.swift b/Sources/ContainerizationOS/Syscall.swift
@@ -24,6 +24,7 @@ import Darwin
 #error("retryingSyscall not supported on this platform.")
 #endif
 
+/// Helper type to deal with running system calls.
 public struct Syscall {
     /// Retry a syscall on EINTR.
     public static func retrying<T: FixedWidthInteger>(_ closure: () -> T) -> T {
diff --git a/Sources/ContainerizationOS/Sysctl.swift b/Sources/ContainerizationOS/Sysctl.swift
@@ -16,6 +16,7 @@
 
 import Foundation
 
+/// Helper type to deal with system control functionalities.
 public struct Sysctl {
     #if os(macOS)
     /// Simple `sysctlbyname` wrapper.
diff --git a/Sources/ContainerizationOS/Terminal.swift b/Sources/ContainerizationOS/Terminal.swift
@@ -16,6 +16,8 @@
 
 import Foundation
 
+/// `Terminal` provides a clean interface to deal with terminal
+/// interactions on Unix platforms.
 public struct Terminal: Sendable {
     private let initState: termios?
 
diff --git a/Sources/ContainerizationOS/User.swift b/Sources/ContainerizationOS/User.swift
@@ -17,6 +17,8 @@
 import ContainerizationError
 import Foundation
 
+/// `User` provides utilities to ensure that a given username exists in
+/// /etc/passwd (and /etc/group).
 public enum User {
     private static let passwdFile = "/etc/passwd"
     private static let groupFile = "/etc/group"
diff --git a/Sources/cctl/ContainerStore.swift b/Sources/cctl/ContainerStore.swift
@@ -35,7 +35,7 @@ extension String {
 
 #endif
 
-public final class ContainerStore: Sendable {
+public struct ContainerStore: Sendable {
     private static let initImage = "vminit:latest"
 
     private let content: ContentStore

Original file line number	Diff line number	Diff line change
`@@ -184,8 +184,8 @@ extension VZVirtualMachineInstance {`
`184`	`184`	`).dupHandle()`
`185`	`185`	`}`
`186`	`186`
`187`		`- func listen(_ port: UInt32) throws -> ConnectionStream {`
`188`		`- let stream = ConnectionStream(port: port)`
	`187`	`+ func listen(_ port: UInt32) throws -> VsockConnectionStream {`
	`188`	`+ let stream = VsockConnectionStream(port: port)`
`189`	`189`	`let listener = VZVirtioSocketListener()`
`190`	`190`	`listener.delegate = stream`
`191`	`191`