docuconf for Swift

swift build

dependencies: [
    // Until the first release, from the main branch:
    .package(url: "https://github.com/Docuconf/docuconf-swift", branch: "main"),
],

enum LogLevel: String, ConfigEnum {
    case debug, info, warn, error
}

struct OrdersConfig: DocuconfConfig {
    @Env("port", "HTTP listen port", .range(1...65535))
    var port = 8080

    @Env("log.level", "Minimum log level")
    var logLevel = LogLevel.info

    @Env("database.url", "Postgres connection string for the orders database", .secret, .schemes("postgres"), .maxLength(2048))
    var databaseURL: URL

    @Env("allowed.origins", "Origins allowed to call the API (CORS)", .minItems(1))
    var allowedOrigins = ["http://localhost:3000"]

    // Durations are read as a number of seconds (REQUEST_TIMEOUT=30); the contract holds "30s".
    @Env("request.timeout", "Timeout for one request", .range(.seconds(1) ... .seconds(300)))
    var requestTimeout: Duration = .seconds(30)

    // A description may be a whole doc comment: its first paragraph is the description, the rest the details.
    @Env("worker.count", """
        Number of background order workers

        Each worker takes one order at a time from the queue and holds one database connection, so keep this
        at or below the pool size:

        - one connection per worker;
        - plus one for the HTTP handlers.
        """, .range(1...64))
    var workerCount = 4
}

Docuconf.exportIfRequested(OrdersConfig.self, name: "orders")

// Reads the environment. On a problem it prints every violation at once (also to /dev/termination-log) and exits 1.
let config = await Docuconf.loadOrExit(OrdersConfig.self)

DATABASE_URL=postgres://orders:pw@localhost:5432/orders swift run Orders

$ PORT=0 swift run Orders
...
docuconf: 2 configuration problems:
  - PORT [out_of_range]: is below min 1 (got "0")
  - DATABASE_URL [missing_required]: is required but not set (Postgres connection string for the orders database)

import Docuconf
import Testing
@testable import Orders

// load(_:environment:) reads only this dictionary: never the process environment, and no termination log.
func load(_ environment: [String: String]) async throws -> OrdersConfig {
    try await Docuconf.load(OrdersConfig.self, environment: environment)
}

@Test func defaults() async throws {
    let config = try await load(["DATABASE_URL": "postgres://orders@db/orders"])
    #expect(config.port == 8080)
    #expect(config.workerCount == 4)
}

@Test func rejectsBadValues() async throws {
    let error = await #expect(throws: ConfigurationError.self) { try await load(["PORT": "70000"]) }
    let found = error?.violations.map { "\($0.input) \($0.code.rawValue)" } ?? []
    #expect(found.contains("PORT out_of_range"))
    #expect(found.contains("DATABASE_URL missing_required"))
}

swift test

swift run Orders docuconf-export --out contract.cue

// Code generated by docuconf. DO NOT EDIT.
package orders

import "docuconf.dev/contract"

contract.#Contract & {
	apiVersion: "docuconf.dev/v1alpha1"
	kind: "ConfigContract"
	metadata: {
		name: "orders"
		generator: {language: "swift", sdk: "docuconf-swift", version: "0.1.0"}
	}
	vars: {
		ALLOWED_ORIGINS: {
			type: "list"
			description: "Origins allowed to call the API (CORS)"
			configKey: "allowed.origins"
			items: "string"
			encoding: "csv"
			minItems: 1
			default: ["http://localhost:3000"]
		}
		DATABASE_URL: {
			type: "url"
			description: "Postgres connection string for the orders database"
			required: true
			secret: true
			configKey: "database.url"
			schemes: ["postgres"]
			maxLength: 2048
		}
		LOG_LEVEL: {
			type: "enum"
			description: "Minimum log level"
			configKey: "log.level"
			values: ["debug", "info", "warn", "error"]
			default: "info"
		}
		PORT: {
			type: "int"
			description: "HTTP listen port"
			configKey: "port"
			min: 1
			max: 65535
			default: 8080
		}
		REQUEST_TIMEOUT: {
			type: "duration"
			description: "Timeout for one request"
			configKey: "request.timeout"
			encoding: "seconds"
			min: "1s"
			max: "5m"
			default: "30s"
		}
		WORKER_COUNT: {
			type: "int"
			description: "Number of background order workers"
			details: "Each worker takes one order at a time from the queue and holds one database connection, so keep this\nat or below the pool size:\n\n- one connection per worker;\n- plus one for the HTTP handlers."
			configKey: "worker.count"
			min: 1
			max: 64
			default: 4
		}
	}
}