WIP: Apply doc comments and make concrete socket addresses optional properties.

Author: milseman

Sources/Samples/Resolve.swift

@@ -40,9 +40,7 @@ struct Resolve: ParsableCommand {
   var ipv6: Bool = false
 
   func run() throws {
-    var flags = SocketAddress.ResolverFlags()
-    flags.insert(.default)
-    flags.insert(.all)
+    var flags: SocketAddress.ResolverFlags = [.default, .all]
     if canonicalName { flags.insert(.canonicalName) }
     if passive { flags.insert(.passive) }
     if numericHost { flags.insert(.numericHost) }

Sources/System/Sockets/SocketAddress+IPv4.swift

@@ -19,18 +19,6 @@ extension SocketAddress {
       self.rawValue = rawValue
       self.rawValue.sin_family = Family.ipv4.rawValue
     }
-
-    public init?(_ address: SocketAddress) {
-      guard address.family == .ipv4 else { return nil }
-      let value: CInterop.SockAddrIn? = address.withUnsafeBytes { buffer in
-        guard buffer.count >= MemoryLayout<CInterop.SockAddrIn>.size else {
-          return nil
-        }
-        return buffer.baseAddress!.load(as: CInterop.SockAddrIn.self)
-      }
-      guard let value = value else { return nil }
-      self.rawValue = value
-    }
   }
 }
 
@@ -43,21 +31,36 @@ extension SocketAddress {
       SocketAddress(buffer)
     }
   }
+
+  /// If `self` holds an IPv4 address, extract it, otherwise return `nil`.
+  @_alwaysEmitIntoClient
+  public var ipv4: IPv4? {
+    guard family == .ipv4 else { return nil }
+    let value: CInterop.SockAddrIn? = self.withUnsafeBytes { buffer in
+      guard buffer.count >= MemoryLayout<CInterop.SockAddrIn>.size else {
+        return nil
+      }
+      return buffer.baseAddress!.load(as: CInterop.SockAddrIn.self)
+    }
+    guard let value = value else { return nil }
+    return IPv4(rawValue: value)
+  }
 }
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv4 {
   /// Create a socket address from a given Internet address and port number.
   @_alwaysEmitIntoClient
-  public init(address: Address, port: Port) {
+  public init(address: Address, port: SocketAddress.Port) {
     rawValue = CInterop.SockAddrIn()
     rawValue.sin_family = CInterop.SAFamily(SocketDescriptor.Domain.ipv4.rawValue);
     rawValue.sin_port = port.rawValue._networkOrder
     rawValue.sin_addr = CInterop.InAddr(s_addr: address.rawValue._networkOrder)
   }
 
+  /// TODO: doc
   @_alwaysEmitIntoClient
-  public init?(address: String, port: Port) {
+  public init?(address: String, port: SocketAddress.Port) {
     guard let address = Address(address) else { return nil }
     self.init(address: address, port: port)
   }
@@ -84,44 +87,6 @@ extension SocketAddress.IPv4: CustomStringConvertible {
   }
 }
 
-// @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
-extension SocketAddress.IPv4 {
-  @frozen
-  /// The port number on which the socket is listening.
-  public struct Port: RawRepresentable, ExpressibleByIntegerLiteral, Hashable {
-    /// The port number, in host byte order.
-    public var rawValue: CInterop.InPort
-
-    @_alwaysEmitIntoClient
-    public init(_ value: CInterop.InPort) {
-      self.rawValue = value
-    }
-
-    @_alwaysEmitIntoClient
-    public init(rawValue: CInterop.InPort) {
-      self.init(rawValue)
-    }
-
-    @_alwaysEmitIntoClient
-    public init(integerLiteral value: CInterop.InPort) {
-      self.init(value)
-    }
-  }
-
-  @_alwaysEmitIntoClient
-  public var port: Port {
-    get { Port(CInterop.InPort(_networkOrder: rawValue.sin_port)) }
-    set { rawValue.sin_port = newValue.rawValue._networkOrder }
-  }
-}
-
-// @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
-extension SocketAddress.IPv4.Port: CustomStringConvertible {
-  public var description: String {
-    rawValue.description
-  }
-}
-
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv4 {
   @frozen
@@ -134,13 +99,9 @@ extension SocketAddress.IPv4 {
     public init(rawValue: CInterop.InAddrT) {
       self.rawValue = rawValue
     }
-
-    @_alwaysEmitIntoClient
-    public init(_ value: CInterop.InAddrT) {
-      self.rawValue = value
-    }
   }
 
+  /// The 32-bit IPv4 address.
   @_alwaysEmitIntoClient
   public var address: Address {
     get {
@@ -151,38 +112,40 @@ extension SocketAddress.IPv4 {
       rawValue.sin_addr.s_addr = newValue.rawValue._networkOrder
     }
   }
+
+  @_alwaysEmitIntoClient
+  public var port: SocketAddress.Port {
+    get { SocketAddress.Port(CInterop.InPort(_networkOrder: rawValue.sin_port)) }
+    set { rawValue.sin_port = newValue.rawValue._networkOrder }
+  }
 }
 
 extension SocketAddress.IPv4.Address {
   /// The IPv4 address 0.0.0.0.
   ///
   /// This corresponds to the C constant `INADDR_ANY`.
   @_alwaysEmitIntoClient
-  public static var any: Self { Self(_INADDR_ANY) }
+  public static var any: Self { Self(rawValue: _INADDR_ANY) }
 
   /// The IPv4 loopback address 127.0.0.1.
   ///
-  /// This corresponds to the C constant `INADDR_ANY`.
+  /// This corresponds to the C constant `INADDR_LOOPBACK`.
   @_alwaysEmitIntoClient
-  public static var loopback: Self { Self(_INADDR_LOOPBACK) }
+  public static var loopback: Self { Self(rawValue: _INADDR_LOOPBACK) }
 
   /// The IPv4 broadcast address 255.255.255.255.
   ///
   /// This corresponds to the C constant `INADDR_BROADCAST`.
   @_alwaysEmitIntoClient
-  public static var broadcast: Self { Self(_INADDR_BROADCAST) }
+  public static var broadcast: Self { Self(rawValue: _INADDR_BROADCAST) }
 }
 
-
-
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv4.Address: CustomStringConvertible {
-  @_alwaysEmitIntoClient
   public var description: String {
     _inet_ntop()
   }
 
-  @usableFromInline
   internal func _inet_ntop() -> String {
     let addr = CInterop.InAddr(s_addr: rawValue._networkOrder)
     return withUnsafeBytes(of: addr) { src in
@@ -211,13 +174,11 @@ extension SocketAddress.IPv4.Address: CustomStringConvertible {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv4.Address: LosslessStringConvertible {
-  @_alwaysEmitIntoClient
   public init?(_ description: String) {
     guard let value = Self._inet_pton(description) else { return nil }
     self = value
   }
 
-  @usableFromInline
   internal static func _inet_pton(_ string: String) -> Self? {
     string.withCString { ptr in
       var addr = CInterop.InAddr()

Sources/System/Sockets/SocketAddress+IPv6.swift

@@ -19,19 +19,6 @@ extension SocketAddress {
       self.rawValue = rawValue
       self.rawValue.sin6_family = Family.ipv6.rawValue
     }
-
-    @_alwaysEmitIntoClient
-    public init?(_ address: SocketAddress) {
-      guard address.family == .ipv6 else { return nil }
-      let value: CInterop.SockAddrIn6? = address.withUnsafeBytes { buffer in
-        guard buffer.count >= MemoryLayout<CInterop.SockAddrIn6>.size else {
-          return nil
-        }
-        return buffer.baseAddress!.load(as: CInterop.SockAddrIn6.self)
-      }
-      guard let value = value else { return nil }
-      self.rawValue = value
-    }
   }
 }
 
@@ -44,13 +31,28 @@ extension SocketAddress {
       SocketAddress(buffer)
     }
   }
+
+  /// If `self` holds an IPv6 address, extract it, otherwise return `nil`.
+  @_alwaysEmitIntoClient
+  public var ipv6: IPv6? {
+    guard family == .ipv6 else { return nil }
+    let value: CInterop.SockAddrIn6? = self.withUnsafeBytes { buffer in
+      guard buffer.count >= MemoryLayout<CInterop.SockAddrIn6>.size else {
+        return nil
+      }
+      return buffer.baseAddress!.load(as: CInterop.SockAddrIn6.self)
+    }
+    guard let value = value else { return nil }
+    return IPv6(rawValue: value)
+  }
+
 }
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv6 {
   /// Create a socket address from an IPv6 address and port number.
   @_alwaysEmitIntoClient
-  public init(address: Address, port: Port) {
+  public init(address: Address, port: SocketAddress.Port) {
     // FIXME: We aren't modeling flowinfo & scope_id yet.
     // If we need to do that, we can add new arguments or define new
     // initializers/accessors later.
@@ -63,7 +65,7 @@ extension SocketAddress.IPv6 {
   }
 
   @_alwaysEmitIntoClient
-  public init?(address: String, port: Port) {
+  public init?(address: String, port: SocketAddress.Port) {
     guard let address = Address(address) else { return nil }
     self.init(address: address, port: port)
   }
@@ -97,11 +99,9 @@ extension SocketAddress.IPv6: CustomStringConvertible {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv6 {
-  public typealias Port = SocketAddress.IPv4.Port
-
   @_alwaysEmitIntoClient
-  public var port: Port {
-    get { Port(CInterop.InPort(_networkOrder: rawValue.sin6_port)) }
+  public var port: SocketAddress.Port {
+    get { SocketAddress.Port(CInterop.InPort(_networkOrder: rawValue.sin6_port)) }
     set { rawValue.sin6_port = newValue.rawValue._networkOrder }
   }
 }
@@ -118,13 +118,9 @@ extension SocketAddress.IPv6 {
     public init(rawValue: CInterop.In6Addr) {
       self.rawValue = rawValue
     }
-
-    @_alwaysEmitIntoClient
-    public init(_ value: CInterop.In6Addr) {
-      self.rawValue = value
-    }
   }
 
+  /// The 128-bit IPv6 address.
   @_alwaysEmitIntoClient
   public var address: Address {
     get {
@@ -142,7 +138,7 @@ extension SocketAddress.IPv6.Address {
   /// This corresponds to the C constant `IN6ADDR_ANY_INIT`.
   @_alwaysEmitIntoClient
   public static var any: Self {
-    Self(CInterop.In6Addr())
+    Self(rawValue: CInterop.In6Addr())
   }
 
   /// The IPv4 loopback address "::1".
@@ -152,7 +148,7 @@ extension SocketAddress.IPv6.Address {
   public static var loopback: Self {
     var addr = CInterop.In6Addr()
     addr.__u6_addr.__u6_addr8.15 = 1
-    return Self(addr)
+    return Self(rawValue: addr)
   }
 }
 
@@ -193,12 +189,10 @@ extension SocketAddress.IPv6.Address: Hashable {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv6.Address: CustomStringConvertible {
-  @_alwaysEmitIntoClient
   public var description: String {
     _inet_ntop()
   }
 
-  @usableFromInline
   internal func _inet_ntop() -> String {
     return withUnsafeBytes(of: rawValue) { src in
       String(_unsafeUninitializedCapacity: Int(_INET6_ADDRSTRLEN)) { dst in
@@ -226,13 +220,11 @@ extension SocketAddress.IPv6.Address: CustomStringConvertible {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv6.Address: LosslessStringConvertible {
-  @_alwaysEmitIntoClient
   public init?(_ description: String) {
     guard let value = Self._inet_pton(description) else { return nil }
     self = value
   }
 
-  @usableFromInline
   internal static func _inet_pton(_ string: String) -> Self? {
     string.withCString { ptr in
       var addr = CInterop.In6Addr()

Sources/System/Sockets/SocketAddress+Local.swift

@@ -14,31 +14,26 @@ private var _pathOffset: Int {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress {
+  /// A "local" (i.e. UNIX domain) socket address, for inter-process
+  /// communication on the same machine.
+  ///
+  /// The corresponding C type is `sockaddr_un`.
   public struct Local {
     internal let _path: FilePath
 
+    /// A "local" (i.e. UNIX domain) socket address, for inter-process
+    /// communication on the same machine.
+    ///
+    /// The corresponding C type is `sockaddr_un`.
     public init(_ path: FilePath) {
       self._path = path
     }
-
-    public init?(_ address: SocketAddress) {
-      guard address.family == .local else { return nil }
-      let path: FilePath? = address.withUnsafeBytes { buffer in
-        guard buffer.count >= _pathOffset + 1 else {
-          return nil
-        }
-        let path = (buffer.baseAddress! + _pathOffset)
-          .assumingMemoryBound(to: CInterop.PlatformChar.self)
-        return FilePath(platformString: path)
-      }
-      guard path != nil else { return nil }
-      self._path = path!
-    }
   }
 }
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress {
+  /// Create a SocketAddress from a local (i.e. UNIX domain) socket address.
   public init(_ local: Local) {
     let offset = _pathOffset
     let length = offset + local._path.length + 1
@@ -57,10 +52,28 @@ extension SocketAddress {
       return length
     }
   }
+
+  /// If `self` holds a local address, extract it, otherwise return `nil`.
+  public var local: Local? {
+    guard family == .local else { return nil }
+    let path: FilePath? = self.withUnsafeBytes { buffer in
+      guard buffer.count >= _pathOffset + 1 else {
+        return nil
+      }
+      let path = (buffer.baseAddress! + _pathOffset)
+        .assumingMemoryBound(to: CInterop.PlatformChar.self)
+      return FilePath(platformString: path)
+    }
+    guard path != nil else { return nil }
+    return Local(path!)
+  }
 }
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.Local {
+  /// The path to the file used to advertise the socket name to clients.
+  ///
+  /// The corresponding C struct member is `sun_path`.
   public var path: FilePath { _path }
 }