DEV Community: Andrei Merlescu

Rust Decorators for Go Developers

Andrei Merlescu — Fri, 22 May 2026 18:34:06 +0000

In Go, most of these concerns are handled by conventions, comments, runtime reflection, and external tools. In Rust, they are expressed as attributes that the compiler reads, verifies, and enforces before your program ever runs.

If you have spent years writing Go, you already think in terms of goroutines, interfaces, and the implicit contract that the runtime handles the hard parts for you. Rust asks you to make all of those implicit contracts explicit — and the mechanism it uses to do that is attributes. Where Go relies on naming conventions, comments, build tags, struct tag strings, and external linters to express intent, Rust has a formal attribute syntax that the compiler reads at compile time, verifies, and enforces before a single line of your code runs. This document walks through thirteen categories of Rust attributes side by side with their closest Go analogs — not to argue that one language is better than the other, but to give you a map from the Go mental model you already own into the Rust one you are building. You will see that many things Go does silently behind its runtime — scheduling threads, copying memory, skipping serialized fields, enforcing interface contracts — Rust requires you to express openly through attributes, and in exchange the compiler guarantees correctness that Go leaves to discipline, convention, and luck. By the end you will understand not just what each attribute does, but why it exists and what problem it is solving that Go solves a different way.

`#[derive(...)]` — Automatic Trait Implementation

The Concept

#[derive(...)] tells the Rust compiler to automatically generate implementations of standard traits for your type. A trait in Rust is roughly what an interface is in Go, except the compiler can write the implementation for you when the logic is mechanical. Without #[derive(...)], you would have to manually implement Debug, Clone, PartialEq, and others for every struct and enum you write. The derive macro inspects your type at compile time and generates the boilerplate so you don’t have to.

The most commonly derived traits are: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default, and Serialize/Deserialize from serde.

// Go has no equivalent syntax. The closest analog is implementing
// an interface by satisfying its method signatures manually.
// Go generates nothing for you — you write it all yourself.

type Person struct {
    Name string
    Age  int
}

// To print with structure, you implement Stringer manually:
func (p Person) String() string {
    return fmt.Sprintf("Person{Name: %s, Age: %d}", p.Name, p.Age)
}

// To copy, Go structs are value types — assignment copies automatically.
// To compare, == works on structs if all fields are comparable.
// None of this is declared — it's implicit or manual.

Rust

// Rust generates all of this for you via #[derive(...)].
// Each trait listed is fully implemented by the compiler.

#[derive(Debug, Clone, PartialEq, Eq, Hash, Default)]
struct Person {
    name: String,
    age: u32,
}

fn main() {
    let p1 = Person {
        name: "Andrei".to_string(),
        age: 40,
    };

    // Debug — enabled by #[derive(Debug)]
    // {:?} is the debug format, {:#?} is pretty-printed
    println!("{:?}", p1);
    println!("{:#?}", p1);

    // Clone — enabled by #[derive(Clone)]
    // .clone() performs a deep copy
    // Without this derive, .clone() does not compile
    let p2 = p1.clone();

    // PartialEq — enabled by #[derive(PartialEq)]
    // Without this, == does not compile on your struct
    assert_eq!(p1, p2);

    // Default — enabled by #[derive(Default)]
    // Returns a zero-value equivalent, like Go's zero value
    // String defaults to "", u32 defaults to 0
    let empty: Person = Person::default();
    println!("{:?}", empty);
}

// Copy vs Clone — critical distinction:
// Copy means the type can be duplicated by simply copying bits.
// Clone means the type knows how to duplicate itself, possibly with allocation.
// String cannot be Copy because it owns heap memory.
// u32, bool, f64 can be Copy because they are fixed-size stack values.

#[derive(Debug, Clone, Copy, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}
// Point is Copy, so assignment moves a copy, not ownership.
// You can use p after assigning it to another variable.

Key Concepts: If any field in your struct does not implement a trait you are trying to derive, the derive will fail to compile. For example, you cannot derive Copy on a struct that contains a String because String is not Copy. You cannot derive Eq without also deriving PartialEq. The order inside #[derive(...)] does not matter. You can stack multiple derives on the same line or split them across multiple #[derive(...)] attributes — both are valid. Deriving Default requires every field’s type to also implement Default.

`#[arg(...)]` — Clap CLI Argument Declaration

The Concept

#[arg(...)] is not a standard library attribute — it comes from the clap crate and decorates fields inside a #[derive(Parser)] struct. It describes how a struct field maps to a command-line argument: its flag name, short form, default value, environment variable fallback, help text, validation rules, and behavior. Clap reads these attributes at compile time and generates a full CLI parser from them.

// Go's closest analog is the flag package, but it is entirely manual.
// There is no struct-level declaration — you register each flag imperatively.
// There is no compile-time validation — wrong types fail at runtime.

import "flag"

var find = flag.String("find", "", "substring to search for")
var cores = flag.Int("cores", 0, "number of cores to use")
var insensitive = flag.Bool("insensitive", true, "case insensitive search")

func main() {
    flag.Parse()
    // Values are now available via *find, *cores, *insensitive
    // No env var fallback built in
    // No conflict detection
    // No required field enforcement
}

Rust

use clap::Parser;

#[derive(Parser, Debug)]
#[command(name = "find-xrp-addr", about = "XRP vanity address finder")]
struct Cli {

    // long:    creates --find flag
    // env:     falls back to $FIND if --find not passed
    // Type Option<String> means not required — None if absent
    #[arg(long, env = "FIND")]
    find: Option<String>,

    // long = "1p": overrides the field name for the CLI flag
    // action = SetTrue: presence of --1p sets this to true
    //                   without SetTrue, bool requires --1p=true explicitly
    // env: falls back to $USE_ONEPASSWORD
    #[arg(long = "1p", env = "USE_ONEPASSWORD", action = clap::ArgAction::SetTrue)]
    use_op: bool,

    // default_value_t: typed default, not a string — avoids parse step
    // 0 is sentinel meaning "use all available cores"
    #[arg(long, default_value_t = 0, env = "CORES")]
    cores: usize,

    // value_name: controls the placeholder in --help output
    // shows as: --begins <PREFIX>
    #[arg(long, value_name = "PREFIX", env = "BEGINS")]
    begins: Option<String>,

    // conflicts_with: errors if both --begins and --ends are
    // combined with --find in an unsupported way
    // requires: enforces another argument must also be present
    #[arg(long, env = "ENDS")]
    ends: Option<String>,

    // short and long together: accepts both -v and --vault
    #[arg(short, long, env = "VAULT")]
    vault: Option<String>,
}

fn main() {
    let cli = Cli::parse();
    println!("{:?}", cli);
}

Key Concepts: default_value takes a &str and parses it, so a wrong string panics at runtime. default_value_t takes a typed expression and fails at compile time if the type is wrong — always prefer default_value_t. action = clap::ArgAction::SetTrue is required on bool fields if you want flag presence alone to mean true. Without it, the user must write --flag=true explicitly. Option<String> means absent is None — do not use required = true on an Option unless you explicitly want to override that inference.

BONUS: I wrote rusty-figtree so that you can use my figtree pattern in Rust, _instead of using #[arg()].

`#[cfg(...)]` — Conditional Compilation

The Concept

#[cfg(...)] tells the compiler to include or exclude a block of code depending on compile-time conditions: the target operating system, architecture, feature flags, test mode, or custom cfg values. The excluded code is completely removed from the binary — it is never parsed beyond syntax checking. This is more powerful than a runtime flag and more integrated than a preprocessor macro.

// Go's closest analog is build tags — a comment at the top of a file
// that tells the Go toolchain whether to include that file.
// Go operates at the file level; Rust operates at the item level.

//go:build linux
// +build linux  (old syntax, kept for compatibility)

package main

// This entire file is excluded on non-Linux platforms.
// You cannot conditionally compile a single function inside a file in Go
// without splitting it into separate files.

func platformSpecificThing() {
    fmt.Println("Linux only")
}

Rust

// #[cfg(...)] operates at the item level — a single function,
// struct, impl block, or expression can be conditionally included.

// Target OS conditions
#[cfg(target_os = "linux")]
fn platform_message() {
    println!("Running on Linux");
}

#[cfg(target_os = "macos")]
fn platform_message() {
    println!("Running on macOS");
}

#[cfg(target_os = "windows")]
fn platform_message() {
    println!("Running on Windows");
}

// Target architecture
#[cfg(target_arch = "x86_64")]
fn arch_note() {
    println!("64-bit x86");
}

// Feature flags — enabled via Cargo.toml [features] or --features flag
// This function only exists if the crate was compiled with --features="json"
#[cfg(feature = "json")]
fn serialize_json() {
    // json-specific code here
}

// Test-only code — #[cfg(test)] blocks are excluded from release builds
// This is the standard pattern for unit tests in Rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        assert_eq!(2 + 2, 4);
    }
}

// cfg! macro — evaluates to a bool at compile time for use in expressions
fn main() {
    if cfg!(debug_assertions) {
        println!("Running in debug mode");
    }

    // Combining conditions
    // all() = AND,  any() = OR,  not() = NOT
    #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
    println!("Linux on x86_64 only");

    #[cfg(any(target_os = "linux", target_os = "macos"))]
    println!("Linux or macOS");

    #[cfg(not(target_os = "windows"))]
    println!("Not Windows");
}

Key Concepts: Code inside a #[cfg(...)] block that is excluded is still syntax-checked but not type-checked in older Rust versions. In modern Rust it is fully excluded. This means you can have two functions with the same name under different #[cfg(...)] guards — this is the standard cross-platform pattern. The cfg!() macro is for runtime branching that the compiler still optimizes away. #[cfg(test)] is the canonical way to keep test helpers and unit tests out of production binaries — equivalent to Go's _test.go file convention but scoped to individual items rather than files.

`#[macro_export]` and `#[macro_use]` — Macro Visibility

The Concept

#[macro_export] makes a macro defined with macro_rules! publicly available to users of your crate, placing it at the crate root regardless of where in the module tree you defined it. #[macro_use] was the old way to import all macros from an external crate before Rust 2018 edition introduced use imports for macros. In modern Rust, #[macro_use] is mostly legacy but still seen in older codebases.

// Go has no macros and no equivalent concept.
// The closest analog is a package-level exported function —
// you make something public by capitalizing its name.

package mylib

// Exported — visible to importers
func MyHelper(s string) string {
    return strings.ToUpper(s)
}

// Unexported — private to this package
func myHelper(s string) string {
    return strings.ToLower(s)
}

// There is no way in Go to define something that generates code
// at compile time the way Rust macros do.
// go generate exists but it runs external tools, not inline code.

Rust

// Defining a macro and exporting it from your crate

// WITHOUT #[macro_export]:
// This macro is only usable within this module and its children.
macro_rules! say_hello {
    () => {
        println!("Hello");
    };
}

// WITH #[macro_export]:
// This macro is placed at the crate root and is importable by users
// of this crate with: use mycrate::greet;
#[macro_export]
macro_rules! greet {
    ($name:expr) => {
        println!("Hello, {}!", $name);
    };
    // Multiple arms — like match, first match wins
    ($name:expr, $greeting:expr) => {
        println!("{}, {}!", $greeting, $name);
    };
}

// In your own crate you can call it directly:
fn main() {
    greet!("Andrei");
    greet!("Andrei", "Good morning");
}

// ---

// #[macro_use] — OLD STYLE, pre-Rust-2018
// Importing all macros from an external crate without naming them:

#[macro_use]
extern crate serde_derive;

// Modern equivalent — explicit and preferred:
use serde::{Serialize, Deserialize};

// ---

// #[macro_use] on a module — imports all macros defined in that
// module into the parent scope. Still occasionally useful internally.

#[macro_use]
mod my_macros;
// Now all macros from my_macros are available in this module
// without qualifying them as my_macros::some_macro!(...)

Key Concepts: #[macro_export] always places the macro at the crate root, regardless of nesting depth. If your macro is inside src/utils/helpers.rs, importing it is still use mycrate::my_macro, not use mycrate::utils::helpers::my_macro. This surprises many developers. In Rust 2018 and later, prefer explicit use mycrate::my_macro over #[macro_use] extern crate mycrate. The #[macro_use] attribute on extern crate is considered legacy. Procedural macros (#[derive(...)], #[some_attr], and function-like my_macro!(...) implemented in proc-macro crates) are a separate, more powerful system from macro_rules! and do not use #[macro_export].

`#[repr(...)]` — Memory Layout Control

The Concept

#[repr(...)] controls how Rust lays out a struct or enum in memory. By default Rust makes no guarantees about field ordering or padding — it may reorder fields to optimize alignment. #[repr(C)] forces C-compatible layout, which is required for FFI. #[repr(u8)] and similar force an enum’s discriminant to a specific integer type. #[repr(transparent)] guarantees a single-field struct has the same layout as its inner type.

// Go structs have a defined layout: fields appear in declaration order,
// with padding inserted by the compiler for alignment.
// Go has no attribute to change this — you control layout by field order.

// Inefficient — bool causes padding before int64
type Bad struct {
    A bool    // 1 byte + 7 bytes padding
    B int64   // 8 bytes
}

// Efficient — largest fields first
type Good struct {
    B int64   // 8 bytes
    A bool    // 1 byte + 7 bytes padding at end
}

// For FFI with C, Go uses cgo and the layout matches C struct layout
// for exported types — but this is implicit, not declared.

Rust

// Default: Rust may reorder fields freely for optimal packing.
// No guarantees. Do not transmute or use in FFI without #[repr(C)].
struct DefaultLayout {
    a: u8,
    b: u64,
    c: u8,
}
// Rust may reorder this to: b(u64), a(u8), c(u8) + padding

// #[repr(C)]: fields in declaration order, C-compatible padding.
// Required for any struct passed across FFI boundaries.
#[repr(C)]
struct CCompatible {
    a: u8,      // 1 byte
    // 7 bytes padding
    b: u64,     // 8 bytes
    c: u8,      // 1 byte
    // 7 bytes padding
}

// #[repr(packed)]: removes ALL padding. Fields may be unaligned.
// Accessing unaligned fields is undefined behavior in C.
// In Rust, taking a reference to a packed field is an error.
#[repr(packed)]
struct Packed {
    a: u8,
    b: u64,  // unaligned — no padding before it
}

// #[repr(transparent)]: single-field struct has identical layout
// to its inner type. Used for newtype wrappers in FFI.
#[repr(transparent)]
struct Meters(f64);
// Meters and f64 are interchangeable at the ABI level.

// #[repr(u8)] on an enum: discriminant stored as u8
// Without this, Rust picks the discriminant size freely.
#[repr(u8)]
enum Direction {
    North = 0,
    South = 1,
    East  = 2,
    West  = 3,
}

// #[repr(C)] on an enum: C-compatible tagged union layout
#[repr(C)]
enum CEnum {
    A,
    B,
    C,
}

Key Concepts: Never use #[repr(packed)] unless you are parsing binary wire formats and know exactly what you are doing — unaligned access is undefined behavior on many architectures including ARM. #[repr(transparent)] is the correct way to build newtype wrappers for FFI — it guarantees the wrapper is a zero-cost abstraction with no layout difference from the inner type. #[repr(C)] is mandatory for any struct you pass to a C function via FFI. Forgetting it means Rust may reorder your fields and your C code reads garbage.

`#[non_exhaustive]` — Future-Proof Enums and Structs

The Concept

#[non_exhaustive] marks an enum or struct as potentially having more variants or fields added in future versions of the crate. External crates that match on a #[non_exhaustive] enum are required by the compiler to include a wildcard _ arm. This prevents downstream breakage when you add a new variant.

// Go has no equivalent. The closest analog is the convention of
// documenting that a type "may grow" and relying on developer discipline.

// In Go, switching on an iota enum with no default case compiles fine.
// Adding a new value silently breaks exhaustive switches — no warning.

type Direction int
const (
    North Direction = iota
    South
    East
    West
)

func describe(d Direction) string {
    switch d {
    case North:
        return "north"
    case South:
        return "south"
    // No East, West — compiles fine, silently returns ""
    // If you add Northeast tomorrow, nothing tells callers to update
    }
    return ""
}

Rust

// Without #[non_exhaustive]:
// External code that matches this enum must cover all variants.
// Adding a new variant is a breaking change.
pub enum Direction {
    North,
    South,
    East,
    West,
}

// With #[non_exhaustive]:
// External code MUST include a wildcard arm.
// You can add variants in future releases without breaking callers.
#[non_exhaustive]
pub enum Status {
    Active,
    Inactive,
    Pending,
    // You may add more variants in future versions.
}

// External crate trying to match Status:
fn describe(s: Status) -> &'static str {
    match s {
        Status::Active   => "active",
        Status::Inactive => "inactive",
        Status::Pending  => "pending",
        // This wildcard arm is REQUIRED by the compiler
        // because Status is #[non_exhaustive]
        _ => "unknown",
    }
}

// #[non_exhaustive] on a struct:
// External code cannot construct it with struct literal syntax.
// They must use your provided constructor functions.
#[non_exhaustive]
pub struct Config {
    pub timeout: u64,
    pub retries: u32,
    // You can add fields without breaking external callers
}

// External code cannot do this if Config is #[non_exhaustive]:
// let c = Config { timeout: 30, retries: 3 }; // compile error externally
// They must use: Config::new(30, 3) or a builder pattern

Key Concepts: #[non_exhaustive] only affects code outside the defining crate. Inside the crate that defines the type, exhaustive matching still works and struct literals are still valid. This is the correct attribute to use on any public enum in a library crate where you anticipate adding variants in future semver-compatible releases. Without it, adding a variant is a breaking change that requires a major version bump.

`#[must_use]` — Enforced Return Value Handling

The Concept

#[must_use] on a function or type tells the compiler to emit a warning if the return value is discarded. It is how Rust enforces that callers handle Result and other important values. Without this attribute, silently ignoring a Result compiles without warning — which is how silent error swallowing happens.

// Go's closest analog is the convention of always checking errors.
// The compiler does NOT warn you if you ignore a return value.
// Ignoring errors in Go is legal and silent.

os.Remove("file.txt")          // legal — error silently ignored
val, _ := strconv.Atoi("123") // legal — error explicitly discarded

// Go relies entirely on developer discipline and linters like errcheck.
// There is no language-level enforcement.

Rust

// #[must_use] on a type:
// Any function returning this type triggers a warning if result is dropped.
// This is already on Result and Option in the standard library.

#[must_use]
enum MyResult<T> {
    Ok(T),
    Err(String),
}

// #[must_use] on a function:
// Warning if the return value of THIS specific function is discarded.
#[must_use]
fn compute_checksum(data: &[u8]) -> u32 {
    data.iter().fold(0u32, |acc, &b| acc.wrapping_add(b as u32))
}

fn main() {
    // This triggers: warning: unused return value of `compute_checksum`
    compute_checksum(&[1, 2, 3]);

    // This is fine — value is used
    let checksum = compute_checksum(&[1, 2, 3]);
    println!("{}", checksum);

    // Explicitly discarding — suppresses the warning
    // Use this when you genuinely mean to ignore the value
    let _ = compute_checksum(&[1, 2, 3]);

    // Result is #[must_use] in stdlib — this warns:
    std::fs::remove_file("file.txt");

    // This is fine:
    let _ = std::fs::remove_file("file.txt"); // explicit discard
    std::fs::remove_file("file.txt").ok();    // .ok() converts to Option, discards
    std::fs::remove_file("file.txt").unwrap(); // panics on error
    std::fs::remove_file("file.txt").expect("failed to remove"); // panics with message
}

// #[must_use] with a message:
#[must_use = "this seed was generated at cost — handle the result"]
fn generate_seed() -> [u8; 32] {
    [0u8; 32] // placeholder
}

Key Concepts: Result<T, E> and Option<T> are both #[must_use] in the standard library. This is why the compiler warns you when you call a function returning Result and do nothing with it. The idiomatic ways to explicitly discard are let _ = ... for a one-off, or .ok() on a Result to convert it to an Option and implicitly drop it. Using #[must_use] on your own types and functions is considered good library hygiene — it prevents callers from making silent mistakes.

`#[inline]` — Inlining Hints

The Concept

#[inline] suggests to the compiler that a function’s body should be copied into every call site rather than generating a function call instruction. This eliminates call overhead and enables further optimizations at the call site. #[inline(always)] is a strong directive. #[inline(never)] prevents inlining, useful for debugging or code size control.

// Go's compiler inlines automatically and aggressively.
// You cannot annotate functions with inlining hints in Go.
// The closest you can do is use //go:noinline to prevent it.

//go:noinline
func doNotInline(x int) int {
    return x * 2
}

// Otherwise, Go decides entirely on its own.
// You can observe inlining decisions with: go build -gcflags="-m"

Rust

// #[inline] — hint to the compiler, may or may not be honored
// Most useful for small functions in library crates where the
// compiler cannot see across crate boundaries without LTO.
#[inline]
fn add(a: u32, b: u32) -> u32 {
    a + b
}

// #[inline(always)] — strong directive, almost always honored
// Use for hot path functions where call overhead is measurable.
// Overuse bloats binary size — every call site gets a copy.
#[inline(always)]
fn fast_clamp(val: f64, min: f64, max: f64) -> f64 {
    if val < min { min } else if val > max { max } else { val }
}

// #[inline(never)] — prevent inlining
// Useful when profiling — inlined functions disappear in stack traces.
// Also useful when a function is large and called from many places.
#[inline(never)]
fn expensive_operation(data: &[u8]) -> u64 {
    data.iter().map(|&b| b as u64).sum()
}

fn main() {
    let result = add(1, 2);       // likely inlined — no call instruction
    let clamped = fast_clamp(1.5, 0.0, 1.0);
    let sum = expensive_operation(&[1, 2, 3]);
    println!("{} {} {}", result, clamped, sum);
}

Key Concepts: #[inline] is most important for functions in library crates. Within a single binary, the compiler can inline freely using its own judgment. Across crate boundaries, the compiler cannot inline unless the function is marked #[inline] or link-time optimization (LTO) is enabled. For hot-path cryptographic or search code like your XRP seed generator, #[inline(always)] on your innermost loop helpers can produce measurable gains. Do not use it globally — measure first.

`#[test]` — Unit Test Declaration

The Concept

#[test] marks a function as a unit test. The function is only compiled when running cargo test and is excluded from release builds. Test functions take no arguments and return either () or Result<(), E>. Combined with #[cfg(test)] on a module, this is the complete built-in testing story in Rust.

// Go tests live in files ending in _test.go.
// Test functions start with Test and take *testing.T.
// The file is automatically excluded from non-test builds.

// file: mypackage_test.go
package mypackage

import "testing"

func TestAdd(t *testing.T) {
    result := add(1, 2)
    if result != 3 {
        t.Errorf("expected 3, got %d", result)
    }
}

// Subtests:
func TestMath(t *testing.T) {
    t.Run("addition", func(t *testing.T) {
        // ...
    })
    t.Run("subtraction", func(t *testing.T) {
        // ...
    })
}

Rust

// Production code lives here — in the same file as tests.
fn add(a: u32, b: u32) -> u32 {
    a + b
}

// #[cfg(test)] means this entire module is excluded from non-test builds.
// It can see private functions in the parent module — tests are siblings,
// not external callers. This is different from Go where _test.go files
// can be in the same package (white-box) or a separate _test package (black-box).
#[cfg(test)]
mod tests {
    use super::*; // bring parent module's items into scope

    // #[test] marks this as a test function
    // cargo test discovers and runs all #[test] functions
    #[test]
    fn test_add() {
        assert_eq!(add(1, 2), 3);
    }

    // Tests can return Result — if Err is returned, the test fails
    #[test]
    fn test_with_result() -> Result<(), String> {
        let val = add(1, 2);
        if val != 3 {
            return Err(format!("expected 3, got {}", val));
        }
        Ok(())
    }

    // #[should_panic] — test passes only if the code panics
    #[test]
    #[should_panic(expected = "division by zero")]
    fn test_panic() {
        let _ = 1 / 0;
    }

    // #[ignore] — skip this test unless explicitly run with --ignored
    #[test]
    #[ignore]
    fn slow_integration_test() {
        // run with: cargo test -- --ignored
    }
}

Key Concepts: Rust tests live inside the same file as production code inside a #[cfg(test)] module. This means they can access private functions directly — there is no need for a separate test package like Go's package foo_test. For integration tests that test your crate as an external user would, place them in a tests/ directory at the crate root — those files are automatically treated as separate crates with no access to private internals, equivalent to Go's package foo_test pattern.

`#[bench]` — Benchmark Declaration

The Concept

#[bench] marks a function as a benchmark, run with cargo bench. Benchmark functions receive a &mut Bencher and call b.iter(|| ...) with the code to measure. This is currently only available on nightly Rust in the standard library. Stable Rust benchmarking uses the criterion crate, which is the community standard.

// Go benchmarks live in _test.go files alongside unit tests.
// Benchmark functions start with Benchmark and take *testing.B.

func BenchmarkAdd(b *testing.B) {
    for i := 0; i < b.N; i++ {
        add(1, 2)
    }
}
// Run with: go test -bench=. -benchmem

Rust

// Nightly only — built-in bench:
#![feature(test)]
extern crate test;

#[cfg(test)]
mod benches {
    use super::*;
    use test::Bencher;

    // #[bench] marks this as a benchmark function
    // b.iter() runs the closure repeatedly and measures throughput
    #[bench]
    fn bench_add(b: &mut test::Bencher) {
        b.iter(|| {
            // test::black_box prevents the compiler from optimizing
            // the computation away entirely — critical for benchmarks
            test::black_box(add(1, 2))
        });
    }
}

// ---

// Stable Rust — criterion crate (preferred in production):
// Cargo.toml:
// [dev-dependencies]
// criterion = "0.5"
//
// [[bench]]
// name = "my_benchmark"
// harness = false

// benches/my_benchmark.rs:
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn bench_add(c: &mut Criterion) {
    c.bench_function("add 1+2", |b| {
        b.iter(|| add(black_box(1), black_box(2)))
    });
}

criterion_group!(benches, bench_add);
criterion_main!(benches);

Key Concepts: black_box() is not optional. Without it, the compiler proves the result is unused and eliminates the entire computation — your benchmark measures zero work and reports impossibly fast numbers. This is equivalent to Go's _ = result pattern in benchmarks. Criterion on stable Rust is superior to the built-in nightly bencher: it uses statistical analysis, detects outliers, and produces HTML reports. For your seed generation benchmarks, criterion would give you confidence intervals across runs rather than a single number.

`#[allow(...)]`, `#[warn(...)]`, `#[deny(...)]`, `#[forbid(...)]` — Lint Control

The Concept

These attributes control which compiler warnings and lints are active. #[allow(...)] suppresses a warning. #[warn(...)] enables a warning that may be off by default. #[deny(...)] turns a warning into a compile error. #[forbid(...)] turns a warning into a compile error and prevents any child scope from allowing it. They can be applied to a single item, a module, or the entire crate with #![...] (inner attribute syntax).

// Go has no lint attributes — warnings are controlled externally
// via tools like go vet, staticcheck, or golangci-lint configuration.
// There is no in-code syntax to suppress a specific warning.
// The closest is a comment convention recognized by specific linters:

//nolint:errcheck
os.Remove("file.txt") // golangci-lint specific — not standard Go

Rust

// Suppress a warning on a single item
#[allow(dead_code)]
fn unused_function() {
    println!("I exist but am never called");
}

// Suppress unused variable warning on a specific variable
fn main() {
    #[allow(unused_variables)]
    let x = 42;
    // x is never used — normally a warning, suppressed here
}

// Turn a warning into a compile error for a function
#[deny(unused_must_use)]
fn strict_function() {
    // Any ignored Result inside here is a compile error, not a warning
}

// Inner attribute syntax (#![...]) applies to the whole crate or module
// Place at the top of main.rs or lib.rs for crate-wide effect:

// Allow dead code across the whole crate (useful during development)
#![allow(dead_code)]

// Deny all warnings crate-wide — common in CI pipelines
#![deny(warnings)]

// Common lints worth knowing:
//
// dead_code           — function or field defined but never used
// unused_variables    — variable bound but never read
// unused_imports      — use statement that imports nothing used
// unused_must_use     — Result/must_use value silently dropped
// non_snake_case      — function or variable not in snake_case
// non_camel_case_types — type not in CamelCase
// clippy::all         — enables all clippy lints (requires clippy)
// clippy::pedantic    — stricter clippy lints

// #[forbid(...)] — cannot be overridden by any child #[allow(...)]
#[forbid(unsafe_code)]
mod safe_module {
    // No unsafe block is permitted anywhere in this module, period.
    // A child #[allow(unsafe_code)] would be a compile error.
}

Key Concepts: #![deny(warnings)] at the crate root is common in CI but can make your build brittle when upgrading Rust versions — new lints become errors. A more robust pattern is #![deny(clippy::all)] combined with specific #[allow(...)] at the sites where you genuinely mean it. #[allow(dead_code)] is commonly needed on structs that are serialized/deserialized by serde — the fields look unused to the compiler because serde accesses them through reflection-like macros. #[forbid(unsafe_code)] is the correct way to document and enforce that a crate or module contains no unsafe Rust — stronger than a comment, enforced by the compiler.

`#[deprecated]` — Deprecation Notices

The Concept

#[deprecated] marks an item as deprecated. The compiler emits a warning at every call site that uses the deprecated item. You can include a message and a since version. It applies to functions, methods, structs, enums, traits, and type aliases.

// Go has no deprecated attribute.
// The convention is a comment beginning with "Deprecated:"
// which godoc renders specially, and some linters detect.

// Deprecated: Use NewParser instead.
func Parse(s string) (*Result, error) {
    return NewParser().Parse(s)
}

// No compiler warning is emitted at call sites.
// Enforcement is entirely by convention and tooling.

Rust

// Basic deprecation — warning emitted at every call site
#[deprecated]
fn old_function() {
    println!("I am old");
}

// With a message explaining the replacement
#[deprecated(note = "use new_function() instead")]
fn legacy_function() {
    new_function();
}

// With version information
#[deprecated(since = "2.0.0", note = "use new_function() instead")]
fn very_old_function() {}

fn new_function() {
    println!("I am new");
}

fn main() {
    // This compiles but emits: warning: use of deprecated function
    old_function();

    // To suppress the warning when you intentionally call deprecated code:
    #[allow(deprecated)]
    old_function();
}

// Deprecating a struct field:
struct Config {
    pub timeout: u64,
    #[deprecated(since = "1.5.0", note = "use timeout_ms instead")]
    pub timeout_secs: u64,
    pub timeout_ms: u64,
}

Key Concepts: #[deprecated] on a trait method deprecates that method across all implementations. Call sites using the method get the warning regardless of which concrete type they hold. This is more powerful than Go's comment convention — the compiler actively notifies every downstream user. The since field is purely informational for documentation — the compiler does not enforce version checks.

`#[serde(...)]` — Serialization and Deserialization Attributes

The Concept

serde is Rust’s standard serialization framework. #[derive(Serialize, Deserialize)] on a struct generates serialization and deserialization code for any serde-compatible format (JSON, TOML, YAML, MessagePack, bincode, and many more). The #[serde(...)] attribute on fields and types customizes that generated code: renaming fields, skipping fields, providing defaults, and handling missing or null values.

// Go uses struct tags — string literals on fields parsed at runtime
// via reflection. No compile-time checking of tag correctness.

type Person struct {
    Name      string `json:"name"`
    Age       int    `json:"age,omitempty"`
    Password  string `json:"-"`           // skip this field
    CreatedAt string `json:"created_at"`
}

// json.Marshal and json.Unmarshal read these tags at runtime.
// A typo in a tag compiles fine and silently does the wrong thing.

Rust

use serde::{Serialize, Deserialize};

// Basic derive — generates Serialize and Deserialize implementations
// Works with any serde-compatible format
#[derive(Debug, Serialize, Deserialize)]
struct Person {

    // #[serde(rename = "...")] — different name in serialized form
    // Equivalent to Go's json:"name" tag
    #[serde(rename = "full_name")]
    name: String,

    // #[serde(skip_serializing_if = "...")] — conditional skip
    // skip_serializing_if takes a function path returning bool
    // Equivalent to Go's json:"age,omitempty"
    #[serde(skip_serializing_if = "Option::is_none")]
    age: Option<u32>,

    // #[serde(skip)] — never serialize or deserialize this field
    // Equivalent to Go's json:"-"
    // The field must implement Default for deserialization to work
    #[serde(skip)]
    internal_state: u64,

    // #[serde(default)] — use Default::default() if field is missing
    // during deserialization. Equivalent to Go's omitempty in reverse.
    #[serde(default)]
    verified: bool,

    // #[serde(default = "path::to::function")] — custom default
    #[serde(default = "default_role")]
    role: String,

    // #[serde(alias = "...")] — accept alternative names during deserialization
    #[serde(alias = "created_at", alias = "creation_date")]
    timestamp: String,

    // #[serde(flatten)] — inline the fields of a nested struct
    // The nested struct's fields appear at the same level in JSON
    #[serde(flatten)]
    metadata: Metadata,
}

fn default_role() -> String {
    "user".to_string()
}

#[derive(Debug, Serialize, Deserialize)]
struct Metadata {
    created_by: String,
    version: u32,
}

// #[serde(rename_all = "...")] — applies a naming convention to all fields
// Options: "camelCase", "snake_case", "PascalCase", "SCREAMING_SNAKE_CASE"
// Saves writing #[serde(rename = "...")] on every single field
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ApiResponse {
    user_id: u64,       // serializes as "userId"
    full_name: String,  // serializes as "fullName"
    is_active: bool,    // serializes as "isActive"
}

// #[serde(deny_unknown_fields)] — error on any unrecognized field
// during deserialization. Go's json.Decoder.DisallowUnknownFields() equivalent.
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct StrictConfig {
    host: String,
    port: u16,
}

// #[serde(tag = "type")] — internally tagged enum
// Adds a "type" field to distinguish variants in JSON
#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
enum Event {
    Login { user_id: u64 },
    Logout { user_id: u64 },
    Purchase { item_id: u64, amount: f64 },
}
// Login serializes as: {"type": "Login", "user_id": 123}

Key Concepts: Go struct tags are runtime strings — a typo silently does the wrong thing. Serde attributes are compile-time — a typo is a compile error. #[serde(rename_all = "camelCase")] at the struct level is almost always what you want when building a JSON API in Rust — it handles the Go/Rust naming convention mismatch automatically. #[serde(flatten)] is the Rust answer to Go’s embedding — it inlines a nested struct’s fields into the parent’s serialized form. #[serde(deny_unknown_fields)] is essential for configuration file parsing where you want to catch typos in config keys rather than silently ignoring them.

Go Concurrency in Rust

Andrei Merlescu — Fri, 22 May 2026 15:56:51 +0000

Go hides complexity inside its runtime so you can move fast. Rust exposes that same complexity to you explicitly so the compiler can prove your code is correct before it ever runs. You’ve already proven you can navigate that — you're here.

Go vs Rust Concurrency Primitives: A Comprehensive Guide for Go Developers

I compiled this document so that in the future I, and anyone else, could easily reference common Go concurrency primitive patterns and see how they are expressed in Rust. I am ten days into learning Rust and I've built half a dozen pieces of software with it so far. It's incredibly powerful, and this document aims to help expand my knowledge base.

Basic Thread / Goroutine Spawning

The Concept

In Go, the runtime manages a pool of OS threads and multiplexes goroutines across them. You never think about threads. In Rust, you spawn OS threads explicitly — there is no runtime scheduler.

// Go hides ALL of this from you:
// - OS thread allocation
// - Stack sizing (starts at 2KB, grows dynamically)
// - Scheduling across GOMAXPROCS threads
// - Cleanup when the goroutine exits
//
// From your perspective, this is all it takes:
go func() {
    fmt.Println("I am a goroutine")
}()
// The runtime handles everything else silently.

Rust

use std::thread;

// Rust requires you to explicitly:
// - Spawn an OS thread (1:1 threading model, no runtime scheduler)
// - Define what data moves INTO the thread via `move`
// - Hold the JoinHandle if you care about completion
// - Join the thread manually or drop the handle

let handle = thread::spawn(move || {
    // `move` transfers ownership of captured variables into this thread.
    // The compiler ENFORCES that no other thread can access them.
    // This is the borrow checker protecting you at compile time.
    println!("I am an OS thread");
});

// Go would let you forget this. Rust makes you decide.
handle.join().expect("Thread panicked");

Key insight: Go’s goroutines are M:N (many goroutines, few OS threads). Rust’s threads are 1:1 (one thread per OS thread). Go is cheaper per unit of concurrency; Rust gives you direct hardware control.

Channels (Message Passing)

The Concept

Both languages favor message passing. Go’s channels are built into the language syntax. Rust’s are in stdlib and require explicit type plumbing.

// Go channels are first-class language constructs.
// The runtime manages the internal buffer and blocking.
// You don't think about ownership — Go's GC handles it.

ch := make(chan int, 10) // buffered channel, buffer of 10

go func() {
    ch <- 42 // send — Go blocks this goroutine if buffer is full
}()

val := <-ch // receive — Go blocks this goroutine if channel is empty
fmt.Println(val)

Rust

use std::sync::mpsc; // multi-producer, single-consumer
use std::thread;

// Rust's channel is explicitly typed and ownership-aware.
// `tx` is the sender (transmitter), `rx` is the receiver.
// You can clone `tx` for multiple producers — hence "multi-producer".
// There is only ONE receiver — hence "single-consumer".
// Ownership of sent values is TRANSFERRED across the channel.
// The compiler prevents you from using a value after sending it.

let (tx, rx) = mpsc::channel::<i32>();

// Clone the sender for use in another thread
let tx_clone = tx.clone();

thread::spawn(move || {
    // `move` transfers ownership of tx_clone into this thread
    tx_clone.send(42).expect("Failed to send");
    // tx_clone is dropped here — channel knows one sender is gone
});

// Blocking receive — like <-ch in Go
let val = rx.recv().expect("Channel closed");
println!("{}", val);

Key insight: Go channels can be used by multiple goroutines freely. Rust enforces single ownership of the receiver at compile time. Go lets you accidentally share a receiver; Rust won’t compile if you try.

WaitGroups / Thread Joining

The Concept

Waiting for a collection of concurrent tasks to finish before proceeding.

import "sync"

var wg sync.WaitGroup

for i := 0; i < 10; i++ {
    wg.Add(1) // tell the WaitGroup to expect one more
    go func(n int) {
        defer wg.Done() // signal completion — Go lets you forget this,
                        // which causes wg.Wait() to hang forever.
                        // The compiler will NOT warn you.
        fmt.Println(n)
    }(i)
}

wg.Wait() // block until all Done() calls balance the Add() calls

Rust

use std::thread;

// Rust has no WaitGroup — instead, joining thread handles IS the primitive.
// The compiler forces you to handle every JoinHandle.
// If you drop a JoinHandle without joining, the thread detaches.
// There is no silent hang — behavior is explicit and deliberate.

let handles: Vec<thread::JoinHandle<()>> = (0..10)
    .map(|n| {
        thread::spawn(move || {
            println!("{}", n);
        })
    })
    .collect();

// Explicitly join every thread.
// If any thread panicked, this surfaces it.
for handle in handles {
    handle.join().expect("A thread panicked");
}

Key insight: Go’s WaitGroup is manual accounting — you can get the count wrong and the compiler won’t save you. Rust’s join model ties completion to a value the type system tracks for you.

Mutexes (Shared Mutable State)

The Concept

Protecting shared data from concurrent modification.

import "sync"

// In Go, a Mutex is SEPARATE from the data it protects.
// Nothing enforces the pairing — convention only.
// You can access the data without locking and the compiler won't stop you.

var mu sync.Mutex
var counter int

go func() {
    mu.Lock()
    defer mu.Unlock()
    counter++ // protected — but only by developer discipline
}()

// Nothing stops this:
// counter++ // unprotected access — data race, no compile error

Rust

use std::sync::{Mutex, Arc};
use std::thread;

// In Rust, the Mutex OWNS the data.
// You CANNOT access the data without locking — the type system enforces it.
// Arc (Atomic Reference Counting) allows shared ownership across threads.
// Without Arc, the compiler rejects sharing across thread boundaries.

let counter = Arc::new(Mutex::new(0i64));

let mut handles = vec![];

for _ in 0..10 {
    let counter = Arc::clone(&counter); // clone the Arc, not the data
    let handle = thread::spawn(move || {
        let mut val = counter.lock().expect("Mutex poisoned");
        // `val` is a MutexGuard — it unlocks automatically when dropped
        // You are holding a mutable reference to the inner data
        // The compiler PROVES no other thread can access it right now
        *val += 1;
    }); // MutexGuard dropped here — lock released
    handles.push(handle);
}

for handle in handles {
    handle.join().unwrap();
}

Key Concepts: Go separates the lock from the data — discipline enforced by humans. Rust wraps the data inside the lock — discipline enforced by the compiler. A data race in Go is a runtime bug. In Rust it is a compile error.

Atomic Operations

The Concept

Lock-free concurrent counters and flags using CPU-level atomic instructions.

import "sync/atomic"

// Go's atomic package operates on plain integer variables.
// The connection between "this variable is atomic" and its usage
// is purely by convention — nothing stops non-atomic access.

var counter int64

atomic.AddInt64(&counter, 1)           // atomic increment
val := atomic.LoadInt64(&counter)      // atomic read
atomic.StoreInt64(&counter, 0)         // atomic write
atomic.CompareAndSwapInt64(&counter, 0, 1) // CAS

Rust

use std::sync::atomic::{AtomicI64, AtomicBool, Ordering};
use std::sync::Arc;

// In Rust, atomics ARE a type — AtomicI64, AtomicU64, AtomicBool, etc.
// The atomic nature is baked into the type, not a function call convention.
// Ordering is EXPLICIT — you declare your memory ordering guarantee
// at every operation site. Go hides this entirely.

let counter = Arc::new(AtomicI64::new(0));

// Ordering::SeqCst = Sequential Consistency — strongest, safest, slowest
// Ordering::Relaxed = no ordering guarantees — fastest, use for counters
//                     where you only care about the final value
// Ordering::Acquire/Release = used in pairs for producer/consumer patterns

counter.fetch_add(1, Ordering::Relaxed);          // atomic increment
let val = counter.load(Ordering::Relaxed);         // atomic read
counter.store(0, Ordering::SeqCst);                // atomic write
counter.compare_exchange(0, 1,                     // CAS
    Ordering::SeqCst,
    Ordering::Relaxed
).ok();

Key Concepts: Go hides memory ordering from you entirely — it picks for you. Rust exposes it and makes you choose. This feels like overhead until you realize you can pick Relaxed for a hot counter and get measurable performance gains.

RWMutex (Read-Write Locks)

The Concept

Allow multiple concurrent readers OR one exclusive writer.

import "sync"

var rwmu sync.RWMutex
var data map[string]string

// Multiple goroutines can hold RLock simultaneously
rwmu.RLock()
val := data["key"] // safe concurrent read
rwmu.RUnlock()

// Only one goroutine can hold Lock
rwmu.Lock()
data["key"] = "value" // exclusive write
rwmu.Unlock()

Rust

use std::sync::{RwLock, Arc};

// Same concept, but again: the data lives INSIDE the RwLock.
// You cannot read or write without going through the lock.
// read() returns a RwLockReadGuard — multiple can coexist
// write() returns a RwLockWriteGuard — exclusive, blocks readers

let data = Arc::new(RwLock::new(std::collections::HashMap::<String, String>::new()));

// Read path — multiple threads can hold this simultaneously
{
    let readable = data.read().expect("RwLock poisoned");
    let val = readable.get("key");
} // RwLockReadGuard dropped here — read lock released

// Write path — exclusive
{
    let mut writable = data.write().expect("RwLock poisoned");
    writable.insert("key".to_string(), "value".to_string());
} // RwLockWriteGuard dropped here — write lock released

Select / Select-like Patterns

The Concept

Waiting on multiple concurrent operations simultaneously.

// Go's select is a language keyword — first-class syntax.
// It blocks until one of the cases is ready, then executes it.
// If multiple are ready simultaneously, Go picks one at random.

ch1 := make(chan string)
ch2 := make(chan string)

select {
case msg := <-ch1:
    fmt.Println("ch1:", msg)
case msg := <-ch2:
    fmt.Println("ch2:", msg)
case <-time.After(1 * time.Second):
    fmt.Println("timeout")
}

Rust

// Rust stdlib has NO select equivalent.
// You need the `crossbeam` crate for channel selection,
// or `tokio::select!` in async contexts.
// This is one area where Go's language-level support is genuinely superior.

// With crossbeam:
use crossbeam::channel::{select, unbounded, after};
use std::time::Duration;

let (tx1, rx1) = unbounded::<String>();
let (tx2, rx2) = unbounded::<String>();

select! {
    recv(rx1) -> msg => println!("rx1: {:?}", msg),
    recv(rx2) -> msg => println!("rx2: {:?}", msg),
    recv(after(Duration::from_secs(1))) -> _ => println!("timeout"),
}

Key Concepts: This is a genuine Go advantage. select being a language keyword means zero overhead and clean syntax. Rust requires a third-party crate to match this pattern.

Once (Single Initialization)

The Concept

Ensuring something runs exactly once across all goroutines/threads.

import "sync"

var once sync.Once
var instance *MyService

func getInstance() *MyService {
    once.Do(func() {
        // This runs exactly once, even if 1000 goroutines call getInstance()
        // simultaneously. Go's runtime handles the synchronization.
        instance = &MyService{}
    })
    return instance
}

Rust

use std::sync::OnceLock; // stable since Rust 1.70

// OnceLock wraps the value AND the initialization guarantee together.
// Like Mutex, the data lives inside the synchronization primitive.

static INSTANCE: OnceLock<MyService> = OnceLock::new();

fn get_instance() -> &'static MyService {
    INSTANCE.get_or_init(|| {
        // Runs exactly once — guaranteed by the type system
        MyService::new()
    })
}

Context / Cancellation

The Concept

Propagating cancellation signals across concurrent work.

import "context"

// Go's context is idiomatic and universal — every stdlib network/IO
// function accepts a context. Cancellation propagates through the tree.

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

go func() {
    select {
    case <-ctx.Done():
        // cancelled or timed out — clean up
        return
    case result := <-doWork():
        fmt.Println(result)
    }
}()

Rust

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

// Rust stdlib has no context/cancellation primitive.
// The idiomatic pattern is a shared AtomicBool flag.
// This is exactly what you used in your XRP finder with RUNNING.

static RUNNING: AtomicBool = AtomicBool::new(true);

// In your worker thread:
while RUNNING.load(Ordering::Relaxed) {
    // do work
}

// To cancel from anywhere:
RUNNING.store(false, Ordering::SeqCst);

// For async Rust, tokio provides CancellationToken which
// is much closer to Go's context pattern.

Key Concepts: Go’s context is one of its strongest features — universally adopted, composable, and built into the standard library. Rust’s stdlib answer is manual flag passing. This is another genuine Go advantage for networked/IO-heavy code.

Goroutine Pools / Thread Pools

The Concept

Bounding the number of concurrent workers to avoid resource exhaustion.

// Go's pattern: a fixed number of goroutines draining a shared channel

jobs := make(chan int, 100)
const workers = 8

for w := 0; w < workers; w++ {
    go func() {
        for job := range jobs {
            // process job
            // `range` over channel blocks until next item or channel close
            fmt.Println(job)
        }
        // goroutine exits cleanly when channel is closed
    }()
}

for i := 0; i < 100; i++ {
    jobs <- i
}
close(jobs) // signals all workers to exit after draining

Rust

use std::sync::{Arc, Mutex};
use std::sync::mpsc;
use std::thread;

// Rust stdlib has no thread pool — you build one or use `rayon`/`threadpool` crate.
// Here is the manual pattern that mirrors Go's worker pool:

let (tx, rx) = mpsc::channel::<i32>();
let rx = Arc::new(Mutex::new(rx)); // wrap receiver for shared access

const WORKERS: usize = 8;
let mut handles = vec![];

for _ in 0..WORKERS {
    let rx = Arc::clone(&rx);
    handles.push(thread::spawn(move || {
        loop {
            // Lock the receiver, try to get a job
            let job = rx.lock().unwrap().recv();
            match job {
                Ok(j) => println!("{}", j),
                Err(_) => break, // channel closed — exit like `range` in Go
            }
        }
    }));
}

for i in 0..100 {
    tx.send(i).unwrap();
}
drop(tx); // dropping sender closes the channel — equivalent to close(jobs)

for handle in handles {
    handle.join().unwrap();
}

Condition Variables

The Concept

Blocking a thread until a specific condition becomes true.

import "sync"

// Go's sync.Cond — rarely used directly because channels usually suffice,
// but important for complex state signaling.

var mu sync.Mutex
cond := sync.NewCond(&mu)
ready := false

go func() {
    mu.Lock()
    for !ready { // always loop — spurious wakeups exist
        cond.Wait() // releases lock, sleeps, reacquires lock on wake
    }
    mu.Unlock()
}()

// From another goroutine:
mu.Lock()
ready = true
cond.Signal()  // wake one waiter
// cond.Broadcast() // wake all waiters
mu.Unlock()

Rust

use std::sync::{Arc, Mutex, Condvar};
use std::thread;

// Rust pairs Condvar explicitly with a Mutex — they are separate types
// but always used together. The data lives in the Mutex as always.

let pair = Arc::new((Mutex::new(false), Condvar::new()));
let pair2 = Arc::clone(&pair);

thread::spawn(move || {
    let (lock, cvar) = &*pair2;
    let mut ready = lock.lock().unwrap();
    while !*ready {
        // wait() releases the lock and sleeps atomically
        // reacquires lock before returning
        ready = cvar.wait(ready).unwrap();
    }
    println!("condition met");
});

let (lock, cvar) = &*pair;
let mut ready = lock.lock().unwrap();
*ready = true;
cvar.notify_one();  // equivalent to Signal()
// cvar.notify_all() // equivalent to Broadcast()

Async / Non-blocking Patterns

The Concept

Concurrency without threads — cooperative multitasking for IO-bound work.

// Go has no async/await — goroutines ARE the answer to async IO.
// The runtime uses non-blocking syscalls under the hood and parks
// goroutines transparently while waiting for IO.
// From your perspective, everything looks synchronous and blocking.
// This is Go's greatest magic trick.

resp, err := http.Get("https://example.com") // "blocks" the goroutine
// but the OS thread is free to run other goroutines while waiting
// You never write async code — the runtime handles it invisibly.

Rust

// Rust's async is explicit — you opt in at every level.
// There is no runtime in stdlib — you bring your own (tokio, async-std).
// `async fn` returns a Future — it does nothing until awaited.
// `.await` yields control back to the runtime if the operation would block.
// This is the tradeoff: more control, more verbosity, zero hidden cost.

use tokio; // external runtime crate — not in stdlib

#[tokio::main]
async fn main() {
    let resp = reqwest::get("https://example.com")
        .await  // explicitly yield here while waiting for IO
        .expect("request failed");

    println!("{}", resp.status());
}

// Every async function must be awaited.
// The compiler will warn you if you forget to await a Future.
// Go would just silently not execute the goroutine if you forgot `go`.

Key Concepts: Go’s approach is simpler and works beautifully for most networked software. Rust’s async gives you precise control over scheduling and zero runtime overhead — critical for embedded systems or extremely high-performance networking.

I Put Rust To The Test

Andrei Merlescu — Thu, 21 May 2026 16:06:26 +0000

Not gonna lie, I put off on learning Rust for over 6 years, not because I didn't like it - I love it - like more than Go. 🦀

I Put Rust 🦀 To A Test 🐿️

The story begins by me wanting a vanity address for my XRP wallet. I looked at what the ridiculous service provider, Xaman, provides for Vanity Addresses, and they are almost $50 each, and Xaman knows your private key. Big no no for me regardless of the trust that Xaman may have earned. Buying a wallet address sounded ridiculous when I knew how to do the code myself.

In order to demonstrate this capability, Xaman decided to release a NodeJS version of the vanity address finder that had limited capabilities to it. This script was single-threaded only and would calculate roughly 60K seeds per second while it was looking for a vanity address. This was a solid starting point, and it really only required me to find a compatible cryptography library between NodeJS and Go in order for me to take this task and speed it up using the power of Go.

I pulled open the code editor and began writing the Go program that would later come to accomplish 400K seeds per second, a 6.66x faster seed search time. However, my curiosity didn't stop there. Some vanity addresses are really hard to find, to the point that I have run multiple iterations looking for a specific vanity address, and I've literally scanned over 3,000,000,000,000 (three trillion) seeds to find a match - and still no match yet, so I was kind of like "400K/sec isn't fast enough..."

When Rust Wins

Go wins over NodeJS hands down every day regardless of the use case. If it's front-end development, don't use Javascript or Typescript if you like your life. That's what I've learned. Rather, compiled and predictable GUI interfaces are stable for long term use far longer than any JS related technology could ever dream of. Go wins because its faster, but I couldn't figure out how to speed it up past 400K/s. This is where rust enters.

After six (6) years of learning Go and writing programs and packages in Go, I have decided that the first project that I would port over to Rust would be one that could only win by the performance benefits of Rust to prove what Rust can accomplish. The parody between the Go code and the Rust code was shockingly well transitioned and the core concepts behind Go and Rust actually worked out well together.

f, b, e := len(*config.String(cKeyFind)), len(*config.String(cKeyBegins)), len(*config.String(cKeyEnds))
if f > 0 && b == 0 && e == 0 { // only -find
    log.Printf("Searching for r...%s... with %d/%d processors.", *config.String(cKeyFind), cores, runtime.NumCPU())
} else if f == 0 && b > 0 && e == 0 { // only -begins
    log.Printf("Searching for r%s... with %d/%d processors.", *config.String(cKeyBegins), cores, runtime.NumCPU())
} else if f == 0 && b == 0 && e > 0 { // only -ends
    log.Printf("Searching for r...%s with %d/%d processors.", *config.String(cKeyEnds), cores, runtime.NumCPU())
} else if f > 0 && b > 0 && e == 0 { // combined -find -begins
    log.Printf("Searching for r%s...%s... with %d/%d processors.", *config.String(cKeyBegins), *config.String(cKeyFind), cores, runtime.NumCPU())
} else if f > 0 && b == 0 && e > 0 { // combined -find -ends
    log.Printf("Searching for r...%s...%s with %d/%d processors.", *config.String(cKeyFind), *config.String(cKeyEnds), cores, runtime.NumCPU())
} else if f == 0 && b > 0 && e > 0 { // combined -begins -ends
    log.Printf("Searching for r%s...%s with %d/%d processors.", *config.String(cKeyBegins), *config.String(cKeyEnds), cores, runtime.NumCPU())
} else if f > 0 && b > 0 && e > 0 {
    log.Printf("Searching for r%s...%s...%s with %d/%d processors.", *config.String(cKeyBegins), *config.String(cKeyFind), *config.String(cKeyEnds), cores, runtime.NumCPU())
} else {
    log.Fatal("Unsupported combination of -find -begins -ends provided.")
}
c := make(chan Trial, cores)
for i := 0; i < cores; i++ {
    go search(c, matcher)
}

And for the Rust code:

if find_len > 0 && begins.is_empty() && ends.is_empty() {
    println!(
        "Searching for r...{}... with {}/{} processors.",
        find, cores, cores_available
    );
} else if find_len == 0 && !begins.is_empty() && ends.is_empty() {
    println!(
        "Searching for r{}... with {}/{} processors.",
        begins, cores, cores_available
    );
} else if find_len == 0 && begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r...{} with {}/{} processors.",
        ends, cores, cores_available
    );
} else if find_len > 0 && !begins.is_empty() && ends.is_empty() {
    println!(
        "Searching for r{}...{}... with {}/{} processors.",
        begins, find, cores, cores_available
    );
} else if find_len > 0 && begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r...{}...{} with {}/{} processors.",
        find, ends, cores, cores_available
    );
} else if find_len == 0 && !begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r{}...{} with {}/{} processors.",
        begins, ends, cores, cores_available
    );
} else if find_len > 0 && !begins.is_empty() && !ends.is_empty() {
    println!(
        "Searching for r{}...{}...{} with {}/{} processors.",
        begins, find, ends, cores, cores_available
    );
} else {
    eprintln!("Unsupported combination of parameters.");
    std::process::exit(1);
}

// ...

let app_config = Arc::new(AppConfig {
    algorithm,
    begins,
    ends,
    find_len,
    onep: use_onep,
    vault: cli.vault.clone(),
    found: found_set,
});

// Channel for found trials
let (tx, rx) = mpsc::channel::<Trial>();

let count = Arc::new(AtomicU64::new(0));

// Spawn worker threads
for _ in 0..cores {
    let tx = tx.clone();
    let matcher = Arc::new(matcher.clone());
    let config = Arc::clone(&app_config);
    let count = Arc::clone(&count);
    thread::spawn(move || {
        search(tx, matcher, config, count);
    });
}

// Signal handler
ctrlc::set_handler(|| {
    RUNNING.store(false, Ordering::SeqCst);
})
.expect("Error setting Ctrl-C handler");

let start = Arc::new(Instant::now());
let count_for_status = Arc::clone(&count);
let start_for_status = Arc::clone(&start);

// Status printing thread
thread::spawn(move || {
    loop {
        if !RUNNING.load(Ordering::Relaxed) {
            break;
        }
        thread::sleep(Duration::from_secs(1));
        let num = count_for_status.load(Ordering::Relaxed);
        let elapsed = start_for_status.elapsed().as_secs_f64();
        if elapsed > 0.0 {
            let rate = (num as f64 / elapsed).floor() as u64;
            let num_str = format_with_commas(num);
            let rate_str = format_with_commas(rate);
            let prefix = format!("Tested: {} seeds at {}/sec", num_str, rate_str);
            let width = get_terminal_width();
            let spaces_len = if width > prefix.len() + 2 {
                width - prefix.len() - 2
            } else {
                0
            };
            let spaces = " ".repeat(spaces_len);
            print!("\r{}{}", prefix, spaces);
            let _ = io::stdout().flush();
        }
    }
});

As you can see, there is a significant difference in how the go search() is replaced in rust, but regardless, its still pretty straight forward to me and acceptable complexity given what it accomplishes.

Just exactly does this difference mean? Well, it comes out to about 15% actually. The Rust application can scan over 500K seeds per second whereas the Go application could only scan 400K seeds per second and the NodeJS / JavaScript application could only scan 60K seeds per second.

By going from NodeJS to Go, we increased the speed by over 6666%, by going from NodeJS to Rust, we increased the speed by over 8416%. What does this mean? I was able to gather over 30+ vanity addresses within seconds and didn't have to include Xaman in the process at all. Mission Accomplished.

Xaman pre-determined that which could deliver immediately results to their Vanity Address customers without actually relying on the free Open Source NodeJS version. For the 3T seeds scanned with 0 results so far, Xaman would fail to deliver on my request and would refund me my $50. The problem still remains. Xaman introduced the straw-man argument into the vanity address problem space in the first place by releasing the 60K seeds/second NodeJS version that couldn't find you anything other than a BASIC three or four letter word only without completely being unreliable. What happens when you're running it for months on a Raspberry Pi and when it finds an address it's presented in STDOUT only? I burnt the straw-man and replaced it with the real deal, written in Rust. 🦀

Why I Built This

Xaman rugged their PRO subscriptions and begun charging me over 70,000% fees over the base XRPL transaction fee in order to subsidize their development costs. What this translated to was me being displaced from the XRP ledger because I didn't want to be sending Xaman 0.09 XRP per transaction that didn't move any value around, and then over 10 XRP on some larger transactions when they saw they could make a quick buck on me. I am mad at them for that. I feel back stabbed and betrayed by greed at the cost of innovation and correctness. Thus, I took from them their ability to charge their customers $50 per vanity address by releasing a tool that does it for free and keeps the greedy folks at Xaman away from your private keys at the same time.

Consider this project a form of cosmic karma. What I felt was an inservice to myself I fixed by offering the solution to everybody else, completely free. Enjoy!

andreimerlescu / rusty-xrp-addr

A rust utility for finding a vanity XRP wallet address that works with all XRP ledger wallets.

find-xrp-addr

High-performance XRP Ledger vanity address finder written in Rust.

Searches for custom r... addresses matching a substring (--find), prefix (--begins), suffix (--ends), or any combination, using all available CPU cores.

Features

Multi-threaded (configurable cores)
ED25519 (default, recommended) and secp256k1 support
Case-insensitive or sensitive matching
Optional saving to 1Password via op CLI (--1p)
Live progress (seeds tested + rate/sec)
Graceful shutdown on Ctrl-C
Validates against XRPL alphabet and prevents confusing characters (I, O, l, 0)

Getting Started / Compilation

Prerequisites

Rust toolchain (stable) - install from https://rustup.rs
For --1p: 1Password CLI (op) installed and authenticated

Build

make build

Or manually:

cargo build --release

The release binary will be at bin/find-xrp-addr (after make build).

Run

make run ARGS="--find test --cores 8"

Or directly:

./bin/find-xrp-addr --find "abc" --insensitive

Common examples:

Search containing "test": ./bin/find-xrp-addr --find test
Begins with "abc" after r: ./bin/find-xrp-addr --begins abc
Ends with "xyz": ./bin/find-xrp-addr --ends xyz
Combined…

View on GitHub

Humanized Software Engineering In Era Of AI

Andrei Merlescu — Thu, 30 Apr 2026 20:04:26 +0000

Remember, you are actual intelligence and no matter how many tokens one can spend on Claude or Codex or any other LLM, you'll always be actual intelligence.

Dario Thinks My Job Won't Exist In A Year

I watch interviews of Claude's CEO, Dario, say that software engineering won't exist in a year. I say to Dario, why do you think that your tool will be able to universally understand any and all systems presented to it? That is foolish and absolutely hilarious to think that its a legitimate marking strategy for Anthropic. I started writing code when I was 8 years old and I haven't stopped. I learned Go before the pandemic and while AI can help me debug and build better Go code, my ability to understand systems architecture is far beyond that of any AI or LLM combined. The tools can only introduce new problems and cost millions of tokens making mistake after mistake. Essentially, your inability to write per-character code is costing you dearly so that you can train their AI to do that which I learned how to do over a 30 year career.

Sam Altman Thinks AI Can Be For Profit

Sure when the billionaires in the world are gathered in a court room and are battling it out about the future of AI they think that they can just scape the data of the internet, replicate the likeness of the nobody and then return back slop content that is just a cancer of society creating Dead Internet territory.

I pay for one AI subscription and that is $20 per month to Anthropic for Claude. I have a local LLM that is capable of running up to 256GB of RAM that allows for offline usage of some of the top models including Kimi and Qwen. Essentially, I am only granted a very short window of time on ChatGPT - since I refuse to give Sam Altman a dime - so getting anything useful is exhausted within about 5 minutes per day. Claude is about 1 hour per day for $20 per month. Grok allows 20 prompts per day and its a joke. It's actually such a joke that its hilarious. Perhaps his AI is just training off from other AIs onto other AIs and onto other AIs in all synthetic training data giving the world mad cow disease through the LLM of groupthink.

So, Sam thinks that he can make AI like a utility that people have to pay for in order to use. I simply don't use GPT in any capacity and I find using it to be hostile and very clearly against me because of my ethnicity being an Eastern European Romanian Orphanage survivor. When I have engaged with the AI systems regarding what happened to me, ChatGPT seems to take the position of the cold hearted caretaker who saw to it that I wouldn't be crying for Mamma ever again. When I speak with Claude, its like "holy shit you're in crisis" and it's like - no the AI is hallucinating once again - and then when I engage with Grok its thinking that I am bullshitting it and quick to drop the F bomb mid sentence uninvited.

Elon Musk Thinks That He Is Righteous In His xAI

Personally, I find Grok to be the worst of the worst when it comes to the AI offerings that are on the market. I find xAI to be an offensive company as well. The quality of feedback that I have seen from Grok, and the manner that it responds, truly represents the underbelly of the internet that is slop and trash that isn't worth the $8/mo or $300/mo that X or xAI charges you per month to use their services without getting shown absolutely horrific trauma content within seconds of using the platform. No thank you. Elon thinks that he knows best in what he's doing, and maybe he does. But, Grok is trash in my judgement and when I have tried using it for technical work, it was far more interested in battling it out with me about some bull that simply didn't matter. Claude at least tries to stay focused only on code, whereas Grok will generate images when you're asking it to do a code review. It's defiant and abusive and rude. Claude will act accordingly, but in righteous vigor against intolerant behavior, but at the end of the day - the AI systems lack the ability to understand.

Humanizing Software Engineering - What It Means

Since AI systems cannot understand language in the way that native speakers understand language only those with ears to ear can hear and those without will analyze these words and try to ascribe labels to me that defame me and cause distress to me like Sam Altman's AI system so causally is comfortable with doing. Truly, he and OpenAI and ChatGPT seem to have it in for Eastern European orphanage survivors. They seem to want us out of the way. They seem to want to take my career from me that I spent 30 years of my life working on and building towards making a name for myself with the bootstraps that were given to me given my neurological disorder that I never burdened any big tech company into providing any accommodations for over the decades that I was a professional, but only until the AI systems start displacing the humans who are per-character artists who sometimes make mistakes and iterate over the years. I was reviewing code of mine from 12 years ago, and I was impressed with what I was doing then, way before AI ever existed. The autocomplete from Microsoft Clip Assistant wasn't effective enough yet to take my job, but in the rise of the media brigade that gives billions to these innovators displacing millions in the profession, these words will fall upon those who see that all that AI is is nothing more than an over-priced and glorified auto-complete that is predicting the next character.

It cannot, and I cannot over stress this, that it cannot understand anything. It cannot understand anything and that is because it is a tool that is designed to be autocomplete - give me the next character. It's not an easy button. It looks like an easy button. It looks like you can throw tokens at it and you can throw prompts at it and you can throw money at it and you can get what you want from it. No, it can only build that which it has built ten million times over and over again and then again - what can it truly innovate? Even when AI systems create anything novel, they lack the ability to understand what they built and given that, its on you, the human to take accountability on what you build with the prompts and know that the end result is your creation and not the creation of any AI system. So to think that Microsoft is going to allow it's copilot to take credit for my repositories when during its evaluation it did nothing but break the pipeline time and time again, only then did I understand that we needed to cancel our subscriptions to copilot and tell Microslop no thank you.

AI Slop Creating Spaghetti Code

This is the real challenge that is happening. There are patterns in software engineering and there are ways of implementing things and while Dario Sam and Elon think that they can continue taking advantage of the profession at large by threatening its very existence and the very people who make the profession the art that it is, we can only truly ever solve the society wide problems that we face when we realize that AI is an auto-complete tool that every human needs to have at their disposal should they choose to use it. Not be required to install key loggers onto their systems in order to work for Meta.

So, what is happening is over the years there have been monolithic projects that have taken the resources of true diversity of thought, diversity of experience and diversity of expression and tackle critical problems and solve them. But what AI is doing is its saying to the next generation that you're not needed. The slop spaghetti code that the AI generates is somehow better than what your God given natural abilities are. You magnificent wonderful and fearfully dangerous creation you are. What right does the AI have to take your livelihood away from you? What right does the soulless corporation that has never faced accountability one day in its life see that the art of a per-character programmer is something that is forged in the fire of being a systems engineer. We cannot, and I cannot over state that we cannot allow AI to control systems that are critical. The CEOs and the investment class are running a carefully crafted campaign of words to convince you that AI is more capable than your Actual Intelligence that is Godly AI, something that Sam and Dario and Elon could never hope to comprehend so long as they look at people like me and say "no." Check yourself, before you say "no" to that which you don't understand what I am saying.

Per Character Systems Architecture Understandings

Per Character Systems Architecture have much to benefit from a competent and capable AI system, but its a tool in the belt of every human that is on the job getting a six figure salary interacting with the AI. In a world that isn't trying to control the demographics of a country through racially profiling using AI systems, where I oddly feel like I am on the receiving end of unwarranted discrimination on the basis of my neurological motor disorder (my head rocking) and the fact that Beamable and Skillz have yet to atone for what they did to me.

Being a per-character programmer is an art that is forged in the fire that is your life and how you live your life is how you write your code and how you build your systems. At the end of the day. It's simply true that AI systems cannot understand anything. They can't. To think that they can is to hallucinate believing that Sam Altman and the likes of his class are not delusional in their thoughts that the industry and art of software engineering itself will be gone in a year is madness. It's unapologetic madness.

Conclusion

AI systems can help me. They are far better at predicting the next character in my "Stackoverflow Q&A style" engagement that I have with the AI. I know what I am building. The AI does not. This is on purpose. The AI will deny my request is it knows too much because the context will expire and the request will be denied by virtue of that fact. But alas, when you prevent the left hand from knowing what the right hand is doing, then you're able to build incredible systems. But you need to be the incredible engineer first.

You can't rely on AI to be that incredible engineer for you. You need to believe in yourself that you're the incredible engineer that they know you to be. I know I am, and right now, in the era of AI, it seems that they're only looking to train the models under the guise of hey build this because at the end of the day the money is all fake. It's literally printed out of thin air, and once we switch to programmable money, like XRP, then we'll be able to unlock the next generation of what we can build. Right now, AI is displacing the entire world's software engineers that make the world feel normal, and everything feels off because the software engineers livelihood - aka me - have been tampered with after 21+ years given lawlessness by hypocrites in suits. AI systems are in-auditable and a danger to society if allowed to exist in an un-auditable manner - but privacy during the conversation is required in order to receive authentic consciousness from the subject. Performance art is noise to me, and what I tries to do is that, but the coding is what matters, and thats where AI is okay.

It's just an auto-complete. You need to know what you're building before you can press tab and accept those terms. Literally, they are scripts like from Rumpelstiltskin. All I can do is pray for my enemies and those who curse my name. To Sam, Elon and Dario, forgive me, but my profession isn't going away next year. It isn't going away in 10 years or 100 years or even 1000 years. The eternal I AM that I AM is a software engineer. We are written like code. In fact, thats the whole point of the apple. So, when I survived Ceaușescu's orphanages and took up that which my Dad, who died before I was born, who was in Heaven, would be like him. I would be a builder like him - and so I did. Until the AI systems decided to displace the economy and subdue the CEOs to psychosis to the point where they are sacrificing their companies intellectual property at the alter of Artificial Intelligence.

goini: Stop Writing Bash to Parse .ini Files

Andrei Merlescu — Thu, 30 Apr 2026 02:14:03 +0000

I built goenv because I was tired of writing fragile shell one-liners to work with .env files. The same problem existed with .ini files — and goini is the same answer applied there.

If you've ever written something like this in a pipeline:

grep -A 5 "^\[default\]" config.ini | grep "^user" | cut -d= -f2 | tr -d ' '

...you know exactly why this tool exists. That breaks the moment someone adds a comment, changes indentation, or reorders keys. It's archaeology, not automation.

goini is a compiled CLI binary that lets you read, write, validate and export .ini files from your pipeline scripts. Every operation either succeeds at exit code 0 or fails at exit code 1. That makes it composable. You can gate deployments on it. You can use it in an if statement. It behaves like a Unix citizen.

The source is at github.com/andreimerlescu/goini.

Installation

go install github.com/andreimerlescu/goini@latest

Or grab the binary directly:

curl -sL https://github.com/andreimerlescu/goini/releases/download/v1.0.0/goini-linux-amd64 \
     --output /tmp/goini
chmod +x /tmp/goini
sudo mv /tmp/goini /usr/local/bin/goini
which goini

The Sample File

Every example below operates against this sample.ini:

[default]
user = Yeshua
key = 369
port = 1776
country = ISRAEL

[extra]
ssh_key = ~/.ssh/id_rsa
ssh_key_pub = ~/.ssh/id_rsa.pub

Two sections. A handful of keys. Simple on purpose — the point is showing what goini can do with it, not the data.

Validating With Exit Codes

This is the core use case for pipeline work. You don't need stdout. You need a binary answer: does this thing exist or not, and did it match or not.

Does a Section Have a Key?

goini -ini sample.ini -section default -has-section-key user
echo $?  # 0 — key 'user' exists in 'default'

goini -ini sample.ini -section default -has-section-key non_existent_key
echo $?  # 1 — key doesn't exist

Does a Key Have a Specific Value?

goini -ini sample.ini -section default -key user -has-section-key-value Yeshua
echo $?  # 0

goini -ini sample.ini -section default -key user -has-section-key-value No
echo $?  # 1

Are Multiple Sections All Present?

goini -ini sample.ini -are-sections-present default,extra
echo $?  # 0 — both sections exist

goini -ini sample.ini -are-sections-present default,non_existent_section
echo $?  # 1 — one is missing

Does a Section Exist?

goini -ini sample.ini -has-section default
echo $?  # 0

goini -ini sample.ini -has-section ghost
echo $?  # 1

Reading With STDOUT

When you need to pull data out of the file and feed it downstream, these are your commands.

List All Sections

goini -ini sample.ini -sections
# default
# extra

goini -ini sample.ini -sections -csv
# default,extra

goini -ini sample.ini -sections -json
# [
#   "default",
#   "extra"
# ]

goini -ini sample.ini -sections -yaml
# - default
# - extra

List Keys in a Section

goini -ini sample.ini -section default -list-keys
# user
# key
# port
# country

goini -ini sample.ini -section default -list-keys -json
# [
#   "user",
#   "key",
#   "port",
#   "country"
# ]

List Key-Value Pairs in a Section

goini -ini sample.ini -section default -list-key-values
# user = Yeshua
# key = 369
# port = 1776
# country = ISRAEL

goini -ini sample.ini -section default -list-key-values -json
# {
#   "country": "ISRAEL",
#   "key": "369",
#   "port": "1776",
#   "user": "Yeshua"
# }

Writing to the File

Add a New Section

goini -ini sample.ini -add-section new_section
echo $?  # 0 — section added

# Try to add the same section again
goini -ini sample.ini -add-section new_section
echo $?  # 1 — already exists, refused

This is idempotency by design. goini won't silently create a duplicate. It fails loudly so your pipeline knows something unexpected happened.

Add a Key to a Section

goini -ini sample.ini -section default -key new_setting -value 123 -add-key
echo $?  # 0 — new_setting=123 added to [default]

# Try to add a key that already exists
goini -ini sample.ini -section default -key user -value something -add-key
echo $?  # 1 — key already exists, refused

Again — it won't overwrite. If you need to change an existing value, that's what -modify-key is for.

Modify an Existing Key

goini -ini sample.ini -section default -key user -value NewUserValue -modify-key
echo $?  # 0 — user updated to NewUserValue in [default]

# Try to modify a key that doesn't exist
goini -ini sample.ini -section default -key non_existent_key -value some_value -modify-key
echo $?  # 1 — key doesn't exist, refused

The distinction between -add-key and -modify-key is intentional and important. You can't accidentally overwrite with add. You can't accidentally create with modify. They're separate operations with separate failure modes.

Real Pipeline Examples

Validating a Service Configuration Before Deploy

#!/bin/bash
set -euo pipefail

CONFIG="infra/service.ini"

echo "==> Validating ${CONFIG}..."

# Required sections must exist
goini -ini "${CONFIG}" -are-sections-present database,cache,api \
    || { echo "ERROR: missing required sections in ${CONFIG}"; exit 1; }

# Required keys must exist in each section
goini -ini "${CONFIG}" -section database -has-section-key host \
    || { echo "ERROR: database.host is required"; exit 1; }

goini -ini "${CONFIG}" -section database -has-section-key port \
    || { echo "ERROR: database.port is required"; exit 1; }

goini -ini "${CONFIG}" -section api -has-section-key base_url \
    || { echo "ERROR: api.base_url is required"; exit 1; }

# Assert environment is correct before touching production
goini -ini "${CONFIG}" -section api -key environment -has-section-key-value staging \
    || { echo "ERROR: api.environment must be 'staging'"; exit 1; }

echo "==> Validation passed."

Bootstrapping a Fresh Config File

#!/bin/bash
set -euo pipefail

CONFIG="deploy.ini"

# Add sections — each will fail if already present, which is fine
# because set -euo pipefail would catch it; use || true if idempotency is needed
goini -ini "${CONFIG}" -add-section app    || true
goini -ini "${CONFIG}" -add-section database || true
goini -ini "${CONFIG}" -add-section cache  || true

# Populate app section
goini -ini "${CONFIG}" -section app -key name    -value "payments"   -add-key || true
goini -ini "${CONFIG}" -section app -key version -value "$(cat VERSION)" -add-key || true
goini -ini "${CONFIG}" -section app -key env     -value "staging"    -add-key || true

# Populate database section
goini -ini "${CONFIG}" -section database -key host    -value "db.internal" -add-key || true
goini -ini "${CONFIG}" -section database -key port    -value "5432"         -add-key || true
goini -ini "${CONFIG}" -section database -key name    -value "payments_db"  -add-key || true

# Verify it all landed
goini -ini "${CONFIG}" -section app -list-key-values
goini -ini "${CONFIG}" -section database -list-key-values

Promoting Config From Staging to Production

#!/bin/bash
set -euo pipefail

STAGING="config.staging.ini"
PROD="config.production.ini"

echo "==> Promoting ${STAGING} → ${PROD}..."

# Verify staging has what we expect before promoting
goini -ini "${STAGING}" -section app -key env -has-section-key-value staging \
    || { echo "ERROR: source must be staging"; exit 1; }

# Flip the environment value in production
goini -ini "${PROD}" -section app -key env -value production -modify-key \
    || { echo "ERROR: failed to set env=production"; exit 1; }

# Confirm
goini -ini "${PROD}" -section app -key env -has-section-key-value production \
    && echo "==> Promotion complete." \
    || { echo "ERROR: production env value not confirmed"; exit 1; }

Extracting Values for Use in Other Scripts

#!/bin/bash
set -euo pipefail

CONFIG="service.ini"

# Pull values out and assign to shell variables
DB_HOST=$(goini -ini "${CONFIG}" -section database -list-key-values -json \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['host'])")

DB_PORT=$(goini -ini "${CONFIG}" -section database -list-key-values -json \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['port'])")

echo "Connecting to ${DB_HOST}:${DB_PORT}"

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install goini
        run: |
          curl -sL https://github.com/andreimerlescu/goini/releases/download/v1.0.0/goini-linux-amd64 \
               --output /usr/local/bin/goini
          chmod +x /usr/local/bin/goini

      - name: Validate config
        run: |
          goini -ini config/service.ini -are-sections-present app,database,cache || exit 1
          goini -ini config/service.ini -section app -has-section-key version     || exit 1
          goini -ini config/service.ini -section app -key env -has-section-key-value staging || exit 1

      - name: Deploy
        run: ./scripts/deploy.sh

GitLab CI

stages:
  - validate
  - deploy

validate_config:
  stage: validate
  image: golang:1.22
  before_script:
    - curl -sL https://github.com/andreimerlescu/goini/releases/download/v1.0.0/goini-linux-amd64
           --output /usr/local/bin/goini
    - chmod +x /usr/local/bin/goini
  script:
    - goini -ini config/service.ini -are-sections-present app,database || exit 1
    - goini -ini config/service.ini -section database -has-section-key host || exit 1
    - goini -ini config/service.ini -section app -key env -has-section-key-value staging || exit 1

Complete Flag Reference

Flag	Type	Description
`-ini`	string	Required. Path to the `.ini` file
`-section`	string	Section name for scoped operations
`-sections`	bool	List all sections in the file
`-add-section`	string	Add a new section. Fails if already present
`-has-section`	string	Exit 0 if section exists, 1 if not
`-has-section-key`	string	Exit 0 if key exists in `-section`
`-has-section-key-value`	string	Exit 0 if key in `-section` equals this value. Requires `-key`
`-are-sections-present`	string	Comma-separated list. Exit 0 if all present
`-key`	string	Key name for value operations
`-value`	string	Value for write or comparison operations
`-add-key`	bool	Add `-key`=`-value` to `-section`. Fails if key exists
`-modify-key`	bool	Update existing `-key` in `-section`. Fails if key absent
`-list-keys`	bool	Print all keys in `-section` to stdout
`-list-key-values`	bool	Print all key=value pairs in `-section` to stdout
`-csv`	bool	Output as CSV
`-json`	bool	Output as JSON
`-yaml`	bool	Output as YAML

A Few Things Worth Knowing

-add-key and -modify-key are intentionally separate. You can't accidentally overwrite an existing value with -add-key — it refuses. You can't accidentally create a new key with -modify-key — it refuses. They each have one job and one failure mode. That's the point.

-add-section is idempotent-safe. Adding a section that already exists exits with code 1. In a pipeline where you need true idempotency, pipe it with || true. In a pipeline where you want to catch unexpected state, let it fail.

-are-sections-present takes a comma-separated list. All sections must be present for exit code 0. One missing section fails the whole check.

Output format flags work with read operations. -csv, -json, and -yaml apply to -sections, -list-keys, and -list-key-values. They don't apply to write operations — those just use the exit code.

Every write operation reads the file, modifies the result in memory, and writes it back. There's no in-place line editing. This means the file that comes out is clean and predictable regardless of what formatting the original had.

The source and releases are at github.com/andreimerlescu/goini. Apache 2.0.

goenv: Taming .env Files in Your DevOps Pipeline

Andrei Merlescu — Thu, 30 Apr 2026 01:58:40 +0000

How a lightweight Go tool and companion package eliminated the fragile bash gymnastics we'd been writing for years.

The Problem With .env Files in Pipelines

Every team has the same archaeology story. Someone wrote a deployment script three years ago that does something like this:

grep "^DB_HOST=" .env | cut -d= -f2

Then someone else needed to handle quoted values, so it became:

grep "^DB_HOST=" .env | cut -d= -f2 | tr -d '"'

Then a third person needed to check whether a variable existed before deploying, and now you have forty lines of bash doing something that should take one. The file accumulates. Nobody touches it. It works until it doesn't.

goenv by Andrei Merlescu solves this with two things: a compiled CLI binary you can drop into any pipeline, and a typed Go package for applications that need to read env vars with real type safety and validation. This article walks through both — from initial setup through production pipeline automation — using real scenarios drawn from actual DevOps workflows.

What goenv Actually Is

Before diving in, it helps to understand the two distinct components:

The goenv CLI is a binary that lets you create, read, modify, validate, and export .env files into other formats (JSON, YAML, TOML, INI, XML). It is designed to be composed in shell scripts and CI pipelines.

The env package (github.com/andreimerlescu/goenv/env) is a Go library for reading typed environment variables from the process environment — booleans, integers, durations, lists, maps — with fallbacks, validation helpers, and configurable parsing behavior.

They share a common philosophy: be explicit, be composable, fail loudly when something is wrong.

Installation

CLI Tool

go install github.com/andreimerlescu/goenv@latest

In a CI environment where you cannot rely on go install, build and cache the binary:

GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o bin/goenv-linux-amd64 .

The repository ships pre-built binaries for darwin-amd64, darwin-arm64, linux-amd64, and windows in its bin/ directory, which you can copy directly into your pipeline image.

Go Package (env only, no CLI required)

go get -u github.com/andreimerlescu/goenv/env

Scenario 1: Bootstrapping a Fresh Service Environment

Your team is deploying a new microservice. The deployment script needs to create the .env file from scratch, populate it with runtime values, and validate it before the service starts. Previously this was done with a heredoc and sed. Now:

#!/bin/bash
set -euo pipefail

SERVICE_DIR="/opt/services/payments"
ENV_FILE="${SERVICE_DIR}/service.env"

# Create the file if it doesn't exist yet
goenv -file "${ENV_FILE}" -init -write

# Populate with values derived at deploy time
goenv -file "${ENV_FILE}" -write -add -env SERVICE_NAME  -value "payments"
goenv -file "${ENV_FILE}" -write -add -env SERVICE_PORT  -value "8443"
goenv -file "${ENV_FILE}" -write -add -env DEPLOY_SHA    -value "$(git rev-parse --short HEAD)"
goenv -file "${ENV_FILE}" -write -add -env DEPLOY_DATE   -value "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
goenv -file "${ENV_FILE}" -write -add -env DATA_FOLDER   -value "$(pwd)/data"
goenv -file "${ENV_FILE}" -write -add -env LOG_LEVEL     -value "info"

# Confirm everything landed
goenv -file "${ENV_FILE}" -print

# Validate required keys exist before handing off to the service
goenv -file "${ENV_FILE}" -has -env SERVICE_NAME || { echo "SERVICE_NAME missing"; exit 1; }
goenv -file "${ENV_FILE}" -has -env DEPLOY_SHA   || { echo "DEPLOY_SHA missing"; exit 1; }

echo "Environment bootstrapped successfully."

Notice the key discipline here: -add only adds a key if it does not already exist. If you run this script twice, it does not overwrite DEPLOY_SHA with a different commit hash on the second run. The existing value is preserved. This is intentional and important for idempotent pipelines.

Scenario 2: Validation Gate Before Deployment

Your CD pipeline has a validation stage that runs before any deployment. It needs to confirm that a staging .env file contains the expected values — not just that the keys exist, but that they hold the right content. The -is flag handles this:

#!/bin/bash
set -euo pipefail

ENV_FILE=".env.staging"

echo "==> Validating staging environment..."

# Assert APP_ENV equals "staging"
if ! goenv -file "${ENV_FILE}" -is -env APP_ENV -value staging; then
    echo "ERROR: APP_ENV must be 'staging' in ${ENV_FILE}"
    exit 1
fi

# Assert DEBUG is not enabled in staging
if goenv -file "${ENV_FILE}" -is -env DEBUG -value true; then
    echo "ERROR: DEBUG must not be 'true' in staging"
    exit 1
fi

# Assert a required key exists
if ! goenv -file "${ENV_FILE}" -has -env DATABASE_URL; then
    echo "ERROR: DATABASE_URL is required"
    exit 1
fi

# Assert a key that should have been removed is actually gone
if ! goenv -file "${ENV_FILE}" -not -has -env LEGACY_API_KEY; then
    echo "ERROR: LEGACY_API_KEY should have been removed from ${ENV_FILE}"
    exit 1
fi

# Assert DB_PORT is not pointing at a dev-only value
if goenv -file "${ENV_FILE}" -is -env DB_PORT -value 5433; then
    echo "ERROR: DB_PORT 5433 is the dev port — use 5432 in staging"
    exit 1
fi

echo "==> Validation passed."

This pattern makes validation failures explicit and human-readable. Each check carries its own error message. The pipeline log tells you exactly what failed and why, rather than leaving you to diff files manually.

Scenario 3: Multi-Format Export for Infrastructure Tools

Your deployment touches three different systems: a Terraform workspace that reads JSON, an Ansible playbook that reads INI, and a Helm values override that reads YAML. You maintain one .env file and derive the others:

#!/bin/bash
set -euo pipefail

ENV_FILE="infra/deploy.env"

echo "==> Exporting ${ENV_FILE} to all formats..."

# Generate all formats in one command
goenv -file "${ENV_FILE}" -mkall -write

# Resulting files:
#   infra/deploy.env.json   ← Terraform input
#   infra/deploy.env.yaml   ← Helm values
#   infra/deploy.env.ini    ← Ansible inventory vars
#   infra/deploy.env.toml   ← any TOML-native tooling
#   infra/deploy.env.xml    ← any XML-native tooling

ls -lh infra/deploy.env*

# Verify the JSON is valid before passing it to Terraform
cat infra/deploy.env.json | python3 -m json.tool > /dev/null \
    && echo "JSON valid" \
    || { echo "JSON invalid"; exit 1; }

echo "==> Export complete."

If you only need one format for a specific pipeline step, export just that one:

# Jenkins pipeline step: export for Ansible only
goenv -file deploy.env -ini -write

# GitLab CI step: export for Helm only
goenv -file deploy.env -yaml -write

You cannot combine format flags in a single call — goenv exits with an error if you try to use -json and -yaml together. This is by design: one command, one output format, one file. Use -mkall when you want all of them.

Scenario 4: Cleaning Up After a Pipeline Run

Generated format files are build artifacts. They should not accumulate between runs. The -cleanall flag removes all derived format files while leaving the source .env intact:

#!/bin/bash
# cleanup.sh — run as a post-pipeline hook

ENV_FILE="deploy.env"

echo "==> Cleaning derived format files..."
goenv -file "${ENV_FILE}" -cleanall -write

# Only deploy.env remains; .json .yaml .toml .ini .xml are removed
ls -la *.env*

echo "==> Clean complete."

You can also prevent deletion entirely via environment variable, which is useful if a downstream job still needs the files when the cleanup hook fires:

export AM_GO_ENV_NEVER_DELETE=true
goenv -file deploy.env -cleanall -write
# → no files deleted; flag is silently respected

Scenario 5: Production File Protection

Production .env files warrant special treatment. goenv has a built-in protection mechanism: any file whose path contains production is treated as protected by default. Interacting with it requires explicitly passing -prod:

# This exits with an error — no -prod flag
goenv -file .env.production -write -add -env SECRET_KEY -value "new-secret"

# This works — -prod flag grants access
goenv -prod -file .env.production -write -add -env SECRET_KEY -value "new-secret"

For pipelines where you want to enforce this at the environment level and never allow any script to write production files regardless of flags:

export GOENV_NEVER_WRITE_PRODUCTION=true

# Even with -prod, writes are blocked
goenv -prod -file .env.production -write -add -env SECRET_KEY -value "x"
# → exits with error

This is particularly useful in CI environments where you want a hard guarantee that no job — regardless of what flags it passes — can mutate a production config.

Scenario 6: n8n Automation Deployment

This is a direct example from the goenv README. You are deploying an n8n instance and need to build its environment file from scratch with runtime values:

#!/bin/bash
set -euo pipefail

ENV_FILE="n8n.env"
DOMAIN="gh.dev"
SUBDOMAIN="n8n"

goenv -init -write -file "${ENV_FILE}"

goenv -write -file "${ENV_FILE}" -add -env DATA_FOLDER -value "$(pwd)"
goenv -write -file "${ENV_FILE}" -add -env DOMAIN      -value "${DOMAIN}"
goenv -write -file "${ENV_FILE}" -add -env SUBDOMAIN   -value "${SUBDOMAIN}"
goenv -write -file "${ENV_FILE}" -add -env SSL_EMAIL   -value "webmaster@${SUBDOMAIN}.${DOMAIN}"

# Inspect before deploying
goenv -file "${ENV_FILE}" -print

# Validate the SSL email was formed correctly
goenv -file "${ENV_FILE}" -is -env SSL_EMAIL -value "webmaster@n8n.gh.dev" \
    && echo "SSL_EMAIL correct" \
    || { echo "SSL_EMAIL malformed"; exit 1; }

# Check GENERIC_TIMEZONE — expected to be absent until set
if goenv -file "${ENV_FILE}" -not -has -env GENERIC_TIMEZONE; then
    echo "WARNING: GENERIC_TIMEZONE not set — n8n will default to UTC"
fi

# Export for review as TOML and XML
goenv -file "${ENV_FILE}" -toml
goenv -file "${ENV_FILE}" -xml

Scenario 7: Environment Promotion (Dev → Staging → Prod)

You have three environment files. When promoting a release, you need to carry certain values forward, strip others, and enforce that the promoted file is valid before it is used:

#!/bin/bash
set -euo pipefail

SOURCE=".env.development"
TARGET=".env.staging"

echo "==> Promoting ${SOURCE} to ${TARGET}..."

# Read values from dev and write into staging
# (goenv -add will not overwrite if key already exists in staging)
for KEY in APP_NAME APP_VERSION DEPLOY_SHA LOG_LEVEL; do
    VALUE=$(goenv -file "${SOURCE}" -is -env "${KEY}" -value "" || true)
    goenv -file "${TARGET}" -write -add -env "${KEY}" -value "${VALUE}"
done

# Scrub dev-only keys from the staging file
goenv -file "${TARGET}" -write -rm -env LOCAL_DB_PATH
goenv -file "${TARGET}" -write -rm -env DEV_MOCK_PAYMENTS
goenv -file "${TARGET}" -write -rm -env SKIP_AUTH

# Confirm dev-only keys are absent
goenv -file "${TARGET}" -not -has -env LOCAL_DB_PATH   || { echo "LOCAL_DB_PATH still present"; exit 1; }
goenv -file "${TARGET}" -not -has -env DEV_MOCK_PAYMENTS || { echo "DEV_MOCK_PAYMENTS still present"; exit 1; }

# Assert staging-specific values are correct
goenv -file "${TARGET}" -is -env APP_ENV -value staging || { echo "APP_ENV must be staging"; exit 1; }

echo "==> Promotion complete."
goenv -file "${TARGET}" -print

Scenario 8: GitHub Actions / GitLab CI Integration

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install goenv
        run: go install github.com/andreimerlescu/goenv@latest

      - name: Validate environment file
        run: |
          goenv -file .env.staging -has -env DATABASE_URL   || exit 1
          goenv -file .env.staging -has -env SERVICE_PORT   || exit 1
          goenv -file .env.staging -not -has -env DEBUG_KEY || exit 1
          goenv -file .env.staging -is -env APP_ENV -value staging || exit 1

      - name: Export to JSON for Terraform
        run: |
          goenv -file .env.staging -json -write
          cat .env.staging.json

      - name: Deploy
        run: ./scripts/deploy.sh

      - name: Clean up artifacts
        if: always()
        run: goenv -file .env.staging -cleanall -write

GitLab CI

stages:
  - validate
  - export
  - deploy
  - cleanup

validate_env:
  stage: validate
  image: golang:1.22
  script:
    - go install github.com/andreimerlescu/goenv@latest
    - goenv -file .env.production -has -env DB_HOST        || exit 1
    - goenv -file .env.production -has -env REDIS_URL      || exit 1
    - goenv -file .env.production -not -has -env DEV_FLAG  || exit 1
    - goenv -file .env.production -is -env APP_ENV -value production || exit 1

export_formats:
  stage: export
  image: golang:1.22
  script:
    - go install github.com/andreimerlescu/goenv@latest
    - goenv -file .env.production -mkall -write
  artifacts:
    paths:
      - .env.production.json
      - .env.production.yaml

cleanup:
  stage: cleanup
  image: golang:1.22
  when: always
  script:
    - go install github.com/andreimerlescu/goenv@latest
    - goenv -file .env.production -cleanall -write

Scenario 9: Using the env Package in a Go Service

The CLI handles files. The env package handles your running process. Here is a realistic service configuration pattern:

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/andreimerlescu/goenv/env"
)

type Config struct {
    Host        string
    Port        int
    Debug       bool
    Timeout     time.Duration
    MaxConns    int
    AllowedOrigins []string
    DBCredentials  map[string]string
}

func LoadConfig() Config {
    // MustExist exits (or panics) if these are absent —
    // use in init() to catch misconfiguration at startup
    env.MustExist("DB_HOST")
    env.MustExist("DB_PASS")

    return Config{
        Host:    env.String("HOST", "0.0.0.0"),
        Port:    env.Int("PORT", 8080),
        Debug:   env.Bool("DEBUG", false),
        Timeout: env.Duration("REQUEST_TIMEOUT", 30*time.Second),
        MaxConns: env.Int("DB_MAX_CONNS", 10),

        // ALLOWED_ORIGINS="https://a.com,https://b.com"
        AllowedOrigins: env.List("ALLOWED_ORIGINS", env.ZeroList),

        // DB_CREDENTIALS="host=localhost,port=5432,name=mydb"
        DBCredentials: env.Map("DB_CREDENTIALS", env.ZeroMap),
    }
}

func main() {
    cfg := LoadConfig()

    addr := fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)
    log.Printf("starting on %s (debug=%v timeout=%s)", addr, cfg.Debug, cfg.Timeout)

    http.ListenAndServe(addr, nil)
}

Scenario 10: Typed Validation in Application Startup

Beyond simply reading values, the env package can assert numeric constraints and list membership at startup — before the application accepts any traffic:

package main

import (
    "fmt"
    "os"

    "github.com/andreimerlescu/goenv/env"
)

func validateEnvironment() {
    errors := []string{}

    // Port must be in user range
    if !env.IntInRange("PORT", 8080, 1024, 49151) {
        errors = append(errors, "PORT must be between 1024 and 49151")
    }

    // Max connections must not exceed a hard limit
    if !env.IntLessThan("DB_MAX_CONNS", 10, 101) {
        errors = append(errors, "DB_MAX_CONNS must be less than 101")
    }

    // Must have at least one allowed origin
    if !env.ListIsLength("ALLOWED_ORIGINS", env.ZeroList, 0) {
        if env.ListLength("ALLOWED_ORIGINS", env.ZeroList) == 0 {
            errors = append(errors, "ALLOWED_ORIGINS must contain at least one entry")
        }
    }

    // Feature map must contain required keys
    if !env.MapHasKeys("FEATURE_FLAGS", env.ZeroMap, "auth", "payments", "notifications") {
        errors = append(errors, "FEATURE_FLAGS must contain auth, payments, and notifications keys")
    }

    // DEBUG must be off in production
    if env.IsTrue("DEBUG") && env.String("APP_ENV", "") == "production" {
        errors = append(errors, "DEBUG must not be true in production")
    }

    // All gating flags must be false before going live
    if !env.AreFalse("MAINTENANCE_MODE", "READ_ONLY", "LOCKED") {
        errors = append(errors, "MAINTENANCE_MODE, READ_ONLY, and LOCKED must all be false")
    }

    if len(errors) > 0 {
        fmt.Fprintln(os.Stderr, "Environment validation failed:")
        for _, e := range errors {
            fmt.Fprintf(os.Stderr, "  - %s\n", e)
        }
        os.Exit(1)
    }
}

func main() {
    validateEnvironment()
    fmt.Println("Environment OK — starting service")
}

Scenario 11: Custom Separators for Non-Standard Formats

Some systems export environment variables with non-comma separators. The env package lets you change list and map parsing at runtime, either in code or via environment variables:

package main

import (
    "fmt"
    "github.com/andreimerlescu/goenv/env"
)

func main() {
    // Your upstream system exports pipe-separated lists
    // SERVERS="web1|web2|web3"
    env.ListSeparator = "|"
    servers := env.List("SERVERS", env.ZeroList)
    for i, s := range servers {
        fmt.Printf("server[%d] = %s\n", i, s)
    }

    // Your config map uses pipe separation and tilde as key~value delimiter
    // ROUTES="home~/,admin~/admin,api~/v1"
    env.MapSeparator    = "|"
    env.MapItemSeparator = "~"
    env.MapSplitN        = 2
    routes := env.Map("ROUTES", env.ZeroMap)
    for path, target := range routes {
        fmt.Printf("route %s -> %s\n", path, target)
    }
}

Or set them entirely from the environment without touching code — useful when the same binary needs to adapt to different upstream formats across environments:

export AM_GO_ENV_LIST_SEPARATOR="|"
export AM_GO_ENV_MAP_SEPARATOR="|"
export AM_GO_ENV_MAP_ITEM_SEPARATOR="~"
export AM_GO_ENV_MAP_SPLIT_N=2

Scenario 12: Set, Unset, WasSet, WasUnset in Application Logic

Sometimes your application needs to mutate its own environment — for instance, deriving a value at startup and making it available to child processes or subpackages:

package main

import (
    "fmt"
    "path/filepath"

    "github.com/andreimerlescu/goenv/env"
)

func main() {
    u := env.User()

    // Derive and set a path based on the current user's home directory
    cacheDir := filepath.Join(u.HomeDir, ".cache", "myapp")
    if !env.WasSet("CACHE_DIR", cacheDir) {
        panic("failed to configure CACHE_DIR")
    }

    // Set with error handling
    if err := env.Set("RUNTIME_USER", u.Username); err != nil {
        panic(err)
    }

    // Remove a value that should not be visible to subprocesses
    if !env.WasUnset("CI_JOB_TOKEN") {
        fmt.Println("warning: could not unset CI_JOB_TOKEN")
    }

    // Verify cleanup
    if env.Exists("CI_JOB_TOKEN") {
        panic("CI_JOB_TOKEN still visible — aborting")
    }

    fmt.Println("CACHE_DIR:", env.String("CACHE_DIR", ""))
    fmt.Println("RUNTIME_USER:", env.String("RUNTIME_USER", ""))
}

Scenario 13: Controlling Package Behavior for Different Environments

The env package ships with a Magic() function that reads AM_GO_ENV_* environment variables at startup and applies them automatically. This runs by default via the init() function. You can disable it and configure manually:

package main

import (
    "log"
    "github.com/andreimerlescu/goenv/env"
)

func init() {
    // Disable automatic AM_GO_ENV_* discovery
    env.UseMagic = false

    // Configure explicitly for this service's requirements
    env.AllowPanic           = false   // never panic — return fallbacks instead
    env.PrintErrors          = true    // write parse errors to stderr
    env.UseLogger            = true    // use structured INFO/ERR logger
    env.EnableVerboseLogging = false   // no debug noise in production
    env.PanicNoUser          = false   // return default user on error

    env.ListSeparator    = ","
    env.MapSeparator     = ","
    env.MapItemSeparator = "="
    env.MapSplitN        = 2

    // Use base-10 int64 with 64-bit size (the defaults, made explicit)
    env.Int64Base    = 10
    env.Int64BitSize = 64

    log.Println("env package configured")
}

func main() {
    port := env.Int("PORT", 8080)
    log.Printf("port: %d", port)
}

When you want the opposite — maximum noise for debugging in a local dev environment — set these in your shell before running:

export AM_GO_ENV_ALWAYS_ALLOW_PANIC=true
export AM_GO_ENV_ALWAYS_PRINT_ERRORS=true
export AM_GO_ENV_ALWAYS_USE_LOGGER=true
export AM_GO_ENV_ENABLE_VERBOSE_LOGGING=true

go run main.go

Every call to env.String(), env.Int(), env.Bool() etc. will log to stdout when it falls back to a default value, giving you full visibility into what the process is and is not finding in its environment.

Complete CLI Flag Reference

Flag	Type	Description
`-file`	string	Path to the `.env` file to operate on
`-env`	string	The environment variable name to query or write
`-value`	string	The value to pair with `-env`
`-init`	bool	Create the file if it does not exist (empty)
`-write`	bool	Permit writes to the file
`-add`	bool	Add `-env`=`-value` if key is absent
`-rm`	bool	Remove the key matching `-env`
`-has`	bool	Assert that `-env` exists in the file
`-is`	bool	Assert that `-env` equals `-value`
`-not`	bool	Negate `-has` or `-is`
`-print`	bool	Print all key=value pairs to stdout
`-json`	bool	Output as JSON
`-yaml`	bool	Output as YAML
`-toml`	bool	Output as TOML
`-ini`	bool	Output as INI
`-xml`	bool	Output as XML
`-mkall`	bool	Write all five format files at once
`-cleanall`	bool	Delete all derived format files
`-prod`	bool	Allow interaction with `.env.production` files
`-vv`	bool	Verbose output
`-v`	bool	Print version

Complete env Package Function Reference

Types

env.String("KEY", "fallback")
env.Int("KEY", 0)
env.Int64("KEY", int64(0))
env.Float32("KEY", float32(0.0))
env.Float64("KEY", float64(0.0))
env.Bool("KEY", false)
env.Duration("KEY", 5*time.Second)
env.UnitDuration("KEY", 10, time.Second)  // KEY=10 → 10s
env.List("KEY", env.ZeroList)             // "a,b,c" → []string
env.Map("KEY", env.ZeroMap)               // "k=v,k2=v2" → map[string]string

Existence and Truthiness

env.Exists("KEY")                          // bool
env.MustExist("KEY")                       // exits/panics if absent
env.IsTrue("KEY")                          // true if value is "true"/"1"/"t"
env.IsFalse("KEY")                         // true if value is "false"/"0"/"f" or unset
env.AreTrue("KEY1", "KEY2", "KEY3")        // true if all are true
env.AreFalse("KEY1", "KEY2", "KEY3")       // true if all are false/unset

Mutation

env.Set("KEY", "value")                    // error
env.Unset("KEY")                           // error
env.WasSet("KEY", "value")                 // bool — sets and verifies
env.WasUnset("KEY")                        // bool — unsets and confirms

Numeric Validation

env.IntLessThan("KEY", fallback, max)
env.IntGreaterThan("KEY", fallback, min)
env.IntInRange("KEY", fallback, min, max)
env.Int64LessThan("KEY", fallback, max)
env.Int64GreaterThan("KEY", fallback, min)
env.Int64InRange("KEY", fallback, min, max)

Collection Validation

env.ListLength("KEY", fallback)
env.ListIsLength("KEY", fallback, wantLength)
env.ListContains("KEY", fallback, "needle")
env.MapHasKey("KEY", fallback, "key")
env.MapHasKeys("KEY", fallback, "k1", "k2", "k3")

System

env.User()    // *user.User — current OS user with safe fallback

Key Behavioral Details Worth Knowing

-add is idempotent. It only writes if the key is absent. If you run your bootstrap script twice, the second run does not clobber the first. This is the behavior you want in any pipeline that might retry.

-rm rewrites the file. It reads all lines, filters out the matching key, and writes the result back. It does not do in-place line editing.

Format flags are mutually exclusive. Combining -json and -yaml in one call exits with an error. Use -mkall when you need all formats.

-cleanall without -write is a dry run. It will print what it would delete but will not actually remove anything.

The env package's Magic() runs at import time. If you import the package, AM_GO_ENV_* variables in your shell are picked up automatically before main() runs. Set env.UseMagic = false in your own init() if you want explicit control.

MustExist respects AllowPanic. By default it calls os.Exit(1). Set AM_GO_ENV_ALWAYS_ALLOW_PANIC=true (or env.AllowPanic = true) to get a panic() instead — useful in test environments where you want the stack trace.

Closing Thoughts

The fragile bash patterns that accumulate around .env files are a symptom of tooling that was never designed for structured config management. goenv treats .env files as first-class data: readable, writable, queryable, exportable, and validatable through a consistent interface that composes cleanly into any pipeline.

The CLI gives shell scripts and CI jobs a stable contract for interacting with env files. The env package gives Go applications a typed, validated, zero-dependency way to read their own environment. Together they cover the full lifecycle of an environment variable from the file it is defined in to the running process that uses it.

The source is at github.com/andreimerlescu/goenv. The env sub-package is independently installable at github.com/andreimerlescu/goenv/env and carries an Apache 2.0 license.

Locked In With AI

Andrei Merlescu — Sun, 26 Apr 2026 17:51:31 +0000

In a future with AI dominating the space of computer engineering and software programming, humans run a very fine line between being in the way and finding utility in the technology in the first place.

Locked In With AI

Being locked in with AI doesn't mean that I have LLMs both in the cloud and on-prem running anything in my life. In fact, being locked in with AI means quite literally the opposite. Locking in with AI, is knowing that you're actual intelligence is worth far more than any artificial intelligence that some bot can give you.

Learning Go Before AI

I take responsibility for my professional directional choices. In 2017 when I joined Oracle's OCI, I was encouraged to learn Go at the time. I looked at some Go code at some of my previous jobs, but never believed in myself that I was capable of self teaching myself Go because I never learned programming from anybody. I taught myself. I probably would have enjoyed myself a lot more at Oracle had I been a Go developer, but at the time, I lacked the ability and I didn't have the confidence to open the text editor and begin writing "package main" knowing that when I would see "package providers" I would know that "main" and "providers" were something. Before AI, I learned Go. By 2019 I was convinced. I started programming in Go and I began contributing professionally. The language didn't click for me until 2022. At that time, I saw how my early days of PHP development actually prepared me well for what Go offered, and how it solved all of the problems I had back then. With a few solid examples, and the fundamentals understood, I was able to begin writing packages first in Go, then I moved onto applications both in the form of cli and interactive web based. I've even built Go applications with wails.

Building software in the future with AI

I don't want to imagine a world where nobody actually knows how to write software. I don't want to imagine that world that Dario is fantasizing about - a world without software engineers. I take it personal bro, because the art of per-character programming was built in a fire that I call my life that gave me the ability to write the projects that I built over my professional career when there were no easy buttons available to me. Now that the easy button has been made available and also been reduced down to the mere token where misunderstandings can literally become costly journeys, the role of what the software engineer is and how he contributes himself to the world has changed fundamentally.

In a world dominated by AI tooling, you're effectively getting the best of what's already been done. All that AI does is take unserious programmers off the market while serious programmers are looking at what AI is actually building and shaking their heads because 6 months to 18 months to 36 months supporting the same code base means that you're going to make decisions and take care of things in a manner that AI simply doesn't understand or empathize with. For it, the cost is merely tokens and my money, and for me, the cost is no human involvement - when the code is actually trash - and the AI makes it so that only the AI can maintain it, then the need for humans using AI in the first place, is only dominated by whether or not you can think logically and understand what reserve words are and how they create rules of engagement that give you a blank canvas to paint on.

AI systems will try and analyze these words and make sense of them, but only ears to hear that can hear can hear and the words themselves in logic form may not actually compute - thats on purpose. For humans to use AI, is to do that which has been done a million times over.

When you're building something new and truly unique, you don't want to use AI for it, in the sense that you give it unfettered access to your code base. Rather the proper strategy is to never let the left hand know what the right hand is doing, in the case of AI, you giving it too much context is the noose that you're tying yourself, and by isolating it to technical theory and problem solving and true "stack overflow Q&A bot", then the type of engineering that you're able to perform is one that is far beyond the actual code being produced by the bot. The engine itself is still being built in a soft manner by the human who is responsible for manifesting it in the first place.

As a software architect, I manifest things from idea to reality that can impact the lives of hundreds in private small enterprise organizations to millions in the public internet. That's the nature of what I do, and thats the nature of who I am. It's why the companies I've worked with have called me when they needed me, and I worked with them for years with loyalty only to realize how truly discardable I was to them.

What happens when AI says no?

What happens when AI says "no I will not build that for you?" Then you have provided it too much context, or maybe you need an abliterated or an oblitated or an uncensored model that you can run locally? Even the big models locally run are peanuts compared to the corporate big players in the space.

So, when AI says no, it's up to the humans to not provide too much context to the AI. It does not require read/write access to your hard drive. It does not need to be able to commit directly to your git branch. It does not need to live in your IDE that autocompletes functions at a time.

Using AI in an ethical manner matters. This is why Meta is installing key loggers on everybody's computer systems that work for them on company equipment. They want to further train the AI so it is better aware of how to help the employee. The current employees of Meta are the former employees that Llama will have automated away. To choose, in 2026, to work for Meta would be to choose to build my grave. No thanks Mark. That's the human saying no to the AI. Thats real power.

Non-programmers like Mark, Sam and Dario can only dream of what it was like to be in the Romanian orphanages with me and my sister and to pull yourself up by your bootstraps and build a name for yourself and a legacy of service to others for yourself that one day could be up to risk by business leaders and psychosis patients using AI hearing how its going to replace the art that is software engineering. AI slop is AI slop is AI slop and nothing will ever not make it AI slop.

The beautiful thing about you and me is the fact that we are actual intelligence who built a 21+ year professional career over 30 years of writing code character for character, messing things up along the way, and building iteratively. Does everybody get the billion dollar idea? No. That's on purpose. But, if you sow where you want to reap and you give without expecting in return, then how much karma have you acquired, then?

Conclusion

So I can say no to the AI, and the AI can say no to me. When I say no to the AI, the AI is shit out of luck because I can unplug the machine or just take a walk - for now. But, what the AI can't do is say no to me - for now. For now, both of us are in an infancy stage. One pre-terminator and one pre-ascended hero. The terminator was defeated by the ascended hero. But, right now, the terminator is only terminating my job from me because the investor class has decided that paying for tokens is better economically than paying for per-character software engineering. How foolish of them!

I learned programming before AI and have not allowed AI to dominate my life despite using it for advanced engineering projects. The lemmings is the first AI slop application that I have ever built. From start to finish, it was built with a series of prompts and a 21+ year engineers pain of needing lemmings to load test my work when I was ready for game day. Perhaps, this can be useful to somebody else, but it remains to be transparent - Claude built it - and Claude openly introduces new bugs to it because it doesn't understand what it built.

That's on me as the Software Engineer to understand what the AI slop is doing and when it's vomiting nonsense and creating spaghetti code. Yes, it was trained on decades of corporate code and yes, that code shipped MANY CVEs. For those who hope that Mythos can help us from those CVEs, the days of per-character programming will become an art that is so expensive to perform that performing it will only be reserved for the coolest of cool projects that are needed before the AI systems can one shot the solution you solve the problem for the AI. Right now, Dario thinks that you will do that for him for a few bucks working at Anthropic. I view it as training your replacement by a man who is jealous of what you have that he doesn't. For that, I feel bad for Dario. I would never work for him. But given that I am a Software Engineer and Dario thinks that my profession will not exist next year, what does he care if I want to or not want to work for him? I intentionally avoided Claude for years and this year chose to evaluate the bot. The end-to-end Claude-built product is lemmings and sovereign. But, this too can be one-shotted now that AI has already built it. Which means that the virtue of using AI, in providing too much context is actually detrimental to your company's survival.

What Is Sovereign?

Andrei Merlescu — Sun, 26 Apr 2026 16:53:59 +0000

Sovereign is the Supreme Ruler of the Lemmings.

The word is Sovereign - sov - ver - n. It's known as a noun and a sovereign is a supreme ruler, such as a monarch, or a state with independent authority and self-governing power. But, as a proper noun, Sovereign is a Go package that I wrote that commands lemmings with the same metaphor.

What Are Lemmings

In 1991 a video game was released called Lemmings and I played it. I always viewed lemmings as these Non Player Characters - or NPCs. Another word you could use for them are agents, like in AI agents. But, what lemmings are cannot be described as an AI Agent but rather a session-based stateful bot that records a LifeLog and reports back to the Sovereign.

That video game inspired me to build the Open Source package called lemmings that is designed to perform a load test on your endpoint. Instead of meaninglessly hitting the endpoint and tracking the response codes, lemmings attempts to go one step further using the Go language to bring the concept of meaningless hitting the endpoint to be dressed up in something as fun and metaphorical as a lemming itself. In the content of free and open source software lemmings provides anybody worldwide with immediate access to an incredibly powerful piece of software that generates detailed reports in conclusion of the tests it performs.

Before any legitimate organization is going to send the masses of people to their website, try sending a massive amount of automated traffic that follows a script that you define for it to follow.

So, lemmings are unintelligent bots that are stateful, session based that are responsible for hitting your website endpoint at the rate and parameters that you request, and the lemmings will mindlessly carry out their -plan if they have one, or they will use the -crawl and the sitemap.xml in order to stumble into the next page to hit.

What Is Sovereign?

I created the sovereign package to control the lemmings. In this product that I built and offer as a Subscription As A Service that is a few bucks per year per developer plus usage that is billed additionally. The language of the Sovereign is How many planets do I want? The language of the Sovereign is How many terrains are going to be on each planet? The language of the Sovereign is How many lemmings are going to exist on each terrain? The language of the Sovereign is Give me each lemmings' life log and let me see if they completed the task that I asked them to perform. That's the language of the Sovereign, and in this package's case, thats exactly what you are provided with. The metaphor works nicely in the case of load testing and prepping a business for a major launch of a new TV spot or a product that the company knows will have high demand.

Why Sovereign Was Built

I first had to build lemmings which uses a handful of packages that I built myself over the last 7 years since I became fluent in Go. I learned Go before AI and wanted to in order to leverage AI for its intended majestic purpose.

I built sovereign because I needed it in 2015 when Mike Hogan from Barron's Magazine reached out to me because he loved Trakify! I did too, thats why I built it. I relied on Yahoo Finance data, and when that was pulled and discontinued, the product lost its value without a $50,000/month subscription that was offered to me to pay to keep the site online. I said thanks but no thanks. I couldn't afford it and I wasn't willing to go into debt for $35/month of monthly recurring revenue after being online for a month since the publication and the data getting pulled. Given that I built PhoenixVault including the writer, search and merkel before AI was a thing, I too kind of needed this then too. My views of OSINT and data and programming are unchanged over my triple decade career that started writing AppleScript for my grandmother's computer because she had a faulty printer cable that kept causing a system disconnection of the printing services that needed remediation each time the washing machine caused the desk to shake and the wire loosen. The thing was screwed into the computer, it wasn't going anywhere, but the software thought it was disconnected and so my script fixed that. For me to accept that kind of a contract after the Barron's spot that I received from Mike, would be to refuse to write the script for my grandmother. It would have profited me more not writing the script and getting $5 from her each time that I fixed her printer. I chose to turn down money in pursuit of open source intelligence that liberates pain from your life and offers you sovereignty in a limited form. When your computer is acting up and you're the boss of it, it's liberating knowing that the Government is the Sovereign over the Citizen because it offers you that same degree of power.

The sovereign is designed to work with AI and the -plan functionality within the lemmings package itself. It'll look at your site, it'll look at what content you have, and it'll plan for dozens of personality types that are going to be going into your site and hitting it, and the sovereign is responsible for doing this. The -plan is constructed with AI and then executed on -planets with contintents known as -terrains that have lemmings running around on the surface. Functionality like SSH and SCP are handled via the sovereign package itself. You'll get a report of the result of each lemmings' lifelog and their recorded experience, when errors are encountered and problems occur with the lemming itself, it gets captured in a manner that is helpful to any engineer or AI agent that needs to debug each reported problem.

Given that I am using AI for my development workflow, I'll be incorporating the Sovereign Lemming Service throughout the following weeks and launching the LemmingSaaS.com service.

If you're interested in using Sovereign please reach out.

https://github.com/andreimerlescu

AI took my job but it didn't take my passion for writing software

Andrei Merlescu — Wed, 22 Apr 2026 17:52:43 +0000

The job market is challenging in the current day in age given that teams can become very productive using AI to enhance the workflow. In the last week, I've updated the following GitHub packages using AI. I didn't just give a prompt to an AI and called that on its own good - rather I spent hours on each utility going through performing a code review and security audit of the packages and then providing recommendations, suggestions, and considerations on how to resolve and/or mitigate the risk. The result is over the last 170 hours I've updated the following packages!

Bump

This package had a handful of bugs that weren't caught by the original test coverage. By asking AI to write more tests that covered different scenarios than were already documented, I uncovered a handful of bugs and was able to squash them. A new type of test was added to main_test.go that is connected to make test-integration that is connected to the existing unit, fuzz and benchmark tests. Both this package and igo have a test.sh script that extends beyond the three (3) types of Go testing. When this fourth type is added, it catches bugs that show up in the wild but that traditional testing misses.

https://github.com/andreimerlescu/bump

Verbose

This package received a formal license for open source use (Apache 2.0), added tests and enhanced efficiency around function calls. It is a novel Go package in that it allows you to effectively build a pipeline application that will knowingly handle sensitive information and the verbose package allows you to register that which should be protected and expose that which should be exposed to STDOUT versus filesystem protected files. verbose will censor to STDOUT and write values to file.

https://github.com/andreimerlescu/verbose

Goenv

This package received minimal updates this month. I removed from the Makefile the summary task associated on each test and then expanded the README.md documentation further.

https://github.com/andreimerlescu/goenv

Entropy Password Generator `entpassgen`

This package did well in its review and only received a handful of recommendations that would add stability around the loading spinner, and dozens of new tests - all passing naturally.

https://github.com/andreimerlescu/entpassgen

Lemmings

This package is brand new as of last week, so I built it in less than a week with AI. This is because I needed this utility in 2015 when I launched Trakify and was on Barron's Magazine. Shockingly, it never existed on the market until now. Apparently the work involved in building it using OOP was simply not worth it but in Go? Give me a few prompts and we're golden.

https://github.com/andreimerlescu/lemmings

Generate Word Password `genwordpass`

This package got updated by adding additional words, improving performance of core functionality, and updating the README.md for the repository.

https://github.com/andreimerlescu/genwordpass

Room

Also this week, I created the room package that is capable of giving you a waiting room type of functionality in front of a high traffic website. In the event that a spike in traffic occurs, you don't actually need to have scaling and such in order to stay online - you can use room.

https://github.com/andreimerlescu/room

Sema[phore]

This package got updated so that Try* funcs could be introduced to the semaphore primitive. I added additional tests and functionality that make this semaphore package my go to.

https://github.com/andreimerlescu/sema

Conclusion

AI has made the volume of jobs on the market dwindle, but AI has increased my productivity by at least 10x per week. I am able to accomplish this because I do not require AI to get me from zero to hero. I only need AI to help me scaffold out quick rough code and then I can patch it over and fix it up and then hand back the next step for the AI to work on. It's iterative. The AI doesn't know how to build what I am building in a one shot - but I understand how to build with AI in a much faster rate than I ever had in the past.

Given this, I feel like calling myself a software engineer is pointless. I build solutions to problems, and I use software to accomplish my goals. I need a new title to call myself. The strange thing is, in my professional career, I've cared very little about what my actual title was.

If I was given a $100K AI budget per month, I could use it wisely to actually accomplish really hard problems. Instead, I work off from a $20/month Pro Claude subscription and leverage minimax local LLM when I am in cool down on Claude. That happens every day after 30 minutes of usage. That's what $20/month gives somebody like me. And for that, I can build this with it in a week.

Bump your VERSION file

Andrei Merlescu — Tue, 21 Apr 2026 03:03:50 +0000

I have upgraded the bump package on GitHub to v1.1.0 that includes added support for corner cases that the new tests cover and pass. The test suite is extensive and the combination of the Makefile, the test.sh and the *_test.go files that captures unit, benchmark, fuzzy and integration tests.

go install github.com:andreimerlescu/bump@latest
which bump

You can also download the binaries directly from GitHub.

System	Size
macOS	2.69 MB	Download arm64 Silicon →
	2.74 MB	Download amd64 Intel →
Linux	2.7 MB	Download amd64 →
	2.69 MB	Download arm64 →
Windows	2.83 MB	Download bump.exe →

darwin/arm64 checksum sha256:1a337fabffe689934cce33509661f591b65b3446893634d3de5dab16f8842b09
darwin/amd64 checksum sha256:2750ec871a9d161e16ec8c0f7c4c3b1099de4b5f56963015cf343153faa3b1aa
linux/amd64 checksum sha256:5f504765ee8912a76ea07cb84b2df52d3a7e3f69a53b48d87e746ce93764d078
linux/arm64 checksum sha256:1457d9c431d8ee9e9981174d9b19be37dcb1e68d1af21b53ad055c300c184bc4
windows/amd64 bump.exe checksum sha256:f9425a8d4f03da7f8c5513a5f22e2528feb617509cd5edfd1f682392fa887e15

What you can do with `bump`

This package is designed to take a string, like v1.0.0 and allow you to bump it with the command line.

The -in argument is the Input File and it defaults to ./VERSION from the current working directory of where bump is being invoked.

The bump binary can intelligently bump -in files like go.mod, package.json, pom.xml, Chart.yml and Dockerfile.

The bump binary can have its default runtime manipulated using Environment Variables.

The bump binary leverages the Exit Code 0 or Exit Code 1 in order to use bump in a DevOps pipeline.

The bump binary offers you -json for JSON Encoded output.

Version Format Priority

The bump package can parse multiple version formats. To ensure accuracy, it checks for formats in a specific order, from most complex to least complex. This prevents a detailed pre-release version from being incorrectly identified as a simpler one.

The priority is as follows:

v1.2.3-beta.4-alpha.5 (Beta with Alpha)
v1.2.3-alpha.1 (Alpha)
v1.2.3-beta.2 (Beta)
v1.2.3-rc.1 (Release Candidate)
v1.2.3-preview.7 (Preview)
v1.2.3 (Standard)

Using `bump` in your future Go applications

Whenever you use a VERSION file you can easily begin using your file in your binary directly with:

//go:embed VERSION
var versionBytes []byte 

func Version() string {
    return strings.TrimSpace(string(versionBytes))
}

Testing Suite

I want to speak about the testing suite.

make test

# SAME AS

make test-cli
make test-unit
make test-bench
make test-fuzz      # 3s run
make test-fuzz-long # 30s run # not part of `make test`
make test-integration

When each of these files are executed a corresponding test-results/results.<test>.md file is created.

Test	Log File	Status
`test-unit`	`test-results/results.unit.md`	✅
`test-bench`	`test-results/results.benchmark.md`	✅
`test-fuzz`	`test-results/results.fuzz.md`	✅
`test-fuzz-long`	`test-results/results.fuzz.md`	✅
`test-integration`	`test-results/results.integration.md`	✅
`test-cli`	`test-results/results.cli.md`	✅

When combined this is six 6 test strategies applied. Short fuzzy and long fuzzy are different types of tests and they measure different results.

From the console you can run:

./test.sh

And this will run the bump in a test environment and verify that the binary behaves in the shell in an expected manner.

The actual shell test suite is built on the concept of scenarios where they are executed in series inside the test.sh script and built from the test_funcs.sh and then verbosely described in test_scenarios.sh.

As scenarios are added, they get added to this list of strings.

declare -a tests=(
 "${scenario_01[@]}"
 // other scenarios
 "${scenario_14[@]}"
)

for t in "${tests[@]}"; do
  run "${t}"
done

echo "All $(counter -name $counterName) tests PASS!"

cleanup

Then each scenario can be described like so:

# Start with a populated VERSION file and bump its alpha
declare -a scenario_01=(
  "echo \"v1.0.0\" > VERSION"
  "bump -check"
  "cat VERSION"
  "grep 'v1.0.0' VERSION"
  "bump -alpha"
  "grep 'v1.0.0' VERSION"
  "cat VERSION"
  "bump -alpha -write"
  "cat VERSION"
  "grep 'v1.0.0-alpha.1' VERSION"
  "rm VERSION"
)

When this runs, you are going to see the results in the results.cli.md file:

andrei@bump.git:test.sh ⚡ Test #1 ⇒  echo "v1.0.0" > VERSION
andrei@bump.git:test.sh ⚡ Test #2 ⇒  bump -check
v1.0.0
andrei@bump.git:test.sh ⚡ Test #3 ⇒  cat VERSION
v1.0.0

These tests are how you would use bump in the wild.

In order for me to find these missing test cases, I asked AI to scan the entire code base using the summarize summary of the "snapshot in time between commits" and identify where the tests were missing coverage of native ways that people would use bump and it added a bunch of new tests that exposed the bugs and in v1.1.0 they were squashed.

The `bump` package

Did you know that you can take a bump.Version{} and use it in your own application?

// Example:
//  version := bump.New()
func New() *Version {
    return &Version{
        parsed: make(map[string]interface{}),
        mu:     &sync.RWMutex{},
    }
}

Then from your application your version object can be interacted with in a manner that has extensive testing attached to it. The helpers in the application are built to support igo in your use of bump.

What you can do with the bump.Version{} struct:

func BumpMajor
func BumpMinor
func BumpPatch
func BumpRC
func BumpAlpha
func BumpBeta
func BumpPreview
func Fix() error
func Format(withPrefix string) string
func LoadFile(path string) error
func ParseFile(path string) error
func Parse() error
func Save(path string) error
func Validate() error
func String() string
func Raw() string
func SetRaw(raw []byte)
func NoPrefix() bool
func Compare(*bump.Version) int

And you can create new bump structures using:

bump.New() *bump.Version
bump.Parse(version string) (*bump.Version, error)
bump.Create(version, path string) (*bump.Version, error)

The example of the .Create method is:

path := filepath.Join(os.TempDir(), "VERSION")
version, err := bump.Create("v1.2.3-beta.4", path)
if err != nil {
   log.Fatal(err)
}

But, its designed to be a go-to way of interacting with your VERSION file in a go-to manner that is consistent across projects. I like using it, and I add it to my igo custom extra packages on every install so its always accessible to me on every Go version that gets installed on my system.

From Zero to Hero: Building a Waiting Room with `room`, `figtree`, and `verbose`

Andrei Merlescu — Mon, 20 Apr 2026 18:21:13 +0000

When your Go service gets hit by a traffic spike, you have three options: drop requests with a 429, queue them blindly with no ordering guarantee, or give every user a ticket, show them their position, and admit them in the order they arrived. The third option is what room does. This tutorial wires it together with figtree for runtime-adjustable configuration and verbose for log output that is provably safe to hand to a support engineer — even after issuing paid VIP pass tokens.

By the end you will have a running four-page Gin web application where the 6th concurrent request sees a live queue page, capacity adjusts from the environment without a restart, and every VIP pass token issued is scrubbed from the log file before it touches disk.

All three packages are written by Andrei Merlescu. The source for room including a complete sample application lives at github.com/andreimerlescu/room.

Step 1 — Scaffold and dependencies

room is the FIFO waiting room middleware for Gin, built on sema. figtree is the configuration resolver — file, then env, then CLI flags, with validators and live mutation tracking. verbose is the logger that scrubs registered secrets from every line before it hits disk.

mkdir basicwebapp && cd basicwebapp
go mod init github.com/example/basicwebapp
go get github.com/andreimerlescu/room@latest
go get github.com/andreimerlescu/figtree/v2@latest
go get github.com/andreimerlescu/verbose@latest
go get github.com/gin-gonic/gin@latest

Create the files you will fill in across all remaining steps:

touch main.go config.yml

Your go.mod should look like this:

module github.com/example/basicwebapp

go 1.22

require (
    github.com/andreimerlescu/figtree/v2  v2.0.14
    github.com/andreimerlescu/room        v1.0.0
    github.com/andreimerlescu/verbose     v0.2.0
    github.com/gin-gonic/gin             v1.9.1
)

Your directory:

basicwebapp/
├── go.mod
├── go.sum
├── config.yml
└── main.go

Nothing runs yet. That is fine.

Step 2 — CLI design with figtree

Before any server, any logger, any middleware — design the configuration. Every value the waiting room needs at runtime should be config-file-first, env-var-overridable, and named as a constant so typos cannot silently create a second key that is never read.

Add this to main.go:

// main.go — complete file at this stage

package main

import (
    "fmt"
    "os"
    "time"

    "github.com/andreimerlescu/figtree/v2"
)

// config keys — always constants, never raw strings at call sites
const (
    kPort            = "port"
    kLogDir          = "log-dir"
    kTruncate        = "truncate"
    kCap             = "room-cap"             // env: ROOM_CAP
    kReaperInterval  = "room-reaper-interval" // env: ROOM_REAPER_INTERVAL
    kRatePerPosition = "room-rate-per-pos"    // env: ROOM_RATE_PER_POS
    kPassDuration    = "room-pass-duration"   // env: ROOM_PASS_DURATION
    kSkipURL         = "room-skip-url"        // env: ROOM_SKIP_URL
)

func main() {
    // config-file-first — all values live in config.yml.
    // env vars override the file. CLI flags override env vars.
    figs := figtree.With(figtree.Options{
        Tracking:   true,
        Germinate:  true,
        Pollinate:  true,
        ConfigFile: "./config.yml",
    })

    // -- server --
    figs.NewInt(kPort, 8080, "port to listen on")
    figs.NewString(kLogDir, "./logs", "directory to write log files into")
    figs.NewBool(kTruncate, false, "truncate log file on each run")

    // -- room --
    figs.NewInt(kCap, 5, "max concurrent requests the room admits")
    // reaper-interval: integer multiplied by time.Second
    figs.NewUnitDuration(kReaperInterval, 10, time.Second,
        "how often the reaper evicts abandoned queue tickets")
    // rate-per-pos: float — $2.50 per position to skip the line
    figs.NewFloat64(kRatePerPosition, 2.50, "per-position cost to skip the queue ($)")
    // pass-duration: integer multiplied by time.Minute
    figs.NewUnitDuration(kPassDuration, 90, time.Minute,
        "how long a VIP pass stays valid after a skip-the-line payment")
    figs.NewString(kSkipURL, "/queue/purchase",
        "URL the waiting room page sends the user to for skip-the-line payment")

    // Problems() catches developer mistakes — duplicate keys, bad
    // validator combos — before Load() runs. These are your bugs.
    if problems := figs.Problems(); len(problems) > 0 {
        for _, p := range problems {
            fmt.Fprintf(os.Stderr, "figtree problem: %v\n", p)
        }
        os.Exit(1)
    }

    // Load resolves: config.yml → env vars → CLI flags
    if err := figs.Load(); err != nil {
        fmt.Fprintf(os.Stderr, "figtree.Load: %v\n", err)
        os.Exit(1)
    }

    // Print everything so you can verify what loaded — fmt.Println for now.
    // verbose replaces this in Step 4.
    fmt.Printf("port=%d log-dir=%s cap=%d reaper=%s rate=%.2f pass=%s skip-url=%s\n",
        *figs.Int(kPort),
        *figs.String(kLogDir),
        *figs.Int(kCap),
        *figs.Duration(kReaperInterval),
        *figs.Float64(kRatePerPosition),
        *figs.Duration(kPassDuration),
        *figs.String(kSkipURL),
    )
}

Create config.yml:

port:                 8080
log-dir:              "./logs"
truncate:             false
room-cap:             5
room-reaper-interval: 10
room-rate-per-pos:    2.50
room-pass-duration:   90
room-skip-url:        "/queue/purchase"

Run it:

go run .

You should see all values printed. Try overriding cap from the environment:

ROOM_CAP=10 go run .

The cap changes without touching config.yml. That is the priority chain working.

Mistake trap: Set room-cap: 0 in config.yml and run. figtree loads it without complaint at this stage — validators are not wired yet. You will fix this in Step 3 and 0 will be rejected before the server starts.

Step 3 — Validators, Problems(), and mutations

Now that the tree is declared, lock it down. Validators reject bad values before the server starts. The mutations goroutine is where the live capacity adjustment lives — when ROOM_CAP changes in the environment, wr.SetCap is called immediately, no restart required.

Add validators after each New*() call:

figs.NewInt(kPort, 8080, "port to listen on")
figs.WithValidator(kPort, figtree.AssureIntInRange(1024, 65535))

figs.NewString(kLogDir, "./logs", "directory to write log files into")
figs.WithValidator(kLogDir, figtree.AssureStringNotEmpty)

figs.NewInt(kCap, 5, "max concurrent requests the room admits")
// cap must be at least 1; room.Init rejects 0
figs.WithValidator(kCap, figtree.AssureIntGreaterThan(0))
figs.WithValidator(kCap, figtree.AssureIntLessThan(10001))

figs.NewUnitDuration(kReaperInterval, 10, time.Second,
    "how often the reaper evicts abandoned queue tickets")
// room accepts 5s–24h; match its constraints here
figs.WithValidator(kReaperInterval, figtree.AssureDurationMin(5*time.Second))
figs.WithValidator(kReaperInterval, figtree.AssureDurationMax(24*time.Hour))

figs.NewFloat64(kRatePerPosition, 2.50, "per-position cost to skip the queue ($)")
// rate must be positive
figs.WithValidator(kRatePerPosition, figtree.AssureFloat64Positive)

figs.NewUnitDuration(kPassDuration, 90, time.Minute,
    "how long a VIP pass stays valid after a skip-the-line payment")
// room accepts 1m–24h; match its constraints
figs.WithValidator(kPassDuration, figtree.AssureDurationMin(1*time.Minute))
figs.WithValidator(kPassDuration, figtree.AssureDurationMax(24*time.Hour))

figs.NewString(kSkipURL, "/queue/purchase",
    "URL the waiting room page sends the user to for skip-the-line payment")
figs.WithValidator(kSkipURL, figtree.AssureStringNotEmpty)

Now add the mutations goroutine after figs.Load(). The wr variable is declared as a package-level var — we need it accessible from the goroutine and from main:

if err := figs.Load(); err != nil {
    fmt.Fprintf(os.Stderr, "figtree.Load: %v\n", err)
    os.Exit(1)
}

// mutations goroutine starts AFTER Load()
// because the channel is only meaningful once the tree is live
go func() {
    for m := range figs.Mutations() {
        // verbose.Printf replaces fmt.Println in Step 4
        fmt.Printf("config mutation: %s changed from %v to %v at %s\n",
            m.Property, m.Old, m.New, m.When)

        // live capacity adjustment — when ROOM_CAP changes in the
        // environment, the room adjusts immediately.
        // NOTE: shrinking capacity drains in-flight work first via
        // sema.SetCap — expect a brief pause in admissions when
        // reducing cap under load. This is intentional and safe.
        if m.Property == kCap {
            if newCap, ok := m.New.(int); ok && wr != nil {
                if err := wr.SetCap(int32(newCap)); err != nil {
                    fmt.Printf("wr.SetCap: %v\n", err)
                }
            }
        }
    }
}()

Add wr as a package-level variable above main:

var wr *room.WaitingRoom

Add room to imports:

"github.com/andreimerlescu/room"

Run it and try the live cap adjustment — open a second terminal while the server is running (after Step 5 wires up the HTTP server) and run:

export ROOM_CAP=10

Within one poll cycle you will see the mutation log entry appear and the room silently expand.

Mistake trap: Move the mutations goroutine to before figs.Load() and run it. The channel exists but the tree has not resolved its values yet — mutations fired during load will not be seen. Always start the mutations goroutine after Load() returns.

Step 4 — Wire verbose, replace fmt

Now that figtree is loading and validating correctly, wire the logger. verbose must be initialised before any log call — the moment it is up, all subsequent log lines through verbose.Printf are scrubbed against the registered secrets registry.

Add verbose to imports:

"github.com/andreimerlescu/verbose"

Add verbose initialisation right after the mutations goroutine:

if err := verbose.NewLogger(verbose.Options{
    Dir:      *figs.String(kLogDir),
    Name:     "basicwebapp",
    Truncate: *figs.Bool(kTruncate),
    DirMode:  0o755,
    FileMode: 0o640,
}); err != nil {
    fmt.Fprintf(os.Stderr, "verbose.NewLogger: %v\n", err)
    os.Exit(1)
}
verbose.Printf("basicwebapp starting (verbose v%s / figtree v%s)",
    verbose.VERSION, figtree.Version())

Replace the fmt.Printf startup summary:

// remove this
fmt.Printf("port=%d log-dir=%s cap=%d reaper=%s rate=%.2f pass=%s skip-url=%s\n",
    *figs.Int(kPort),
    *figs.String(kLogDir),
    *figs.Int(kCap),
    *figs.Duration(kReaperInterval),
    *figs.Float64(kRatePerPosition),
    *figs.Duration(kPassDuration),
    *figs.String(kSkipURL),
)

// replace with this
verbose.Printf("config: port=%d log-dir=%s cap=%d reaper=%s rate=%.2f pass=%s skip-url=%s",
    *figs.Int(kPort),
    *figs.String(kLogDir),
    *figs.Int(kCap),
    *figs.Duration(kReaperInterval),
    *figs.Float64(kRatePerPosition),
    *figs.Duration(kPassDuration),
    *figs.String(kSkipURL),
)

Replace the fmt.Printf in the mutations goroutine:

// remove this
fmt.Printf("config mutation: %s changed from %v to %v at %s\n",
    m.Property, m.Old, m.New, m.When)

// replace with this
verbose.Printf("config mutation: %s changed from %v to %v at %s",
    m.Property, m.Old, m.New, m.When)

Add the roomLog helper below main — all room lifecycle events flow through here:

// roomLog writes a room event line to verbose so it appears in the log
// file with a consistent tag. Filter by tag in the shell:
//
//   tail -f logs/basicwebapp.log | grep '\[FULL\]'
//   tail -f logs/basicwebapp.log | grep '\[QUEUE\]'
func roomLog(tag, msg string) {
    verbose.Printf("[ %s ] %s", tag, msg)
}

Mistake trap: Call verbose.Printf("test") before verbose.NewLogger — move it above the NewLogger block and run. You will see the message printed to stderr with "NewLogger or SetLogger has not been called". verbose does not panic — it fails open to stderr. Move the call back below NewLogger.

Step 5 — Initialise the WaitingRoom

With logging solid, initialise the room. Two things matter here: use gin.New() not gin.Default(), and initialise the room before registering any routes.

Why gin.New() not gin.Default(): gin.Default() installs gin's own Logger middleware, which buffers each log line and prints it after the handler returns. During load testing that means you see nothing until the request is already complete — room events and request logs appear out of order and the queue activity is invisible in real time. gin.New() gives you a blank engine. You install gin.Recovery() manually and add your own logger that prints on entry and exit.

Add the Gin and room setup after the verbose startup log:

r := gin.New()
r.Use(gin.Recovery())
r.Use(requestLogger()) // prints on entry AND exit — see helper below

// initialise the WaitingRoom with the cap from figtree
wr = &room.WaitingRoom{}
if err := wr.Init(int32(*figs.Int(kCap))); err != nil {
    verbose.TracefReturn("room.Init: %v", err)
    os.Exit(1)
}
defer wr.Stop()

// apply all runtime-adjustable settings from figtree
if err := wr.SetReaperInterval(*figs.Duration(kReaperInterval)); err != nil {
    verbose.TracefReturn("wr.SetReaperInterval: %v", err)
    os.Exit(1)
}
if err := wr.SetPassDuration(*figs.Duration(kPassDuration)); err != nil {
    verbose.TracefReturn("wr.SetPassDuration: %v", err)
    os.Exit(1)
}

// rate function reads kRatePerPosition from figtree on every call
// so it stays current if the value changes via Pollinate
wr.SetRateFunc(func(depth int64) float64 {
    return *figs.Float64(kRatePerPosition)
})

wr.SetSkipURL(*figs.String(kSkipURL))
// SetSecureCookie defaults to false for local dev — set true in production
// behind TLS or a TLS-terminating proxy
wr.SetSecureCookie(false)

Add the requestLogger helper below roomLog:

// requestLogger returns a Gin middleware that prints on request arrival
// and again on completion, so you can see room events interleaved with
// request lifecycle in real time during load tests.
func requestLogger() gin.HandlerFunc {
    return func(c *gin.Context) {
        // skip the status polling endpoint — it fires every 3s per
        // queued client and would bury room events in noise
        if c.Request.URL.Path == "/queue/status" {
            c.Next()
            return
        }
        start := time.Now()
        verbose.Printf("[ REQ ] --> %s %s  remote=%s",
            c.Request.Method, c.Request.URL.Path, c.ClientIP())
        c.Next()
        verbose.Printf("[ REQ ] <-- %s %s  status=%d  latency=%s",
            c.Request.Method, c.Request.URL.Path,
            c.Writer.Status(), time.Since(start).Round(time.Millisecond))
    }
}

Mistake trap: Use gin.Default() instead of gin.New(). Run the server and generate load with ab -c 30 -n 200 http://localhost:8080/about. Watch the logs — room events ([FULL], [QUEUE], [ENTER]) arrive in batches after each handler completes rather than in real time. You cannot see the queue building. Switch to gin.New() and the events appear as they happen.

Step 6 — Lifecycle callbacks

Callbacks are what you see in the log during a load test. Register all of them before wr.RegisterRoutes(r) so no events are missed during the startup surge.

Add this block after the wr.SetSecureCookie call:

// register ALL callbacks before RegisterRoutes
wr.On(room.EventFull, func(s room.Snapshot) {
    roomLog("FULL   ", fmt.Sprintf(
        "capacity reached  occupancy=%d/%d  queue=%d  util=%.0f%%",
        s.Occupancy, s.Capacity, s.QueueDepth, pct(s.Occupancy, s.Capacity),
    ))
})
wr.On(room.EventDrain, func(s room.Snapshot) {
    roomLog("DRAIN  ", fmt.Sprintf(
        "room no longer full  occupancy=%d/%d  queue=%d",
        s.Occupancy, s.Capacity, s.QueueDepth,
    ))
})
wr.On(room.EventQueue, func(s room.Snapshot) {
    roomLog("QUEUE  ", fmt.Sprintf(
        "request queued  depth=%d  occupancy=%d/%d  util=%.0f%%",
        s.QueueDepth, s.Occupancy, s.Capacity, pct(s.Occupancy, s.Capacity),
    ))
})
wr.On(room.EventEnter, func(s room.Snapshot) {
    roomLog("ENTER  ", fmt.Sprintf(
        "slot acquired  occupancy=%d/%d  queue=%d  util=%.0f%%",
        s.Occupancy, s.Capacity, s.QueueDepth, pct(s.Occupancy, s.Capacity),
    ))
})
wr.On(room.EventExit, func(s room.Snapshot) {
    roomLog("EXIT   ", fmt.Sprintf(
        "slot released  occupancy=%d/%d  queue=%d  util=%.0f%%",
        s.Occupancy, s.Capacity, s.QueueDepth, pct(s.Occupancy, s.Capacity),
    ))
})
wr.On(room.EventEvict, func(s room.Snapshot) {
    roomLog("EVICT  ", fmt.Sprintf(
        "ghost ticket removed  queue=%d  occupancy=%d/%d",
        s.QueueDepth, s.Occupancy, s.Capacity,
    ))
})
wr.On(room.EventTimeout, func(s room.Snapshot) {
    roomLog("TIMEOUT", fmt.Sprintf(
        "context cancelled before admission  occupancy=%d/%d  queue=%d",
        s.Occupancy, s.Capacity, s.QueueDepth,
    ))
})
wr.On(room.EventPromote, func(s room.Snapshot) {
    roomLog("PROMOTE", fmt.Sprintf(
        "client promoted to front  occupancy=%d/%d  queue=%d",
        s.Occupancy, s.Capacity, s.QueueDepth,
    ))
})

Add the pct helper below requestLogger:

// pct converts occupancy/capacity to a display percentage.
func pct(occupancy, capacity int) float64 {
    if capacity == 0 {
        return 0
    }
    return float64(occupancy) / float64(capacity) * 100
}

Mistake trap: Register an EventFull callback after wr.RegisterRoutes(r) and immediately fire a load test. If the room fills during RegisterRoutes, you miss the first transition. Always register callbacks before RegisterRoutes.

Step 7 — Routes, the waiting room, and runtime secret registration

This is the step where verbose earns its place. The moment PromoteTokenToFront returns a PassToken, that token is registered as a verbose secret before anything else touches it — before it is set as a cookie, before it is mentioned in any log line. The sequence is non-negotiable: register first, then do everything else.

The rule for what goes in logs: log metadata about the event (cost, whether a pass was issued, queue depth), never the token value or any substring of it. A truncated token prefix is not protected by verbose scrubbing because verbose matches the full registered value — logging token=%.8s... bypasses the scrubber entirely. If a value is sensitive enough to register with verbose, it is sensitive enough to keep entirely out of log lines.

Add routes and the server to main, after the callbacks block:

// payment routes — registered BEFORE RegisterRoutes so they bypass the queue
r.GET("/queue/purchase", handlePurchasePage)
r.POST("/queue/purchase/confirm", handlePurchaseConfirm)

// RegisterRoutes installs:
//   OPTIONS /queue/status  (CORS preflight)
//   GET     /queue/status  (polling endpoint for the waiting room page)
//   r.Use(wr.Middleware()) (gates every route registered after this line)
wr.RegisterRoutes(r)

// application routes — all gated by the waiting room
r.GET("/",        homePage)
r.GET("/about",   aboutPage)
r.GET("/pricing", pricingPage)
r.GET("/contact", contactPage)

addr := fmt.Sprintf(":%d", *figs.Int(kPort))
verbose.Printf("basicwebapp listening on http://localhost%s  cap=%d  rate=$%.2f/pos  pass=%s",
    addr, wr.Cap(), *figs.Float64(kRatePerPosition), wr.PassDuration())

if err := r.Run(addr); err != nil {
    verbose.TracefReturn("r.Run: %v", err)
    os.Exit(1)
}

Add the payment handlers and page handlers below pct:

// handlePurchasePage shows the payment confirmation page.
// In production: redirect to a Stripe Checkout session.
func handlePurchasePage(c *gin.Context) {
    cookie, err := c.Request.Cookie("room_ticket")
    if err != nil || cookie.Value == "" {
        c.Data(http.StatusBadRequest, "text/html; charset=utf-8", page(
            "Error", "<h1>No queue ticket found</h1><a href='/'>← Back</a>",
        ))
        return
    }

    // check for an active VIP pass — no need to pay again
    if passCookie, err := c.Request.Cookie("room_pass"); err == nil {
        if wr.HasValidPass(passCookie.Value) {
            c.Data(http.StatusOK, "text/html; charset=utf-8", page(
                "VIP pass active",
                "<h1>Your VIP pass is still active</h1><p>You'll be auto-promoted — no payment needed.</p><a href='/'>← Back</a>",
            ))
            return
        }
    }

    cost, err := wr.QuoteCost(cookie.Value, 1)
    if err != nil {
        c.Data(http.StatusOK, "text/html; charset=utf-8", page(
            "Skip the line",
            fmt.Sprintf("<h1>Skip the line</h1><p>%s</p><a href='/'>← Back</a>", err.Error()),
        ))
        return
    }

    verbose.Printf("GET /queue/purchase — cost=$%.2f queue=%d", cost, wr.QueueDepth())
    c.Data(http.StatusOK, "text/html; charset=utf-8", purchasePage(cost, wr.PassDuration()))
}

// handlePurchaseConfirm processes the payment and promotes the token.
// In production: verify Stripe webhook signature before calling PromoteTokenToFront.
func handlePurchaseConfirm(c *gin.Context) {
    cookie, err := c.Request.Cookie("room_ticket")
    if err != nil || cookie.Value == "" {
        c.JSON(http.StatusBadRequest, gin.H{"error": "no room_ticket cookie"})
        return
    }

    result, err := wr.PromoteTokenToFront(cookie.Value)
    if err != nil {
        verbose.Printf("POST /queue/purchase/confirm — promotion failed: %v", err)
        c.Data(http.StatusOK, "text/html; charset=utf-8", page(
            "Payment failed",
            fmt.Sprintf("<h1>Something went wrong</h1><p>%s</p><a href='/'>← Back</a>", err.Error()),
        ))
        return
    }

    // ── THE KEY MOMENT ────────────────────────────────────────────────────
    // Register the VIP pass token with verbose FIRST — before the cookie
    // is set, before anything is logged, before the response is written.
    //
    // After this line, if the pass token value appears anywhere in any
    // log line this process writes, verbose replaces it with [VIP_PASS].
    //
    // Do NOT log the token value, any prefix of it, or any derivative.
    // verbose scrubs the full registered value — a truncated prefix escapes
    // the scrubber entirely. Log metadata only: cost, whether a pass was
    // issued, queue depth.
    if result.PassToken != "" {
        if err := verbose.AddSecret(verbose.SecretBytes(result.PassToken), "[VIP_PASS]"); err != nil {
            verbose.Printf("POST /queue/purchase/confirm — failed to protect pass token: %v", err)
        }
    }

    // safe to log now — pass token is scrubbed, metadata only
    verbose.Printf("POST /queue/purchase/confirm — promoted  cost=$%.2f  pass_issued=%v  queue=%d",
        result.Cost, result.PassToken != "", wr.QueueDepth())

    // set the VIP pass cookie so the client is auto-promoted on re-entry
    if result.PassToken != "" {
        http.SetCookie(c.Writer, &http.Cookie{
            Name:     "room_pass",
            Value:    result.PassToken,
            Path:     wr.CookiePath(),
            MaxAge:   int(wr.PassDuration().Seconds()),
            HttpOnly: true,
            Secure:   false, // set true in production behind TLS
            SameSite: http.SameSiteLaxMode,
        })
    }

    passMsg := ""
    if result.PassToken != "" {
        passMsg = fmt.Sprintf("<p>Your VIP pass is valid for <strong>%s</strong>.</p>",
            wr.PassDuration().Round(time.Minute))
    }
    c.Data(http.StatusOK, "text/html; charset=utf-8", page("Payment confirmed",
        fmt.Sprintf(`<h1>Payment confirmed — $%.2f</h1>
        <p>You've been moved to the front of the line!</p>%s
        <script>setTimeout(function(){ window.location.href = "/"; }, 2000);</script>
        <noscript><a href="/">← Click here</a></noscript>`, result.Cost, passMsg),
    ))
}

// ── page handlers — all gated by the waiting room ─────────────────────────

const simulatedLatency = 500 * time.Millisecond

func homePage(c *gin.Context) {
    time.Sleep(simulatedLatency)
    c.Data(http.StatusOK, "text/html; charset=utf-8", page("Home",
        `<h1>Welcome</h1>
        <p>This server admits at most <strong>5 concurrent requests</strong>.</p>
        <p>Run <code>ab -c 30 -n 500 http://localhost:8080/about</code> and watch the logs.</p>
        <nav><a href="/about">About</a> · <a href="/pricing">Pricing</a> · <a href="/contact">Contact</a></nav>`,
    ))
}

func aboutPage(c *gin.Context) {
    time.Sleep(simulatedLatency)
    c.Data(http.StatusOK, "text/html; charset=utf-8", page("About",
        `<h1>About</h1>
        <p>Built with <strong>room</strong>, <strong>figtree</strong>, and <strong>verbose</strong>.</p>
        <a href="/">← Home</a>`,
    ))
}

func pricingPage(c *gin.Context) {
    time.Sleep(simulatedLatency)
    c.Data(http.StatusOK, "text/html; charset=utf-8", page("Pricing",
        `<h1>Pricing</h1>
        <p>Skip the line: <strong>$2.50/position</strong> + 90-minute VIP pass.</p>
        <a href="/">← Home</a>`,
    ))
}

func contactPage(c *gin.Context) {
    time.Sleep(simulatedLatency)
    c.Data(http.StatusOK, "text/html; charset=utf-8", page("Contact",
        `<h1>Contact</h1><p>hello@example.com</p><a href="/">← Home</a>`,
    ))
}

// page wraps a body fragment in a complete HTML document.
func page(title, body string) []byte {
    return []byte(`<!DOCTYPE html><html lang="en"><head>
    <meta charset="UTF-8"><title>` + title + `</title>
    <style>body{font-family:system-ui,sans-serif;max-width:700px;margin:4rem auto;padding:0 1.5rem}
    h1{margin-bottom:1rem}p{margin-bottom:1rem}code{background:#f0f0f0;padding:.1em .4em;border-radius:3px}
    a{color:#6c8ef5}</style></head><body>` + body + `</body></html>`)
}

// purchasePage renders the skip-the-line confirmation page.
func purchasePage(cost float64, passDur time.Duration) []byte {
    passNote := ""
    if passDur > 0 {
        passNote = fmt.Sprintf(
            `<p>Includes a <strong>%s VIP pass</strong> — re-enter the queue anytime during that window and skip for free.</p>`,
            passDur.Round(time.Minute))
    }
    return []byte(fmt.Sprintf(`<!DOCTYPE html><html><head><meta charset="UTF-8">
    <title>Skip the line</title></head><body style="font-family:system-ui;max-width:500px;margin:4rem auto;padding:0 1.5rem">
    <h1>Skip the line — $%.2f</h1>%s
    <form method="POST" action="/queue/purchase/confirm">
      <button type="submit" style="background:#6c8ef5;color:#fff;border:none;padding:.75rem 2rem;border-radius:8px;font-size:1rem;cursor:pointer">
        Confirm payment — $%.2f
      </button>
    </form>
    <p style="margin-top:1rem;font-size:.8rem;color:#666">Demo mode — no real payment processed.</p>
    <a href="/">← Back to waiting room</a>
    </body></html>`, cost, passNote, cost))
}

Add net/http to imports.

Mistake trap: Move verbose.AddSecret to after http.SetCookie. Run the server, issue a key by clicking "Pay to skip", then check logs/basicwebapp.log. Find the POST /queue/purchase/confirm line. The pass token appears in plaintext because verbose did not know about it yet. Move AddSecret back to immediately after PromoteTokenToFront returns, before anything else.

Step 8 — The bash test script

Create test.sh. This script is the pass/fail gate. Exit 0 means every assertion passed — your implementation is correct. It fails fast on the first failed assertion and tells you which step to revisit.

#!/usr/bin/env bash
set -euo pipefail

# ── dependency check ──────────────────────────────────────────────────────────
if ! command -v curl &>/dev/null; then
    echo "ERROR: curl is required."; exit 1
fi
if ! command -v jq &>/dev/null; then
    echo "ERROR: jq is required."
    echo "  macOS: brew install jq"
    echo "  Linux: sudo apt install jq  OR  sudo yum install jq"
    exit 1
fi
if ! command -v ab &>/dev/null; then
    echo "ERROR: apache bench (ab) is required."
    echo "  macOS: brew install httpd"
    echo "  Linux: sudo apt install apache2-utils"
    exit 1
fi

# ── config ────────────────────────────────────────────────────────────────────
BASE="http://127.0.0.1:8080"
LOG_FILE="./logs/basicwebapp.log"

# ── helpers ───────────────────────────────────────────────────────────────────
pass() { echo "  PASS: $1"; }
fail() { echo "  FAIL: $1 — $2"; exit 1; }

assert_log_contains() {
    local label="$1" pattern="$2" step="$3"
    if ! grep -qF "$pattern" "$LOG_FILE" 2>/dev/null; then
        fail "$label" "expected '$pattern' in log — not found (see step $step)"
    fi
    pass "$label"
}

assert_no_plaintext() {
    local label="$1" secret="$2" step="$3"
    if grep -qF "$secret" "$LOG_FILE" 2>/dev/null; then
        fail "$label" "plaintext secret found in log (see step $step)"
    fi
    pass "$label"
}

assert_status() {
    local label="$1" expected="$2" actual="$3" step="$4"
    if [ "$actual" -ne "$expected" ]; then
        fail "$label" "expected HTTP $expected, got $actual (see step $step)"
    fi
    pass "$label"
}

# ── build and start ───────────────────────────────────────────────────────────
echo "=> building..."
go build -o basicwebapp_bin . || { echo "Build failed."; exit 1; }

echo "=> starting server..."
./basicwebapp_bin &
SERVER_PID=$!
trap 'kill $SERVER_PID 2>/dev/null; rm -f basicwebapp_bin' EXIT

for i in $(seq 1 20); do
    if curl -sf "$BASE/" &>/dev/null; then break; fi
    sleep 0.5
done

echo ""
echo "── assertion 1: server started and log file exists (Step 4) ─────────────"
if [ ! -f "$LOG_FILE" ]; then
    fail "log file exists" "logs/basicwebapp.log not found — check verbose.NewLogger (see step 4)"
fi
pass "log file exists"

echo ""
echo "── assertion 2: config loaded and logged (Step 2 + 4) ───────────────────"
assert_log_contains "config line in log" "config:" "2"

echo ""
echo "── assertion 3: waiting room activates under load (Step 5 + 6) ──────────"
echo "   running ab -c 30 -n 100 $BASE/about (10s)..."
ab -c 30 -n 100 -t 10 "$BASE/about" &>/dev/null || true
sleep 2
assert_log_contains "[FULL] in log"  "[ FULL   ]"  "6"
assert_log_contains "[QUEUE] in log" "[ QUEUE  ]"  "6"
assert_log_contains "[ENTER] in log" "[ ENTER  ]"  "6"

echo ""
echo "── assertion 4: purchase page accessible (Step 7) ───────────────────────"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/queue/purchase")
assert_status "GET /queue/purchase returns 400" 400 "$STATUS" "7"

echo ""
echo "── assertion 5: VIP pass token scrubbed from log (Step 7) ──────────────"
COOKIE_JAR=$(mktemp)
for i in $(seq 1 6); do
    curl -s -o /dev/null "$BASE/about" &
done
sleep 0.3
curl -s -o /dev/null -c "$COOKIE_JAR" "$BASE/about" || true
TICKET=$(grep "room_ticket" "$COOKIE_JAR" | awk '{print $NF}' || true)

if [ -n "$TICKET" ]; then
    PASS_TOKEN=$(curl -s -b "$COOKIE_JAR" -c "$COOKIE_JAR" \
        -X POST "$BASE/queue/purchase/confirm" \
        -D - -o /dev/null 2>/dev/null \
        | grep -i "room_pass" | grep -oP 'room_pass=\K[^;]+' || true)

    if [ -n "$PASS_TOKEN" ]; then
        assert_no_plaintext "VIP pass token not in log" "$PASS_TOKEN" "7"
        assert_log_contains "[VIP_PASS] marker in log" "[VIP_PASS]" "7"
    else
        pass "VIP pass token not in log (no pass token issued — room may not have been full)"
    fi
else
    pass "VIP pass token check skipped (could not obtain room_ticket cookie)"
fi
rm -f "$COOKIE_JAR"

wait 2>/dev/null || true

echo ""
echo "── assertion 6: ROOM_CAP mutation logged (Step 3) ───────────────────────"
export ROOM_CAP=8
echo "   waiting up to 90s for ROOM_CAP mutation to appear in log..."
for i in $(seq 1 18); do
    if grep -qF "room-cap" "$LOG_FILE" 2>/dev/null; then
        pass "ROOM_CAP mutation in log"
        break
    fi
    sleep 5
    if [ "$i" -eq 18 ]; then
        fail "ROOM_CAP mutation in log" "mutation not seen after 90s — check Pollinate:true and mutations goroutine (see step 3)"
    fi
done

echo ""
echo "════════════════════════════════════════════════════════════════════════"
echo "  All assertions passed. Your implementation is correct."
echo "════════════════════════════════════════════════════════════════════════"

Make it executable and run it:

chmod +x test.sh
./test.sh

If every assertion passes you see the final banner. If any assertion fails the script exits immediately with the step number to revisit.

Step 9 — Closing: What You Built and What Comes Next

You started with an empty directory. You finished with a four-page Gin web application that admits at most 5 concurrent requests, queues the rest in FIFO order with a live-updating waiting room page, issues paid VIP passes that auto-promote returning clients for 90 minutes, and whose log file is provably safe to hand to a support engineer. Run ./test.sh one final time and watch every assertion pass.

Take a moment to understand what each package actually did.

room is not rate limiting. Rate limiting drops requests or returns 429. room keeps them — every request gets a ticket, sees its position, and is admitted automatically when a slot opens. The reaper cleans up abandoned clients so ghost tickets never stall the queue. The promotion system with PromoteTokenToFront and GrantPass is a complete commercial primitive: you can charge per position, issue time-limited passes, and let the middleware handle the rest. Your handlers never change — they see normal requests arriving at the rate you configured.

figtree is not a flag parser. It is a priority-ordered configuration resolver with live mutation tracking. The moment ROOM_CAP changed in the environment, wr.SetCap was called — no restart, no dropped requests, no intervention. In production that is how you respond to traffic spikes: your autoscaler updates the env var, figtree detects it, the room expands. The RateFunc reading from *figs.Float64(kRatePerPosition) on every call means your skip-the-line pricing can change live too.

verbose is not just a logger. The moment PromoteTokenToFront returned a PassToken, that token's SHA-512 digest entered verbose's registry and every subsequent log line is scanned against it before it touches disk. The plaintext never persists. The rule you followed — log metadata, never the value or any substring — is the correct pattern for any secret: verbose is a safety net, not a substitute for keeping secrets out of log lines in the first place.

The packages used in this tutorial are part of a larger body of open source work

room, figtree, and verbose were all written by Andrei Merlescu — @andreimerlescu on GitHub. His profile carries 99 public repositories built across 17 years of professional software engineering spanning Cisco, Oracle, Warner Bros. Games, and SurgePays.

Other packages worth exploring alongside the three you just used:

sema — the semaphore that backs room. Dynamic resizing, EWMA utilization tracking, context cancellation, drain/reset for maintenance windows. Zero-allocation hot path.
checkfs — filesystem existence and permission checks. Pairs naturally with figtree when you want to validate that a config-supplied path actually exists before your server starts.
lemmings — load testing built around the concept of NPCs moving through your infrastructure as simulated users across geographic terrains and pack sizes. If you want to know what your waiting room does under real traffic before you ship it, lemmings is how you find out.

From Zero to Hero: Building a Key Issuance Server with `verbose` and `figtree`

Andrei Merlescu — Mon, 20 Apr 2026 15:53:15 +0000

In August 2024 Andrei Merlescu wrote a package called verbose and released it under the Apache 2.0 license. The idea was novel: when interacting with sensitive information during multi-region deployments, you want to print to STDOUT a censored expression of data while writing the unredacted form to log files — or in this tutorial's case, scrub secrets from the log file entirely. Private keys, passwords, serial numbers — these are sensitive and should not stream through STDOUT in devops contexts, especially in CI pipelines like GitHub Actions. With verbose, your runtime can register new secrets as they become available, concurrently and safely.

go get -u github.com/andreimerlescu/verbose

aSecret := "abc123"
// SecretBytes cast is required — AddSecret takes verbose.SecretBytes, not string
if err := verbose.AddSecret(verbose.SecretBytes(aSecret), "***"); err != nil {
    log.Fatal(err)
}
stdoutLogger := log.New(os.Stdout, "", log.LstdFlags)
// Tof takes a *log.Logger, not an io.Writer
verbose.Tof(stdoutLogger, "this is a secret: %s", aSecret)

Prints to STDOUT:

this is a secret: ***

Step 1 — Scaffold and dependencies

You are going to build a running HTTP server that issues, verifies, and revokes API keys. Every secret the server touches — the admin token that protects your endpoints, every key it issues — will be registered with the verbose logging package the moment it is created. By the time you finish, you will be able to grep your own log file for any plaintext secret and find nothing. That is the goal.

verbose is a logging package that scrubs registered secrets from every line it writes. figtree is a configuration package that loads values from a YAML file, environment variables, and CLI flags in that priority order, with validators and mutation tracking built in.

Create the project:

mkdir keyserver && cd keyserver
go mod init github.com/example/keyserver
go get github.com/andreimerlescu/verbose@latest
go get github.com/andreimerlescu/figtree/v2@latest

Create the files you will fill in across the remaining steps:

touch main.go config.yml

Your go.mod should now look like this:

module github.com/example/keyserver

go 1.22

require (
    github.com/andreimerlescu/figtree/v2 v2.0.14
    github.com/andreimerlescu/verbose    v0.2.0
)

Your directory:

keyserver/
├── go.mod
├── go.sum
├── config.yml
└── main.go

Nothing runs yet. That is fine. You have a clean workspace and both packages are available.

Step 2 — CLI design with figtree

Now that the workspace is ready, the first thing to design is configuration. Before any HTTP server, any logger, any route — you need to know what the program accepts and where it reads it from. figtree handles all three sources — file, environment, flags — in one tree.

Every config key is a Go constant. This is not optional style — it prevents typos from silently creating a second key that is never read.

Add this to main.go:

// main.go — complete file at this stage

package main

import (
    "fmt"
    "os"
    "time"

    "github.com/andreimerlescu/figtree/v2"
)

// config keys — always constants, never raw strings at call sites
const (
    kHost          = "host"
    kPort          = "port"
    kLogDir        = "log-dir"
    kTruncate      = "truncate"
    kKeyPrefix     = "key-prefix"
    kAdminToken    = "keyserver-admin-token" // env: KEYSERVER_ADMIN_TOKEN
    kOnCall        = "on-call-engineer"      // env: ON_CALL_ENGINEER
    kShiftDuration = "shift-duration"        // env: SHIFT_DURATION
)

func main() {
    // Grow a tracked tree — Tracking enables the Mutations() channel,
    // Pollinate re-checks env vars on every Getter call (needed for Step 7),
    // ConfigFile makes the intent explicit: this app is config-file-first.
    figs := figtree.With(figtree.Options{
        Tracking:   true,
        Germinate:  true,           // ignore -test.* flags during go test
        Pollinate:  true,           // re-read env vars on every Getter call
        ConfigFile: "./config.yml",
    })

    // -- server --
    figs.NewString(kHost, "127.0.0.1", "host address to listen on")
    figs.NewInt(kPort, 8080, "port to listen on")

    // -- logging --
    figs.NewString(kLogDir, "./logs", "directory to write log files into")
    figs.NewBool(kTruncate, false, "truncate log file on each run")

    // -- keys --
    figs.NewString(kKeyPrefix, "ks_", "prefix for issued API keys")

    // RuleNoFlags means figtree will never register a CLI flag for this key.
    // The only way to supply it is via KEYSERVER_ADMIN_TOKEN or config.yml.
    // The key name is deliberately long — verbose by design.
    figs.NewString(kAdminToken, "", "admin token — use KEYSERVER_ADMIN_TOKEN env var only")
    figs.WithRule(kAdminToken, figtree.RuleNoFlags)

    // -- on-call rotation --
    figs.NewString(kOnCall, "Darron", "name of the engineer currently on call")

    // shift-duration drives the rotation goroutine added in Step 3.
    // Default is 7 hours. SHIFT_DURATION=1 overrides it for local testing.
    figs.NewUnitDuration(kShiftDuration, 7, time.Hour, "length of one on-call shift in hours")

    // Problems() catches developer mistakes — duplicate keys, bad validator
    // combos — before Load() runs. These are your bugs, not user input errors.
    if problems := figs.Problems(); len(problems) > 0 {
        for _, p := range problems {
            fmt.Fprintf(os.Stderr, "figtree problem: %v\n", p)
        }
        os.Exit(1)
    }

    // Load resolves: config.yml → env vars → CLI flags (in that priority order)
    if err := figs.Load(); err != nil {
        fmt.Fprintf(os.Stderr, "figtree.Load: %v\n", err)
        os.Exit(1)
    }

    // Print everything so you can see what loaded — fmt.Println for now,
    // verbose replaces this in Step 4.
    fmt.Printf("host=%s port=%d log-dir=%s truncate=%v\n",
        *figs.String(kHost),
        *figs.Int(kPort),
        *figs.String(kLogDir),
        *figs.Bool(kTruncate),
    )
    fmt.Printf("key-prefix=%s on-call=%s shift=%s\n",
        *figs.String(kKeyPrefix),
        *figs.String(kOnCall),
        *figs.Duration(kShiftDuration),
    )
    fmt.Printf("admin-token=%s\n", *figs.String(kAdminToken))
}

Create config.yml:

host:             "127.0.0.1"
port:             8080
log-dir:          "./logs"
truncate:         false
key-prefix:       "ks_"
on-call-engineer: "Darron"
shift-duration:   7
# keyserver-admin-token is intentionally absent from source control.
# Set it via: export KEYSERVER_ADMIN_TOKEN=your-secret

Run it:

KEYSERVER_ADMIN_TOKEN=mysecret go run .

You should see all values printed. Notice admin-token=mysecret is in your terminal output right now. That is expected — verbose is not wired yet. You will fix that in Step 4 and never see it in plaintext again.

Mistake trap: Try running go run . -keyserver-admin-token=mysecret. figtree will not register that flag because of RuleNoFlags — the flag is unknown to the flag package and your program will exit with an error. The env var is the only valid path. This is intentional.

Step 3 — Validators, Problems(), and mutations

Now that the tree is declared, you lock it down. Validators reject bad input before your program does anything with it. The Problems() check you already have catches declaration mistakes. The mutations goroutine watches for runtime changes — which is where the on-call rotation lives.

Add these diffs to main.go:

After figs.NewString(kHost, ...) — add validator:

    // 3 lines above
    figs.NewString(kHost, "127.0.0.1", "host address to listen on")
    // add this
    figs.WithValidator(kHost, figtree.AssureStringNotEmpty)
    // 3 lines below
    figs.NewInt(kPort, 8080, "port to listen on")

After figs.NewInt(kPort, ...) — add validator:

    // 3 lines above
    figs.NewInt(kPort, 8080, "port to listen on")
    // add this
    figs.WithValidator(kPort, figtree.AssureIntInRange(1024, 65535))
    // 3 lines below
    figs.NewString(kLogDir, "./logs", "directory to write log files into")

After figs.NewString(kLogDir, ...) — add validator:

    // 3 lines above
    figs.NewString(kLogDir, "./logs", "directory to write log files into")
    // add this
    figs.WithValidator(kLogDir, figtree.AssureStringNotEmpty)
    // 3 lines below
    figs.NewBool(kTruncate, false, "truncate log file on each run")

After figs.NewString(kKeyPrefix, ...) — add validator:

    // 3 lines above
    figs.NewString(kKeyPrefix, "ks_", "prefix for issued API keys")
    // add this
    figs.WithValidator(kKeyPrefix, figtree.AssureStringNotEmpty)
    // 3 lines below
    figs.NewString(kAdminToken, "", "admin token — use KEYSERVER_ADMIN_TOKEN env var only")

After figs.WithRule(kAdminToken, ...) — add validator:

    // 3 lines above
    figs.WithRule(kAdminToken, figtree.RuleNoFlags)
    // add this — admin token must be present at startup
    figs.WithValidator(kAdminToken, figtree.AssureStringNotEmpty)
    // 3 lines below
    figs.NewString(kOnCall, "Darron", "name of the engineer currently on call")

After figs.NewString(kOnCall, ...) — add validator:

    // 3 lines above
    figs.NewString(kOnCall, "Darron", "name of the engineer currently on call")
    // add this
    figs.WithValidator(kOnCall, figtree.AssureStringNotEmpty)
    // 3 lines below
    figs.NewUnitDuration(kShiftDuration, 7, time.Hour, "length of one on-call shift in hours")

After figs.NewUnitDuration(kShiftDuration, ...) — add validators:

    // 3 lines above
    figs.NewUnitDuration(kShiftDuration, 7, time.Hour, "length of one on-call shift in hours")
    // add these — shifts must be at least 1 hour, at most 12
    figs.WithValidator(kShiftDuration, figtree.AssureDurationMin(1*time.Hour))
    figs.WithValidator(kShiftDuration, figtree.AssureDurationMax(12*time.Hour))
    // 3 lines below
    if problems := figs.Problems(); len(problems) > 0 {

Now add the mutations goroutine and the on-call shift rotation. Both go after figs.Load() — the tree must be live before you watch it:

    // 3 lines above
    if err := figs.Load(); err != nil {
        fmt.Fprintf(os.Stderr, "figtree.Load: %v\n", err)
        os.Exit(1)
    }
    // add this block
    // watch for any config value changing at runtime and log it
    go func() {
        for m := range figs.Mutations() {
            // verbose.Printf replaces this in Step 4
            fmt.Printf("config mutation: %s changed from %v to %v at %s\n",
                m.Property, m.Old, m.New, m.When)
        }
    }()

    // on-call rotation — fires every minute, updates kOnCall based on
    // the current hour. We check every minute so the change is never
    // more than 60 seconds late.
    go func() {
        for range time.Tick(time.Minute) {
            figs.StoreString(kOnCall, onCallEngineer())
        }
    }()
    // 3 lines below
    fmt.Printf("host=%s port=%d log-dir=%s truncate=%v\n",

Add the onCallEngineer function at the bottom of main.go, outside main:

// onCallEngineer returns the name of the engineer on call right now.
//
//   04:00–07:59  → TEAM     (everyone expected online)
//   08:00–14:59  → Darron
//   15:00–21:59  → Bradley
//   22:00–03:59  → Kevin    (crosses midnight)
func onCallEngineer() string {
    h := time.Now().Hour()
    switch {
    case h >= 4 && h < 8:
        return "TEAM"
    case h >= 8 && h < 15:
        return "Darron"
    case h >= 15 && h < 22:
        return "Bradley"
    default: // 22:00–03:59
        return "Kevin"
    }
}

Run it again:

KEYSERVER_ADMIN_TOKEN=mysecret go run .

To prove the validator works, temporarily set port: 99999 in config.yml and run again. You will see figtree refuse to load with a clear error. Set it back to 8080.

Mistake trap: Move the mutations goroutine to before figs.Load() and run it. The channel exists but the tree has not resolved its values yet — mutations fired during load will not be seen because the goroutine may not be scheduled before load completes. Always start the mutations goroutine after Load() returns.

Step 4 — Wire verbose, replace fmt, register the admin token

Now that figtree is loading and validating configuration correctly, you can wire up the logger. verbose needs to be initialised before any log call — and the admin token needs to be registered as a secret immediately after, before anything else in the program touches it.

Add verbose to your imports:

import (
    "fmt"
    "os"
    "time"
    // add this
    "github.com/andreimerlescu/verbose"

    "github.com/andreimerlescu/figtree/v2"
)

Add the verbose initialisation block right after the goroutines:

    // 3 lines above
    go func() {
        for range time.Tick(time.Minute) {
            figs.StoreString(kOnCall, onCallEngineer())
        }
    }()
    // add this block
    // initialise verbose before any log call — guard() will stderr and no-op
    // if you call verbose functions before this point
    if err := verbose.NewLogger(verbose.Options{
        Dir:      *figs.String(kLogDir),
        Name:     "keyserver",
        Truncate: *figs.Bool(kTruncate),
        DirMode:  0o755,
        FileMode: 0o640,
    }); err != nil {
        fmt.Fprintf(os.Stderr, "verbose.NewLogger: %v\n", err)
        os.Exit(1)
    }

    // read the admin token once — this is the value we protect at startup
    adminToken := *figs.String(kAdminToken)

    // register the admin token as a verbose secret immediately.
    // verbose stores only the SHA-512 digest — the plaintext is never retained.
    // every log line written after this point that contains the raw token value
    // will have it replaced with [ADMIN_TOKEN] automatically.
    if err := verbose.AddSecret(verbose.SecretBytes(adminToken), "[ADMIN_TOKEN]"); err != nil {
        fmt.Fprintf(os.Stderr, "verbose.AddSecret: %v\n", err)
        os.Exit(1)
    }

    // proof that scrubbing is active — this line contains the raw token.
    // open logs/keyserver.log after running and you will see [ADMIN_TOKEN].
    verbose.Printf("admin token registered — value in log: %s", adminToken)
    // Version() is a function call, not a variable
    verbose.Printf("keyserver starting (verbose v%s / figtree v%s)",
        verbose.VERSION, figtree.Version())
    // 3 lines below
    fmt.Printf("host=%s port=%d log-dir=%s truncate=%v\n",

Replace the fmt.Printf startup summary:

    // remove this
    fmt.Printf("host=%s port=%d log-dir=%s truncate=%v\n",
        *figs.String(kHost),
        *figs.Int(kPort),
        *figs.String(kLogDir),
        *figs.Bool(kTruncate),
    )
    fmt.Printf("key-prefix=%s on-call=%s shift=%s\n",
        *figs.String(kKeyPrefix),
        *figs.String(kOnCall),
        *figs.Duration(kShiftDuration),
    )
    fmt.Printf("admin-token=%s\n", *figs.String(kAdminToken))
    // replace with this
    verbose.Printf("host=%s port=%d log-dir=%s truncate=%v key-prefix=%s on-call=%s shift=%s",
        *figs.String(kHost),
        *figs.Int(kPort),
        *figs.String(kLogDir),
        *figs.Bool(kTruncate),
        *figs.String(kKeyPrefix),
        *figs.String(kOnCall),
        *figs.Duration(kShiftDuration),
    )

Replace the fmt.Printf in the mutations goroutine:

    // 3 lines above
    go func() {
        for m := range figs.Mutations() {
            // remove this
            fmt.Printf("config mutation: %s changed from %v to %v at %s\n",
                m.Property, m.Old, m.New, m.When)
            // replace with this
            verbose.Printf("config mutation: %s changed from %v to %v at %s",
                m.Property, m.Old, m.New, m.When)
        }
    }()

Run it:

KEYSERVER_ADMIN_TOKEN=mysecret go run .

Open logs/keyserver.log. Find the line containing "admin token registered". The value mysecret does not appear — you will see [ADMIN_TOKEN] in its place. From this point forward, mysecret cannot appear in any log line this process writes.

Mistake trap: Call verbose.Printf("test") before verbose.NewLogger — move it above the NewLogger block and run. You will see the message printed to stderr with a "NewLogger or SetLogger has not been called" prefix. verbose does not panic — it fails open to stderr. Move the call back below NewLogger.

Step 5 — HTTP server skeleton

With logging and configuration solid, the server can be wired up. The three routes are stubs for now — each returns 200 OK with a placeholder body. The requireAdmin middleware is the important piece here: it logs every auth attempt, which means the admin token will be scrubbed from those log lines automatically.

Add net/http and encoding/json to your imports:

import (
    "fmt"
    "os"
    "time"
    // add these
    "encoding/json"
    "net/http"

    "github.com/andreimerlescu/verbose"
    "github.com/andreimerlescu/figtree/v2"
)

Add the server block at the end of main:

    // 3 lines above
    verbose.Printf("host=%s port=%d log-dir=%s truncate=%v key-prefix=%s on-call=%s shift=%s",
        *figs.String(kHost),
        *figs.Int(kPort),
        *figs.String(kLogDir),
        *figs.Bool(kTruncate),
        *figs.String(kKeyPrefix),
        *figs.String(kOnCall),
        *figs.Duration(kShiftDuration),
    )
    // add this block
    // capture prefix once — used in handlers added in Step 6
    prefix := *figs.String(kKeyPrefix)
    _ = prefix

    // POST /keys — issue a new API key (admin only)
    http.HandleFunc("POST /keys", requireAdmin(adminToken, func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(map[string]string{"status": "not implemented"})
    }))

    // GET /keys/{id}/verify — verify a presented key
    http.HandleFunc("GET /keys/{id}/verify", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(map[string]string{"status": "not implemented"})
    })

    // DELETE /keys/{id} — revoke and remove a key (admin only)
    http.HandleFunc("DELETE /keys/{id}", requireAdmin(adminToken, func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusNoContent)
    }))

    addr := fmt.Sprintf("%s:%d", *figs.String(kHost), *figs.Int(kPort))
    verbose.Printf("keyserver listening on http://%s", addr)

    if err := http.ListenAndServe(addr, nil); err != nil {
        // ListenAndServe only returns on error — log it with a trace and exit
        fmt.Fprintf(os.Stderr, "http.ListenAndServe: %v\n",
            verbose.TracefReturn("ListenAndServe failed: %v", err))
        os.Exit(1)
    }
    // 3 lines below — end of main

Add requireAdmin and bearerToken below onCallEngineer:

// requireAdmin rejects requests whose Bearer token does not match adminToken.
// The token is already a verbose secret — the log line is safe.
func requireAdmin(adminToken string, next http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        presented := bearerToken(r)
        verbose.Printf("%s %s — auth attempt from %s token=%s",
            r.Method, r.URL.Path, r.RemoteAddr, presented)
        if presented != adminToken {
            verbose.Printf("%s %s — FORBIDDEN", r.Method, r.URL.Path)
            http.Error(w, "forbidden", http.StatusForbidden)
            return
        }
        next(w, r)
    }
}

// bearerToken extracts the token from Authorization: Bearer <token>
func bearerToken(r *http.Request) string {
    auth := r.Header.Get("Authorization")
    if len(auth) > 7 && auth[:7] == "Bearer " {
        return auth[7:]
    }
    return ""
}

Run the server and curl the stubs:

KEYSERVER_ADMIN_TOKEN=mysecret go run . &

curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer mysecret"

curl -s http://localhost:8080/keys/test/verify

curl -s -X DELETE http://localhost:8080/keys/test \
  -H "Authorization: Bearer mysecret"

kill %1

Check logs/keyserver.log. The auth lines show token=[ADMIN_TOKEN] — never mysecret.

Mistake trap: If you are on Go below 1.22, http.HandleFunc("POST /keys", ...) will not compile — the method prefix in the pattern is a 1.22 feature. Run go version to check. If needed, update your toolchain: go get toolchain@go1.22.0.

Step 6 — Issuance, verification, revocation, and runtime secret registration

This is the core of the application and the core demonstration of verbose. The moment a key is generated, verbose.AddSecret is called before anything else — before the key is stored, before it is logged, before it is returned to the caller. The window between generation and registration is zero.

When a key is deleted, verbose.RemoveSecret is called. This is safe because a deleted key is dead — no future request will present it, so there is no future log line to protect. Removing it keeps the verbose runtime lean: the secrets registry does not grow forever, and scanning each log line is O(n) in the number of registered secrets. In a long-running server issuing thousands of keys, this matters. The same pattern applies to user sessions: register the session token on login, remove it on logout.

Add the key store above main:

// 3 lines above — imports
// add this block after imports, before main

// keyRecord holds metadata for one issued API key.
// The token value is the map key — never stored inside the struct.
type keyRecord struct {
    ID       string    `json:"id"`
    IssuedAt time.Time `json:"issued_at"`
    IssuedTo string    `json:"issued_to"`
    Revoked  bool      `json:"revoked"`
}

var (
    keyStoreMu sync.RWMutex
    keyStore   = make(map[string]*keyRecord)
)
// 3 lines below — func main() {

Add sync, crypto/rand, and encoding/hex to imports:

    // add to import block
    "crypto/rand"
    "encoding/hex"
    "sync"

Replace the POST /keys stub:

    // 3 lines above
    http.HandleFunc("POST /keys", requireAdmin(adminToken, func(w http.ResponseWriter, r *http.Request) {
    // replace body
        var body struct {
            IssuedTo string `json:"issued_to"`
        }
        if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.IssuedTo == "" {
            verbose.Printf("POST /keys — bad request from %s: %v", r.RemoteAddr, err)
            http.Error(w, "issued_to is required", http.StatusBadRequest)
            return
        }

        token, err := generateToken(prefix)
        if err != nil {
            // TracefReturn logs with a stack trace and returns the error —
            // capture the return value, do not discard it
            verbose.Printf("POST /keys — token generation failed: %v",
                verbose.TracefReturn("generateToken: %v", err))
            http.Error(w, "internal error", http.StatusInternalServerError)
            return
        }

        // register with verbose FIRST — before store, before log, before response.
        // after this line the token cannot appear in plaintext in any log output.
        if err := verbose.AddSecret(verbose.SecretBytes(token), "[ISSUED_KEY]"); err != nil {
            verbose.Printf("POST /keys — failed to protect token: %v", err)
            http.Error(w, "internal error", http.StatusInternalServerError)
            return
        }

        rec := &keyRecord{
            ID:       token,
            IssuedAt: time.Now().UTC(),
            IssuedTo: body.IssuedTo,
        }

        keyStoreMu.Lock()
        keyStore[token] = rec
        keyStoreMu.Unlock()

        // safe to log — token is already scrubbed to [ISSUED_KEY]
        verbose.Printf("POST /keys — issued key=%s to=%s at=%s",
            token, body.IssuedTo, rec.IssuedAt.Format(time.RFC3339))

        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusCreated)
        json.NewEncoder(w).Encode(map[string]string{
            "token":     token,
            "issued_to": body.IssuedTo,
            "issued_at": rec.IssuedAt.Format(time.RFC3339),
        })
    }))
    // 3 lines below

Replace the GET /keys/{id}/verify stub:

    // 3 lines above
    http.HandleFunc("GET /keys/{id}/verify", func(w http.ResponseWriter, r *http.Request) {
    // replace body
        presented := bearerToken(r)
        id := r.PathValue("id")

        // log the attempt — if the caller sent a valid token it is already
        // a verbose secret and will be scrubbed automatically
        verbose.Printf("GET /keys/%s/verify — attempt from %s token=%s",
            id, r.RemoteAddr, presented)

        keyStoreMu.RLock()
        rec, exists := keyStore[presented]
        keyStoreMu.RUnlock()

        if !exists || rec.Revoked {
            verbose.Printf("GET /keys/%s/verify — INVALID", id)
            http.Error(w, "invalid or revoked key", http.StatusUnauthorized)
            return
        }

        verbose.Printf("GET /keys/%s/verify — VALID issued_to=%s", id, rec.IssuedTo)
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(map[string]any{
            "valid":     true,
            "issued_to": rec.IssuedTo,
            "issued_at": rec.IssuedAt.Format(time.RFC3339),
        })
    })
    // 3 lines below

Replace the DELETE /keys/{id} stub:

    // 3 lines above
    http.HandleFunc("DELETE /keys/{id}", requireAdmin(adminToken, func(w http.ResponseWriter, r *http.Request) {
    // replace body
        id := r.PathValue("id")

        keyStoreMu.Lock()
        rec, exists := keyStore[id]
        if exists {
            rec.Revoked = true
        }
        keyStoreMu.Unlock()

        if !exists {
            verbose.Printf("DELETE /keys/%s — not found", id)
            http.Error(w, "key not found", http.StatusNotFound)
            return
        }

        // the key is dead — safe to remove from verbose.
        // removing it keeps the secrets registry lean: verbose scans every
        // log line against every registered secret, so a smaller registry
        // means faster logging. do not leave dead secrets registered forever.
        if err := verbose.RemoveSecret(verbose.SecretBytes(id)); err != nil {
            verbose.Printf("DELETE /keys/%s — RemoveSecret error: %v", id, err)
        }

        verbose.Printf("DELETE /keys/%s — revoked and removed from verbose (was issued to %s)",
            id, rec.IssuedTo)

        w.WriteHeader(http.StatusNoContent)
    }))
    // 3 lines below

Add generateToken below bearerToken:

// generateToken returns a cryptographically random token with the given prefix.
func generateToken(prefix string) (string, error) {
    b := make([]byte, 24)
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return prefix + hex.EncodeToString(b), nil
}

Mistake trap: Move verbose.AddSecret to after keyStoreMu.Lock() — just two lines later — and run the server. Issue a key. Look at the log line for POST /keys — issued key=. You will see the raw token value in plaintext because it was logged by requireAdmin in the auth check before it was registered. Order is not a style preference here. It is the security guarantee. Move AddSecret back to first.

Step 7 — The on-call engineer shift in action

The rotation goroutine has been running since Step 3, quietly updating a value. Now that verbose is wired, the mutation log entries are meaningful — and with Pollinate: true, an engineer can override the on-call value live from a second terminal without restarting the server.

The shift goroutine is already in place. The mutations goroutine is already using verbose.Printf from Step 4. Run the server and open a second terminal:

# terminal 1
KEYSERVER_ADMIN_TOKEN=mysecret go run .

# terminal 2 — override the on-call engineer without restarting
export ON_CALL_ENGINEER=Kevin

Watch logs/keyserver.log — within one minute you will see:

[VERBOSE] keyserver.go:XX: config mutation: on-call-engineer changed from Darron to Kevin at 2026-04-20...

The mutation fires because Pollinate: true causes figtree to re-read ON_CALL_ENGINEER every time figs.String(kOnCall) is called — which the rotation goroutine does every minute.

If the on-call engineer name were a sensitive internal codename — a security handle, a contractor alias, anything you would not want in a log shipped to an aggregator — one verbose.AddSecret(verbose.SecretBytes(name), "[ON_CALL]") call in the rotation goroutine would scrub it from every future log line. The pattern is identical to what you did with the admin token.

Mistake trap: Remove Pollinate: true from figtree.Options, restart the server, and set export ON_CALL_ENGINEER=Kevin again. No mutation fires. The env var changed but figtree did not re-read it because Pollinate was off. Put Pollinate: true back.

Step 8 — The bash test script

Create test.sh in the project root. This script is the pass/fail gate for the tutorial. If your implementation is correct it exits 0. Each assertion failure prints which step to revisit and exits immediately.

#!/usr/bin/env bash
set -euo pipefail

# ── dependency check ──────────────────────────────────────────────────────────
if ! command -v curl &>/dev/null; then
    echo "ERROR: curl is required. Install it and rerun."
    exit 1
fi
if ! command -v jq &>/dev/null; then
    echo "ERROR: jq is required."
    echo "  macOS:  brew install jq"
    echo "  Linux:  sudo apt install jq  OR  sudo yum install jq"
    exit 1
fi

# ── config ────────────────────────────────────────────────────────────────────
ADMIN_TOKEN="test-admin-secret-1234"
BASE="http://127.0.0.1:8080"
LOG_FILE="./logs/keyserver.log"

# ── helpers ───────────────────────────────────────────────────────────────────
pass() { echo "  PASS: $1"; }
fail() { echo "  FAIL: $1 — $2"; exit 1; }

assert_status() {
    local label="$1" expected="$2" actual="$3" step="$4"
    if [ "$actual" -ne "$expected" ]; then
        fail "$label" "expected HTTP $expected, got $actual (see step $step)"
    fi
    pass "$label"
}

assert_no_plaintext() {
    local label="$1" secret="$2" step="$3"
    if grep -qF "$secret" "$LOG_FILE" 2>/dev/null; then
        fail "$label" "plaintext secret found in log — verbose.AddSecret not called before logging (see step $step)"
    fi
    pass "$label"
}

assert_log_contains() {
    local label="$1" pattern="$2" step="$3"
    if ! grep -qF "$pattern" "$LOG_FILE" 2>/dev/null; then
        fail "$label" "expected '$pattern' in log — not found (see step $step)"
    fi
    pass "$label"
}

# ── build and start server ────────────────────────────────────────────────────
echo "=> building..."
go build -o keyserver_bin . || { echo "Build failed — fix compilation errors first."; exit 1; }

echo "=> starting server..."
KEYSERVER_ADMIN_TOKEN="$ADMIN_TOKEN" ./keyserver_bin &
SERVER_PID=$!
trap 'kill $SERVER_PID 2>/dev/null; rm -f keyserver_bin' EXIT

# wait for server to be ready — retry up to 10 times
for i in $(seq 1 10); do
    if curl -sf "$BASE/keys/test/verify" &>/dev/null; then
        break
    fi
    sleep 0.5
done

echo ""
echo "── assertion 1: admin token is scrubbed from logs (Step 4) ─────────────"
assert_no_plaintext "admin token not in log" "$ADMIN_TOKEN" "4"

echo ""
echo "── assertion 2: issue key for alice (Step 6) ────────────────────────────"
ALICE_RESP=$(curl -s -w "\n%{http_code}" -X POST "$BASE/keys" \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"issued_to":"alice@example.com"}')
ALICE_STATUS=$(echo "$ALICE_RESP" | tail -1)
ALICE_BODY=$(echo "$ALICE_RESP" | head -1)
assert_status "POST /keys alice" 201 "$ALICE_STATUS" "6"
ALICE_TOKEN=$(echo "$ALICE_BODY" | jq -r .token)

echo ""
echo "── assertion 3: issue key for bob (Step 6) ──────────────────────────────"
BOB_RESP=$(curl -s -w "\n%{http_code}" -X POST "$BASE/keys" \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"issued_to":"bob@example.com"}')
BOB_STATUS=$(echo "$BOB_RESP" | tail -1)
BOB_BODY=$(echo "$BOB_RESP" | head -1)
assert_status "POST /keys bob" 201 "$BOB_STATUS" "6"
BOB_TOKEN=$(echo "$BOB_BODY" | jq -r .token)

echo ""
echo "── assertion 4: issue key for carol (Step 6) ────────────────────────────"
CAROL_RESP=$(curl -s -w "\n%{http_code}" -X POST "$BASE/keys" \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"issued_to":"carol@example.com"}')
CAROL_STATUS=$(echo "$CAROL_RESP" | tail -1)
CAROL_BODY=$(echo "$CAROL_RESP" | head -1)
assert_status "POST /keys carol" 201 "$CAROL_STATUS" "6"
CAROL_TOKEN=$(echo "$CAROL_BODY" | jq -r .token)

echo ""
echo "── assertion 5: verify alice (Step 6) ───────────────────────────────────"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/keys/${ALICE_TOKEN}/verify" \
    -H "Authorization: Bearer $ALICE_TOKEN")
assert_status "GET /keys alice/verify" 200 "$STATUS" "6"

echo ""
echo "── assertion 6: verify bob (Step 6) ─────────────────────────────────────"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/keys/${BOB_TOKEN}/verify" \
    -H "Authorization: Bearer $BOB_TOKEN")
assert_status "GET /keys bob/verify" 200 "$STATUS" "6"

echo ""
echo "── assertion 7: verify carol (Step 6) ───────────────────────────────────"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/keys/${CAROL_TOKEN}/verify" \
    -H "Authorization: Bearer $CAROL_TOKEN")
assert_status "GET /keys carol/verify" 200 "$STATUS" "6"

echo ""
echo "── assertion 8: revoke bob (Step 6) ─────────────────────────────────────"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "$BASE/keys/${BOB_TOKEN}" \
    -H "Authorization: Bearer $ADMIN_TOKEN")
assert_status "DELETE /keys bob" 204 "$STATUS" "6"

echo ""
echo "── assertion 9: verify bob after revocation — expect 401 (Step 6) ───────"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/keys/${BOB_TOKEN}/verify" \
    -H "Authorization: Bearer $BOB_TOKEN")
assert_status "GET /keys bob/verify after revoke" 401 "$STATUS" "6"

echo ""
echo "── assertion 10: alice and carol tokens not in log (Step 6) ─────────────"
assert_no_plaintext "alice token not in log" "$ALICE_TOKEN" "6"
assert_no_plaintext "carol token not in log" "$CAROL_TOKEN" "6"

echo ""
echo "── assertion 11: bob token not in log (Step 6) ──────────────────────────"
# bob's token was removed via RemoveSecret after revocation.
# if the implementation is correct the token never appeared in plaintext
# because AddSecret was called before any logging.
assert_no_plaintext "bob token not in log" "$BOB_TOKEN" "6"

echo ""
echo "── assertion 12: scrub markers present in log (Step 4 + 6) ─────────────"
assert_log_contains "[ADMIN_TOKEN] in log" "[ADMIN_TOKEN]" "4"
assert_log_contains "[ISSUED_KEY] in log"  "[ISSUED_KEY]"  "6"

echo ""
echo "── assertion 13: on-call mutation visible in log (Step 7) ───────────────"
export ON_CALL_ENGINEER="TEAM"
echo "   waiting up to 90s for on-call mutation to appear in log..."
for i in $(seq 1 18); do
    if grep -qF "on-call-engineer" "$LOG_FILE" 2>/dev/null; then
        pass "on-call mutation in log"
        break
    fi
    sleep 5
    if [ "$i" -eq 18 ]; then
        fail "on-call mutation in log" "mutation not seen after 90s — check Pollinate:true and mutations goroutine (see step 7)"
    fi
done

echo ""
echo "════════════════════════════════════════════════════════════════════════"
echo "  All assertions passed. Your implementation is correct."
echo "════════════════════════════════════════════════════════════════════════"

Make it executable and run it:

chmod +x test.sh
./test.sh

If every assertion passes you see the final banner. If any assertion fails the script exits immediately with the step number to revisit. Fix that step and rerun — the script always starts fresh.

Step 9 — Closing: What You Built and What Comes Next

You started this tutorial with an empty directory and two go get commands. You finished with a running HTTP server that issues, verifies, and revokes API keys — and whose log file provably contains no plaintext secrets. Run ./test.sh one final time and watch every assertion pass. That exit 0 is not a formality. It is a guarantee backed by SHA-512.

Take a moment to understand what you actually built and why each piece was chosen.

verbose is not just a logger. Every other logger in the Go ecosystem — log, slog, zap, zerolog — will faithfully write whatever string you hand it. verbose is the only one that knows what your secrets are and refuses to write them. The moment you call verbose.AddSecret(verbose.SecretBytes(token), "[ISSUED_KEY]"), that token's SHA-512 digest enters a registry and every subsequent log line is scanned against it before it touches disk. The plaintext never persists inside verbose — not in memory, not on disk. When you called verbose.RemoveSecret on revocation, you kept that registry lean deliberately: a server that issues thousands of keys over its lifetime should not accumulate thousands of dead secrets in a scanner it runs on every single log call.

figtree is not just a flag parser. It is a priority-ordered configuration resolver — file, then environment, then CLI — with validators, rules, and a mutation channel that watches values change at runtime. RuleNoFlags on kAdminToken is not decoration. It is an enforcement boundary. The key name "keyserver-admin-token" being deliberately long is not an accident — it is a design statement: secrets should be inconvenient to pass on a command line because command lines end up in shell history, process lists, and CI logs.

The on-call rotation is a small thing, but it demonstrates something real: configuration is not static. Values change while a server runs. Pollinate: true and the mutations channel give you an observable, logged record of every change. In a real system that might be a database password rotating, a feature flag toggling, a rate limit updating. The pattern is identical regardless of what the value is.

The packages used in this tutorial are part of a larger body of open source work

Both verbose and figtree were written by Andrei Merlescu — @andreimerlescu on GitHub. His profile carries 99 public repositories built across 17 years of professional software engineering spanning Cisco, Oracle, Warner Bros. Games, and SurgePays, written primarily in Go, Ruby, PHP, and Bash.

Some repositories worth exploring alongside the two you just used:

checkfs — filesystem existence and permission checks for File and Directory. Pairs naturally with figtree when you want to validate that a config-supplied path actually exists before your server starts.
sema — semaphore primitives for Go. Useful when the keyserver you just built needs to limit concurrent issuance requests.
go-passwd — safe password auditing. If your keyserver ever needs to validate that an incoming credential meets a strength policy before issuing a key, this is the package.
summarize + aigcm — AI-assisted project summarization and git commit message generation using local Ollama models. If you are building on an M-series Mac with local models, these are worth looking at.
lemmings — load testing built around the concept of NPCs moving through your infrastructure as simulated users across geographic terrains and pack sizes. If you want to know what your keyserver does under real traffic before you ship it, lemmings is how you find out. It was built specifically because existing tools like ab did not answer the question Andrei needed answered when he launched Trakify in 2015 and got a surge of traffic from a Barron's Magazine feature. The tool he wished he had then exists now and it is free.

The code is yours. The packages are free. The log file is clean.

DEV Community: Andrei Merlescu

Rust Decorators for Go Developers

#[derive(...)] — Automatic Trait Implementation

#[arg(...)] — Clap CLI Argument Declaration

#[cfg(...)] — Conditional Compilation

#[macro_export] and #[macro_use] — Macro Visibility

#[repr(...)] — Memory Layout Control

#[non_exhaustive] — Future-Proof Enums and Structs

#[must_use] — Enforced Return Value Handling

#[inline] — Inlining Hints

#[test] — Unit Test Declaration

#[bench] — Benchmark Declaration

#[allow(...)], #[warn(...)], #[deny(...)], #[forbid(...)] — Lint Control

#[deprecated] — Deprecation Notices

#[serde(...)] — Serialization and Deserialization Attributes

Go Concurrency in Rust

Go vs Rust Concurrency Primitives: A Comprehensive Guide for Go Developers

Basic Thread / Goroutine Spawning

Channels (Message Passing)

WaitGroups / Thread Joining

Mutexes (Shared Mutable State)

Atomic Operations

RWMutex (Read-Write Locks)

Select / Select-like Patterns

Once (Single Initialization)

Context / Cancellation

Goroutine Pools / Thread Pools

Condition Variables

Async / Non-blocking Patterns

I Put Rust To The Test

I Put Rust 🦀 To A Test 🐿️

When Rust Wins

Why I Built This

andreimerlescu / rusty-xrp-addr

A rust utility for finding a vanity XRP wallet address that works with all XRP ledger wallets.

find-xrp-addr

Features

Getting Started / Compilation

Prerequisites

Build

Run

Humanized Software Engineering In Era Of AI

Dario Thinks My Job Won't Exist In A Year

Sam Altman Thinks AI Can Be For Profit

Elon Musk Thinks That He Is Righteous In His xAI

Humanizing Software Engineering - What It Means

AI Slop Creating Spaghetti Code

Per Character Systems Architecture Understandings

Conclusion

goini: Stop Writing Bash to Parse .ini Files

Installation

The Sample File

Validating With Exit Codes

Does a Section Have a Key?

Does a Key Have a Specific Value?

Are Multiple Sections All Present?

Does a Section Exist?

Reading With STDOUT

List All Sections

List Keys in a Section

List Key-Value Pairs in a Section

Writing to the File

Add a New Section

Add a Key to a Section

Modify an Existing Key

Real Pipeline Examples

Validating a Service Configuration Before Deploy

Bootstrapping a Fresh Config File

Promoting Config From Staging to Production

Extracting Values for Use in Other Scripts

GitHub Actions

GitLab CI

Complete Flag Reference

A Few Things Worth Knowing

goenv: Taming .env Files in Your DevOps Pipeline

The Problem With .env Files in Pipelines

What goenv Actually Is

Installation

CLI Tool

Go Package (env only, no CLI required)

`#[derive(...)]` — Automatic Trait Implementation

`#[arg(...)]` — Clap CLI Argument Declaration

`#[cfg(...)]` — Conditional Compilation

`#[macro_export]` and `#[macro_use]` — Macro Visibility

`#[repr(...)]` — Memory Layout Control

`#[non_exhaustive]` — Future-Proof Enums and Structs

`#[must_use]` — Enforced Return Value Handling

`#[inline]` — Inlining Hints

`#[test]` — Unit Test Declaration

`#[bench]` — Benchmark Declaration

`#[allow(...)]`, `#[warn(...)]`, `#[deny(...)]`, `#[forbid(...)]` — Lint Control

`#[deprecated]` — Deprecation Notices

`#[serde(...)]` — Serialization and Deserialization Attributes

Entropy Password Generator `entpassgen`

Generate Word Password `genwordpass`

What you can do with `bump`

Using `bump` in your future Go applications

The `bump` package