Why build a package's shared client behind a sync.Once instead of in an init() function?

## The two shapes Eager, at import time: ```go var client *http.Client func init() { client = dial(os.Getenv("SERVICE_ADDR")) } ``` Lazy, on first use: ```go var ( once sync.Once client *http.Client ) func shared() *http.Client { once.Do(func() { client = dial(os.Getenv("SERVICE_ADDR")) }) return client } ``` They differ on *when* the work happens, *who* pays for it, and *how failure travels*. ## What `init()` costs you **It runs whether or not anything needs it.** Package initialisation is driven by the import graph, not by use. A command-line tool that imports the package for one helper function still dials the service at start-up. A unit test for an unrelated function in the same package still dials it. So does `go test` on any package that imports it transitively. **It runs before the program is configured.** `init()` completes before `main` begins, so flags are unparsed and any configuration your program loads in `main` does not exist yet. The only inputs available are environment variables and compile-time constants, which is why eagerly initialised packages so often reach for `os.Getenv` and nothing else. **It cannot report failure.** `func init()` takes no parameters and returns no values. A failure has exactly two outlets: panic — killing a process that might not even need this package — or store the error in a variable and hope every accessor checks it. Neither hands a decision to a caller who could retry, fall back, or degrade. **It is hostile to tests.** A test cannot run before `init()`; the best it can do is set environment variables in `TestMain` before the package under test is loaded, which is fragile, or accept the dial. That makes packages with heavy `init()` slow and awkward to test. ## What the `sync.Once` version buys **Work is paid for by the first use, not by every process.** Binaries and tests that never call the accessor never construct anything. **The accessor has a signature.** Because you control it, it can be `func shared() (*http.Client, error)` and give the error to whoever asked. That alone removes the panic-at-import failure mode. **Setup order becomes explicit.** The value is built after `main` has read flags and configuration, so the initialiser can consume settings that did not exist at import time. **Concurrency is still handled.** The one thing `init()` did give you for free — no concurrent access, because it runs single-threaded before anything else — `sync.Once` restores: exactly one execution, and other callers block until it finishes. ## What lazy initialisation costs in exchange **Failure moves from boot to traffic.** A bad `SERVICE_ADDR` in the eager version stops the process on start-up, where a deployment system will notice. In the lazy version the process starts healthy and the first request discovers the problem — possibly minutes later, possibly under load, possibly on one instance and not another. **The first caller pays the latency.** If construction takes a second, some unlucky request takes a second longer. Under a cold start with a burst of traffic, everyone in that burst waits, because the other callers block inside `Do`. **A hidden global remains a hidden global.** The `sync.Once` accessor is still package-level mutable state with an implicit lifetime. Nothing in a function signature says the function depends on a client, so nothing forces a test to provide one. **Failure is not retried.** A `Once` cannot be re-armed. If the first attempt fails, every later caller in that process gets the same failure — a serious issue for anything that could succeed on a second try. ## The option that is usually right Most production services build their dependencies explicitly: `main` reads configuration, constructs the client, checks the error, and passes it into whatever needs it. That gets fail-fast start-up *and* a testable seam *and* a visible lifetime — including a place to close the thing. `sync.Once` earns its place where a global genuinely is the design: memoising something inside a library that callers should not have to construct, or a value that is expensive and only some code paths need. `init()` remains defensible for cheap, infallible, self-contained work — registering an image format or a database driver with a registry, building a lookup table — where there is nothing to fail and nothing to configure. ## The tell in the logs A useful diagnostic when you inherit such a package: log one line inside the initialiser. With `init()` it appears at start-up in every binary that imports the package. With `sync.Once` it appears at most once, on the first real use, and never again — which tells you both that the guard is working and exactly when the dependency was first needed.