Requests and Responses

POST /books HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
Content-Length: 44

{"title":"Emma","author":"Jane Austen"}

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /books/4
Content-Length: 46

{"author":"Jane Austen","id":4,"title":"Emma"}

import Vapor

struct HeaderReport: Content {
    var preferredFormat: String
    var acceptedTypes: [String]
    var bearerToken: String?
    var basicUser: String?
    var forwardedFor: [String]
    var range: String?
    var cookieNames: [String]
}

func headerRoutes(_ routes: some RoutesBuilder) {
    routes.get("headers") { req async throws -> HeaderReport in
        // Typed accessors parse the raw header for you.
        let accept = req.headers.accept
        let preference = accept.comparePreference(for: .json, to: .html)
        let preferred = preference == .orderedAscending ? "html" : "json"

        // Raw access: names are case-insensitive, a header can occur several times.
        let allAccept = req.headers[.accept]
        _ = allAccept

        return HeaderReport(
            preferredFormat: preferred,
            acceptedTypes: accept.mediaTypes.map { $0.serialize() },
            bearerToken: req.headers.bearerAuthorization?.token,
            basicUser: req.headers.basicAuthorization?.username,
            forwardedFor: req.headers.forwarded.compactMap { $0.for },
            range: req.headers.range.map { $0.serialize() },
            cookieNames: req.cookies.all.keys.sorted()
        )
    }

    routes.get("headers", "set") { req async throws -> Response in
        let response = Response(status: .ok)
        response.headers.add(name: "X-Library", value: "bookshelf")
        response.headers.replaceOrAdd(name: .cacheControl, value: "no-store")
        response.headers.contentType = .plainText
        response.headers.remove(name: "X-Debug")
        response.body = .init(string: "headers set\n")
        return response
    }
}

$ curl -s http://127.0.0.1:8080/headers \
    -H 'Accept: text/html, application/json;q=0.5' -H 'Authorization: Bearer abc.def' \
    -H 'Cookie: a=1; b=2' -H 'Forwarded: for=192.0.2.60;proto=http' -H 'Range: bytes=0-99'
{"range":"bytes=0-99","preferredFormat":"html","acceptedTypes":["text\/html","application\/json; q=0.5"],"forwardedFor":["192.0.2.60"],"cookieNames":["a","b"],"bearerToken":"abc.def"}

$ curl -i http://127.0.0.1:8080/headers/set
HTTP/1.1 200 OK
X-Library: bookshelf
cache-control: no-store
content-type: text/plain; charset=utf-8
content-length: 12
server: bookshelf

headers set

import Vapor

struct UploadResult: Content {
    var bytes: Int
    var lines: Int
}

func bodyRoutes(_ routes: some RoutesBuilder) {
    // Default: the body is collected (up to app.routes.defaultMaxBodySize, 16kb) before the handler runs.
    routes.post("echo") { req async throws -> String in
        guard let text = req.body.string else {
            throw Abort(.badRequest, reason: "Expected a UTF-8 body")
        }
        return text
    }

    // A larger collected limit for one route.
    routes.on(.POST, "import", body: .collect(maxSize: "2mb")) { req async throws -> UploadResult in
        guard let buffer = req.body.data else { throw Abort(.badRequest) }
        let lines = buffer.readableBytesView.filter { $0 == UInt8(ascii: "\n") }.count
        return UploadResult(bytes: buffer.readableBytes, lines: lines)
    }

    // Streaming: the handler starts as soon as the headers are in; the body arrives chunk by chunk.
    routes.on(.PUT, "blobs", ":name", body: .stream) { req async throws -> UploadResult in
        let limit = 50 * 1024 * 1024
        var bytes = 0
        var lines = 0
        for try await chunk in req.body {
            bytes += chunk.readableBytes
            if bytes > limit { throw Abort(.payloadTooLarge) }
            lines += chunk.readableBytesView.filter { $0 == UInt8(ascii: "\n") }.count
        }
        return UploadResult(bytes: bytes, lines: lines)
    }
}

$ curl -si -X POST http://127.0.0.1:8080/echo --data-binary @big.txt     # 2,000,000 bytes
HTTP/1.1 413 Payload Too Large
content-type: application/json; charset=utf-8
content-length: 43

{"error":true,"reason":"Payload Too Large"}

$ printf 'a\nb\nc\n' | curl -s -X POST http://127.0.0.1:8080/import --data-binary @-
{"lines":3,"bytes":6}

$ printf 'a\nb\nc\n' | curl -s -X PUT http://127.0.0.1:8080/blobs/x --data-binary @-
{"lines":3,"bytes":6}

import Vapor

func cookieRoutes(_ routes: some RoutesBuilder) {
    routes.get("visits") { req async throws -> Response in
        let previous = req.cookies["visits"].flatMap { Int($0.string) } ?? 0
        let response = Response(status: .ok, body: .init(string: "visit number \(previous + 1)\n"))
        response.cookies["visits"] = HTTPCookies.Value(
            string: String(previous + 1),
            maxAge: 60 * 60 * 24,
            path: "/",
            isSecure: true,
            isHTTPOnly: true,
            sameSite: .lax
        )
        return response
    }

    routes.post("visits", "reset") { req async throws -> Response in
        let response = Response(status: .noContent)
        response.cookies["visits"] = .expired
        return response
    }
}

$ curl -si http://127.0.0.1:8080/visits | grep -i -e set-cookie -e visit
set-cookie: visits=1; Max-Age=86400; Path=/; Secure; HttpOnly; SameSite=Lax
visit number 1

$ curl -s http://127.0.0.1:8080/visits -H 'Cookie: visits=4'
visit number 5

$ curl -si -X POST http://127.0.0.1:8080/visits/reset | grep -i -e HTTP/ -e set-cookie
HTTP/1.1 204 No Content
set-cookie: visits=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; SameSite=Lax

import Vapor

/// A handler result that is either a book, or a tombstone.
enum BookLookup: AsyncResponseEncodable {
    case found(BookDTO)
    case gone(reason: String)

    func encodeResponse(for request: Request) async throws -> Response {
        switch self {
        case .found(let book):
            return try await book.encodeResponse(for: request)
        case .gone(let reason):
            let response = Response(status: .gone)
            try response.content.encode(["error": reason], as: .json)
            return response
        }
    }
}

/// A plain value wrapped to be returned as CSV.
struct CSVDocument: AsyncResponseEncodable {
    var header: [String]
    var rows: [[String]]
    var filename: String

    func encodeResponse(for request: Request) async throws -> Response {
        let text = ([header] + rows).map { $0.joined(separator: ",") }.joined(separator: "\n") + "\n"
        let response = Response(status: .ok, body: .init(string: text))
        response.headers.contentType = HTTPMediaType(type: "text", subType: "csv", parameters: ["charset": "utf-8"])
        response.headers.contentDisposition = .init(.attachment, filename: filename)
        return response
    }
}

func encodableRoutes(_ routes: some RoutesBuilder) {
    routes.get("lookup", ":id") { req async throws -> BookLookup in
        let id = try req.parameters.require("id", as: Int.self)
        if id == 99 { return .gone(reason: "withdrawn by the publisher") }
        guard let book = Library.books.first(where: { $0.id == id }) else { throw Abort(.notFound) }
        return .found(book)
    }

    routes.get("books.csv") { req async throws -> CSVDocument in
        CSVDocument(
            header: ["id", "title", "author"],
            rows: Library.books.map { [String($0.id), $0.title, $0.author] },
            filename: "books.csv"
        )
    }

    // A route that returns one of several unrelated types: type-erase with AnyAsyncResponse.
    routes.get("either", ":kind") { req async throws -> AnyAsyncResponse in
        switch req.parameters.get("kind") {
        case "text": return AnyAsyncResponse("plain text\n")
        case "status": return AnyAsyncResponse(HTTPStatus.accepted)
        default: return AnyAsyncResponse(Library.books)
        }
    }
}

$ curl -s http://127.0.0.1:8080/lookup/1
{"author":"Frank Herbert","id":1,"title":"Dune"}
$ curl -si http://127.0.0.1:8080/lookup/99 | sed -n '1p;$p'
HTTP/1.1 410 Gone
{"error":"withdrawn by the publisher"}
$ curl -si http://127.0.0.1:8080/books.csv
HTTP/1.1 200 OK
content-length: 84
content-type: text/csv; charset=utf-8
content-disposition: attachment; filename="books.csv"

id,title,author
1,Dune,Frank Herbert
2,Hyperion,Dan Simmons
3,Solaris,Stanislaw Lem

import Vapor

func cachingRoutes(_ routes: some RoutesBuilder) {
    let published = Date(timeIntervalSince1970: 1_700_000_000)

    routes.get("catalog") { req async throws -> Response in
        let etag = "\"catalog-v\(Library.books.count)\""

        // Conditional GET: If-None-Match matches, so no body is sent.
        if req.headers.first(name: .ifNoneMatch) == etag {
            let notModified = Response(status: .notModified)
            notModified.headers.replaceOrAdd(name: .eTag, value: etag)
            return notModified
        }

        let response = Response()
        try response.content.encode(Library.books, as: .json)
        response.headers.replaceOrAdd(name: .eTag, value: etag)
        response.headers.lastModified = .init(published)
        response.headers.cacheControl = .init(isPublic: true, maxAge: 300)
        return response
    }

    routes.get("books", "page", ":n") { req async throws -> Response in
        let page = try req.parameters.require("n", as: Int.self)
        let response = Response()
        try response.content.encode(Library.books, as: .json)
        response.headers.links = [
            .init(uri: "/books/page/\(page + 1)", relation: .next, attributes: [:]),
            .init(uri: "/books/page/1", relation: .first, attributes: [:]),
        ]
        return response
    }
}

$ curl -si http://127.0.0.1:8080/catalog
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
content-length: 153
etag: "catalog-v3"
last-modified: Tue, 14 Nov 2023 22:13:20 GMT
cache-control: public, max-age=300

$ curl -si http://127.0.0.1:8080/catalog -H 'If-None-Match: "catalog-v3"'
HTTP/1.1 304 Not Modified
etag: "catalog-v3"

$ curl -si http://127.0.0.1:8080/books/page/2 | grep -i '^link'
link: </books/page/3>; rel="next", </books/page/1>; rel="first"

import Vapor

func configure(_ app: Application) async throws {
    // Body limit for routes that use the default .collect strategy (the default is 16kb).
    app.routes.defaultMaxBodySize = "1mb"

    // Compression of responses (only if the client sends Accept-Encoding) and of request bodies.
    app.http.server.configuration.responseCompression = .enabledForCompressibleTypes
    app.http.server.configuration.requestDecompression = .enabled(limit: .ratio(10))
    app.http.server.configuration.serverName = "bookshelf"

    try routes(app)
}

$ curl -si -X POST http://127.0.0.1:8080/echo --data-binary @b100.txt -H 'Accept-Encoding: gzip' -o /dev/null -D - | grep -i -e content-encoding -e content-length
Content-Encoding: gzip
content-length: 132

import VaporTesting
import Testing
@testable import App

@Suite("Request and response")
struct RequestAndResponseTests {
    private func withApp(_ test: (Application) async throws -> Void) async throws {
        let app = try await Application.make(.testing)
        do {
            try await configure(app)
            try await test(app)
        } catch {
            try await app.asyncShutdown()
            throw error
        }
        try await app.asyncShutdown()
    }

    @Test("inspect reports method, path, query, id and body size")
    func inspect() async throws {
        try await withApp { app in
            try await app.testing().test(
                .POST, "inspect?x=1",
                headers: ["X-Request-Id": "test-1", "Content-Type": "text/plain"],
                body: ByteBuffer(string: "hello")
            ) { res async throws in
                #expect(res.status == .ok)
                let summary = try res.content.decode(RequestSummary.self)
                #expect(summary.id == "test-1")
                #expect(summary.method == "POST")
                #expect(summary.query == "x=1")
                #expect(summary.bodyBytes == 5)
                #expect(summary.route == "POST /inspect")
            }
        }
    }

    @Test("POST /books answers 201 with a Location header")
    func created() async throws {
        try await withApp { app in
            try await app.testing().test(.POST, "books", beforeRequest: { req in
                try req.content.encode(NewBook(title: "Emma", author: "Jane Austen"))
            }, afterResponse: { res async throws in
                #expect(res.status == .created)
                #expect(res.headers.first(name: .location) == "/books/4")
                #expect(try res.content.decode(BookDTO.self).title == "Emma")
            })
        }
    }

    @Test("a body over the limit is rejected with 413")
    func tooLarge() async throws {
        try await withApp { app in
            app.routes.defaultMaxBodySize = "1kb"
            try await app.testing(method: .running(port: 0)).test(
                .POST, "echo",
                body: ByteBuffer(repeating: UInt8(ascii: "x"), count: 4096)
            ) { res async in
                #expect(res.status == .payloadTooLarge)
            }
        }
    }

    @Test("cookies are read from the request and written to the response")
    func cookies() async throws {
        try await withApp { app in
            try await app.testing().test(.GET, "visits", headers: ["Cookie": "visits=4"]) { res async in
                #expect(res.body.string == "visit number 5\n")
                #expect(res.headers.setCookie?["visits"]?.string == "5")
                #expect(res.headers.setCookie?["visits"]?.isHTTPOnly == true)
            }
        }
    }

    @Test("a matching If-None-Match gives 304 without a body")
    func conditionalGet() async throws {
        try await withApp { app in
            try await app.testing().test(.GET, "catalog", headers: ["If-None-Match": "\"catalog-v3\""]) { res async in
                #expect(res.status == .notModified)
                #expect(res.body.readableBytes == 0)
            }
        }
    }

    @Test("the streamed body arrives as newline-delimited JSON")
    func streaming() async throws {
        try await withApp { app in
            try await app.testing(method: .running(port: 0)).test(.GET, "books/stream") { res async in
                #expect(res.headers.first(name: .transferEncoding) == "chunked")
                #expect(res.body.string.split(separator: "\n").count == 3)
            }
        }
    }
}