Skip to content

ADR-0001: fx over wire for dependency injection

  • Status: Accepted
  • Date: 2026-04-13 (backfill — decision predates ADR practice)
  • Deciders: @lusoris
  • Tags: core, di, lifecycle

Context

Every framework module (config, log, db, http, jobs, …) needs to be composable so apps pull only what they need. Two mainstream Go DI tools:

  • google/wire — compile-time code generation. Static, fast, no runtime overhead.
  • uber-go/fx — runtime DI with explicit lifecycle (OnStart / OnStop) hooks.

The framework also needs ordered startup/shutdown (DB before HTTP, OTel before everything emitting telemetry, leader election before the outbox drainer). Per principles.md §2.1, no init() side effects are allowed — all wiring must be explicit.

Decision

We will use go.uber.org/fx as the dependency-injection and lifecycle backbone for every package in the framework. Every module exposes its capability as fx.Module or fx.Options; apps compose modules in fx.New(...).Run().

Alternatives considered

Option Pros Cons Why not chosen
google/wire Compile-time, zero runtime cost, errors caught early No lifecycle primitives — start/stop ordering is the app author's problem; codegen step on every change Lifecycle is the killer feature for our use case (DB → leader → drainer ordering). Manual ordering across 20+ apps doesn't scale.
Hand-rolled func New…(deps…) (*T, error) No deps, full control Every app re-implements wiring + lifecycle ordering. Defeats the framework's purpose. Reinvents the wheel.
uber-go/dig (fx's underlying container) Runtime DI, lighter than fx No lifecycle, no module composition — fx adds exactly what we need on top fx already wraps dig with the missing pieces.

Consequences

  • Positive: Apps wire 5-line fx.New(golusoris.Core, golusoris.DB, golusoris.HTTP, ...) instead of 100 lines of glue. Lifecycle hooks make ordered shutdown trivial. Each module is independently testable by composing only the deps it needs.
  • Negative: Runtime errors when graphs are misconfigured (missing provider, type collision) instead of compile-time errors. Mitigated by go test + fxtest.New(t, ...) in every module's tests.
  • Follow-ups: Every new module ships with an fx.Module + a smoke test (fxtest.New) verifying it can start + stop in isolation. Documented in .claude/skills/wire-fx-module.md.

References