docuconf for Go

go get github.com/docuconf/docuconf-go@main
go install github.com/docuconf/docuconf-go/cmd/docuconf@main

// Package config is the orders service's configuration: an ordinary
// caarlos0/env struct with docuconf's tags. It lives in its own package
// because `docuconf export` imports it, and package main cannot be imported.
package config

import (
	"time"

	"github.com/docuconf/docuconf-go"
)

// Config is everything the orders service reads at boot.
// Doc comments become the descriptions in the contract: the first
// paragraph is the description, and any later paragraphs are its details.
type Config struct {
	// HTTP listen port.
	Port int `env:"PORT" envDefault:"8080" min:"1" max:"65535"`

	// Minimum log level emitted.
	LogLevel string `env:"LOG_LEVEL" envDefault:"info" values:"debug,info,warn,error"`

	// Postgres connection string for the orders database.
	DatabaseURL docuconf.Secret `env:"DATABASE_URL,required" schemes:"postgres" maxLength:"2048"`

	// Origins allowed to call the API from a browser.
	AllowedOrigins []string `env:"ALLOWED_ORIGINS" envDefault:"http://localhost:3000" minItems:"1"`

	// Time limit for handling one request.
	RequestTimeout time.Duration `env:"REQUEST_TIMEOUT" envDefault:"30s" min:"1s" max:"5m"`

	// Number of background workers processing orders.
	//
	// Each worker holds one database connection, so keep it below the
	// database's connection limit divided by the number of replicas.
	// Raise it when the order queue grows faster than it drains.
	WorkerCount int `env:"WORKER_COUNT" envDefault:"4" min:"1" max:"64"`

	// Certificate to serve HTTPS with. Without it, the service serves HTTP.
	TLS docuconf.TLSKeyPair `file:"serving-tls" path:"/etc/orders/tls" dnsNames:"orders.example.com" minRemaining:"720h" reload:"watch"`

	// Discount codes accepted at checkout.
	Discounts docuconf.ConfigFile[Discounts] `file:"discounts" path:"/etc/orders/discounts/discounts.yaml"`
}

// Discounts is the content of the discounts file.
type Discounts struct {
	// Percent off for each discount code.
	Codes map[string]int `json:"codes" yaml:"codes"`
}

cfg := docuconf.ParseOrExit[config.Config]()

DATABASE_URL=postgres://orders:pw@localhost:5432/orders go run .

$ PORT=0 go run .
docuconf: 2 configuration problems:
  PORT: 0 is below min 1 (out_of_range)
  DATABASE_URL: is required but not set (missing_required)
exit status 1

package config_test

import (
	"errors"
	"testing"

	"github.com/docuconf/docuconf-go"
	"github.com/docuconf/docuconf-go/examples/orders/internal/config"
)

// Load from an explicit environment: the process environment is not read or changed.
func load(env map[string]string) (config.Config, error) {
	return docuconf.ParseWithOptions[config.Config](docuconf.Options{
		Environment:    env,
		TerminationLog: "-", // don't write /dev/termination-log from tests
	})
}

func TestDefaults(t *testing.T) {
	cfg, err := load(map[string]string{"DATABASE_URL": "postgres://orders@db/orders"})
	if err != nil {
		t.Fatal(err)
	}
	if cfg.Port != 8080 || cfg.WorkerCount != 4 {
		t.Errorf("got port %d, %d workers", cfg.Port, cfg.WorkerCount)
	}
}

func TestRejectsBadValues(t *testing.T) {
	_, err := load(map[string]string{"PORT": "70000"})
	var verr *docuconf.ValidationError
	if !errors.As(err, &verr) {
		t.Fatalf("want a ValidationError, got %v", err)
	}
	if !verr.Has(docuconf.CodeOutOfRange) || !verr.Has(docuconf.CodeMissingRequired) {
		t.Errorf("got %v", verr.Violations)
	}
}

go test ./internal/config/

docuconf export -pkg ./internal/config -type Config -name orders-api -package orders -o 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-api"
		generator: {
			language: "go"
			sdk:      "docuconf-go"
			version:  "0.1.0"
		}
	}
	vars: {
		ALLOWED_ORIGINS: {
			type:        "list"
			description: "Origins allowed to call the API from a browser"
			default: ["http://localhost:3000"]
			items:     "string"
			encoding:  "csv"
			separator: ","
			minItems:  1
		}
		DATABASE_URL: {
			type:        "url"
			description: "Postgres connection string for the orders database"
			required:    true
			secret:      true
			schemes: ["postgres"]
			maxLength: 2048
		}
		LOG_LEVEL: {
			type:        "enum"
			description: "Minimum log level emitted"
			default:     "info"
			values: ["debug", "info", "warn", "error"]
		}
		PORT: {
			type:        "int"
			description: "HTTP listen port"
			default:     8080
			min:         1
			max:         65535
		}
		REQUEST_TIMEOUT: {
			type:        "duration"
			description: "Time limit for handling one request"
			default:     "30s"
			min:         "1s"
			max:         "5m"
			encoding:    "go"
		}
		WORKER_COUNT: {
			type:        "int"
			description: "Number of background workers processing orders"
			details:     "Each worker holds one database connection, so keep it below the database's connection limit divided by the number of replicas. Raise it when the order queue grows faster than it drains."
			default:     4
			min:         1
			max:         64
		}
	}
	files: {
		discounts: {
			type:        "config"
			format:      "yaml"
			description: "Discount codes accepted at checkout"
			path:        "/etc/orders/discounts/discounts.yaml"
			schema: {
				type: "object"
				required: ["codes"]
				additionalProperties: false
				properties: {
					codes: {
						type:        "object"
						description: "Percent off for each discount code"
						additionalProperties: {
							type: "integer"
						}
					}
				}
			}
		}
		"serving-tls": {
			type:        "tls"
			description: "Certificate to serve HTTPS with. Without it, the service serves HTTP"
			secret:      true
			path:        "/etc/orders/tls"
			reload:      "watch"
			dnsNames: ["orders.example.com"]
			minRemaining: "720h"
		}
	}
}

$ docuconf vet -contract contract.cue -values values.yaml
DATABASE_URL: is secret, so it must come from a secretKeyRef, written {secretKeyRef: {name: <secret>, key: <key>}}, or an injector, never a literal or another reference
DATABSE_URL: is not declared in the contract (check the spelling)
PORT: 70000 is above max 65535