Socket updates (#4)

* Update getsockopt/setsockopt

* Add getsockopt/setsockopt docs

* Doc updates

* Add overloads for bind/connect taking concrete address types

* ShutdownKind: Remove Codable conformance.

* Listen: close the client connection socket before exiting

This is supposed to demonstrate acceptable use, we can’t leave resource cleanup to exit()

* Make IPv4.Address and IPv6.Address expressible by string literals

* Document SocketAddress better.

Author: lorentey

Sources/Samples/Listen.swift

@@ -106,12 +106,14 @@ struct Listen: ParsableCommand {
       } else {
         let conn = try socket.accept(client: &client)
         complain("Connection from \(client.niceDescription)")
-        while true {
-          let (count, flags) =
+        try conn.closeAfter {
+          while true {
+            let (count, flags) =
             try conn.receive(into: buffer, sender: &client, ancillary: &ancillary)
-          guard count > 0 else { break }
-          print(prefix(client: client, flags: flags), terminator: "")
-          try FileDescriptor.standardOutput.writeAll(buffer[..<count])
+            guard count > 0 else { break }
+            print(prefix(client: client, flags: flags), terminator: "")
+            try FileDescriptor.standardOutput.writeAll(buffer[..<count])
+          }
         }
       }
     }

Sources/System/Sockets/SocketAddress+IPv4.swift

@@ -47,7 +47,7 @@ extension SocketAddress {
     return IPv4(rawValue: value)
   }
 
-  /// Construct a `SocketAddress` holding an IPv4 address and port
+  /// Construct a `SocketAddress` holding an IPv4 address and port number.
   @_alwaysEmitIntoClient
   public init(ipv4 address: IPv4.Address, port: Port) {
     self.init(IPv4(address: address, port: port))
@@ -194,3 +194,13 @@ extension SocketAddress.IPv4.Address: LosslessStringConvertible {
     }
   }
 }
+
+// @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
+extension SocketAddress.IPv4.Address: ExpressibleByStringLiteral {
+  public init(stringLiteral value: String) {
+    guard let address = Self(value) else {
+      preconditionFailure("'\(value)' is not a valid IPv4 address string")
+    }
+    self = address
+  }
+}

Sources/System/Sockets/SocketAddress+IPv6.swift

@@ -238,3 +238,13 @@ extension SocketAddress.IPv6.Address: LosslessStringConvertible {
     }
   }
 }
+
+// @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
+extension SocketAddress.IPv6.Address: ExpressibleByStringLiteral {
+  public init(stringLiteral value: String) {
+    guard let address = Self(value) else {
+      preconditionFailure("'\(value)' is not a valid IPv6 address string")
+    }
+    self = address
+  }
+}

Sources/System/Sockets/SocketAddress.swift

@@ -8,11 +8,57 @@
 */
 
 // @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
-/// An opaque type holding a socket address and port number in some address family.
+/// An opaque type representing a socket address in some address family,
+/// such as an IP address along with a port number.
 ///
-/// TODO: Show examples of creating an ipv4 and ipv6 address
+/// `SocketAddress` values can be passed directly to `SocketDescriptor.connect`
+/// or `.bind` to establish a network connection.
 ///
-/// The corresponding C type is `sockaddr_t`
+/// We can use the `SocketAddress.resolveName` method resolve a pair of
+/// host/service name strings to a list of socket addresses:
+///
+///     let results =
+///       try SocketAddress.resolveName(hostname: "swift.org", service: "https")
+///     for result in results {
+///       let try socket =
+///         SocketDescriptor.open(result.domain, result.type, result.protocol)
+///       do {
+///         try socket.connect(to: result.address)
+///       } catch {
+///         try? socket.close()
+///         throw error
+///       }
+///       return socket
+///     }
+///
+/// To create an IPv4, IPv6 or Local domain address, we can use convenience
+/// initializers that take the corresponding information:
+///
+///     let ipv4 = SocketAddress(ipv4: "127.0.0.1", port: 8080)!
+///     let ipv6 = SocketAddress(ipv6: "::1", port: 80)!
+///     let local = SocketAddress(local: "/var/run/example.sock")
+///
+/// (Note that you may prefer to use the concrete address types
+/// `SocketAddress.IPv4`, `SocketAddress.IPv6` and `SocketAddress.Local`
+/// instead -- they provide easy access to the address parameters.)
+///
+/// `SocketAddress` also provides ways to access its underlying contents
+/// as a raw unsafe memory buffer. This is useful for dealing with address
+/// families that `System` doesn't model, or for passing the socket address
+/// to C functions that expect a pointer to a `sockaddr` value.
+///
+/// `SocketAddress` stores its contents in a managed storage buffer, and
+/// it can serve as a reusable receptacle for addresses that are returned
+/// by system calls. You can use the `init(minimumCapacity:)` initializer
+/// to create an empty socket address with the specified storage capacity,
+/// then you can pass it to functions like `.accept(client:)` to retrieve
+/// addresses without repeatedly allocating memory.
+///
+/// `SocketAddress` is able to hold any IPv4 or IPv6 address without allocating
+/// any memory. For other address families, it may need to heap allocate a
+/// storage buffer, depending on the size of the stored value.
+///
+/// The corresponding C type is `sockaddr_t`.
 public struct SocketAddress {
   internal var _variant: _Variant
 

Sources/System/Sockets/SocketDescriptor.swift

@@ -330,7 +330,7 @@ extension SocketDescriptor {
 
   /// Specify the part (or all) of a full-duplex connection to shutdown.
   @frozen
-  public struct ShutdownKind: RawRepresentable, Hashable, Codable, CustomStringConvertible {
+  public struct ShutdownKind: RawRepresentable, Hashable, CustomStringConvertible {
     @_alwaysEmitIntoClient
     public var rawValue: CInt
 

Sources/System/Sockets/SocketOperations.swift

@@ -48,14 +48,38 @@ extension SocketDescriptor {
     }.map(SocketDescriptor.init(rawValue:))
   }
 
-  /// Bind a name to a socket.
+  /// Bind a socket to an address.
   ///
   /// The corresponding C function is `bind`.
   @_alwaysEmitIntoClient
   public func bind(to address: SocketAddress) throws {
     try _bind(to: address).get()
   }
 
+  /// Bind a socket to an IPv4 address.
+  ///
+  /// The corresponding C function is `bind`.
+  @_alwaysEmitIntoClient
+  public func bind(to address: SocketAddress.IPv4) throws {
+    try _bind(to: SocketAddress(address)).get()
+  }
+
+  /// Bind a socket to an IPv6 address.
+  ///
+  /// The corresponding C function is `bind`.
+  @_alwaysEmitIntoClient
+  public func bind(to address: SocketAddress.IPv6) throws {
+    try _bind(to: SocketAddress(address)).get()
+  }
+
+  /// Bind a socket to an address in the local domain.
+  ///
+  /// The corresponding C function is `bind`.
+  @_alwaysEmitIntoClient
+  public func bind(to address: SocketAddress.Local) throws {
+    try _bind(to: SocketAddress(address)).get()
+  }
+
   @usableFromInline
   internal func _bind(to address: SocketAddress) -> Result<(), Errno> {
     let success = address.withUnsafeCInterop { addr, len in
@@ -139,6 +163,30 @@ extension SocketDescriptor {
     try _connect(to: address).get()
   }
 
+  /// Initiate a connection to an IPv4 address.
+  ///
+  /// The corresponding C function is `connect`.
+  @_alwaysEmitIntoClient
+  public func connect(to address: SocketAddress.IPv4) throws {
+    try _connect(to: SocketAddress(address)).get()
+  }
+
+  /// Initiate a connection to an IPv6 address.
+  ///
+  /// The corresponding C function is `connect`.
+  @_alwaysEmitIntoClient
+  public func connect(to address: SocketAddress.IPv6) throws {
+    try _connect(to: SocketAddress(address)).get()
+  }
+
+  /// Initiate a connection to an address in the local domain.
+  ///
+  /// The corresponding C function is `connect`.
+  @_alwaysEmitIntoClient
+  public func connect(to address: SocketAddress.Local) throws {
+    try _connect(to: SocketAddress(address)).get()
+  }
+
   @usableFromInline
   internal func _connect(to address: SocketAddress) -> Result<(), Errno> {
     let success = address.withUnsafeCInterop { addr, len in