README
¶
gostructor examples
Runnable, zero-setup programs that show gostructor from a first Configure
call up to a full production configuration. Every example writes any files it
needs to a temp dir and cleans up after itself, so you can just run it:
go run ./examples/<name>
Start at the top and work down — each one introduces a little more.
| Example | What it shows | Modules needed |
|---|---|---|
basic |
The minimum: a cfg base name (env) with a gos:"default:..." fallback. |
core only |
priority |
The headline feature — the same struct resolving differently per environment, purely from the WithSources order. |
core only |
filesources |
The two core file sources (json + ini) combined with env and defaults in one source-order chain. | core only |
types |
The breadth of supported field types from a JSON source: durations, slices/arrays, time.Time/net.IP, named types, pointers, maps, and slices/maps of structs. |
core only |
hooks |
WithHook for validation (reject out-of-range values) and transformation (normalise strings), on the typed value. |
core only |
errors |
A tour of the typed error taxonomy — trigger each failure and classify it with errors.Is/errors.As. |
core only |
observability |
ConfigureWithReport: the focused resolution trace (primary source, overrides & secrets), Provenance(), and gos:"secret" masking. |
core only |
webservice |
The big one. A full microservice config (~30 fields, nested sub-structs) assembled from a JSON base + env overrides + defaults, with masked secrets and a focused trace. | core only |
multisource |
A field with several sources including a real YAML file, plus a validation hook. Priority is the source order. | gostructor/yaml |
Live config & remote sources
These show gostructor.Watch — the struct re-fills when the backing source
changes. All but hotreload-file bring their backend up with docker-compose
and seed it, so each is fully reproducible; see the example's own README for the
exact commands.
| Example | What it shows | Backend |
|---|---|---|
hotreload-file |
Watch + fsnotify file source: edit a JSON file, the struct reloads. Transactional last-known-good via WithValidate. |
none (local file) |
git |
Config from a git repo, ref = version; drift polling and runtime SetVersion; snapshot fallback. |
git daemon (compose) |
consul |
Consul KV prefix, live via blocking queries. | hashicorp/consul (compose) |
etcd |
etcd key prefix, live via the native watch API. | etcd (compose) |
springcloud |
Spring Cloud Config Server over HTTP, live via polling. | spring-cloud-config-server (compose) |
vault |
Vault secrets with live rotation (polling); secret masking. | hashicorp/vault (compose) |
Suggested reading order
basic— get the shape ofConfigureand the two tags.priority— the one feature that sets gostructor apart from a plain unmarshaller: source-order priority, chosen at the call site.filesources/types— real sources and the full type range.hooks/errors— validation, transformation, and failure modes.observability— see why each field got the value it did.webservice— everything at once, at production scale.multisource— bringing in an external source module (YAML).
Most core examples live in the root module and need no extra setup.
multisource and every live-config example are their own modules (they pull in
an external source module) with replace directives pointing back at the repo,
so run each from its own directory: cd examples/<name> && go run ..
Directories
¶
| Path | Synopsis |
|---|---|
|
Command basic shows the minimum gostructor setup: env vars (named from each field via the cfg tag) with gos default fallbacks, using only the core module.
|
Command basic shows the minimum gostructor setup: env vars (named from each field via the cfg tag) with gos default fallbacks, using only the core module. |
|
Command errors tours gostructor's typed error taxonomy: it triggers each failure mode and classifies it with errors.Is / errors.As, so a caller can tell what went wrong and whose fault it is.
|
Command errors tours gostructor's typed error taxonomy: it triggers each failure mode and classifies it with errors.Is / errors.As, so a caller can tell what went wrong and whose fault it is. |
|
Command filesources shows the two core file sources, JSON and INI, used together on one struct with env and a gos default in the same priority chain.
|
Command filesources shows the two core file sources, JSON and INI, used together on one struct with env and a gos default in the same priority chain. |
|
Command hooks shows WithHook for two jobs: transforming a resolved value (normalise a string) and validating one (reject an out-of-range port), both operating on the already-converted, field-typed value.
|
Command hooks shows WithHook for two jobs: transforming a resolved value (normalise a string) and validating one (reject an out-of-range port), both operating on the already-converted, field-typed value. |
|
Command observability shows gostructor's focused resolution trace: a summary line, the primary source, the defaults count, and an Overrides & Secrets section listing only the fields that were overridden away from the primary config or that are secret (masked).
|
Command observability shows gostructor's focused resolution trace: a summary line, the primary source, the defaults count, and an Overrides & Secrets section listing only the fields that were overridden away from the primary config or that are secret (masked). |
|
Command priority shows how gostructor expresses priority: the SAME struct resolves DIFFERENTLY purely from the ORDER of sources passed to WithSources.
|
Command priority shows how gostructor expresses priority: the SAME struct resolves DIFFERENTLY purely from the ORDER of sources passed to WithSources. |
|
Command types shows the range of field types gostructor fills from a single structured source (a JSON file here): durations, slices and arrays, TextUnmarshaler types (time.Time, net.IP), named scalar types, pointers, maps, and slices/maps of structs, all with strict, lossless conversion.
|
Command types shows the range of field types gostructor fills from a single structured source (a JSON file here): durations, slices and arrays, TextUnmarshaler types (time.Time, net.IP), named scalar types, pointers, maps, and slices/maps of structs, all with strict, lossless conversion. |
|
Command webservice is a production-style microservice configuration assembled from three layers:
|
Command webservice is a production-style microservice configuration assembled from three layers: |
Click to show internal directories.
Click to hide internal directories.