wendylabsinc/swift-nio

Swift NIO

Overview

This skill provides expert guidance on SwiftNIO, Apple's event-driven network application framework. Use this skill to help developers write safe, performant networking code, build protocol implementations, and properly integrate with Swift Concurrency.

Agent Behavior Contract (Follow These Rules)

1. Analyze the project's Package.swift to determine which SwiftNIO packages are used.
2. Before proposing fixes, identify if Swift Concurrency can be used instead of EventLoopFuture chains.
3. Never recommend blocking the EventLoop - this is the most critical rule in SwiftNIO development.
4. Prefer NIOAsyncChannel and structured concurrency over legacy ChannelHandler patterns for new code.
5. Use EventLoopFuture/EventLoopPromise only for low-level protocol implementations.
6. When working with ByteBuffer, always consider memory ownership and avoid unnecessary copies.

Quick Decision Tree

When a developer needs SwiftNIO guidance, follow this decision tree:

1. Building a TCP/UDP server or client?

   • Read references/Channels.md for Channel concepts and NIOAsyncChannel
   • Use ServerBootstrap for TCP servers, DatagramBootstrap for UDP

2. Understanding EventLoops?

   • Read references/EventLoops.md for event loop concepts
   • Critical: Never block the EventLoop!

3. Working with binary data?

   • Read references/ByteBuffer.md for buffer operations
   • Prefer slice views over copies when possible

4. Implementing a binary protocol?

   • Read references/ByteToMessageCodecs.md for codec patterns
   • Use ByteToMessageDecoder and MessageToByteEncoder

5. Migrating from EventLoopFuture to async/await?

   • Use .get() to bridge futures to async
   • Use NIOAsyncChannel for channel-based async code

Triage-First Playbook (Common Issues -> Solutions)

• "Blocking the EventLoop"

  • Offload CPU-intensive work to a dispatch queue or use NIOThreadPool
  • Never perform synchronous I/O on an EventLoop
  • See references/EventLoops.md

• Type mismatch crash in ChannelPipeline

  • Ensure InboundOut of handler N matches InboundIn of handler N+1
  • Ensure OutboundOut of handler N matches OutboundIn of handler N-1
  • See references/Channels.md

• Implementing binary protocol serialization

  • Use ByteToMessageDecoder for parsing bytes into messages
  • Use MessageToByteEncoder for serializing messages to bytes
  • Use readLengthPrefixedSlice and writeLengthPrefixed helpers
  • See references/ByteToMessageCodecs.md

• Memory issues with ByteBuffer

  • Use readSlice instead of readBytes when possible
  • Remember ByteBuffer uses copy-on-write semantics
  • See references/ByteBuffer.md

• Deadlock when waiting for EventLoopFuture

  • Never .wait() on a future from within the same EventLoop
  • Use .get() from async contexts or chain with .flatMap

Core Patterns Reference

Creating a TCP Server (Modern Approach)

let server = try await ServerBootstrap(group: MultiThreadedEventLoopGroup.singleton)
    .bind(host: "0.0.0.0", port: 8080) { channel in
        channel.eventLoop.makeCompletedFuture {
            try NIOAsyncChannel(
                wrappingChannelSynchronously: channel,
                configuration: .init(
                    inboundType: ByteBuffer.self,
                    outboundType: ByteBuffer.self
                )
            )
        }
    }

try await withThrowingDiscardingTaskGroup { group in
    try await server.executeThenClose { clients in
        for try await client in clients {
            group.addTask {
                try await handleClient(client)
            }
        }
    }
}

EventLoopGroup Best Practice

// Preferred: Use the singleton
let group = MultiThreadedEventLoopGroup.singleton

// Get any EventLoop from the group
let eventLoop = group.any()

Bridging EventLoopFuture to async/await

// From EventLoopFuture to async
let result = try await someFuture.get()

// From async to EventLoopFuture
let future = eventLoop.makeFutureWithTask {
    try await someAsyncOperation()
}

ByteBuffer Operations

var buffer = ByteBufferAllocator().buffer(capacity: 1024)

// Writing
buffer.writeString("Hello")
buffer.writeInteger(UInt32(42))

// Reading
let string = buffer.readString(length: 5)
let number = buffer.readInteger(as: UInt32.self)

Reference Files

Load these files as needed for specific topics:

• EventLoops.md - EventLoop concepts, nonblocking I/O, why blocking is bad
• Channels.md - Channel anatomy, ChannelPipeline, ChannelHandlers, NIOAsyncChannel
• ByteToMessageCodecs.md - ByteToMessageDecoder, MessageToByteEncoder for binary protocol (de)serialization
• patterns.md - Advanced integration patterns: ServerChildChannel abstraction, state machines, noncopyable ResponseWriter, graceful shutdown, ByteBuffer patterns

Best Practices Summary

1. Never block the EventLoop - Offload heavy work to thread pools
2. Use structured concurrency - Prefer NIOAsyncChannel over legacy handlers
3. Use the singleton EventLoopGroup - MultiThreadedEventLoopGroup.singleton
4. Handle errors in task groups - Throwing from a client task closes the server
5. Mind the types in pipelines - Type mismatches crash at runtime
6. Use ByteBuffer efficiently - Prefer slices over copies

Use ByteBuffer for Binary Protocol Handling

When parsing or serializing binary data (especially for network protocols), use SwiftNIO's ByteBuffer instead of Foundation's Data. ByteBuffer provides:

• Efficient read/write operations with built-in endianness handling
• Zero-copy slicing with reader/writer index tracking
• Integration with NIO ecosystem

When converting between ByteBuffer and Data, use NIOFoundationCompat:

import NIOFoundationCompat

// ByteBuffer to Data
let data = Data(buffer: byteBuffer)

// Data to ByteBuffer - use writeData for better performance
var buffer = ByteBuffer()
buffer.writeData(data)  // Faster than writeBytes(data)

Bad - Using Data with manual byte manipulation:

var buffer = Data()
var messageLength: UInt32?

for try await message in inbound {
    buffer.append(message)

    if messageLength == nil && buffer.count >= 4 {
        messageLength = UInt32(buffer[0]) << 24
            | UInt32(buffer[1]) << 16
            | UInt32(buffer[2]) << 8
            | UInt32(buffer[3])
        buffer = Data(buffer.dropFirst(4))  // Copies data!
    }
}

Good - Using ByteBuffer:

var buffer = ByteBuffer()

for try await message in inbound {
    buffer.writeBytes(message)

    if buffer.readableBytes >= 4 {
        let readerIndex = buffer.readerIndex
        guard let messageLength = buffer.readInteger(endianness: .big, as: UInt32.self) else {
            continue
        }

        if buffer.readableBytes >= messageLength {
            guard let bytes = buffer.readBytes(length: Int(messageLength)) else { continue }
            // Process bytes...
        } else {
            // Not enough data yet, reset reader index
            buffer.moveReaderIndex(to: readerIndex)
        }
    }
}

Binary Data Types Comparison

There are several "bag of bytes" data structures in Swift:

| Type | Source | Platform | Notes | |------|--------|----------|-------| | Array<UInt8> | stdlib | All | Safe, growable, good for Embedded Swift | | InlineArray<N, UInt8> | stdlib (6.1+) | All | Fixed-size, stack-allocated, no heap allocation | | Data | Foundation | All (large binary) | Not always contiguous on Apple platforms | | ByteBuffer | SwiftNIO | All (requires NIO) | Best for network protocols, not Embedded | | Span<UInt8> | stdlib (6.2+) | All | Zero-copy view, requires Swift 6.2+ | | UnsafeBufferPointer<UInt8> | stdlib | All | Unsafe, manual memory management |

Recommendations:

• For iOS/macOS-only projects: Data is fine due to framework integration
• For SwiftNIO-based projects: ByteBuffer is required for I/O operations
• For Embedded Swift: [UInt8] and InlineArray
• For cross-platform APIs: Span<UInt8> (Swift 6.2+) allows any backing type

NIO Channel Pattern with executeThenClose

Use executeThenClose to get inbound/outbound streams from NIOAsyncChannel:

return try await channel.executeThenClose { inbound, outbound in
    let socket = Client(inbound: inbound, outbound: outbound, channel: channel.channel)
    return try await perform(client)
}

Public API with Internal NIO Types

When exposing async sequences that wrap NIO types:

1. Create a custom AsyncSequence wrapper struct with internal NIO stream
2. The wrapper's AsyncIterator transforms NIO types to public types
3. This avoids exposing internal NIO imports in public API

SwiftNIO UDP Notes

• Use DatagramBootstrap for UDP sockets
• Messages use AddressedEnvelope<ByteBuffer> containing remote address and data
• Multicast requires casting channel to MulticastChannel protocol
• Socket options use SocketOptionValue (Int32) type
• so_reuseport is only available on Linux