SWIFT-1396 Update Vapor example to use async/await (#726)

Author: kmahar

Examples/VaporExample/Package.swift

@@ -1,15 +1,15 @@
-// swift-tools-version:5.2
+// swift-tools-version:5.5
 import PackageDescription
 
 let package = Package(
     name: "VaporExample",
     platforms: [
-        .macOS(.v10_15)
+        .macOS(.v12)
     ],
     dependencies: [
-        .package(url: "https://github.com/vapor/vapor", .upToNextMajor(from: "4.7.0")),
+        .package(url: "https://github.com/vapor/vapor", .upToNextMajor(from: "4.50.0")),
         .package(url: "https://github.com/vapor/leaf", .upToNextMajor(from: "4.0.0")),
-        .package(url: "https://github.com/mongodb/mongodb-vapor", .upToNextMajor(from: "1.0.0"))
+        .package(url: "https://github.com/mongodb/mongodb-vapor", .exact("1.1.0-alpha.1"))
     ],
     targets: [
         .target(
@@ -18,9 +18,16 @@ let package = Package(
                 .product(name: "Vapor", package: "vapor"),
                 .product(name: "Leaf", package: "leaf"),
                 .product(name: "MongoDBVapor", package: "mongodb-vapor")
+            ],
+            swiftSettings: [
+                // Enable better optimizations when building in Release configuration. Despite the use of
+                // the `.unsafeFlags` construct required by SwiftPM, this flag is recommended for Release
+                // builds. For details, see
+                // <https://github.com/swift-server/guides/blob/main/docs/building.md#building-for-production>.
+                .unsafeFlags(["-cross-module-optimization"], .when(configuration: .release))
             ]
         ),
-        .target(name: "Run", dependencies: [
+        .executableTarget(name: "Run", dependencies: [
             .target(name: "App"),
             .product(name: "MongoDBVapor", package: "mongodb-vapor")
         ])

Examples/VaporExample/README.md

@@ -8,22 +8,22 @@ This application is intended to demonstrate best practices for integrating the d
 
 The application contains both a REST API as well as a minimal frontend built with Vapor's templating language [Leaf](https://github.com/vapor/leaf).
 
-This application require Swift 5.2 and MongoDB 3.6+. It will run on Linux as well as macOS 10.15+.
+This application requires Swift 5.5+ and MongoDB 3.6+. It will run on Linux as well as macOS 12+.
+
+If you are looking for an example application that uses older Swift versions prior to the introduction of structured concurrency, please refer to a previous version of this application and README [here](https://github.com/mongodb/mongo-swift-driver/tree/5d9fad121d7cb3ded61087de300ff007766ccd55/Examples/VaporExample).
 
 ## Building and Running the Application
 1. Install MongoDB on your system if you haven't already. Downloads are available [here](https://www.mongodb.com/download-center/community).
 1. Start up MongoDB running locally: `mongod --dbpath some-directory-here`. You may need to specify a `dbpath` directory for the database to use.
 1. Run `./loadData.sh` to load example application data into the database.
-1. Install Swift 5.2+ on your system if you haven't already. You can download Swift and find instructions for installing it [here](https://swift.org/download/).
+1. Install Swift 5.5+ on your system if you haven't already. You can download Swift and find instructions for installing it [here](https://swift.org/download/).
 1. From the root directory of the project, run `swift build`. This will likely take a while the first time you do so.
 1. Once building has completed, run `swift run` from the root directory. You should get a message that the server has started running on `http://127.0.0.1:8080`.
 1. Open up your browser and visit `http://127.0.0.1:8080`. You should see the application and be able to test out adding, deleting, and editing data in the collection.
 
 ## Application Architecture
 
-This is a fully asynchronous application. At its core is [SwiftNIO](https://github.com/apple/swift-nio), which is used to implement both Vapor and the MongoDB driver.
-
-The application has both web and REST API interfaces, which support storing a list of kittens and details about them.
+This is a fully asynchronous application with both web and REST API interfaces, which support storing a list of kittens and details about them.
 
 The server will handle the following types of web requests:
 1. A GET request at the root URL `/` loads the main index page containing a list of kittens.
@@ -43,19 +43,14 @@ If you'd like to point the application to a MongoDB server elsewhere (e.g. on [M
 
 The call to `configure()` initializes a global `MongoClient` to back your application. `MongoClient` is implemented with that approach in mind: it is safe to use across threads, and is backed by a [connection pool](https://en.wikipedia.org/wiki/Connection_pool) which enables sharing resources throughout the application.
 
-Throughout your application, you can access the global client via `app.mongoDB.client`. Note that the global client may return `EventLoopFuture`s on *any* `EventLoop` in the application's `EventLoopGroup`, so if you use this client you will need to ensure you "hop" the futures back to the event loop you are currently on. See the `EventLoopFuture` [documentation](https://apple.github.io/swift-nio/docs/current/NIO/Classes/EventLoopFuture.html) for more details.
-
-To avoid the need to hop `EventLoop`s, whenever you are using MongoDB in a request handler, we strongly recommend you use an `EventLoopBoundMongoClient` instead, accessible via `req.mongoDB.client`. This type is a small wrapper around the global client, which returns `EventLoopFuture`s on a specific `EventLoop` which it is "bound" to. Using an `EventLoopBoundMongoClient` that is backed by the same `EventLoop` as a `Request` means you can use the client within a request handler without worrying about thread safety. You can access an `EventLoopBoundMongoClient` for a `Request` via `req.mongoDB.client`.
-
-`MongoDatabase`s and `MongoCollection`s you retrieve from an `EventLoopBoundMongoClient` will automatically be bound to the same event loop as the parent client.
+Throughout your application, you can access the global client via `app.mongoDB.client`.
 
 For convenience, we recommend adding your own computed properties to `Request` that return `MongoDatabase`s and `MongoCollection`s you frequently access, as is shown in `Sources/App/routes.swift` 
 with the `kittenCollection` property:
 ```swift
 extension Request {
-    /// Convenience extension for obtaining a collection which uses the same event loop as a request.
     var kittenCollection: MongoCollection<Kitten> {
-        self.mongoDB.client.db("home").collection("kittens", withType: Kitten.self)
+        self.application.mongoDB.client.db("home").collection("kittens", withType: Kitten.self)
     }
 }
 ```
@@ -70,7 +65,7 @@ When creating a `MongoCollection`, you can pass in the name of a `Codable` type:
 let collection = req.mongoDB.client.db("home").collection("kittens", withType: Kitten.self)
 ```
 
-This will instantiate a `MongoCollection<Kitten>`. You can then use `Kitten` directly with many API methods -- for example, `insertOne` will directly accept a `Kitten` instance, and `findOne` will return an `EventLoopFuture<Kitten>`.
+This will instantiate a `MongoCollection<Kitten>`. You can then use `Kitten` directly with many API methods -- for example, `insertOne` will directly accept a `Kitten` instance, and `findOne` will return a `Kitten?`.
 
 Sometimes you may need to work with the `BSONDocument` type as well, for example when providing a query filter. If you want to construct these documents from `Codable` types you may do so using `BSONEncoder`, as we do with the `updateDocument` in the `updateKitten()` method via the `KittenUpdate` struct.
 

Examples/VaporExample/Sources/App/routes.swift

@@ -4,19 +4,17 @@ import Vapor
 /// Adds a collection of web routes to the application.
 func webRoutes(_ app: Application) throws {
     /// Handles a request to load the main index page containing a list of kittens.
-    app.get { req -> EventLoopFuture<View> in
-        req.findKittens().flatMap { kittens in
-            // Return the corresponding Leaf view, providing the list of kittens as context.
-            req.view.render("index.leaf", ["kittens": kittens])
-        }
+    app.get { req async throws -> View in
+        let kittens = try await req.findKittens()
+        // Return the corresponding Leaf view, providing the list of kittens as context.
+        return try await req.view.render("index.leaf", ["kittens": kittens])
     }
 
     /// Handles a request to load a page with info about a particular kitten.
-    app.get("kittens", ":name") { req -> EventLoopFuture<View> in
-        try req.findKitten().flatMap { kitten in
-            // Return the corresponding Leaf view, providing the kitten as context.
-            req.view.render("kitten.leaf", kitten)
-        }
+    app.get("kittens", ":name") { req async throws -> View in
+        let kitten = try await req.findKitten()
+        // Return the corresponding Leaf view, providing the kitten as context.
+        return try await req.view.render("kitten.leaf", kitten)
     }
 }
 
@@ -25,33 +23,33 @@ func restAPIRoutes(_ app: Application) throws {
     let rest = app.grouped("rest")
 
     /// Handles a request to load the list of kittens.
-    rest.get { req -> EventLoopFuture<[Kitten]> in
-        req.findKittens()
+    rest.get { req async throws -> [Kitten] in
+        try await req.findKittens()
     }
 
     /// Handles a request to add a new kitten.
-    rest.post { req -> EventLoopFuture<Response> in
-        try req.addKitten()
+    rest.post { req async throws -> Response in
+        try await req.addKitten()
     }
 
     /// Handles a request to load info about a particular kitten.
-    rest.get("kittens", ":name") { req -> EventLoopFuture<Kitten> in
-        try req.findKitten()
+    rest.get("kittens", ":name") { req async throws -> Kitten in
+        try await req.findKitten()
     }
 
-    rest.delete("kittens", ":name") { req -> EventLoopFuture<Response> in
-        try req.deleteKitten()
+    rest.delete("kittens", ":name") { req async throws -> Response in
+        try await req.deleteKitten()
     }
 
-    rest.patch("kittens", ":name") { req -> EventLoopFuture<Response> in
-        try req.updateKitten()
+    rest.patch("kittens", ":name") { req async throws -> Response in
+        try await req.updateKitten()
     }
 }
 
 extension Request {
-    /// Convenience extension for obtaining a collection which uses the same event loop as a request.
+    /// Convenience extension for obtaining a collection.
     var kittenCollection: MongoCollection<Kitten> {
-        self.mongoDB.client.db("home").collection("kittens", withType: Kitten.self)
+        self.application.mongoDB.client.db("home").collection("kittens", withType: Kitten.self)
     }
 
     /// Constructs a document using the name from this request which can be used a filter for MongoDB
@@ -65,69 +63,73 @@ extension Request {
         return ["name": .string(name)]
     }
 
-    func findKittens() -> EventLoopFuture<[Kitten]> {
-        self.kittenCollection.find().flatMap { cursor in
-            cursor.toArray()
-        }.flatMapErrorThrowing { error in
+    func findKittens() async throws -> [Kitten] {
+        do {
+            return try await self.kittenCollection.find().toArray()
+        } catch {
             throw Abort(.internalServerError, reason: "Failed to load kittens: \(error)")
         }
     }
 
-    func findKitten() throws -> EventLoopFuture<Kitten> {
+    func findKitten() async throws -> Kitten {
         let nameFilter = try self.getNameFilter()
-        return self.kittenCollection.findOne(nameFilter)
-            .unwrap(or: Abort(.notFound, reason: "No kitten with matching name"))
+        guard let kitten = try await self.kittenCollection.findOne(nameFilter) else {
+            throw Abort(.notFound, reason: "No kitten with matching name")
+        }
+        return kitten
     }
 
-    func addKitten() throws -> EventLoopFuture<Response> {
+    func addKitten() async throws -> Response {
         let newKitten = try self.content.decode(Kitten.self)
-        return self.kittenCollection.insertOne(newKitten)
-            .map { _ in Response(status: .created) }
-            .flatMapErrorThrowing { error in
-                // Give a more helpful error message in case of a duplicate key error.
-                if let err = error as? MongoError.WriteError, err.writeFailure?.code == 11000 {
-                    throw Abort(.conflict, reason: "A kitten with the name \(newKitten.name) already exists!")
-                }
-                throw Abort(.internalServerError, reason: "Failed to save new kitten: \(error)")
+        do {
+            try await self.kittenCollection.insertOne(newKitten)
+            return Response(status: .created)
+        } catch {
+            // Give a more helpful error message in case of a duplicate key error.
+            if let err = error as? MongoError.WriteError, err.writeFailure?.code == 11000 {
+                throw Abort(.conflict, reason: "A kitten with the name \(newKitten.name) already exists!")
             }
+            throw Abort(.internalServerError, reason: "Failed to save new kitten: \(error)")
+        }
     }
 
-    func deleteKitten() throws -> EventLoopFuture<Response> {
+    func deleteKitten() async throws -> Response {
         let nameFilter = try self.getNameFilter()
-        return self.kittenCollection.deleteOne(nameFilter)
-            .flatMapErrorThrowing { error in
-                throw Abort(.internalServerError, reason: "Failed to delete kitten: \(error)")
+        do {
+            // since we aren't using an unacknowledged write concern we can expect deleteOne to return a non-nil result.
+            guard let result = try await self.kittenCollection.deleteOne(nameFilter) else {
+                throw Abort(.internalServerError, reason: "Unexpectedly nil response from database")
             }
-            // since we are not using an unacknowledged write concern we can expect deleteOne to return
-            // a non-nil result.
-            .unwrap(or: Abort(.internalServerError, reason: "Unexpectedly nil response from database"))
-            .flatMapThrowing { result in
-                guard result.deletedCount == 1 else {
-                    throw Abort(.notFound, reason: "No kitten with matching name")
-                }
-                return Response(status: .ok)
+            guard result.deletedCount == 1 else {
+                throw Abort(.notFound, reason: "No kitten with matching name")
             }
+            return Response(status: .ok)
+        } catch {
+            throw Abort(.internalServerError, reason: "Failed to delete kitten: \(error)")
+        }
     }
 
-    func updateKitten() throws -> EventLoopFuture<Response> {
+    func updateKitten() async throws -> Response {
         let nameFilter = try self.getNameFilter()
         // Parse the update data from the request.
         let update = try self.content.decode(KittenUpdate.self)
         /// Create a document using MongoDB update syntax that specifies we want to set a field.
         let updateDocument: BSONDocument = ["$set": .document(try BSONEncoder().encode(update))]
 
-        return self.kittenCollection.updateOne(filter: nameFilter, update: updateDocument)
-            .flatMapErrorThrowing { error in
-                throw Abort(.internalServerError, reason: "Failed to update kitten: \(error)")
+        do {
+            // since we aren't using an unacknowledged write concern we can expect updateOne to return a non-nil result.
+            guard let result = try await self.kittenCollection.updateOne(
+                filter: nameFilter,
+                update: updateDocument
+            ) else {
+                throw Abort(.internalServerError, reason: "Unexpectedly nil response from database")
             }
-            // since we are not using an unacknowledged write concern we can expect updateOne to return
-            // a non-nil result.
-            .unwrap(or: Abort(.internalServerError, reason: "Unexpectedly nil response from database"))
-            .flatMapThrowing { result in
-                guard result.matchedCount == 1 else {
-                    throw Abort(.notFound, reason: "No kitten with matching name")
-                }
-                return Response(status: .ok)
+            guard result.matchedCount == 1 else {
+                throw Abort(.notFound, reason: "No kitten with matching name")
             }
+            return Response(status: .ok)
+        } catch {
+            throw Abort(.internalServerError, reason: "Failed to update kitten: \(error)")
+        }
     }
 }