README.md

swift-http-error-handling

Interpret HTTP responses and handle failures in Swift.

Overview

In the HTTP protocol, a client sends a request to a server and the server sends a response back to the client. The response contains a status code to help the client interpret the response.

HTTP libraries like Foundation pass the response through to the caller without interpreting the response as a success or failure. HTTPErrorHandling can help the caller interpret HTTP responses and handle failures.

The module works with any HTTP library that is compatible with Swift’s standard HTTP request and response types. The module can be used on its own in code that directly uses an HTTP library, or the module can be used as a building block by higher-level networking libraries.

Representing an HTTP Application Failure

After interpreting an HTTP response as a success or a failure, there needs to be a way to represent a failure. In Swift, failures are represented by a type that conforms to the Error protocol. Therefore, the module exposes an HTTPApplicationError type to represent a failure.

Interpreting HTTP Responses

The module extends HTTPResponse with a throwIfFailed method that interprets the response as a success or failure. The method throws HTTPApplicationError if the response is interpreted as a failure.

Some HTTP servers add additional details about a failure to the response body. The throwIfFailed method allows for the response body to be deserialized and attached to the error so that the additional failure details can be accessed later.

Retrying HTTP Requests

The module extends HTTPRequest to add conformance to RetryableRequest, which is a protocol from the swift-retry package that adds safe retry methods to the type. The safe retry methods enforce that the HTTP request is idempotent.

The retry method implementations automatically choose a RecoveryAction for HTTPApplicationError using HTTP-specific information including whether the failure is transient and the value of the Retry-After header, if present.

Example Usage With URLSession

import Foundation
import HTTPErrorHandling
import HTTPTypes
import HTTPTypesFoundation

let request = HTTPRequest(method: .get,
                          scheme: "https",
                          authority: "example.com",
                          path: "/")

let responseBody = try await request.retry { request in
   let (responseBody, response) = try await URLSession.shared.data(for: request)
   try response.throwIfFailed()
   return responseBody
}

See the documentation for more examples.