FlyingFox

https://github.com/swhitty/flyingfox
Admin
FlyingFox is a lightweight HTTP server built with Swift Concurrency using non-blocking BSD sockets,...
Tokens:105,925
Snippets:714
Trust Score:9.2
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### GET /hello

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Example of a basic server that responds to a GET request on /hello.

```APIDOC
## [GET] /hello

### Description
Returns a simple greeting message.

### Method
GET

### Endpoint
/hello

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **body** (Data) - The response body containing the text "Hello, world!".

#### Response Example
```
Hello, world!
```
```

--------------------------------

### Basic HTTPServer setup and route

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Creates an HTTPServer on port 8080, appends a route for GET /hello, and runs the server until the task is cancelled.

```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("GET /hello") { _ in
    HTTPResponse(statusCode: .ok, body: Data("Hello, world!".utf8))
}
try await server.run() // runs until the current task is cancelled
```

--------------------------------

### Example: proxying routes with ProxyHTTPHandler

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/RedirectHTTPHandler.md

Shows how to route HTTP requests to a proxy. Uses the .proxy(via:) convenience for a simple GET route, then shows ProxyHTTPHandler with custom session and timeout for a POST route, and starts the server.

```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("GET *", to: .proxy(via: "https://pie.dev"))
// GET /get?fish=chips  ---->  GET https://pie.dev/get?fish=chips

// With a configurable timeout and session
let session: URLSession = .shared
await server.appendRoute("POST *", to: ProxyHTTPHandler(base: "https://api.example.com",
                                                        session: session,
                                                        timeout: 30))
try await server.run()
```

--------------------------------

### start()

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Deprecated. Use run() instead. Starts the server and begins accepting connections.

```APIDOC
## [METHOD] start

### Description
Deprecated. Use run() instead. Starts the server and begins accepting connections.

### Signature
@available(*, deprecated, renamed: "run") public func start() async throws

### Throws
Throws an error if the server fails to start or run.
```

--------------------------------

### Example: connect and exchange data

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/AsyncSocket.md

Example showing how to connect, write, read, and close with AsyncSocket.

```APIDOC
## Example: connect and exchange data

### Description
This example demonstrates how to connect to a remote socket, write data, read a single byte, and close the socket using the `AsyncSocket` API.

### Code Example
```swift
import FlyingSocks

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

--------------------------------

### HTTPServer lifecycle: start, wait, graceful stop, error handling

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Shows how to start a server, wait until it is listening, print its address, gracefully stop with a timeout, cancel as fallback, and handle errors on a second run attempt.

```swift
import FlyingFox

let server = HTTPServer(address: .loopback(port: 8080), timeout: 5)

let serverTask = Task { try await server.run() }
try await server.waitUntilListening(timeout: 2)
print(await server.listeningAddress as Any) // ip6("::1", port: 8080)

// … serve …

await server.stop(timeout: 3)   // graceful: waits up to 3 s for in-flight requests
serverTask.cancel()             // fallback: cancels immediately

do {
    try await server.run()      // a second run() attempt throws
} catch SocketError.unsupportedAddress {
    print("server already started")
} catch {
    print("server failed: \(error)")
}
```

--------------------------------

### HTTP Body Sequence and HTTPClient Examples

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPBodySequence.md

Code examples demonstrating how to consume HTTP request bodies lazily, buffer them, handle errors, and use the HTTPClient to send requests.

```APIDOC
## POST /upload

### Description
Streams the request body lazily using `request.bodySequence`, accumulating the total byte count without buffering the entire body in memory.

### Method
POST

### Endpoint
/upload

### Parameters
#### Request Body
- **body** (stream of Data chunks) - Required - The request body is consumed as an asynchronous sequence of `Data` chunks via `request.bodySequence`.

### Request Example
```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("POST /upload") { request in
    var total = 0
    for try await chunk in request.bodySequence {   // stream, do not buffer whole
        total += chunk.count
    }
    return HTTPResponse(statusCode: .ok, body: Data("received \(total) bytes".utf8))
}

try await server.run()
```

### Response
#### Success Response (200)
- **body** (Data) - A response body containing the total number of bytes received, formatted as `received <total> bytes`.

#### Response Example
```swift
HTTPResponse(statusCode: .ok, body: Data("received 1234 bytes".utf8))
```
```

```APIDOC
## POST /echo

### Description
Buffers the entire request body using `request.bodyData` and echoes it back in the response.

### Method
POST

### Endpoint
/echo

### Parameters
#### Request Body
- **body** (Data) - Required - The full request body, buffered via `request.bodyData`.

### Request Example
```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("POST /echo") { request in
    let body = try await request.bodyData          // buffer whole body
    return HTTPResponse(statusCode: .ok, body: body)
}
try await server.run()
```

### Response
#### Success Response (200)
- **body** (Data) - The request body echoed back unchanged.

#### Response Example
```swift
HTTPResponse(statusCode: .ok, body: body)
```
```

```APIDOC
## POST /strict

### Description
Streams the request body with error handling, returning a 413 Payload Too Large response if the body exceeds 1,000,000 bytes.

### Method
POST

### Endpoint
/strict

### Parameters
#### Request Body
- **body** (stream of Data chunks) - Required - The request body is consumed as an asynchronous sequence of `Data` chunks via `request.bodySequence`.

### Request Example
```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("POST /strict") { request in
    var data = Data()
    do {
        for try await chunk in request.bodySequence {
            data.append(chunk)
            if data.count > 1_000_000 { throw LimitError() }
        }
        return HTTPResponse(statusCode: .ok, body: data)
    } catch {
        return HTTPResponse(statusCode: .payloadTooLarge)
    }
}
try await server.run()

struct LimitError: Error {}
```

### Response
#### Success Response (200)
- **body** (Data) - The accumulated request body data.

#### Error Response (413)
- **statusCode** (HTTPStatusCode) - `.payloadTooLarge` returned when the body exceeds the size limit.

#### Response Example
```swift
HTTPResponse(statusCode: .ok, body: data)
HTTPResponse(statusCode: .payloadTooLarge)
```
```

```APIDOC
## HTTPClient.sendHTTPRequest(_:to:)

### Description
Sends an HTTP request to a specified socket address and returns the decoded HTTP response. This is a synchronous-ish client for talking to a FlyingFox server or any HTTP/1.1 server over a bound socket.

### Method
sendHTTPRequest(_:to:)

### Signature
```swift
public mutating func sendHTTPRequest(_ request: HTTPRequest, to address: some SocketAddress) async throws -> HTTPResponse
```

### Parameters
- **request** (HTTPRequest) - Required - The HTTP request to send.
- **address** (some SocketAddress) - Required - The socket address to connect to.

### Returns
- **HTTPResponse** - The response decoded from the socket.

### Throws
- **SocketError** - Connection/socket errors.
- **HTTPDecoder.Error("Invalid Status Line")** - The response body decoder requires at least 3 status-line components.

### Behavior
Each call closes any previous socket, connects via `AsyncSocket.connected(to:address:)` (default 5 s timeout), writes `HTTPEncoder.encodeRequest(request)`, and reads `HTTPDecoder(sharedRequestBufferSize: 4096, sharedRequestReplaySize: 102_400).decodeResponse(from:)`. The struct is `~Copyable` and closes the last socket in `deinit`.

### Example
```swift
import FlyingFox
import FlyingSocks

var client = HTTPClient()
let request = HTTPRequest(method: .GET, version: .http11, path: "/ping", query: [],
                          headers: [.host: "localhost"], body: Data())
do {
    let response = try await client.sendHTTPRequest(request, to: sockaddr_in.inet(port: 8080))
    print(response.statusCode.code, try await response.bodyData)
} catch {
    print("connection failed: \(error)")
}
```
```

--------------------------------

### run()

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Starts the server and begins accepting connections. This method runs until the server is stopped.

```APIDOC
## [METHOD] run

### Description
Starts the server and begins accepting connections. This method runs until the server is stopped.

### Signature
public func run() async throws

### Throws
Throws an error if the server fails to start or run.
```

--------------------------------

### start() deprecated method

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Deprecated alias of run().

```swift
@available(*, deprecated, renamed: "run")
public func start() async throws
```

--------------------------------

### Start HTTPServer with port

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Starts the HTTP server on the specified port. The server runs within the current task and must be awaited.

```swift
import FlyingFox

let server = HTTPServer(port: 80)
try await server.run()
```

--------------------------------

### Connect and Exchange Data Example

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/AsyncSocket.md

Example of connecting to a remote socket, writing data, reading a byte, and closing the connection using AsyncSocket.

```swift
import FlyingSocks

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

--------------------------------

### HTTPRoute string-literal initializer init(_:headers:body:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRoute.md

Primary human-facing initializer that parses a string with components(for:). If the first whitespace-delimited token does not start with '/', it is treated as a comma-delimited method list (e.g., "GET,POST /path"); otherwise all methods match. Empty method lists expand to HTTPMethod.allMethods.

```swift
public init(
    _ string: String,
    headers: [HTTPHeader: String] = [:],
    body: (any HTTPBodyPattern)? = nil
)
```

--------------------------------

### GET /hello

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Adds a route to the server that delegates requests to a handler. The handler is called for each matching request.

```APIDOC
## [GET] /hello

### Description
Adds a route to the server that delegates requests to a handler. The handler is called for each matching request.

### Method
GET

### Endpoint
/hello

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **statusCode** (HTTPStatusCode) - The status code of the response.

#### Response Example
```json
{
  "statusCode": 200
}
```
```

--------------------------------

### GET /mock

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Routes requests to a static file. Returns HTTP 404 if the file does not exist.

```APIDOC
## [GET] /mock

### Description
Routes requests to a static file. Returns HTTP 404 if the file does not exist.

### Method
GET

### Endpoint
/mock

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **file** (File) - The static file content.

#### Response Example
```json
{
  "file": "mock.json"
}
```

#### Error Response (404)
- **statusCode** (HTTPStatusCode) - The status code of the response.

#### Error Response Example
```json
{
  "statusCode": 404
}
```
```

--------------------------------

### GET /mock/*

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Routes requests to static files within a directory. Returns HTTP 404 if a file does not exist.

```APIDOC
## [GET] /mock/*

### Description
Routes requests to static files within a directory. Returns HTTP 404 if a file does not exist.

### Method
GET

### Endpoint
/mock/*

### Parameters
#### Path Parameters
- **\*** (string) - Required - The path to the file within the directory.

### Request Example
None

### Response
#### Success Response (200)
- **file** (File) - The static file content.

#### Response Example
```json
{
  "file": "Stubs/fish/index.html"
}
```

#### Error Response (404)
- **statusCode** (HTTPStatusCode) - The status code of the response.

#### Error Response Example
```json
{
  "statusCode": 404
}
```
```

--------------------------------

### Custom logger and server wiring example

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/Logging.md

Shows a custom Logging implementation and how to pass it to HTTPServer. Also lists the built-in logger options: .print, .oslog, and .disabled.

```swift
import FlyingFox
import FlyingSocks

struct PrefixedLogger: Logging {
    var prefix: String

    private func emit(_ level: String, _ message: String) {
        print("[\(prefix)/\(level)] \(message)")
    }
    func logDebug(_ debug: @autoclosure () -> String)     { emit("debug", debug()) }
    func logInfo(_ info: @autoclosure () -> String)       { emit("info", info()) }
    func logWarning(_ warning: @autoclosure () -> String) { emit("warning", warning()) }
    func logError(_ error: @autoclosure () -> String)     { emit("error", error()) }
    func logCritical(_ critical: @autoclosure () -> String) { emit("critical", critical()) }
}

let server = HTTPServer(port: 8080, logger: PrefixedLogger(prefix: "myapp"))
// or use the built-ins:
//   HTTPServer(port: 8080, logger: .print(category: "MyServer"))
//   HTTPServer(port: 8080, logger: .oslog(bundle: .main, category: "MyServer"))
//   HTTPServer(port: 8080, logger: .disabled)
try await server.run()
```

--------------------------------

### HTTPRequest (Client)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRequest.md

Example of building an HTTPRequest for HTTPClient or proxies using FlyingFox and FlyingSocks. Shows how to set method, path, headers, body, and send the request.

```APIDOC
## HTTPRequest (Client)

### Description
Constructs an HTTP request object with method, version, path, query, headers, and body, then sends it via HTTPClient to a specified address. Demonstrates setting headers and reading the response body.

### Method
POST (as example)

### Endpoint
/account (as example)

### Parameters
#### Request Body
- **body** (Data) - Required - The request body data, e.g., JSON payload.

#### Headers
- **Content-Type** (string) - Required - The media type of the request body, e.g., "application/json".
- **Authorization** (string) - Optional - Bearer token for authentication, e.g., "Bearer abc123".

### Request Example
```swift
var request = HTTPRequest(
    method: .POST,
    version: .http11,
    path: "/account",
    query: [],
    headers: [.contentType: "application/json"],
    body: Data(#"{"balance": 5}"#.utf8)
)
request.headers[.authorization] = "Bearer abc123"
```

### Response
#### Success Response (200)
- **bodyData** (Data) - The response body data.

#### Response Example
```swift
let response = try await client.sendHTTPRequest(request, to: sockaddr_in.inet(ip4: "127.0.0.1", port: 8080))
let payload = try await response.bodyData
```
```

--------------------------------

### Custom logger and server wiring

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/Logging.md

Example of defining a custom Logging implementation and passing it to HTTPServer initializer, along with built-in logger options.

```APIDOC
## Custom logger and server wiring

### Description
Example of defining a custom Logging implementation and passing it to HTTPServer initializer, along with built-in logger options.

### Example
swift
import FlyingFox
import FlyingSocks

struct PrefixedLogger: Logging {
    var prefix: String

    private func emit(_ level: String, _ message: String) {
        print("[\(prefix)/\(level)] \(message)")
    }
    func logDebug(_ debug: @autoclosure () -> String)     { emit("debug", debug()) }
    func logInfo(_ info: @autoclosure () -> String)       { emit("info", info()) }
    func logWarning(_ warning: @autoclosure () -> String) { emit("warning", warning()) }
    func logError(_ error: @autoclosure () -> String)     { emit("error", error()) }
    func logCritical(_ critical: @autoclosure () -> String) { emit("critical", critical()) }
}

let server = HTTPServer(port: 8080, logger: PrefixedLogger(prefix: "myapp"))
// or use the built-ins:
//   HTTPServer(port: 8080, logger: .print(category: "MyServer"))
//   HTTPServer(port: 8080, logger: .oslog(bundle: .main, category: "MyServer"))
//   HTTPServer(port: 8080, logger: .disabled)
try await server.run()

```

--------------------------------

### Serve a single bundled file with FileHTTPHandler

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/FileHTTPHandler.md

Serves a single bundled file from the main bundle. The `FileHTTPHandler` with `GET,HEAD` supports range requests. Requires `import FlyingFox` and an `HTTPServer` on port 8080.

```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("GET /mock", to: .file(named: "mock.json"))
await server.appendRoute("GET,HEAD /jaws", to: FileHTTPHandler(named: "jaws.m4v", in: .main)) // range requests
try await server.run()
```

--------------------------------

### GET /creature/:name?type=:beast

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Example of a routed handler with route parameters.

```APIDOC
## [GET] /creature/:name?type=:beast

### Description
Returns a message describing the creature and its type.

### Method
GET

### Endpoint
/creature/:name?type=:beast

### Parameters
#### Path Parameters
- **name** (String) - Required - The name of the creature.

#### Query Parameters
- **type** (Beast) - Required - The type of the creature, must be one of "fish" or "dog".

### Request Example
```
GET /creature/whale?type=fish
```

### Response
#### Success Response (200)
- **body** (Data) - The response body containing the message "{name} is a {beast.rawValue}".

#### Response Example
```
whale is a fish
```
```

--------------------------------

### init(config:handler:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Initializes an HTTPServer with a fully specified server Configuration and an optional catch-all handler.

```APIDOC
## init(config:handler:)

### Description
Initializes an HTTPServer with a fully specified server Configuration and an optional catch-all handler. The server is not started by this initializer; call run() to begin listening.

### Method
Initializer

### Endpoint
HTTPServer.init(config:handler:)

### Parameters
- **config** (Configuration) - Required - A fully specified server Configuration (see configuration documentation).
- **handler** ((any HTTPHandler)?) - Optional - An optional catch-all handler; if provided it is registered against the wildcard route "*" as the root handler.

### Request Example
```swift
let config = HTTPServer.Configuration(...)
let server = HTTPServer(config: config, handler: myHandler)
```

### Response
No return value.
```

--------------------------------

### Send HTTP GET request with HTTPClient

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPBodySequence.md

Example usage of `HTTPClient` to send a GET request to `/ping` on localhost:8080 and print the status code and response body. Catches and prints connection errors.

```swift
import FlyingFox
import FlyingSocks

var client = HTTPClient()
let request = HTTPRequest(method: .GET, version: .http11, path: "/ping", query: [],
                          headers: [.host: "localhost"], body: Data())
do {
    let response = try await client.sendHTTPRequest(request, to: sockaddr_in.inet(port: 8080))
    print(response.statusCode.code, try await response.bodyData)
} catch {
    print("connection failed: \(error)")
}
```

--------------------------------

### RedirectHTTPHandler error handling example

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/RedirectHTTPHandler.md

Example of error handling when calling handleRequest. It constructs a RedirectHTTPHandler with base and statusCode .found, then sends a GET request with a query. If the base or location is unparsable, it throws URLError(.badURL) and prints "redirect failed: ...".

```swift
import FlyingFox

let handler = RedirectHTTPHandler(base: "https://pie.dev", statusCode: .found)
let request = HTTPRequest(method: .GET, version: .http11,
                          path: "/fish",
                          query: [.init(name: "a", value: "b")],
                          headers: [:], body: Data())
do {
    let response = try await handler.handleRequest(request)
    print(response.statusCode.code, response.headers[.location] ?? "")
} catch {
    print("redirect failed: \(error)") // URLError(.badURL) for unparsable base/location
}
```

--------------------------------

### GET /thing/:id

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRequest.md

Example of route parameter extraction in FlyingFox's HTTPServer. Shows how to access route parameters as strings and typed values.

```APIDOC
## GET /thing/:id

### Description
Extracts route parameters from the URL path. Demonstrates accessing a string parameter and converting it to a typed value (e.g., Int).

### Method
GET

### Endpoint
/thing/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier from the URL path. Can be accessed as a string or converted to a typed value.

### Request Example
```
GET /thing/42
```

### Response
#### Success Response (200)
- **body** (Data) - The response body containing the id and its numeric representation, e.g., "id=42 numeric=Optional(42)".

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: text/plain

id=42 numeric=Optional(42)
```

#### Error Response (400)
- Returned when the route parameter is missing.
```

--------------------------------

### init(methods:path:headers:body:) (Sequence), init(method:path:headers:body:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRoute.md

Convenience overloads accepting a sequence of HTTP methods or a single method.

```APIDOC
## init(methods:path:headers:body:) (Sequence), init(method:path:headers:body:)

### Description
Convenience overloads accepting a sequence of HTTP methods or a single method.

### Method
INIT

### Endpoint
N/A

### Parameters
#### Parameters
- **methods** (`some Sequence<HTTPMethod>`) - Required - Methods to match against
- **method** (`HTTPMethod`) - Required - A single HTTP method
- **path** (`String`) - Required - Path (optionally including `?query`) parsed into components by `readComponents`
- **headers** (`[HTTPHeader: String]`) - Optional - Required header values; any value where the string is `"*"`
- **body** (`(any HTTPBodyPattern)?`) - Optional - Body matcher, e.g. `JSONBodyPattern`

### Request Example
```swift
HTTPRoute(methods: [.GET, .POST], path: "/users")
HTTPRoute(method: .GET, path: "/users")
```

### Response
#### Success Response (N/A)
No return value.

#### Response Example
N/A
```

--------------------------------

### Annotate HTTPHandler with @HTTPRoute and @JSONRoute

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Use the FlyingFoxMacros annotations to automatically synthesize an HTTPHandler. The example defines a handler with @HTTPRoute and @JSONRoute endpoints and starts an HTTPServer on port 80.

```swift
import FlyingFox
import FlyingFoxMacros

@HTTPHandler
struct MyHandler {

  @HTTPRoute("/ping")
  func ping() { }

  @HTTPRoute("/pong")
  func getPong(_ request: HTTPRequest) -> HTTPResponse {
    HTTPResponse(statusCode: .accepted)
  }

  @JSONRoute("POST /account")
  func createAccount(body: AccountRequest) -> AccountResponse {
    AccountResponse(id: UUID(), balance: body.balance)
  }
}

let server = HTTPServer(port: 80, handler: MyHandler())
try await server.run()
```

--------------------------------

### Configure HTTPServer with handlers

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/configuration.md

Sets up an HTTP server on port 8080 with a timeout of 10 seconds and a print logger. Routes are added for static files, proxy requests, and WebSocket connections, then the server is run.

```swift
import FlyingFox
import FlyingSocks

let server = HTTPServer(port: 8080, timeout: 10, logger: .print(category: "web"))
await server.appendRoute("GET /static/*", to: DirectoryHTTPHandler(
    root: URL(fileURLWithPath: "/srv/static"),
    serverPath: "/static",
    cacheControl: [.public, .maxAge(60), .immutable]
))
await server.appendRoute("GET /proxy/*", to: ProxyHTTPHandler(
    base: "https://api.example.com", timeout: 20
))
await server.appendRoute("GET /socket", to: .webSocket(EchoWSMessageHandler(), frameSize: 8_192))
try await server.run()
```

--------------------------------

### init(port:timeout:logger:handler:) (extension)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Initializes an HTTPServer that binds all interfaces on the given port, with two overloads for handler types.

```APIDOC
## init(port:timeout:logger:handler:) (extension, 2 overloads)

### Description
Initializes an HTTPServer that binds all interfaces on the given port. Two overloads are provided: one accepting an optional HTTPHandler, and one accepting a closure handler. On non-Windows platforms the address is sockaddr_in6.inet6(port:) (IPv6 any-address ::); on Windows it is sockaddr_in.inet(port:) (0.0.0.0).

### Method
Initializer

### Endpoint
HTTPServer.init(port:timeout:logger:handler:) (extension)

### Parameters
- **port** (UInt16) - Required - The port to bind.
- **timeout** (TimeInterval) - Optional - Per-request handling timeout in seconds. Default: 15.
- **logger** (any Logging) - Optional - Logger receiving connection/request/error messages. Default: defaultLogger().
- **handler** ((any HTTPHandler)?) - Optional - Optional root handler registered against "*". Default: nil.
- **handler** (@Sendable @escaping (HTTPRequest) async throws -> HTTPResponse) - Optional - A closure handler for requests. Default: nil.

### Request Example
```swift
let server = HTTPServer(port: 8080, timeout: 30, logger: myLogger, handler: myHandler)
```

### Response
No return value.
```

--------------------------------

### init(address:timeout:pool:logger:handler:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Initializes an HTTPServer with an address family to bind, a per-request handling timeout, an event pool, a logger, and an optional root handler.

```APIDOC
## init(address:timeout:pool:logger:handler:)

### Description
Initializes an HTTPServer with an address family to bind, a per-request handling timeout, an event pool, a logger, and an optional root handler. The server is not started by this initializer; call run() to begin listening.

### Method
Initializer

### Endpoint
HTTPServer.init(address:timeout:pool:logger:handler:)

### Parameters
- **address** (some SocketAddress) - Required - Address family to bind: sockaddr_in, sockaddr_in6, or sockaddr_un (e.g. .loopback(port:), .inet(port:), .unix(path:)).
- **timeout** (TimeInterval) - Optional - Per-request handling timeout in seconds; a handler exceeding it is cancelled and the request answers 500 Internal Server Error. Default: 15.
- **pool** (some AsyncSocketPool) - Optional - The event pool used to suspend blocked sockets (SocketPool<kQueue>, <ePoll>, or <Poll> depending on the platform). Default: HTTPServer.defaultPool().
- **logger** (any Logging) - Optional - Logger receiving connection/request/error messages. Default: HTTPServer.defaultLogger().
- **handler** ((any HTTPHandler)?) - Optional - Optional root handler registered against "*". Default: nil.

### Request Example
```swift
let server = HTTPServer(address: .loopback(port: 8080), timeout: 30, pool: myPool, logger: myLogger, handler: myHandler)
```

### Response
No return value.
```

--------------------------------

### init(config:handler:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Initializes a new HTTPServer actor with the provided configuration and an optional handler.

```APIDOC
## [ACTOR] HTTPServer

### Description
Initializes a new HTTPServer actor with the provided configuration and an optional handler.

### Method
init

### Signature
public init(config: Configuration, handler: (any HTTPHandler)? = nil)

### Parameters
- **config** (Configuration) - Required - The server configuration.
- **handler** (any HTTPHandler?) - Optional - The root HTTP handler for incoming requests.

### Response
Returns a new HTTPServer actor instance.
```

--------------------------------

### GET /creature/:name?type=:beast

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRoute.md

Extracts path and query parameters from a request without a handler. The route matches GET requests to /creature/:name with an optional query parameter type.

```APIDOC
## [GET] /creature/:name?type=:beast

### Description
Extracts path and query parameters from a request without a handler. The route matches GET requests to /creature/:name with an optional query parameter type.

### Method
GET

### Endpoint
/creature/:name?type=:beast

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the creature

#### Query Parameters
- **type** (string) - Optional - The type of beast

### Request Example
```swift
let request = HTTPRequest(
    method: .GET,
    version: .http11,
    path: "/creature/fish",
    query: [.init(name: "type", value: "dog")],
    headers: [.host: "example.com"],
    body: Data()
)
```

### Response
Returns a dictionary of extracted parameters.

#### Response Example
```swift
let params = route.extractParameters(from: request)
print(params["name"])  // Optional("fish")
print(params["beast"]) // Optional("dog")
```

```

--------------------------------

### init(methods:path:headers:body:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRoute.md

Initializes an HTTPRoute with a set of HTTP methods, a path, optional headers, and an optional body pattern.

```APIDOC
## init(methods:path:headers:body:)

### Description
Initializes an HTTPRoute with a set of HTTP methods, a path, optional headers, and an optional body pattern.

### Method
INIT

### Endpoint
N/A

### Parameters
#### Parameters
- **methods** (`Set<HTTPMethod>`) - Required - Methods to match against
- **path** (`String`) - Required - Path (optionally including `?query`) parsed into components by `readComponents`
- **headers** (`[HTTPHeader: String]`) - Optional - Required header values; any value where the string is `"*"`
- **body** (`(any HTTPBodyPattern)?`) - Optional - Body matcher, e.g. `JSONBodyPattern`

### Request Example
```swift
HTTPRoute(methods: [.GET, .POST], path: "/users", headers: [.contentType: "application/json"], body: JSONBodyPattern())
```

### Response
#### Success Response (N/A)
No return value.

#### Response Example
N/A
```

--------------------------------

### waitUntilListening(timeout:) extension method

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Suspends until the server has started listening. Implemented with withIdentifiableThrowingContinuation; when run() binds the socket the continuation is resumed. Throws SocketError.timeout if the server does not start within timeout seconds. Defined in FlyingFox/Sources/HTTPServer+Listening.swift.

```swift
public func waitUntilListening(timeout: TimeInterval = 5) async throws
```

--------------------------------

### Example: error handling with ProxyHTTPHandler

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/RedirectHTTPHandler.md

Error-handling example: calls handleRequest directly and prints the status code. Catches URLError to inspect the error code (e.g., .badURL, .badServerResponse, .timedOut) and a generic catch for other errors.

```swift
import FlyingFox

let proxy = ProxyHTTPHandler(base: "https://pie.dev", timeout: 5)
let request = HTTPRequest(method: .GET, version: .http11, path: "/get", query: [], headers: [:], body: Data())

do {
    let response = try await proxy.handleRequest(request)
    print(response.statusCode.code, try await response.bodyData)
} catch let error as URLError {
    print("proxy failed:", error.code) // .badURL, .badServerResponse, .timedOut, …
} catch {
    print("proxy failed:", error)
}
```

--------------------------------

### init(address:timeout:pool:logger:handler:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPServer.md

Initializes a new HTTPServer actor with an address, timeout, pool, logger, and optional handler.

```APIDOC
## [ACTOR] HTTPServer

### Description
Initializes a new HTTPServer actor with an address, timeout, pool, logger, and optional handler.

### Method
init

### Signature
public init(address: some SocketAddress, timeout: TimeInterval = 15, pool: some AsyncSocketPool = defaultPool(), logger: any Logging = defaultLogger(), handler: (any HTTPHandler)? = nil)

### Parameters
- **address** (some SocketAddress) - Required - The socket address to bind the server to.
- **timeout** (TimeInterval) - Optional - The timeout interval for connections. Defaults to 15.
- **pool** (some AsyncSocketPool) - Optional - The socket pool to use. Defaults to defaultPool().
- **logger** (any Logging) - Optional - The logger to use. Defaults to defaultLogger().
- **handler** (any HTTPHandler?) - Optional - The root HTTP handler for incoming requests.

### Response
Returns a new HTTPServer actor instance.
```

--------------------------------

### init(headers:webSocket:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPResponse.md

Builds a 101 Switching Protocols response with a WebSocket handler. The server then performs the WebSocket handshake and frame exchange.

```APIDOC
## init(headers:webSocket:)

### Description
Builds a `101 Switching Protocols` response with `payload == .webSocket(handler)`. The server then performs the WebSocket handshake and frame exchange.

### Initializer
`public init(headers: HTTPHeaders = [:], webSocket handler: some WSHandler)`

### Parameters
- **headers** (`HTTPHeaders`) - Optional - Response headers. Default: `[:]`
- **webSocket** (`some WSHandler`) - Required - WebSocket handler.

### Example
```swift
let response = HTTPResponse(webSocket: myHandler)
```
```

--------------------------------

### RedirectHTTPHandler usage example

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/RedirectHTTPHandler.md

Example of using RedirectHTTPHandler with HTTPServer. It shows fixed-location redirects, dynamic redirects via base URL, prefix removal with serverPath, and a custom status code. The server runs on port 8080.

```swift
import FlyingFox

let server = HTTPServer(port: 8080)

// Fixed location: GET /fish/chips  --->  301 Location: https://pie.dev/get
await server.appendRoute("GET /fish/*", to: .redirect(to: "https://pie.dev/get"))

// Dynamic: GET /fish/chips  --->  301 Location: https://pie.dev/fish/chips
await server.appendRoute("GET /fish/*", to: .redirect(via: "https://pie.dev"))

// Prefix removal: GET /fish/chips  --->  301 Location: https://pie.dev/chips
await server.appendRoute("GET /fish/*", to: .redirect(via: "https://pie.dev", serverPath: "/fish"))

// Custom status code
await server.appendRoute("GET /moved", to: RedirectHTTPHandler(location: "https://example.com/new", statusCode: .temporaryRedirect))
try await server.run()
```

--------------------------------

### GET *

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Proxies requests via a base URL.

```APIDOC
## [GET] *

### Description
Proxies requests via a base URL.

### Method
GET

### Endpoint
*

### Parameters
#### Query Parameters
- **fish** (string) - Optional - Query parameters are forwarded to the proxy URL.

### Request Example
None

### Response
#### Success Response (200)
- **response** (HTTPResponse) - The response from the proxied URL.

#### Response Example
```json
{
  "response": "proxied response"
}
```
```

--------------------------------

### Configure and run HTTPServer with custom settings

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/configuration.md

Use this Swift snippet to create an HTTPServer with a custom configuration, including address, timeout, buffer sizes, socket pool, and logger. It then runs the server. Requires FlyingFox and FlyingSocks imports.

```swift
import FlyingFox
import FlyingSocks

let config = HTTPServer.Configuration(
    address: sockaddr_in6.loopback(port: 8443),
    timeout: 30,
    sharedRequestBufferSize: 8_192,
    sharedRequestReplaySize: 4_194_304,
    pool: SocketPool.ePoll(maxEvents: 64, logger: .print(category: "epoll")),
    logger: .oslog(bundle: .main, category: "MyServer")
)

let server = HTTPServer(config: config, handler: nil)
try await server.run()
```

--------------------------------

### HTTPRoute init(methods:path:headers:body:) with Set

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRoute.md

Creates an HTTPRoute with a set of methods, a path (optionally including query), required header values, and an optional body matcher. The path is parsed into components by readComponents; header values equal to "*" match any value.

```swift
public init(
    methods: Set<HTTPMethod>,
    path: String,
    headers: [HTTPHeader: String] = [:],
    body: (any HTTPBodyPattern)? = nil
)
```

--------------------------------

### ProxyHTTPHandler.init(base:session:timeout:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/configuration.md

Initializes a proxy HTTP handler.

```APIDOC
## ProxyHTTPHandler.init(base:session:timeout:)

### Description
Initializes a proxy HTTP handler that forwards requests to a base URL using a URLSession.

### Parameters
- **base** (String) - Required - The base URL to proxy to.
- **session** (URLSession) - Optional - The URLSession to use. Defaults to `.shared`.
- **timeout** (TimeInterval?) - Optional - The timeout interval. Defaults to `nil`.

### Usage
```swift
ProxyHTTPHandler(base: "https://api.example.com", session: .shared, timeout: nil)
```
```

--------------------------------

### Get server listening address

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Retrieves the current listening address of the server.

```swift
await server.listeningAddress
```

--------------------------------

### init(_:headers:body:) (string-literal form)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRoute.md

The primary human-facing initializer that parses a string to define the route.

```APIDOC
## init(_:headers:body:) (string-literal form)

### Description
The primary human-facing initializer. The string is parsed by `components(for:)`: if the first whitespace-delimited token does not start with `/` it is treated as a comma-delimited method list (`"GET,POST /path"`); otherwise all methods match. Empty method lists expand to `HTTPMethod.allMethods`.

### Method
INIT

### Endpoint
N/A

### Parameters
#### Parameters
- **_ string** (`String`) - Required - The string to parse, e.g. `"GET,POST /path"`
- **headers** (`[HTTPHeader: String]`) - Optional - Required header values; any value where the string is `"*"`
- **body** (`(any HTTPBodyPattern)?`) - Optional - Body matcher, e.g. `JSONBodyPattern`

### Request Example
```swift
HTTPRoute("GET,POST /users")
HTTPRoute("/users")
```

### Response
#### Success Response (N/A)
No return value.

#### Response Example
N/A
```

--------------------------------

### GET /moved

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/RedirectHTTPHandler.md

Redirects requests to a fixed location with a custom status code.

```APIDOC
## [GET] /moved

### Description
Redirects requests to a fixed location with a custom status code.

### Method
GET

### Endpoint
/moved

### Response
#### Success Response (307)
- **Location** (string) - The redirect target URL.

#### Response Example
HTTP/1.1 307 Temporary Redirect
Location: https://example.com/new

### Error Handling
- If the location is invalid, a `URLError(.badURL)` is thrown.
```

--------------------------------

### init(method:version:path:query:headers:body:remoteAddress:)

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/HTTPRequest.md

Alternative initializer taking decoded path and query parameters. The target is produced by HTTPEncoder.makeTarget(path:query:).

```swift
public init(
    method: HTTPMethod,
    version: HTTPVersion,
    path: String,
    query: [QueryItem],
    headers: HTTPHeaders,
    body: HTTPBodySequence,
    remoteAddress: Address? = nil
)
```

--------------------------------

### ProxyHTTPHandler

Source: https://github.com/swhitty/flyingfox/blob/main/_autodocs/api-reference/RedirectHTTPHandler.md

Documentation for the ProxyHTTPHandler struct, including its initializer and handleRequest method, with examples.

```APIDOC
## ProxyHTTPHandler

### Description
A proxy HTTP handler that forwards requests to a specified base URL. It implements the `HTTPHandler` protocol and is used to proxy incoming requests to another server.

### Method
- `init(base:session:timeout:)` - Initializes a new proxy handler.
- `handleRequest(_:)` - Handles an incoming HTTP request by forwarding it to the base URL.

### Parameters
#### init(base:session:timeout:)
- **base** (String) - Required - The base URL to forward requests to.
- **session** (URLSession) - Optional - The URLSession to use for the request. Defaults to `.shared`.
- **timeout** (TimeInterval?) - Optional - The timeout interval for the request. If set, configures `URLRequest.timeoutInterval`.

#### handleRequest(_:)
- **request** (HTTPRequest) - Required - The incoming HTTP request to forward.

### Behavior
1. `makeURL(for:)` - Appends the request path to the base URL and appends query items. Throws `URLError(.badURL)` if the base is not a valid URL.
2. `makeURLRequest(for:)` - Sets the HTTP method, body, and forwards headers except `.host`, `.connection`, and `.contentLength`.
3. `session.data(for:)` - Performs the request. Throws `URLError(.badServerResponse)` if the response is not an `HTTPURLResponse`.
4. `makeResponse(for:data:)` - Copies response headers, removes `Content-Encoding`, and builds an `HTTPResponse`.

### Example
```swift
import FlyingFox

let server = HTTPServer(port: 8080)
await server.appendRoute("GET *", to: .proxy(via: "https://pie.dev"))
// GET /get?fish=chips  ---->  GET https://pie.dev/get?fish=chips

// With a configurable timeout and session
let session: URLSession = .shared
await server.appendRoute("POST *", to: ProxyHTTPHandler(base: "https://api.example.com",
                                                        session: session,
                                                        timeout: 30))
try await server.run()
```

### Example: error handling
```swift
import FlyingFox

let proxy = ProxyHTTPHandler(base: "https://pie.dev", timeout: 5)
let request = HTTPRequest(method: .GET, version: .http11, path: "/get", query: [], headers: [:], body: Data())

do {
    let response = try await proxy.handleRequest(request)
    print(response.statusCode.code, try await response.bodyData)
} catch let error as URLError {
    print("proxy failed:", error.code) // .badURL, .badServerResponse, .timedOut, …
} catch {
    print("proxy failed:", error)
}
```
```

--------------------------------

### GET /fish/*

Source: https://github.com/swhitty/flyingfox/blob/main/README.md

Groups multiple handlers with requests and matches them against HTTPRoute using RoutedHTTPHandler.

```APIDOC
## [GET] /fish/*

### Description
Groups multiple handlers with requests and matches them against HTTPRoute using RoutedHTTPHandler.

### Method
GET

### Endpoint
/fish/*

### Parameters
#### Path Parameters
- **\*** (string) - Required - The path to match against registered routes.

### Request Example
None

### Response
#### Success Response (200)
- **response** (HTTPResponse) - The response from the matched handler.

#### Response Example
```json
{
  "response": "matched handler response"
}
```
```
Tokens:
Raw