Osiris

A multipart form encoder for Swift, as well as some other utilities that make working with HTTP a bit simpler and more flexible.

Installation

Copy the files you want to use into your project, and then customize them to suit your needs.

Multipart Form Encoding

Create an encoder and then add parts to it as needed:

let avatarData = UIImage(from: somewhere).jpegData(compressionQuality: 1)
let encoder = MultipartFormEncoder()
let body = try encoder.encodeData(parts: [
    .text(name: "email", text: "[email protected]"),
    .text(name: "password", text: "secret"),
    .binary(name: "avatar", type: "image/jpeg", data: avatarData, filename: "avatar.jpg"),
])

The form can be encoded as Data in memory, or to a file. There's a hard limit of 50 MB on encoding to memory but in practice you probably never want to go that high purely in memory. If you're adding any kind of image or video file then it's probably better to stream to a file.

let body = try encoder.encodeFile(parts: [/* ... */])
var request = URLRequest(url: URL(string: "https://example.com/accounts")!)
request.httpMethod = "POST"
request.httpBodyStream = InputStream(url: body.url)
request.addValue(body.contentType, forHTTPHeaderField: "Content-Type")
request.addValue("\(body.contentLength)", forHTTPHeaderField: "Content-Length")
// ... whatever you normally do with requests

HTTPRequest

Basic usage:

let url = URL(string: "https://example.com")!
let request = HTTPRequest(method: .get, url: url)

Fancier usage:

let url = URL(string: "https://example.com")!
let params = ["email" : "[email protected]", "password" : "secret"]
let request = HTTPRequest(method: .post, url: url, contentType: .json, parameters: params)
request.addHeader(name: "x-custom", value: "42")
request.addMultipartJPEG(name: "avatar", image: UIImage(), quality: 1, filename: "avatar.jpg")

You can build a URLRequest from an HTTPRequest instance using RequestBuilder. Or make your own builder.

HTTPResponse

This enum makes sense of the 3 parameters of URLSession's completion block. Its initializer takes in the optional URLResponse, Data, and Error values and determines if the request succeeded or failed, taking the HTTP status code into account. 200-level statuses are successes and anything else is a failure.

The success case has two associated values: HTTPURLResponse and Data?, while the failure case has three associated values: Error, HTTPURLResponse, and Data?.

Some properties are exposed for convenience:

• data: the optional body data returned by the server.

• status: the HTTP status code returned by the server, or 0 if the request itself failed, e.g. if the server cannot be reached.

• headers: a dictionary of headers.

• bodyString: the response body as a String. This is an empty string if the body is empty or there was an error decoding it as UTF8.

• dictionaryFromJSON: the decoded body for JSON responses. This is an empty dictionary if the body is empty or there was an error decoding it as a JSON dictionary.

• underlyingResponse: the HTTPURLResponse in case you need to dive in.

RequestBuilder

This class takes in an HTTPRequest instance and turns it into a URLRequest for use with URLSession.

Usage:

let urlRequest: URLRequest
do {
    urlRequest = try RequestBuilder.build(request: request)
}
catch {
    log.error("Invalid request \(request): \(error)")
    return
}
// ... do something with urlRequest

It encodes multipart requests in memory, so you'll need to change it or make your own builder for advanced functionality like encoding multipart forms to disk instead.

FormEncoder

This was lifted from Alamofire, but with some minor changes.

let body = FormEncoder.encode(["email" : "[email protected]", "password" : "secret"])
// => "email=someone%40example.com&password=secret"

Service: Putting it all Together

Take a look at Service.swift to see how it can all come together. Grafting your specific service API onto the primitives shown there is an exercise. In 1SE we're just adding methods to Service for each specific call, but you could keep them separate instead if you prefer that.

I don't recommend you use Service as shown here, but maybe use it as a jumping off point for something that makes sense to you for your specific application.

Credits

Mostly created by Sami Samhuri for 1SE. FormEncoder.swift was lifted from Alamofire.

License

Copyright © 2017 1 Second Everyday. All rights reserved.

Released under the terms of the MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.