File add API server in Vapor 4

A easy file add server written in Swift

For this straightforward file add tutorial we’ll solely use the Vapor Swift package deal as a dependency. 📦

// swift-tools-version:5.3
import PackageDescription

let package deal = Bundle(
    title: "myProject",
    platforms: [
       .macOS(.v10_15)
    ],
    dependencies: [
        .package(url: "https://github.com/vapor/vapor", from: "4.35.0"),
    ],
    targets: [
        .target(
            name: "App",
            dependencies: [
                .product(name: "Vapor", package: "vapor"),
            ],
            swiftSettings: [
                .unsafeFlags(["-cross-module-optimization"], .when(configuration: .launch))
            ]
        ),
        .goal(title: "Run", dependencies: [.target(name: "App")]),
        .testTarget(title: "AppTests", dependencies: [
            .target(name: "App"),
            .product(name: "XCTVapor", package: "vapor"),
        ])
    ]
)

You possibly can setup the mission with the required recordsdata utilizing the Vapor toolbox, alternatively you’ll be able to create all the pieces by hand utilizing the Swift Bundle Supervisor, lengthy story quick, we simply want a starter Vapor mission with out extra dependencies. Now when you open the Bundle.swift file utilizing Xcode, we will setup our routes by altering the configure.swift file.

import Vapor

public func configure(_ app: Utility) throws {

    /// allow file middleware
    app.middleware.use(FileMiddleware(publicDirectory: app.listing.publicDirectory))

    /// set max physique measurement
    app.routes.defaultMaxBodySize = "10mb"

    /// setup the add handler
    app.publish("add") { req -> EventLoopFuture in
        let key = attempt req.question.get(String.self, at: "key")
        let path = req.software.listing.publicDirectory + key
        return req.physique.accumulate()
            .unwrap(or: Abort(.noContent))
            .flatMap { req.fileio.writeFile($0, at: path) }
            .map { key }
    }
}

First we use the FileMiddleware, this can enable us to server recordsdata utilizing the Public listing inside our mission folder. Should you don’t have a listing named Public, please create one, for the reason that file add server will want that. Don’t overlook to offer correct file system permissions if crucial, in any other case we received’t be capable of write our knowledge contained in the listing. 📁

The subsequent factor that we set is the default most physique measurement. This property can restrict the quantity of information that our server can settle for, you don’t actually wish to use this technique for big recordsdata as a result of uploaded recordsdata shall be saved within the system reminiscence earlier than we write them to the disk.

If you wish to add massive recordsdata to the server you must contemplate streaming the file as an alternative of accumulating the file knowledge from the HTTP physique. The streaming setup would require a bit extra work, nevertheless it’s not that difficult, in case you are curious about that answer, you must learn the Recordsdata API and the physique streaming part utilizing official Vapor docs website.

This time we simply need a lifeless easy file add API endpoint, that collects the incoming knowledge utilizing the HTTP physique right into a byte buffer object, then we merely write this buffer utilizing the fileio to the disk, utilizing the given key from the URL question parameters. If all the pieces was achieved with out errors, we will return the important thing for the uploaded file.

File add duties utilizing the URLSession API
The Basis frameworks offers us a pleasant API layer for widespread networking duties. We will use the URLSession uploadTask technique to ship a brand new URLRequest with an information object to a given server, however IMHO this API is sort of unusual, as a result of the URLRequest object already has a httpBody property, however you must explicitly move a “from: Information?” argument while you assemble the duty. However why? 🤔

import Basis

extension URLSession {

    func uploadTask(with request: URLRequest, completionHandler: @escaping (Information?, URLResponse?, Error?) -> Void) -> URLSessionUploadTask {
        uploadTask(with: request, from: request.httpBody, completionHandler: completionHandler)
    }
}

Anyway, I made slightly extension technique, so once I create the URLRequest I can set the httpBody property of it and safely move it earlier than the completion block and use the contents because the from parameter. Very unusual API design selection from Apple… 🤐

We will put this little snippet right into a easy executable Swift package deal (or after all we will create a whole software) to check our add server. In our case I’ll place all the pieces right into a principal.swift file.

import Basis
import Dispatch

extension URLSession {

    func uploadTask(with request: URLRequest, completionHandler: @escaping (Information?, URLResponse?, Error?) -> Void) -> URLSessionUploadTask {
        uploadTask(with: request, from: request.httpBody, completionHandler: completionHandler)
    }
}


let fileData = attempt Information(contentsOf: URL(fileURLWithPath: "/Customers/[user]]/[file].png"))
var request = URLRequest(url: URL(string: "http://localhost:8080/add?key=(UUID().uuidString).png")!)
request.httpMethod = "POST"
request.httpBody = fileData

let activity = URLSession.shared.uploadTask(with: request) { knowledge, response, error in
    guard error == nil else {
        fatalError(error!.localizedDescription)
    }
    guard let response = response as? HTTPURLResponse else {
        fatalError("Invalid response")
    }
    guard response.statusCode == 200 else {
        fatalError("HTTP standing error: (response.statusCode)")
    }
    guard let knowledge = knowledge, let outcome = String(knowledge: knowledge, encoding: .utf8) else {
        fatalError("Invalid or lacking HTTP knowledge")
    }
    print(outcome)
    exit(0)
}

activity.resume()
dispatchMain()

The above instance makes use of the Dispatch framework to attend till the asynchronous file add finishes. It’s best to change the situation (and the extension) of the file if crucial earlier than you run this script. Since we outlined the add route as a POST endpoint, we have now to set the httpMethod property to match this, additionally we retailer the file knowledge within the httpBody variable earlier than we create our activity. The add URL ought to comprise a key, that the server can use as a reputation for the file. You possibly can add extra properties after all or use header values to verify if the consumer has correct authorization to carry out the add operation. Then we name the add activity extension technique on the shared URLSession property. The great factor about uploadTask is you can run them on the background if wanted, that is fairly useful if it involves iOS growth. 📱

Contained in the completion handler we have now to verify for a number of issues. To start with if there was an error, the add will need to have failed, so we name the fatalError technique to interrupt execution. If the response was not a legitimate HTTP response, or the standing code was not okay (200) we additionally cease. Lastly we wish to retrieve the important thing from the response physique so we verify the information object and convert it to a UTF8 string if potential. Now we will use the important thing mixed with the area of the server to entry the uploaded file, this time I simply printed out the outcome, however hey, that is only a demo, in an actual world software you would possibly wish to return a JSON response with extra knowledge. 😅

Vanilla JavaScript file uploader

Yet one more factor… you should utilize Leaf and a few Vanilla JavaScript to add recordsdata utilizing the newly created add endpoint. Really it’s very easy to implement a brand new endpoint and render a Leaf template that does the magic. You’ll want some fundamental HTML and some strains of JS code to submit the contents of the file as an array buffer. It is a fundamental instance.

As you’ll be able to see it’s a typical XHR request mixed with the FileReader JavaScript API. We use the FileReader to transform our enter to a binary knowledge, this fashion our server can write it to the file system within the anticipated format. Typically individuals are utilizing a multipart-encoded type to entry recordsdata on the server, however when you must work with an API you may also switch uncooked file knowledge. If you wish to study extra about XHR requests and AJAX calls, you must learn my earlier article.

I even have a publish about totally different file add strategies utilizing commonplace HTML types and a Vapor 4 server as a backend. I hope you’ll discover the precise answer that you simply want on your software. 👍