Static Files and File I/O

// Vapor 4.122.2, signature of the main initializer
public init(
    publicDirectory: String,
    defaultFile: String? = nil,
    directoryAction: DirectoryAction = .none,
    advancedETagComparison: Bool = false,
    cachePolicy: CachePolicy = .browserDefault
)

import Vapor

func configure(_ app: Application) async throws {
    // L1: serve Public/ with defaults
    app.middleware.use(ImmutableAssetsMiddleware(prefix: "/assets/"))
    app.middleware.use(FileMiddleware(
        publicDirectory: app.directory.publicDirectory,
        defaultFile: "index.html",
        directoryAction: .redirect,
        advancedETagComparison: false,
        cachePolicy: .cacheUpToDuration(.minutes(5))
    ))
    app.middleware.use(SPAFallbackMiddleware(publicDirectory: app.directory.publicDirectory))
    try routes(app)
}

$ curl -I localhost:8080/
HTTP/1.1 200 OK
last-modified: Sat, 17 Oct 2026 14:43:23 GMT
etag: "1792248203-19"
accept-ranges: bytes
content-type: text/html; charset=utf-8
content-length: 19
cache-control: max-age=300
age: 0

$ curl -I localhost:8080/docs
HTTP/1.1 301 Moved Permanently
location: /docs/

$ curl -I localhost:8080/docs/
HTTP/1.1 200 OK
content-type: text/html; charset=utf-8
cache-control: max-age=300

$ curl -s -i -H 'Range: bytes=0-3' localhost:8080/index.html
HTTP/1.1 206 Partial Content
etag: "1792248203-19"
accept-ranges: bytes
content-range: bytes 0-3/19
content-type: text/html; charset=utf-8
content-length: 4

<h1>

$ curl -s -i -H 'If-None-Match: "1792248203-19"' localhost:8080/index.html
HTTP/1.1 304 Not Modified
etag: "1792248203-19"
cache-control: max-age=300

$ curl -s -i -H 'Range: bytes=99-120' localhost:8080/index.html
HTTP/1.1 400 Bad Request

import Vapor

/// Marks fingerprinted build output (for example /assets/app.3f9a1c.js) as cacheable for a year.
/// Registered before FileMiddleware so it sees the response on the way out.
struct ImmutableAssetsMiddleware: AsyncMiddleware {
    let prefix: String

    func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
        let response = try await next.respond(to: request)
        if request.url.path.hasPrefix(prefix), response.status == .ok {
            response.headers.cacheControl = .init(isPublic: true, immutable: true, maxAge: 31_536_000)
        }
        return response
    }
}

/// Serves index.html for unknown browser navigations so client-side routing works.
/// Registered after FileMiddleware, so real files win.
struct SPAFallbackMiddleware: AsyncMiddleware {
    let publicDirectory: String

    func respond(to request: Request, chainingTo next: any AsyncResponder) async throws -> Response {
        do {
            return try await next.respond(to: request)
        } catch let error as any AbortError where error.status == .notFound {
            let path = request.url.path
            let wantsHTML = request.headers[.accept].contains { $0.contains("text/html") }
            let hasExtension = path.split(separator: "/").last?.contains(".") ?? false
            guard request.method == .GET, wantsHTML, !hasExtension, !path.hasPrefix("/api/") else { throw error }
            return try await request.fileio.asyncStreamFile(at: publicDirectory + "index.html")
        }
    }
}

$ curl -I localhost:8080/assets/app.3f9a1c.js
HTTP/1.1 200 OK
etag: "1792248203-15"
accept-ranges: bytes
content-type: application/javascript
content-length: 15
age: 0
cache-control: immutable, public, max-age=31536000

$ curl -s -i -H 'Accept: text/html' localhost:8080/books/42
HTTP/1.1 200 OK
etag: "1792248203-19"
content-type: text/html; charset=utf-8
content-length: 19

$ curl -s -i -H 'Accept: application/json' localhost:8080/books/42
HTTP/1.1 404 Not Found

$ curl -s -i -H 'Accept: text/html' localhost:8080/api/nope
HTTP/1.1 404 Not Found

$ curl -s -i -H 'Accept: text/html' localhost:8080/x.png
HTTP/1.1 404 Not Found

import Vapor
import NIOCore

func routes(_ app: Application) throws {
    app.get("api", "health") { _ in "ok" }
    try app.register(collection: FileController())
}

struct FileController: RouteCollection {
    func boot(routes: any RoutesBuilder) throws {
        let files = routes.grouped("files")
        files.get("size", ":name", use: size)
        files.get("lines", ":name", use: lineCount)
        files.get("notes", ":name", use: readWhole)
        files.put("notes", ":name", use: write)
        files.get("export", ":name", use: download)
        files.get("report", use: report)
    }

    private func notesPath(_ req: Request) throws -> String {
        guard let name = req.parameters.get("name") else { throw Abort(.badRequest) }
        return try SafePath.resolve(name: name, in: req.application.directory.resourcesDirectory + "notes/")
    }

    /// Same as notesPath, but answers 404 instead of letting FileIO throw a 500 for a missing file.
    private func existingNotesPath(_ req: Request) async throws -> String {
        let path = try notesPath(req)
        let exists = try await req.application.threadPool.runIfActive {
            var isDirectory: ObjCBool = false
            return FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory) && !isDirectory.boolValue
        }
        guard exists else { throw Abort(.notFound) }
        return path
    }

    /// readFile: chunked read; the handle is closed at EOF, and on error by the caller.
    @Sendable func lineCount(_ req: Request) async throws -> String {
        let chunks = try await req.fileio.readFile(at: try await existingNotesPath(req), chunkSize: 8 * 1024)
        var lines = 0
        do {
            for try await chunk in chunks {
                lines += chunk.readableBytesView.reduce(0) { $1 == UInt8(ascii: "\n") ? $0 + 1 : $0 }
            }
        } catch {
            try? await chunks.closeHandle()
            throw error
        }
        return "\(lines)"
    }

    /// collectFile: the whole file in memory. Only for small files.
    @Sendable func readWhole(_ req: Request) async throws -> String {
        let buffer = try await req.fileio.collectFile(at: try await existingNotesPath(req))
        return String(buffer: buffer)
    }

    @Sendable func size(_ req: Request) async throws -> String {
        let buffer = try await req.fileio.collectFile(at: try await existingNotesPath(req))
        return "\(buffer.readableBytes)"
    }

    /// writeFile: replaces the file; body limited by the route's collect limit.
    @Sendable func write(_ req: Request) async throws -> HTTPStatus {
        guard let body = req.body.data, body.readableBytes <= 64 * 1024 else { throw Abort(.payloadTooLarge) }
        try await req.fileio.writeFile(body, at: try notesPath(req))
        return .noContent
    }

    /// asyncStreamFile: ETag, Last-Modified, Range and Content-Type are handled for you.
    @Sendable func download(_ req: Request) async throws -> Response {
        let path = try await existingNotesPath(req)
        let response = try await req.fileio.asyncStreamFile(at: path, mediaType: .plainText)
        response.headers.contentDisposition = .init(.attachment, filename: "notes.txt")
        return response
    }

    /// Copy of a stream with a completion callback.
    @Sendable func report(_ req: Request) async throws -> Response {
        let path = req.application.directory.resourcesDirectory + "notes/a.txt"
        let logger = req.logger
        return try await req.fileio.asyncStreamFile(at: path, chunkSize: 4096) { result in
            switch result {
            case .success: logger.info("file sent")
            case .failure(let error): logger.warning("file send failed", metadata: ["error": "\(error)"])
            }
        }
    }
}

enum SafePath {
    /// Resolves a client-supplied file name below `base`, or throws 400/404.
    static func resolve(name: String, in base: String) throws -> String {
        guard !name.isEmpty, !name.contains("/"), !name.contains("\\"), !name.contains("\0"),
              name != ".", name != ".." else {
            throw Abort(.badRequest, reason: "Invalid file name.")
        }
        let baseURL = URL(fileURLWithPath: base, isDirectory: true).resolvingSymlinksInPath()
        let candidate = baseURL.appendingPathComponent(name).resolvingSymlinksInPath()
        guard candidate.path.hasPrefix(baseURL.path + "/") else {
            throw Abort(.notFound)
        }
        return candidate.path
    }
}

$ curl localhost:8080/files/lines/a.txt
3
$ curl -i -X PUT -d 'hello notes' localhost:8080/files/notes/b.txt
HTTP/1.1 204 No Content
$ curl -i localhost:8080/files/export/b.txt
HTTP/1.1 200 OK
last-modified: Sat, 17 Oct 2026 14:44:00 GMT
etag: "1792248240-11"
accept-ranges: bytes
content-type: text/plain; charset=utf-8
content-length: 11
content-disposition: attachment; filename="notes.txt"

hello notes
$ curl -i localhost:8080/files/notes/nope.txt
HTTP/1.1 404 Not Found