Introducing the `swift-http-error-handling` package!

Community Showcase
, , ,
1

Hey again, Swift community!

I am excited to introduce swift-http-error-handling, my open-source package for interpreting HTTP responses and handling failures. It is built on top of the swift-retry package, which I announced a couple weeks ago.

The motivation for both of these packages came from an app I was building where the app needed to retry operations, including HTTP requests. Hopefully, you will find the two packages easy to use and suitable for your own use cases.

Continue reading to learn more about the swift-http-error-handling package.

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.

2 Likes
2

I added some more details to the Overview section of the above post and the README so that readers can quickly understand what the package does without having to dig into the documentation.

3

That sounds like retroactive conformance of an external type - your package doesn't define the type (HTTPRequest) nor the protocol (RetryableRequest). That's not permitted (since SE-0364). It's currently subject to a compiler warning but may become an error in future.

(not meaning to rain on your parade - this seems like a great new package - just trying to avoid you future pain)

1 Like