A Go library that maps one annotated struct to and from YAML, environment variables and key-value stores. Saving a YAML file keeps its comments and key order.

The problem

Most Go config libraries go one way. They fill a struct from a file or the environment and stop. Writing the same struct back means a second set of tags and a second mapping, and the two drift apart. When a tool does write YAML back, it usually rewrites the file and throws away the comments a person put there.

What I built

ferry drives both directions off one struct tag. Load fills a struct from a source, Dump writes it to a sink. Load from a YAML file and dump to a key-value store in two calls, with no intermediate format.

Drivers exist for environment variables (load only), YAML (load and dump) and a Consul-shaped KV store. A save through the YAML driver edits the document in place, so comments, key order and keys your struct doesn't know about all survive.

How it works

The core has no non-stdlib dependencies. A struct type compiles once into a cached schema, and a driver is two methods: it receives the set of addresses the type needs and returns a function that does the I/O. Sources and sinks are separate interfaces, so dumping to environment variables is a compile error at the call site.

Defaults are parsed by the same codec as the field, so default=30s and timeout: 30s in a file mean exactly the same thing. There is a one-call conformance suite for anyone writing a new driver.

Every design decision is written down in 15 ADRs, which serve as the spec.

Outcome

v0, on purpose, while the tag grammar gets real use. The README publishes a benchmark table generated by a harness that refuses to run unless every library produces the identical struct. On YAML, ferry is 1.5 to 2 times faster than viper.