#Configuration

[!NOTE] The configuration core is in progress. This page shows the API that exists today. Merge policies, secrets, and validation come in later changes. The design overview shows the full plan.

#One load, start to finish

graph TD
  B[Builder and file tree] --> L[Load]
  L --> N[Need: file requests]
  N --> H[Host adds the answers to the tree]
  H --> A[Load again]
  A --> C[Done: Config]

#The smallest program

///|
test "the smallest program" {
  let config = @config.build([
    @config.in_memory_pairs([("app.name", @config.string("demo"))]),
    @config.in_memory_pairs([("app.name", @config.string("acme"))]),
  ])
  @expect.expect(@config.get_text(config, "app.name")).to_equal("acme")
}

#Sources and the builder

///|
test "describe sources with a builder" {
  let base = @config.builder()
    |> @config.format(@toml.format())
    |> @config.defaults({ "server": { "port": 8080, "host": "localhost" } })
  let builder = base
    |> @config.file("/srv/app.toml")
    |> @config.add(
      @config.in_memory_pairs([("server.port", @config.int(9000))]),
    )
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.toml"),
    (
      #|[server]
      #|host = "example.org"
    ),
  )
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  @expect.expect(@config.get_text(config, "server.host")).to_equal(
    "example.org",
  )
  @expect.expect(@config.get_text(config, "server.port")).to_equal("9000")
}

#The layer stack

Overrides (700) | command-line values
Environment variables (600) | APP_SERVER__PORT=9000
User override file (400) | app.user.toml
Local override file (390) | app.local.toml
Environment file (375) | app.Staging.toml
Workspace member file (350) | pkgs/api/app.toml
Workspace, explicit, or legacy file (300) | app.toml
Global user file (200) | ~/.config/app/
System file (100) | /etc/app/
Defaults (0) | compiled in

///|
test "a decreasing priority is an error" {
  let builder = @config.builder()
    |> @config.add(@config.ConfigSource::skipped(Environment))
    |> @config.file("/srv/app.toml", priority=300)
  try @config.load(builder, @config.FileTree::new(complete=true)) catch {
    SourceOrder(previous~, previous_priority~, ..) =>
      @expect.expect((previous, previous_priority)).to_equal((
        "environment", 600,
      ))
    _ => fail("expected a source-order error")
  } noraise {
    _ => fail("expected a source-order error")
  }
}

#Files and the request loop

///|
/// Answer one request from `disk`, a map from file path text to file text. A
/// directory exists when a file path in `disk` is below it.
fn answer(
  tree : @config.FileTree,
  request : @config.FileRequest,
  disk : Map[String, String],
) -> @config.FileTree raise @config.ConfigError {
  match request {
    ReadFile(path) =>
      match disk.get(path.to_string()) {
        Some(text) => tree.with_file(path, text)
        None => tree.with_missing(path)
      }
    ListDir(dir) => {
      let entries : Array[@config.DirEntry] = []
      for text, _ in disk {
        let path = @config.FileTreePath::parse(text)
        guard path != dir && path.is_within(dir) else { continue }
        let below = path.names()[dir.names().length():]
        let entry : @config.DirEntry = if below.length() > 1 {
          { name: below[0], kind: Directory }
        } else {
          { name: below[0], kind: File }
        }
        if !entries.contains(entry) {
          entries.push(entry)
        }
      }
      if entries.is_empty() {
        tree.with_missing(dir)
      } else {
        tree.with_listing(dir, entries)
      }
    }
  }
}

///|
/// Load until the configuration is done, answering each request from `disk`.
fn load_from(
  builder : @config.ConfigBuilder,
  disk : Map[String, String],
) -> @config.Config raise @config.ConfigError {
  let mut tree = @config.FileTree::new()
  while true {
    match @config.load(builder, tree) {
      Done(config) => return config
      Need(requests) =>
        for request in requests {
          tree = answer(tree, request, disk)
        }
    }
  }
  abort("the loop ends only with a configuration")
}

///|
test "a host answers the requests of a load" {
  let builder = @config.builder()
    |> @config.working_dir("/srv")
    |> @config.format(@toml.format())
    |> @config.file("conf/app.toml")
  let config = load_from(builder, { "/srv/conf/app.toml": "name = \"acme\"" })
  @expect.expect(@config.get_text(config, "name")).to_equal("acme")
  @expect.expect(config.reports()[0].path).to_equal(Some("/srv/conf/app.toml"))
}

#File-tree paths

///|
test "file-tree paths keep their root" {
  let file = @config.FileTreePath::parse("C:/w/app.toml")
  @expect.expect(file.parent().map(dir => dir.to_string())).to_equal(Some("C:/w"))
  let root = @config.FileTreePath::parse("D:/")
  @expect.expect(root.parent()).to_equal(None)
  @expect.expect(root.join("acme.toml").to_string()).to_equal("D:/acme.toml")
  let native = @config.FileTreePath::from_native("C:\\w\\app.toml", Windows)
  @expect.expect(native).to_equal(file)
  @expect.expect(file.to_native(Windows)).to_equal("C:\\w\\app.toml")
  try @config.FileTreePath::parse("C:app.toml") catch {
    InvalidFilePath(rule~, ..) => @expect.expect(rule).to_equal(DriveRelative)
    _ => fail("expected an invalid-path error")
  } noraise {
    _ => fail("C:app.toml is relative to the current directory of drive C")
  }
}

#Candidate files

///|
test "one existing candidate loads" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.add(
      @config.ConfigSource::candidates(
        ["/srv/app.toml", "/srv/.config/app.toml"],
        display="App",
      ),
    )
  let config = load_from(builder, { "/srv/.config/app.toml": "mode = \"dev\"" })
  let report = config.reports()[0]
  @expect.expect((report.status, report.path)).to_equal((
    Loaded,
    Some("/srv/.config/app.toml"),
  ))
}

///|
test "two existing candidates are ambiguous" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.add(
      @config.ConfigSource::candidates(
        ["/srv/app.toml", "/srv/.config/app.toml"],
        display="App",
      ),
    )
  let disk = { "/srv/app.toml": "", "/srv/.config/app.toml": "" }
  try load_from(builder, disk) catch {
    Ambiguous(location~, candidates~, ..) as error => {
      @expect.expect(location).to_equal("/srv")
      @expect.expect(candidates.length()).to_equal(2)
      @expect.expect(error.message()).to_start_with(
        "Ambiguous App configuration; found:",
      )
    }
    _ => fail("expected an ambiguity error")
  } noraise {
    _ => fail("expected an ambiguity error")
  }
}

#Formats

///|
test "the extension selects the format" {
  let formats = @config.builder()
    |> @config.format(@toml.format())
    |> @config.ConfigBuilder::formats
  @expect.expect(@config.parse_file(formats, "/srv/APP.TOML", "a = 1")).to_equal(
    @config.fields([("a", @config.int(1))]),
  )
  try @config.parse_file(formats, "/srv/app.ion", "{}") catch {
    UnsupportedFormat(extensions~, ..) =>
      @expect.expect(extensions).to_equal(["toml"])
    _ => fail("expected an unsupported-format error")
  } noraise {
    _ => fail("expected an unsupported-format error")
  }
}

#Merge rules

#Where each value came from

///|
test "the origin of each value" {
  let config = @config.build([
    @config.ConfigSource::defaults({ "ir": { "layout": "tree", "mode": "safe" } }),
    @config.in_memory_pairs(
      [("ir.mode", @config.string("fast"))],
      name="command line",
    ),
  ])
  let origins = config.provenance().map(record => {
    (record.0.to_string(), record.1.map(origin => origin.source))
  })
  @expect.expect(origins).to_equal([
    ("ir.layout", ["defaults"]),
    ("ir.mode", ["command line"]),
  ])
  @expect.expect(config.reports()[0].kind.report_name()).to_equal("defaults")
}

#Excluding a subtree

///|
test "an excluded key warns" {
  let source = @config.in_memory_pairs([
      ("workspace.out_dir", @config.string("out")),
      ("ir.layout", @config.string("tree")),
    ])
    .exclude([@config.KeyPath::parse("workspace.out_dir")], warn=true)
  let config = @config.build([source])
  @expect.expect(config.get(@config.KeyPath::parse("workspace.out_dir"))).to_equal(
    None,
  )
  @expect.expect(config.warnings().length()).to_equal(1)
}

#Source providers

///|
test "a provider adds the file of its directory" {
  let local_file : @config.SourceProvider = {
    name: "local",
    expand: context => {
      guard context.working_dir is Some(dir) else {
        return Done(@config.Expansion::new([]))
      }
      Done(@config.Expansion::new([
          @config.ConfigSource::candidates(
            ["\{dir}/app.local.toml"],
            display="local",
            role=LocalOverride,
          ),
        ]))
    },
  }
  let builder = @config.builder()
    |> @config.working_dir("/srv")
    |> @config.format(@toml.format())
    |> @config.provider(local_file)
  let config = load_from(builder, { "/srv/app.local.toml": "debug = true" })
  @expect.expect(@config.get_text(config, "debug")).to_equal("true")
  @expect.expect(config.reports()[0].priority).to_equal(390)
}

#Bind typed values

///|
struct ServerOptions {
  host : String
  port : Int
} derive(FromJson, Eq, Debug)

///|
test "bind a section to a record" {
  let config = @config.build([
    @config.ConfigSource::defaults({
      "server": { "host": "localhost", "port": 8080 },
    }),
  ])
  let server : ServerOptions = config |> @config.bind("server")
  @expect.expect(server).to_equal({ host: "localhost", port: 8080 })
  let metrics : ServerOptions? = config.bind("metrics")
  @expect.expect(metrics).to_equal(None)
}

///|
test "a decode error names the file that set the value" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.file("/srv/app.toml")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.toml"),
    "server.host = \"example.org\"\nserver.port = \"eighty\"",
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  try {
    let _ : ServerOptions = config |> @config.bind("server")
  } catch {
    error =>
      @expect.expect(error.message()).to_equal(
        "server.port: Int::from_json: expected number (set in project /srv/app.toml)",
      )
  } noraise {
    _ => fail("expected a decode error")
  }
}

#Bind over a default value

///|
struct ServerDefaults {
  host : String
  port : Int
  tags : Array[String]
} derive(FromJson, ToJson, Eq, Debug)

///|
test "configured keys win over the default" {
  let config = @config.build([
    @config.in_memory_pairs([
      ("server.port", @config.int(9000)),
      ("server.tags", @config.list([@config.string("eu")])),
    ]),
  ])
  let server = config
    |> @config.bind_or("server", ({
      host: "localhost",
      port: 8080,
      tags: ["default"],
    } : ServerDefaults))
  @expect.expect(server).to_equal({ host: "localhost", port: 9000, tags: ["eu"] })
  @expect.expect(config.bind_or("mode", "safe")).to_equal("safe")
}

#Secret references in a bound section

///|
struct ApiClient {
  url : String
} derive(FromJson)

///|
test "a secret reference stops binding" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.file("/srv/app.toml")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.toml"),
    "api.url = \"https://example.org\"\napi.token = { env = \"API_TOKEN\" }",
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  try {
    let client : ApiClient = config |> @config.bind("api")
    ignore(client.url)
  } catch {
    error =>
      @expect.expect(error.message()).to_equal(
        "api.token: is a secret reference; bind it as SecretRef with bind_with (set in project /srv/app.toml)",
      )
  } noraise {
    _ => fail("expected a decode error")
  }
  let url : String = config |> @config.bind("api.url")
  @expect.expect(url).to_equal("https://example.org")
}

#Validate bound values

///|
struct IrSettings {
  layout : String
  strict_mode : Bool
} derive(FromJson, ToJson)

///|
impl @config.Validate for IrSettings with validate(self) {
  if self.layout == "split" && !self.strict_mode {
    [
      @config.violation(
        ["layout", "strict_mode"],
        "split layout needs strict_mode = true",
      ),
    ]
  } else {
    []
  }
}

///|
test "validation names each value and its source" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.file("/srv/app.toml")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.toml"),
    "ir.layout = \"split\"",
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  let default : IrSettings = { layout: "tree", strict_mode: false }
  try {
    let ir = config
      |> @config.bind_or("ir", default)
      |> @config.validated(config, "ir")
    ignore(ir.value)
  } catch {
    error =>
      @expect.expect(error.message()).to_equal(
        (
          #|ir.layout: split layout needs strict_mode = true (set in project /srv/app.toml)
          #|ir.strict_mode: split layout needs strict_mode = true (not set by any source)
        ),
      )
  } noraise {
    _ => fail("expected a validation error")
  }
}

#Named options

///|
struct BackendSettings {
  out_dir : String
  level : Int
} derive(FromJson, ToJson)

///|
impl @config.Validate for BackendSettings with validate(self) {
  if self.level > 0 {
    []
  } else {
    [@config.violation(["level"], "must be positive")]
  }
}

///|
test "bind each backend as a named instance" {
  let config = @config.build([
    @config.in_memory_pairs([
      ("backends.ts.out_dir", @config.string("dist/ts")),
      ("backends.scala.level", @config.int(2)),
    ]),
  ])
  let backends : @config.NamedOptions[BackendSettings] = config
    |> @config.named("backends", (config, key) => {
      config
      |> @config.bind_or(key, ({ out_dir: "out", level: 1 } : BackendSettings))
      |> @config.validated(config, key)
    })
  @expect.expect(backends.names()).to_equal(["ts", "scala"])
  guard backends.get("ts") is Some(ts) else { fail("no ts instance") }
  @expect.expect(ts.name).to_equal(Some("ts"))
  @expect.expect(ts.key.to_string()).to_equal("backends.ts")
  @expect.expect(ts.value.out_dir).to_equal("dist/ts")
}

#Unknown keys

///|
test "a misspelled key is an error with its source" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.file("/srv/app.toml")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.toml"),
    "ir.layout = \"split\"\nir.strict_mod = true",
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  let default : IrSettings = { layout: "tree", strict_mode: false }
  let ir = config |> @config.bind_or("ir", default)
  @expect.expect(ir.strict_mode).to_equal(false)
  try {
    config |> @config.bind_or("ir", default, unknown=Reject) |> ignore
  } catch {
    error =>
      @expect.expect(error.message()).to_equal(
        "ir.strict_mod: is an unknown key (set in project /srv/app.toml)",
      )
  } noraise {
    _ => fail("expected a validation error")
  }
  let legacy = config
    |> @config.bind_or("ir", default, unknown=RejectExcept(["strict_mod"]))
  @expect.expect(legacy.layout).to_equal("split")
}

#Exact decoding with FromConfig

///|
struct Invoice {
  rate : @ion.Decimal
  max_items : Int64
  lock : @config.Sourced[String]
  server : ServerOptions
}

///|
impl @config.FromConfig for Invoice with from_config(node) {
  {
    rate: node.get("rate"),
    max_items: node.get("max_items"),
    lock: node.get("lock"),
    server: node.child("server").json(),
  }
}

///|
test "exact decoding keeps the decimal scale and the file" {
  let builder = @config.builder()
    |> @config.format(@ion_format.format())
    |> @config.file("/srv/app.ion")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.ion"),
    (
      #|{
      #|  billing: {
      #|    rate: 1.50,
      #|    max_items: 9007199254740993,
      #|    lock: "deps.lock",
      #|    server: { host: "localhost", port: 8080 },
      #|  },
      #|}
    ),
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  let billing : Invoice = config |> @config.bind_with("billing")
  @expect.expect(billing.rate.coefficient().to_string()).to_equal("150")
  @expect.expect(billing.rate.exponent()).to_equal(-2)
  @expect.expect(billing.max_items).to_equal(9007199254740993L)
  guard billing.lock.blame is Set([origin]) else { fail("one origin") }
  @expect.expect(origin.location).to_equal(Some("/srv/app.ion"))
  @expect.expect(billing.server).to_equal({ host: "localhost", port: 8080 })
}

#Time limits

///|
test "bind a timeout from configuration text" {
  let builder = @config.builder()
    |> @config.format(@toml.format())
    |> @config.file("/srv/app.toml")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/app.toml"), "[http]\ntimeout = \"1m 30s\"",
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  let timeout : @lander_core.TimeLimit = config
    |> @config.bind_with("http.timeout")
  @expect.expect(timeout.to_millis()).to_equal(90000)
}

#Environment variables and overrides

///|
test "an environment variable overrides a file" {
  let builder = @config.builder()
    |> @config.env_vars({ "ACME_SERVER__PORT": "9000", "HOME": "/home/u" })
    |> @config.format(@toml.format())
    |> @config.file("/srv/acme.toml")
    |> @config.env(prefix="ACME")
  let tree = @config.FileTree::new(complete=true).with_file(
    @config.FileTreePath::parse("/srv/acme.toml"),
    "server.port = 8080\nserver.host = \"example.org\"",
  )
  guard @config.load(builder, tree) is Done(config) else { fail("no config") }
  @expect.expect(@config.get_text(config, "server.port")).to_equal("9000")
  let origin = config.origins(@config.KeyPath::parse("server.port"))[0]
  @expect.expect(origin.location).to_equal(Some("ACME_SERVER__PORT"))
}