Network receptacles (#3)

* Update getsockopt/setsockopt

* Add getsockopt/setsockopt docs

* Doc updates

Author: lorentey

Sources/Samples/Connect.swift

@@ -38,34 +38,53 @@ struct Connect: ParsableCommand {
   @Flag(help: "Send data out-of-band")
   var outOfBand: Bool = false
 
+  @Option(help: "TCP connection timeout, in seconds")
+  var connectionTimeout: CInt?
+
+  @Option(help: "Socket send timeout, in seconds")
+  var sendTimeout: CInt?
+
+  @Option(help: "Socket receive timeout, in seconds")
+  var receiveTimeout: CInt?
+
+  @Option(help: "TCP connection keepalive interval, in seconds")
+  var keepalive: CInt?
+
   func connect(
     to addresses: [SocketAddress.Info]
   ) throws -> (SocketDescriptor, SocketAddress)? {
-    for addressinfo in addresses {
-      do {
-        let socket = try SocketDescriptor.open(
-          addressinfo.domain,
-          addressinfo.type,
-          addressinfo.protocol)
-        do {
-          try socket.connect(to: addressinfo.address)
-          return (socket, addressinfo.address)
-        }
-        catch {
-          try? socket.close()
-          throw error
-        }
+    // Only try the first address for now
+    guard let addressinfo = addresses.first else { return nil }
+    print(addressinfo)
+    let socket = try SocketDescriptor.open(
+      addressinfo.domain,
+      addressinfo.type,
+      addressinfo.protocol)
+    do {
+      if let connectionTimeout = connectionTimeout {
+        try socket.setOption(.tcp, .tcpConnectionTimeout, to: connectionTimeout)
+      }
+      if let sendTimeout = sendTimeout {
+        try socket.setOption(.socketOption, .sendTimeout, to: sendTimeout)
       }
-      catch {
-        continue
+      if let receiveTimeout = receiveTimeout {
+        try socket.setOption(.socketOption, .receiveTimeout, to: receiveTimeout)
       }
+      if let keepalive = keepalive {
+        try socket.setOption(.tcp, .tcpKeepAlive, to: keepalive)
+      }
+      try socket.connect(to: addressinfo.address)
+      return (socket, addressinfo.address)
+    }
+    catch {
+      try? socket.close()
+      throw error
     }
-    return nil
   }
 
   func run() throws {
     let addresses = try SocketAddress.resolveName(
-      hostname: nil,
+      hostname: hostname,
       service: service,
       family: ipv6 ? .ipv6 : .ipv4,
       type: udp ? .datagram : .stream)

Sources/System/Sockets/SocketAddress+IPv4.swift

@@ -120,7 +120,7 @@ extension SocketAddress.IPv4 {
     }
   }
 
-  /// The port this socket is listening on.
+  /// The port number associated with this address.
   @_alwaysEmitIntoClient
   public var port: SocketAddress.Port {
     get { SocketAddress.Port(CInterop.InPort(_networkOrder: rawValue.sin_port)) }

Sources/System/Sockets/SocketAddress+IPv6.swift

@@ -47,7 +47,7 @@ extension SocketAddress {
     return IPv6(rawValue: value)
   }
 
-  /// Construct a `SocketAddress` holding an IPv4 address and port
+  /// Construct a `SocketAddress` holding an IPv6 address and port
   @_alwaysEmitIntoClient
   public init(ipv6 address: IPv6.Address, port: Port) {
     self.init(IPv6(address: address, port: port))
@@ -107,7 +107,7 @@ extension SocketAddress.IPv6: CustomStringConvertible {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress.IPv6 {
-  /// The port on which this socket is listening.
+  /// The port number associated with this address.
   @_alwaysEmitIntoClient
   public var port: SocketAddress.Port {
     get { SocketAddress.Port(CInterop.InPort(_networkOrder: rawValue.sin6_port)) }
@@ -120,7 +120,7 @@ extension SocketAddress.IPv6 {
   /// A 128-bit IPv6 address.
   @frozen
   public struct Address: RawRepresentable {
-    /// The raw internet address value, in host byte order.
+    /// The raw IPv6 address value. (16 bytes in network byte order.)
     @_alwaysEmitIntoClient
     public var rawValue: CInterop.In6Addr
 
@@ -147,7 +147,7 @@ extension SocketAddress.IPv6.Address {
     Self(rawValue: CInterop.In6Addr())
   }
 
-  /// The IPv4 loopback address "::1".
+  /// The IPv6 loopback address "::1".
   ///
   /// This corresponds to the C constant `IN6ADDR_LOOPBACK_INIT`.
   @_alwaysEmitIntoClient

Sources/System/Sockets/SocketAddress+Local.swift

@@ -14,15 +14,15 @@ 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
+  /// A socket address in the local (a.k.a. UNIX) domain, for inter-process
   /// communication on the same machine.
   ///
   /// The corresponding C type is `sockaddr_un`.
   public struct Local: Hashable {
     internal let _path: FilePath
 
-    /// A "local" (i.e. UNIX domain) socket address, for inter-process
-    /// communication on the same machine.
+    /// Creates a socket address in the local (a.k.a. UNIX) domain,
+    /// for inter-process communication on the same machine.
     ///
     /// The corresponding C type is `sockaddr_un`.
     public init(_ path: FilePath) { self._path = path }
@@ -31,7 +31,7 @@ extension SocketAddress {
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 extension SocketAddress {
-  /// Create a SocketAddress from a local (i.e. UNIX domain) socket address.
+  /// 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
@@ -75,7 +75,7 @@ extension SocketAddress {
 
 // @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 path representing the socket name in the local filesystem namespace.
   ///
   /// The corresponding C struct member is `sun_path`.
   public var path: FilePath { _path }

Sources/System/Sockets/SocketAddress+Resolution.swift

@@ -12,7 +12,8 @@ extension SocketAddress {
   /// Information about a resolved address.
   ///
   /// The members of this struct can be passed directly to
-  /// `SocketDescriptor.connect()` or `SocketDescriptor.bind().
+  /// `SocketDescriptor.open()`, `SocketDescriptor.connect()`
+  /// or `SocketDescriptor.bind()` to initiate connections.
   ///
   /// This loosely corresponds to the C `struct addrinfo`.
   public struct Info {
@@ -390,7 +391,9 @@ extension SocketAddress {
 extension SocketAddress {
   /// Get a list of IP addresses and port numbers for a host and service.
   ///
-  /// TODO: communicate that on failure, this throws a `ResolverError`.
+  /// On failure, this throws either a `ResolverError` or an `Errno`,
+  /// depending on the error code returned by the underlying `getaddrinfo`
+  /// function.
   ///
   /// The method corresponds to the C function `getaddrinfo`.
   public static func resolveName(
@@ -507,6 +510,10 @@ extension SocketAddress {
 extension SocketAddress {
   /// Resolve a socket address to hostname and service name.
   ///
+  /// On failure, this throws either a `ResolverError` or an `Errno`,
+  /// depending on the error code returned by the underlying `getnameinfo`
+  /// function.
+  ///
   /// This method corresponds to the C function `getnameinfo`.
   public static func resolveAddress(
     _ address: SocketAddress,

Sources/System/Sockets/SocketOptions.swift

@@ -442,64 +442,164 @@ extension SocketDescriptor {
 }
 
 extension SocketDescriptor {
-  // TODO: Convenience/performance overloads for `Bool` and other concrete types
-
-  /// Get an option associated with this socket.
+  // TODO: Wrappers and convenience overloads for other concrete types
+  // (timeval, linger)
+  // For now, clients can use the UMRBP-based variants below.
+
+  /// Copy an option associated with this socket into the specified buffer.
+  ///
+  /// The method corresponds to the C function `getsockopt`.
+  ///
+  /// - Parameters:
+  ///    - level: The option level. To get a socket-level option, specify `.socketLevel`.
+  ///       Otherwise use the protocol value that defines your desired option.
+  ///    - option: The option identifier within the level.
+  ///    - buffer: The buffer into which to copy the option value.
+  ///
+  /// - Returns: The number of bytes copied into the supplied buffer.
   @_alwaysEmitIntoClient
-  public func getOption<T>(
-    _ level: ProtocolID, _ option: Option
-  ) throws -> T {
-    try _getOption(level, option).get()
+  public func getOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    into buffer: UnsafeMutableRawBufferPointer
+  ) throws -> Int {
+    try _getOption(level, option, into: buffer).get()
   }
 
-  @usableFromInline
-  internal func _getOption<T>(
-    _ level: ProtocolID, _ option: Option
-  ) -> Result<T, Errno> {
-    // We can't zero-initialize `T` directly, nor can we pass an uninitialized `T`.
-    // to `withUnsafeMutableBytes(of:)`. Instead, we will allocate :-(
-    let rawBuf = UnsafeMutableRawBufferPointer.allocate(
-      byteCount: MemoryLayout<T>.stride,
-      alignment: MemoryLayout<T>.alignment)
-    rawBuf.initializeMemory(as: UInt8.self, repeating: 0)
-    let resultPtr = rawBuf.baseAddress!.bindMemory(to: T.self, capacity: 1)
-    defer {
-      resultPtr.deinitialize(count: 1)
-      rawBuf.deallocate()
+  /// Return the value of an option associated with this socket as a `CInt` value.
+  ///
+  /// The method corresponds to the C function `getsockopt`.
+  ///
+  /// - Parameters:
+  ///    - level: The option level. To get a socket-level option, specify `.socketLevel`.
+  ///       Otherwise use the protocol value that defines your desired option.
+  ///    - option: The option identifier within the level.
+  ///    - type: The type to return. Must be set to `CInt.self` (the default).
+  ///
+  /// - Returns: The current value of the option.
+  @_alwaysEmitIntoClient
+  public func getOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    as type: CInt.Type = CInt.self
+  ) throws -> CInt {
+    var value: CInt = 0
+    try withUnsafeMutableBytes(of: &value) { buffer in
+      // Note: return value is intentionally ignored.
+      _ = try _getOption(level, option, into: buffer).get()
     }
+    return value
+  }
 
-    var length: CInterop.SockLen = 0
+  /// Return the value of an option associated with this socket as a `Bool` value.
+  ///
+  /// The method corresponds to the C function `getsockopt`.
+  ///
+  /// - Parameters:
+  ///    - level: The option level. To get a socket-level option, specify `.socketLevel`.
+  ///       Otherwise use the protocol value that defines your desired option.
+  ///    - option: The option identifier within the level.
+  ///    - type: The type to return. Must be set to `Bool.self` (the default).
+  ///
+  /// - Returns: True if the current value is not zero; otherwise false.
+  @_alwaysEmitIntoClient
+  public func getOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    as type: Bool.Type = Bool.self
+  ) throws -> Bool {
+    try 0 != getOption(level, option, as: CInt.self)
+  }
 
+  @usableFromInline
+  internal func _getOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    into buffer: UnsafeMutableRawBufferPointer
+  ) -> Result<Int, Errno> {
+    var length = CInterop.SockLen(buffer.count)
     let success = system_getsockopt(
       self.rawValue,
       level.rawValue,
       option.rawValue,
-      resultPtr, &length)
+      buffer.baseAddress, &length)
+    return nothingOrErrno(success).map { _ in Int(length) }
+  }
+}
 
-    return nothingOrErrno(success).map { resultPtr.pointee }
+extension SocketDescriptor {
+  /// Set the value of an option associated with this socket to the contents
+  /// of the specified buffer.
+  ///
+  /// The method corresponds to the C function `setsockopt`.
+  ///
+  /// - Parameters:
+  ///    - level: The option level. To set a socket-level option, specify `.socketLevel`.
+  ///       Otherwise use the protocol value that defines your desired option.
+  ///    - option: The option identifier within the level.
+  ///    - buffer: The buffer that contains the desired option value.
+  @_alwaysEmitIntoClient
+  public func setOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    from buffer: UnsafeRawBufferPointer
+  ) throws {
+    try _setOption(level, option, from: buffer).get()
+  }
+
+  /// Set the value of an option associated with this socket to the supplied
+  /// `CInt` value.
+  ///
+  /// The method corresponds to the C function `setsockopt`.
+  ///
+  /// - Parameters:
+  ///    - level: The option level. To set a socket-level option, specify `.socketLevel`.
+  ///       Otherwise use the protocol value that defines your desired option.
+  ///    - option: The option identifier within the level.
+  ///    - value: The desired new value for the option.
+  @_alwaysEmitIntoClient
+  public func setOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    to value: CInt
+  ) throws {
+    return try withUnsafeBytes(of: value) { buffer in
+      // Note: return value is intentionally ignored.
+      _ = try _setOption(level, option, from: buffer).get()
+    }
   }
 
-  /// Set an option associated with this socket.
+  /// Set the value of an option associated with this socket to the supplied
+  /// `Bool` value.
+  ///
+  /// The method corresponds to the C function `setsockopt`.
+  ///
+  /// - Parameters:
+  ///    - level: The option level. To set a socket-level option, specify `.socketLevel`.
+  ///       Otherwise use the protocol value that defines your desired option.
+  ///    - option: The option identifier within the level.
+  ///    - value: The desired new value for the option. (`true` gets stored
+  ///       as `(1 as CInt)`. `false` is represented by `(0 as CInt)`).
   @_alwaysEmitIntoClient
-  public func setOption<T>(
-    _ level: ProtocolID, _ option: Option, to value: T
+  public func setOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    to value: Bool
   ) throws {
-    try _setOption(level, option, to: value).get()
+    try setOption(level, option, to: (value ? 1 : 0) as CInt)
   }
 
   @usableFromInline
-  internal func _setOption<T>(
-    _ level: ProtocolID, _ option: Option, to value: T
-  ) -> Result<(), Errno> {
-    let len = CInterop.SockLen(MemoryLayout<T>.stride)
-    let success = withUnsafeBytes(of: value) {
-      return system_setsockopt(
-        self.rawValue,
-        level.rawValue,
-        option.rawValue,
-        $0.baseAddress,
-        len)
-    }
+  internal func _setOption(
+    _ level: ProtocolID,
+    _ option: Option,
+    from buffer: UnsafeRawBufferPointer
+  ) -> Result<Void, Errno> {
+    let success = system_setsockopt(
+      self.rawValue,
+      level.rawValue,
+      option.rawValue,
+      buffer.baseAddress, CInterop.SockLen(buffer.count))
     return nothingOrErrno(success)
   }
 }