docuconf for Gleam

gleam deps download

# Until the first release, from the main branch:
docuconf_gleam = { git = "https://github.com/Docuconf/docuconf-gleam", ref = "main" }

pub fn spec() -> docuconf.Spec(Config) {
  use port <- docuconf.env(
    docuconf.int("PORT", "HTTP listen port")
    |> docuconf.min_int(1)
    |> docuconf.max_int(65_535)
    |> docuconf.default(8080),
  )
  use log_level <- docuconf.env(
    docuconf.enum("LOG_LEVEL", "Minimum log level emitted", log_levels)
    |> docuconf.default(wisp.InfoLevel),
  )
  // A secret is exported as `secret: true`: the platform supplies it from a
  // Secret. docuconf never prints its value, and the app gets a
  // `docuconf.Secret`, which prints redacted; `docuconf.reveal` reads it.
  use database_url <- docuconf.env(
    docuconf.url("DATABASE_URL", "Primary Postgres connection string")
    |> docuconf.schemes(["postgres"])
    // At most 2048 characters; a longer URL fails the boot with out_of_range.
    |> docuconf.max_length(2048)
    |> docuconf.secret
    |> docuconf.required,
  )
  use allowed_origins <- docuconf.env(
    docuconf.string_list(
      "ALLOWED_ORIGINS",
      "Origins allowed to call the API (CORS), comma-separated",
      separator: ",",
    )
    |> docuconf.min_items(1)
    |> docuconf.default(["http://localhost:3000"]),
  )
  use request_timeout <- docuconf.env(
    docuconf.duration("REQUEST_TIMEOUT", "Timeout for one API request")
    // Longer docs for `docuconf docs`, in Markdown. Never read at runtime.
    |> docuconf.details(
      "Raise it when clients upload large order batches. Keep it below the
load balancer's idle timeout, or the client sees a reset rather than a
`504`.",
    )
    |> docuconf.min_duration(duration.seconds(1))
    |> docuconf.max_duration(duration.minutes(5))
    |> docuconf.default(duration.seconds(30)),
  )
  use worker_count <- docuconf.env(
    docuconf.int("WORKER_COUNT", "Background workers that process orders")
    |> docuconf.min_int(1)
    |> docuconf.max_int(64)
    |> docuconf.default(4),
  )
  // Each `use` above bound a handle; `build` reads the values once they
  // have all loaded and passed their checks.
  use v <- docuconf.build
  Config(
    port: port(v),
    log_level: log_level(v),
    database_url: database_url(v),
    allowed_origins: allowed_origins(v),
    request_timeout: request_timeout(v),
    worker_count: worker_count(v),
  )
}

let config = docuconf.load_or_exit(config.spec())

DATABASE_URL=postgres://orders:pw@localhost:5432/orders gleam run

$ PORT=0 gleam run
...
docuconf: 2 configuration problems:
  - DATABASE_URL [missing_required]: required, but not set
  - PORT [out_of_range]: "0" is below min 1

import docuconf
import gleam/dict
import gleeunit
import orders/config

pub fn main() -> Nil {
  gleeunit.main()
}

fn load(env: List(#(String, String))) {
  let options =
    docuconf.options()
    |> docuconf.with_env(dict.from_list(env))
  docuconf.load_with(config.spec(), options)
}

pub fn declaration_test() {
  assert docuconf.check_declaration(config.spec()) == []
}

pub fn defaults_test() {
  let assert Ok(config) = load([#("DATABASE_URL", "postgres://u:p@db/orders")])
  assert config.port == 8080
  assert docuconf.reveal(config.database_url) == "postgres://u:p@db/orders"
}

pub fn bad_port_test() {
  let assert Error(docuconf.InvalidConfig([violation])) =
    load([#("DATABASE_URL", "postgres://db/orders"), #("PORT", "0")])
  assert violation.input == "PORT"
  assert violation.code == docuconf.OutOfRange
}

pub fn contract_is_up_to_date_test() {
  assert docuconf.check_contract(
      config.spec(),
      name: "orders",
      against: "contract.cue",
    )
    == Ok(Nil)
}

gleam test

gleam run -m orders/contract

import docuconf
import gleam/io
import orders/config

pub fn main() -> Nil {
  case
    docuconf.write_contract(config.spec(), name: "orders", to: "contract.cue")
  {
    Ok(Nil) -> io.println("wrote contract.cue")
    Error(error) -> panic as docuconf.describe(error)
  }
}

// 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: "gleam"
			sdk: "docuconf"
			version: "0.1.0"
		}
	}
	vars: {
		ALLOWED_ORIGINS: {
			type: "list"
			description: "Origins allowed to call the API (CORS), comma-separated"
			items: "string"
			encoding: "csv"
			separator: ","
			minItems: 1
			default: ["http://localhost:3000"]
		}
		DATABASE_URL: {
			type: "url"
			description: "Primary Postgres connection string"
			required: true
			secret: true
			schemes: ["postgres"]
			maxLength: 2048
		}
		LOG_LEVEL: {
			type: "enum"
			description: "Minimum log level emitted"
			values: ["debug", "info", "warn", "error"]
			default: "info"
		}
		PORT: {
			type: "int"
			description: "HTTP listen port"
			min: 1
			max: 65535
			default: 8080
		}
		REQUEST_TIMEOUT: {
			type: "duration"
			description: "Timeout for one API request"
			details: "Raise it when clients upload large order batches. Keep it below the\nload balancer's idle timeout, or the client sees a reset rather than a\n`504`."
			encoding: "go"
			min: "1s"
			max: "5m"
			default: "30s"
		}
		WORKER_COUNT: {
			type: "int"
			description: "Background workers that process orders"
			min: 1
			max: 64
			default: 4
		}
	}
}