DOCSEARCHbyAlgolia
Submit Docs

NIO Transport Services

repository·main·Indexed 43 days ago

https://github.com/apple/swift-nio-transport-services

An extension for SwiftNIO that provides first-class support for Apple platforms by leveraging Network.framework and Dispatch. It enables the use of NIO's programming model while providing native support for proxies, VPNs, and connectivity waiting on macOS 10.14+, iOS 12+, tvOS 12+, and watchOS 6+.

Tokens
2.3K
Snippets
4
Records
12
Agent score
53%

What's inside NIOTS

  1. What is NIO Transport Services and when to use it?

    main

    NIO Transport Services (NIOTS) is an extension to SwiftNIO that provides first-class support for Apple platforms by leveraging Network.framework for connectivity and Dispatch for concurrency.

    Key Benefits

    • Network.framework Integration: Provides richer insights into network behavior than standard NIO, including the ability to wait for connectivity until a network route is available.
    • Native Support: Includes built-in support for proxy and VPN configurations provided by the OS.
    • Seamless Migration: Regular SwiftNIO applications can migrate to NIOTS by simply replacing their existing EventLoop, EventLoopGroup, and Bootstrap implementations with the NIOTS alternatives.

    Supported Platforms

    NIOTS is functionally useful on platforms where Network.framework is available:

    • macOS 10.14+
    • iOS 12+
    • tvOS 12+
    • watchOS 6+

  2. What is NIO Transport Services and how does it work?

    main

    NIO Transport Services (NIOTS) is an extension for SwiftNIO that provides first-class support for Apple platforms.

    Instead of using standard POSIX sockets, NIOTS uses Apple's Network.framework for network connectivity and Dispatch for concurrency. This allows NIOTS to provide:

    • Richer network insights than standard NIO.
    • The ability to wait for connectivity until a network route becomes available.
    • Built-in support for proxies and VPNs via Network.framework.

    To use it, you simply replace your existing NIO EventLoop, EventLoopGroup, and Bootstraps with the NIOTS equivalents.

  3. Install NIO Transport Services via Swift Package Manager

    main

    To use NIO Transport Services in your Swift project, add it as a dependency in your Package.swift file. For the 1.x version family, use the following configuration:

    dependencies: [
    .package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.13.0")
]

  4. Install NIO Transport Services in Xcode

    main

    If you are using an Xcode project (Xcode 11+):

    1. Go to File -> Swift Packages -> Add Package Dependency.
    2. Enter https://github.com/apple/swift-nio-transport-services.git and click Next twice.
    3. Select the NIOTransportServices module and click Finish.
    4. You can then use import NIOTransportServices in your source files.

  5. Add NIO Transport Services as a dependency

    main

    To use NIO Transport Services in your project, add it as a dependency via Swift Package Manager (SwiftPM) or Xcode.

    Using SwiftPM

    Add the following to your Package.swift dependencies clause:

    dependencies: [
    .package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.13.0")
]

    Then, add NIOTransportServices to your target's dependencies.

    Using Xcode

    1. Go to File -> Swift Packages -> Add Package Dependency.
    2. Enter https://github.com/apple/swift-nio-transport-services.git and click Next twice.
    3. Select NIOTransportServices and click Finish.
    4. You can then use import NIOTransportServices in your code.

  6. Supported Platforms and Availability

    main

    NIOTS is functionally useful on platforms where Network.framework is available:

    • macOS: 10.14+
    • iOS: 12+
    • tvOS: 12+
    • watchOS: 6+

    Note that the library can be built on other platforms (macOS 10.12+, iOS 10+, tvOS 10+, watchOS 6+, and Linux) because code is protected by import guards, but it will only provide the Transport Services functionality on the supported versions listed above.

  7. Swift version compatibility for NIO Transport Services 1.x

    main

    The 1.x version family requires Swift 5.7 or newer for the latest releases, though older versions support older Swift toolchains. Refer to the table below for specific minimum requirements:

    NIOTS VersionMinimum Swift Version
    1.0.0 ..< 1.11.05.0
    1.11.0 ..< 1.12.05.2
    1.12.0 ..< 1.15.05.4
    1.15.0 ..< 1.17.05.5.2
    1.17.0 ..< 1.19.05.6
    1.19.0 ..< 1.21.05.7
    1.21.0 ..< 1.25.05.8
    1.25.0 ..< 1.26.05.10
    1.26.0 ..< 1.27.06.0
    1.27.0 ...6.1

  8. NIO Transport Services 1.x Compatibility and Versioning

    main

    NIO Transport Services 1.x is part of the SwiftNIO 2 family. It requires swift-nio and an Apple OS supporting Network.framework.

    Swift Version Requirements

    Depending on the version of swift-nio-transport-services you are using, the minimum required Swift version varies:

    Version RangeMinimum Swift Version
    1.0.0 ..< 1.11.05.0
    1.11.0 ..< 1.12.05.2
    1.12.0 ..< 1.14.05.4
    1.15.0 ..< 1.17.05.5.2
    1.17.0 ..< 1.19.05.6
    1.19.0 ..< 1.21.05.7
    1.21.0 ...5.8

  9. Use NIOTSConnectionBootstrap to connect via Network.framework

    main

    To establish a connection using Apple's Network.framework via swift-nio-transport-services, use NIOTSConnectionBootstrap. This bootstrap allows you to configure TLS options using NWProtocolTLS.Options() and set connection timeouts. It is typically used within an NIOTSEventLoopGroup and requires a channelInitializer to set up the pipeline (e.g., adding HTTP handlers).

    let group = NIOTSEventLoopGroup()
let channel = try! NIOTSConnectionBootstrap(group: group)
    .connectTimeout(.hours(1))
    .channelOption(ChannelOptions.socket(IPPROTO_TCP, TCP_NODELAY), value: 1)
    .tlsOptions(NWProtocolTLS.Options())
    .channelInitializer { channel in
        channel.eventLoop.makeCompletedFuture {
            try channel.pipeline.syncOperations.addHTTPClientHandlers()
            // Add custom handlers here
        }
    }
    .connect(host: "httpbin.org", port: 443)
    .wait()

// Wait for the connection to close
try! channel.closeFuture.wait()

  10. Run a basic HTTP/1.1 server using NIOTSListenerBootstrap

    main

    To create a basic HTTP/1.1 server using NIOTransportServices, use NIOTSListenerBootstrap to bind to a host and port. You must provide an NIOTSEventLoopGroup and configure the channel pipeline. A common pattern is to use configureHTTPServerPipeline to set up standard HTTP/1.1 handling and then add a custom ChannelInboundHandler to process requests.

    Note: This requires Network.framework support, available on macOS 10.14+, iOS 12.0+, tvOS 12.0+, and watchOS 6.0+.

    import NIOCore
import NIOTransportServices
import NIOHTTP1
import Network

let group = NIOTSEventLoopGroup()
let channel = try! NIOTSListenerBootstrap(group: group)
    .childChannelInitializer { channel in
        channel.eventLoop.makeCompletedFuture { 
            try channel.pipeline.syncOperations.configureHTTPServerPipeline(
                withPipeliningAssistance: true,
                withErrorHandling: true
            )
            // Add your custom handler here
            try channel.pipeline.syncOperations.addHandler(HTTP1ServerHandler())
        }
    }
    .bind(host: "127.0.0.1", port: 8888)
    .wait()

print("Server listening on \(channel.localAddress!)")
try! channel.closeFuture.wait()

  11. Configure an HTTP/1.1 server pipeline

    main

    When setting up an HTTP server with NIOTSListenerBootstrap, use the configureHTTPServerPipeline method on the channel's pipeline to enable standard HTTP/1.1 features.

    Available parameters:

    • withPipeliningAssistance: Boolean indicating whether to enable assistance for HTTP pipelining.
    • withErrorHandling: Boolean indicating whether to enable standard HTTP error handling in the pipeline.

  12. Configure NIOTSConnectionBootstrap

    main

    When using NIOTSConnectionBootstrap, you can configure the following:

    • .connectTimeout(_:): Sets the maximum time to wait for a connection to be established.
    • .channelOption(_:value:): Sets standard SwiftNIO ChannelOptions (e.g., TCP_NODELAY).
    • .tlsOptions(_:): Configures TLS using NWProtocolTLS.Options() from the Network framework.
    • .channelInitializer(_:): A closure used to configure the ChannelPipeline once the connection is established.
    • .connect(host:port:): Initiates the connection to the specified host and port.