API/config schema

Source: docs/examples/02_config.decl · part of the validation cases.

02_config.decl

// Benchmark case 2 — API/config schema (ROADMAP §0.5)
// Exercises: open records, defaults, optionality vs null, conditional
// constraints, per-environment override with `with`.

export type LogLevel = "debug" | "info" | "warn" | "error"

export type TlsConfig = {
    enabled?: bool = false
    min_version?: "1.2" | "1.3" = "1.3"
    cert_path?: string

    when enabled {
        assert cert_present: "cert_path" in $this
            else error `tls is enabled but cert_path is missing`
    }
}

export type ServerConfig = {
    host?: string = "0.0.0.0"
    port?: 1..65535 = 8080
    workers?: 1..256 = 4
    log_level?: LogLevel = "info"
    request_timeout?: quantity<Time> = 30s
    tls?: TlsConfig = {}
    rate_limits?: { [/[a-z][a-z0-9_]*/]: int } = {}

    // forward compatibility: unknown flags pass through opaquely
    ...

    insecure = !tls.enabled
    assert sane_workers: workers <= 64
        else warn `worker count ${workers} is unusually high`
}

// The shared baseline is itself a validated value.
export output base: ServerConfig = {
    host: "api.internal"
    rate_limits: { "search": 100, "write": 20 }
}

// Environment layering: `with` updates exactly what is written —
// defaults that `base` already resolved are left alone (see the
// merge defaults-trap note, spec 13.7).
export output prod: ServerConfig = base with {
    workers: 32
    log_level: "warn"
    tls: base.tls with { enabled: true, cert_path: "/etc/ssl/api.pem" }
}

export output dev: ServerConfig = base with {
    log_level: "debug"
    port: 8081
}

// External validation: an ops-managed JSON file, same rules.
export input deployed: ServerConfig

Evaluated output

What decl evaluate 02_config.decl prints, one section per output.

base

{
  "host": "api.internal",
  "rate_limits": {
    "search": 100,
    "write": 20
  },
  "port": 8080,
  "workers": 4,
  "log_level": "info",
  "request_timeout": {
    "value": 30,
    "unit": "s"
  },
  "tls": {
    "enabled": false,
    "min_version": "1.3"
  },
  "insecure": true
}

prod

{
  "host": "api.internal",
  "rate_limits": {
    "search": 100,
    "write": 20
  },
  "port": 8080,
  "workers": 32,
  "log_level": "warn",
  "request_timeout": {
    "value": 30,
    "unit": "s"
  },
  "tls": {
    "enabled": true,
    "min_version": "1.3",
    "cert_path": "/etc/ssl/api.pem"
  },
  "insecure": false
}

dev

{
  "host": "api.internal",
  "rate_limits": {
    "search": 100,
    "write": 20
  },
  "port": 8081,
  "workers": 4,
  "log_level": "debug",
  "request_timeout": {
    "value": 30,
    "unit": "s"
  },
  "tls": {
    "enabled": false,
    "min_version": "1.3"
  },
  "insecure": true
}