FlyingFox Documentation

The FlyingSocks module provides a cross-platform asynchronous interface to standard BSD sockets. It wraps low-level Socket operations into a modern Swift async/await interface.

AsyncSocket is configured with the O_NONBLOCK flag. When data is unavailable and EWOULDBLOCK is encountered, it catches SocketError.blocked and suspends the current task using an AsyncSocketPool until the socket is ready.

import FlyingSocks

let socket = try await AsyncSocket.connected(to: .inet(ip4: "192.168.0.100", port: 80))
try await socket.write(Data([0x01, 0x02, 0x03]))
try socket.close()

Add FlyingFox as a dependency in your Package.swift file.

Requirements:

• Swift 5.10+
• Xcode 15.4+
• Supported Platforms: iOS 13+, tvOS 13+, watchOS 8+, macOS 10.15+, and Linux. (Android and Windows 10 support is experimental).

.package(url: "https://github.com/swhitty/FlyingFox.git", .upToNextMajor(from: "0.27.1"))

The HTTPServer can be initialized with various SocketAddress types, allowing it to listen on different network interfaces or via UNIX domain sockets for IPC.

Supported address types:

• .loopback(port: Int): Listens only on localhost.
• .unix(path: String): Listens on a UNIX domain socket at the specified path.
• Standard sockaddr clusters like sockaddr_in (IPv4), sockaddr_in6 (IPv6), and sockaddr_un (UNIX) are also supported via conformance.

// Only listens on localhost 8080
let server = HTTPServer(address: .loopback(port: 8080))

// Only listens on Unix socket "Ants"
let server = HTTPServer(address: .unix(path: "Ants"))

You can handle requests by implementing the HTTPHandler protocol or by using closures.

Protocol Implementation: Implement handleRequest(_:) to process an HTTPRequest and return an HTTPResponse.

Closure Implementation: Use appendRoute to attach a closure directly to a path.

Routing Logic:

• Requests are routed to the handler of the first matching route.
• If a handler cannot process a request, it can throw HTTPUnhandledError to allow the next matching route to attempt handling it.
• Requests that match no routes receive an HTTP 404 response.

// Protocol approach
protocol HTTPHandler {
  func handleRequest(_ request: HTTPRequest) async throws -> HTTPResponse
}

// Closure approach
await server.appendRoute("/hello") { request in
  return HTTPResponse(statusCode: .ok)
}

Routes can include named parameters using the : prefix in paths or query items. These values can be extracted from the request.routeParameters dictionary.

Manual Extraction:

// Route: "GET /creature/:name?type=:beast"
let name = request.routeParameters["name"]
let beast = request.routeParameters["beast"]

Automatic Extraction: Parameters can be automatically mapped to closure arguments if the types conform to HTTPRouteParameterValue. Supported types include String, Int, Double, Bool, and custom types conforming to HTTPRouteParameterValue.

enum Beast: String, HTTPRouteParameterValue {
  case fish, dog
}

// The closure arguments are automatically populated
handler.appendRoute("GET /creature/:name?type=:beast") { (name: String, beast: Beast) -> HTTPResponse in
  return HTTPResponse(statusCode: .ok)
}

WebSockets can be handled in two ways:

1. WebSocketHTTPHandler (High-level): Uses a WSMessageHandler to exchange AsyncStream<WSMessage> pairs. This is the recommended approach for most use cases.

   • WSMessage can be .text(String), .data(Data), or .close(WSCloseCode).

2. WSHandler (Low-level): Provides raw WSFrame streams via makeFrames(for:). Use this if you need to work directly with the WebSocket protocol frames.

// High-level WSMessageHandler
protocol WSMessageHandler {
  func makeMessages(for client: AsyncStream<WSMessage>) async throws -> AsyncStream<WSMessage>
}

// Usage
await server.appendRoute("GET /socket", to: .webSocket(EchoWSMessageHandler()))

The Socket type wraps a file descriptor and throws SocketError instead of returning error codes. Common errors include:

• .blocked: Thrown when data is unavailable (EWOULDBLOCK).
• .disconnected: The connection was lost.
• .unsupportedAddress: The provided address is invalid.
• .timeout(message: String): An operation timed out.
• .failed(type: String, errno: Int32, message: String): A generic failure containing the error type, errno, and a message.