SwiftNIO Extras

NIOExtras is a collection of utilities designed to assist in building and debugging Swift-NIO applications. It provides tools across four main categories:

1. Debugging Aids: ChannelHandlers for logging inbound/outbound pipeline events and logging data in packet capture (PCAP) format.
2. Encoding and Decoding: Helpers for common data frame formats, including fixed-length frames, newline-terminated frames, length-prefixed frames, and frames defined by a context-length header.
3. Channel Pipeline Aids: Tools like ServerQuiescingHelper for managing child channels and RequestResponseHandler for simplifying request-response flows.
4. Data Types: Specialized types like NIOLengthFieldBitLength to support framing logic.

The NIOHTTPCompression module provides channel handlers to automatically manage the compression and decompression of HTTP data. When added to your pipeline, the handlers automatically manage the Content-Encoding, Content-Length, and accept-encoding HTTP headers.

Important Considerations:

• Performance: Compression/decompression is performed on the event loop thread, which can impact performance.
• Efficiency: This works most effectively when there is sufficient data written between flushes.

When building an HTTP server, use the following handlers in your pipeline to handle compressed requests from clients:

• NIOHTTPRequestDecompressor: Decompresses incoming requests.
• HTTPResponseCompressor: Compresses outgoing responses.

NIOExtras provides several decoders to handle structured data streams:

• Fixed Length: Use FixedLengthFrameDecoder for frames with a constant size.
• Newline Terminated: Use LineBasedFrameDecoder for text-based protocols where lines end in newlines.
• Length Prefixed: Use LengthFieldBasedFrameDecoder for frames that include a length field in the header.
• JSON-RPC: Use NIOJSONRPCFraming for JSON-RPC specific framing requirements.

When building an HTTP client, use the following handlers in your pipeline to handle compressed responses from a server:

• NIOHTTPRequestCompressor: Compresses outgoing requests.
• NIOHTTPResponseDecompressor: Decompresses incoming responses.

NIOSOCKS provides an implementation of the SOCKS v5 protocol (RFC1928). To use this protocol in your application, add the appropriate channel handler to the start of your ChannelPipeline.

• For a SOCKS client: Use SOCKSClientHandler.
• For a SOCKS server: Use SOCKSServerHandshakeHandler.

Refer to the NIOSOCKSClient target in the repository for a complete implementation example.

To use swift-nio-extras in your project, add it as a dependency in your Package.swift file.

Prerequisites:

• swift-nio version 2.30.0 or better.
• zlib and its development headers installed on your system.

Dependency Configuration:

.package(url: "https://github.com/apple/swift-nio-extras.git", from: "1.0.0"),

You can use specialized ChannelHandlers to monitor activity within your pipeline:

• Use DebugInboundEventsHandler to log inbound channel pipeline events.
• Use DebugOutboundEventsHandler to log outbound channel pipeline events.
• Use NIOWritePCAPHandler to log data in packet capture (PCAP) format for network analysis.

NIOSOCKS defines specific types for the messages exchanged during the SOCKS v5 handshake and request phases.

Client Messages:

• ClientMessage: Base type for client messages.
• ClientGreeting: The initial message sent by the client to the server.
• SOCKSRequest: The message sent by the client to request a connection to a specific destination.

Server Messages:

• ServerMessage: Base type for server messages.
• SelectedAuthenticationMethod: Response indicating which authentication method the server has chosen.
• SOCKSResponse: Response to a SOCKSRequest indicating success or failure.