Configuration and Environment

import Vapor

/// A secret that never prints its value.
struct Secret: Sendable, CustomStringConvertible, CustomDebugStringConvertible {
    let reveal: String
    var description: String { "<redacted>" }
    var debugDescription: String { "<redacted>" }
}

/// Everything the Bookshelf service reads from its environment, validated once at start-up.
struct AppConfig: Sendable, CustomStringConvertible {
    let publicBaseURL: String
    let maxPageSize: Int
    let enableDocs: Bool
    let databaseURL: Secret
    let jwtSecret: Secret

    /// One error that lists every problem, so a deployment is fixed in one round trip.
    struct Invalid: Error, CustomStringConvertible {
        let problems: [String]
        var description: String { "Invalid configuration: " + problems.joined(separator: "; ") }
    }

    static func load(for environment: Environment) async throws -> AppConfig {
        var problems: [String] = []

        // Plain values with defaults that are safe in every environment.
        let maxPageSize: Int = Environment.process.BOOKSHELF_MAX_PAGE_SIZE ?? 50
        let enableDocs: Bool = Environment.process.BOOKSHELF_ENABLE_DOCS ?? (environment != .production)

        // Values with a development default but required everywhere else.
        let publicBaseURL: String
        if let value = Environment.get("BOOKSHELF_PUBLIC_URL") {
            publicBaseURL = value
        } else if environment == .production || environment == .staging {
            problems.append("BOOKSHELF_PUBLIC_URL is required in \(environment.name)")
            publicBaseURL = ""
        } else {
            publicBaseURL = "http://localhost:8080"
        }

        // Secrets: a value in the variable itself, or a file named by <KEY>_FILE.
        let databaseURL = try await secret("DATABASE_URL", problems: &problems)
        let jwtSecret = try await secret("JWT_SECRET", problems: &problems)

        guard problems.isEmpty else { throw Invalid(problems: problems) }
        return AppConfig(
            publicBaseURL: publicBaseURL, maxPageSize: maxPageSize, enableDocs: enableDocs,
            databaseURL: databaseURL, jwtSecret: jwtSecret)
    }

    private static func secret(_ key: String, problems: inout [String]) async throws -> Secret {
        if let value = Environment.get(key), !value.isEmpty { return Secret(reveal: value) }
        if let value = try await Environment.secret(key: "\(key)_FILE"), !value.isEmpty {
            return Secret(reveal: value)
        }
        problems.append("\(key) or \(key)_FILE is required")
        return Secret(reveal: "")
    }

    var description: String {
        "AppConfig(publicBaseURL: \(publicBaseURL), maxPageSize: \(maxPageSize), "
            + "enableDocs: \(enableDocs), databaseURL: \(databaseURL), jwtSecret: \(jwtSecret))"
    }
}

// MARK: - Storage on the application, accessor on the request

extension Application {
    private struct AppConfigKey: StorageKey {
        typealias Value = AppConfig
    }

    var config: AppConfig {
        get {
            guard let config = self.storage[AppConfigKey.self] else {
                fatalError("AppConfig is not set. Call app.config = ... in configure(_:) first.")
            }
            return config
        }
        set { self.storage[AppConfigKey.self] = newValue }
    }
}

extension Request {
    var config: AppConfig { self.application.config }
}

import Vapor

func configure(_ app: Application) async throws {
    // 1. Read and validate every setting before anything else starts.
    app.config = try await AppConfig.load(for: app.environment)
    app.logger.info("Configuration loaded", metadata: ["config": "\(app.config)"])

    // 2. Environment-specific wiring.
    switch app.environment {
    case .production, .staging:
        app.logger.notice("Running with production-like settings", metadata: ["env": "\(app.environment.name)"])
    case .testing:
        break
    default:
        app.logger.debug("Development defaults")
    }

    try routes(app)
}

import Vapor

struct ConfigSummary: Content {
    let environment: String
    let isRelease: Bool
    let publicBaseURL: String
    let maxPageSize: Int
    let enableDocs: Bool
}

func routes(_ app: Application) throws {
    app.get { req async in "It works!" }
    app.get("hello") { req async -> String in "Hello, world!" }
    app.get("config") { req async -> ConfigSummary in
        let config = req.config
        return ConfigSummary(
            environment: req.application.environment.name, isRelease: req.application.environment.isRelease,
            publicBaseURL: config.publicBaseURL, maxPageSize: config.maxPageSize, enableDocs: config.enableDocs)
    }
}

$ swift build
$ .build/debug/App routes
[ WARNING ] Invalid configuration: DATABASE_URL or DATABASE_URL_FILE is required; JWT_SECRET or JWT_SECRET_FILE is required

$ DATABASE_URL=postgres://user:PLACEHOLDER@localhost/bookshelf JWT_SECRET=change-me .build/debug/App serve --log debug
[ DEBUG ] Could not load .env.development file: Not found: Unable to open or create file at path '.env.development' ...
[ DEBUG ] Could not load .env file: Not found: Unable to open or create file at path '.env' ...
[ INFO ] Configuration loaded [config: AppConfig(publicBaseURL: http://localhost:8080, maxPageSize: 50, enableDocs: true, databaseURL: <redacted>, jwtSecret: <redacted>)]

$ .build/debug/App routes --env production
[ WARNING ] Invalid configuration: BOOKSHELF_PUBLIC_URL is required in production; DATABASE_URL or DATABASE_URL_FILE is required; JWT_SECRET or JWT_SECRET_FILE is required

import VaporTesting
import Testing
import Foundation
@testable import App

@Suite(.serialized) struct ConfigTests {
    /// Sets process variables for the duration of `body` and restores them afterwards.
    func withProcessVariables(_ values: [String: String], _ body: () async throws -> Void) async throws {
        let previous = values.keys.map { ($0, Environment.get($0)) }
        for (key, value) in values { Environment.process[dynamicMember: key] = value }
        defer { for (key, old) in previous { Environment.process[dynamicMember: key] = old } }
        try await body()
    }

    @Test func configRouteReportsValidatedSettings() async throws {
        try await withProcessVariables([
            "DATABASE_URL": "postgres://user:PLACEHOLDER@localhost/bookshelf",
            "JWT_SECRET": "test-placeholder-secret",
            "BOOKSHELF_MAX_PAGE_SIZE": "7",
        ]) {
            try await withApp(configure: configure) { app in
                try await app.testing().test(.GET, "config") { res async in
                    #expect(res.status == .ok)
                    #expect(res.body.string.contains("\"maxPageSize\":7"))
                    #expect(res.body.string.contains("\"environment\":\"testing\""))
                }
            }
        }
    }

    @Test func missingSecretsAreReportedTogether() async throws {
        try await withProcessVariables(["DATABASE_URL": "", "JWT_SECRET": ""]) {
            do {
                try await withApp(configure: configure) { _ in }
                Issue.record("configure should have thrown")
            } catch let error as AppConfig.Invalid {
                #expect(error.problems.count == 2)
            }
        }
    }

    @Test func customEnvironmentWithoutCommandLine() async throws {
        let env = Environment(name: "staging", arguments: ["vapor"])
        #expect(env == .staging)
        #expect(env.arguments == ["vapor"])
    }

    @Test func detectReadsEnvFlag() throws {
        #expect(try Environment.detect(arguments: ["App", "serve", "--env", "prod"]) == .production)
        #expect(try Environment.detect(arguments: ["App", "-e", "staging"]) == .staging)
    }
}

ENTRYPOINT ["./App"]
CMD ["serve", "--env", "production", "--hostname", "0.0.0.0", "--port", "8080"]

services:
  app:
    image: bookshelf:latest
    command: ["serve", "--env", "staging", "--hostname", "0.0.0.0", "--port", "8080"]
    environment:
      LOG_LEVEL: info
      BOOKSHELF_PUBLIC_URL: https://staging.example.com
      DATABASE_URL_FILE: /run/secrets/database_url
      JWT_SECRET_FILE: /run/secrets/jwt_secret
    secrets:
      - database_url
      - jwt_secret

secrets:
  database_url:
    file: ./secrets/database_url.txt     # placeholder, keep out of version control
  jwt_secret:
    file: ./secrets/jwt_secret.txt

apiVersion: apps/v1
kind: Deployment
metadata:
  name: bookshelf
spec:
  replicas: 2
  selector:
    matchLabels:
      app: bookshelf
  template:
    metadata:
      labels:
        app: bookshelf
    spec:
      containers:
        - name: bookshelf
          image: registry.example.com/bookshelf:1.0.0
          args: ["serve", "--env", "production", "--hostname", "0.0.0.0", "--port", "8080"]
          env:
            - name: BOOKSHELF_PUBLIC_URL
              value: https://books.example.com
            - name: DATABASE_URL_FILE
              value: /etc/secrets/bookshelf/database-url
            - name: JWT_SECRET_FILE
              value: /etc/secrets/bookshelf/jwt-secret
          volumeMounts:
            - name: secrets
              mountPath: /etc/secrets/bookshelf
              readOnly: true
      volumes:
        - name: secrets
          secret:
            secretName: bookshelf-secrets      # created outside Git, values are placeholders here