di

README

di

A dependency-injection container for Go 1.27+, built on generic methods. Register services with s.Provide(...), resolve them with s.Get[T](). No reflection over your constructors, no code generation, no dependencies.

app := di.New()
app.Provide(func(s *di.Scope) *DB { return s.Must(sql.Open("postgres", dsn)) }).
    OnStop(func(ctx context.Context, db *DB) error { return db.Close() })
app.Provide(func(s *di.Scope) *Repo { return &Repo{db: s.Get[*DB]()} })

repo, err := app.Resolve[*Repo]()

• Keys are Go types. No naming scheme, no string collisions between packages.
• Constructors return T, not (T, error). A missing dependency or a failed constructor unwinds to the enclosing Resolve or Start as an error that names the full dependency path and the registration site.
• Typed lifecycle. OnStart, OnDrain, OnStop and Worker hooks are typed on the service. Nothing is discovered by sniffing interfaces.
• Deterministic shutdown. Reverse build order, child scopes first, every error reported.
• Scopes for requests and tests. Child scopes shadow their parent; the last registration of a key wins until that key has served a value.

Installation

go get github.com/floatdrop/di

Requires Go 1.27 or newer. Editor support for generic methods needs gopls v0.23 or newer.

Quick start

Every embedded example in this document is a compiled program under examples/, built in CI.

// Quick start: register a few services, start and stop the application.
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/floatdrop/di"
)

type Config struct{ DSN string }
type DB struct{ dsn string }
type Repo struct{ db *DB }
type Server struct{ repo *Repo }

func main() {
	app := di.New()

	app.Value(Config{DSN: "postgres://localhost/app"})

	app.Provide(func(s *di.Scope) *DB { return &DB{dsn: s.Get[Config]().DSN} }).
		OnStop(func(ctx context.Context, db *DB) error { fmt.Println("db closed"); return nil })

	app.Provide(func(s *di.Scope) *Repo { return &Repo{db: s.Get[*DB]()} })

	app.Provide(func(s *di.Scope) *Server { return &Server{repo: s.Get[*Repo]()} }).
		Eager().
		OnStart(func(ctx context.Context, srv *Server) error { fmt.Println("listening"); return nil }).
		OnStop(func(ctx context.Context, srv *Server) error { fmt.Println("server stopped"); return nil })

	ctx := context.Background()
	if err := app.Start(ctx); err != nil {
		log.Fatal(err)
	}
	defer func() {
		if err := app.Stop(ctx); err != nil {
			log.Println(err)
		}
	}()

	fmt.Println("serving", app.Get[*Server]().repo.db.dsn)
}

Guide

Registration

Each registration returns a typed Binding[T]. Its methods refine the registration and must be called before the scope is first resolved.

Call	Registers
s.Provide(func(*di.Scope) T)	A lazily built singleton. T is inferred.
s.Value(v)	An instance you already have.

Method	Effect
.Scoped()	One instance per resolving scope, built and stopped there.
.Group()	A member of the group for T, read back with s.All[T]().
.Eager()	Build during Start, in registration order.
.OnStart(f), .OnStop(f)	Lifecycle hooks, f is func(context.Context, T) error.
.OnDrain(f)	Runs before anything is stopped, while the scope still resolves.
.Worker(f)	A long-running function, cancelled on stop.

An interface is served by a constructor that returns the implementation:

app.Provide(func(s *di.Scope) Reader { return s.Get[*Repo]() })

The compiler checks that *Repo satisfies Reader, and the two keys share one instance because the constructor returns the same pointer. Declare it Scoped() as well when the target is.

Rules the container enforces:

• The last registration of a key wins. That is how a child scope shadows its parent and how a test substitutes a fake.
• Once a key has served a value it can no longer be replaced, in the scope that owns it or in any scope that resolved through it. Replacing it would leave one key with two live values, so it panics instead. A resolution that failed built nothing and leaves the key re-registerable.
• Combinations that cannot be honoured are rejected when the scope is first resolved, whatever order the methods were called in: Eager on a scoped binding, and Scoped on a Value.

Resolution

Call	Returns
s.Get[T]()	T. Inside a constructor a failure unwinds to the caller; at top level it panics with the error.
s.Resolve[T]()	(T, error). Never panics on a wiring problem.
s.Maybe[T]()	(T, bool), for optional dependencies.
s.All[T]()	Every member of the group for T, across the scope chain.
s.Must(v, err)	v, or aborts the constructor with err.
s.Context()	The context passed to Start, so constructors can dial with a deadline.

Errors wrap di.ErrNotProvided, di.ErrCycle or di.ErrStopped:

di: building *app.Repo (provided at app/wire.go:31): *app.DB: not provided (needed by [*app.Repo])
di: building *app.A (provided at ...): di: building *app.B (provided at ...): di: dependency cycle: [*app.A *app.B] -> *app.A

Scopes

A child scope resolves through its parent, reuses the parent's singletons, and owns the lifecycle of what it builds itself.

// Scopes: a child scope sees everything in its parent and can shadow it.
package main

import (
	"fmt"

	"github.com/floatdrop/di"
)

type DB struct{ dsn string }
type User struct{ Name string }
type Handler struct {
	db   *DB
	user *User
}

func main() {
	app := di.New()
	app.Provide(func(*di.Scope) *DB { return &DB{dsn: "postgres://localhost/app"} })

	// One child per request: request-scoped values live here, shared
	// singletons such as *DB are reused from app.
	req := app.Child("request")
	req.Value(&User{Name: "ada"})
	req.Provide(func(s *di.Scope) *Handler {
		return &Handler{db: s.Get[*DB](), user: s.Get[*User]()}
	})

	h := req.Get[*Handler]()
	fmt.Println(h.user.Name, "->", h.db.dsn)
	fmt.Println("same db:", h.db == app.Get[*DB]())
}

A singleton is built in the scope that registered it, so a child cannot rewire a parent's singleton. A service that must see child-scoped values is declared Scoped(): one instance per resolving scope, built there.

Groups

Group() makes a registration one member of the group for its type rather than the binding for it, and All resolves every member across the scope chain. A health endpoint is the usual case. There is no health-check hook, because a group of checkers is the same thing in user code, and the handler decides what healthy means:

type Checker interface{ Check(ctx context.Context) error }

app.Provide(func(s *di.Scope) Checker { return s.Get[*DB]() }).Group()

mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
    for _, c := range app.All[Checker]() {
        if err := c.Check(r.Context()); err != nil {
            http.Error(w, err.Error(), http.StatusServiceUnavailable)
            return
        }
    }
    fmt.Fprintln(w, "ok")
})

All builds any member not built yet, so a checker's target is up by the time it is asked. Members keep their own lifetime and hooks, and a plain registration of the same type is neither shadowed by the group nor part of it.

Lifecycle

Start builds every Eager binding, then runs OnStart hooks in build order. If a constructor or hook fails, Start stops the scope and returns both errors; that rolls back exactly the services that started, child scopes included. A service built after Start runs its OnStart as part of being built, so nothing is handed out unstarted.

Stop runs in three phases. It drains, then stops child scopes, then runs OnStop hooks in reverse build order, and returns every failure joined. A service is stopped only when its stop is owed: its OnStart succeeded, or it has no OnStart to pair with, in which case OnStop is a plain destructor. Afterwards the scope and everything under it refuses to resolve, with di.ErrStopped.

Stop is idempotent and safe to call concurrently: only the first call tears the scope down, and the others wait for it and report its result. A hook must therefore not call Stop on its own scope or an ancestor, which would be a wait on itself; call Shutdown, which never blocks.

Start hooks must not block. A server binds its listener synchronously, so a busy port fails Start, then serves in a goroutine.

Draining

OnDrain runs before anything is stopped, from the innermost scope outwards and in reverse build order, while every scope still resolves normally. It is where a service stops taking new work and waits for the work it already has.

app.Provide(newServer).Eager().
    OnDrain(func(ctx context.Context, srv *http.Server) error { return srv.Shutdown(ctx) }).
    OnStop(func(ctx context.Context, srv *http.Server) error { return srv.Close() })

An HTTP server is the case that needs it. Its handlers hold request scopes that are children of the application scope, so shutting the server down from OnStop would be racing the teardown of the scopes those handlers are still using: a request in flight would start failing with di.ErrStopped before the server had finished waiting for it. Draining first gives handlers their scopes and dependencies until they return.

Workers

Worker is for anything that loops until told to stop: consumers, pollers, schedulers.

app.Provide(newMailer).Eager().Worker(func(ctx context.Context, m *Mailer) error {
    return m.Loop(ctx) // returns when ctx is cancelled
})

The function runs in its own goroutine from the moment the service starts. Its context is cancelled when the service stops, and Stop waits for it within the stop deadline. Returning an error calls Shutdown, so a worker that dies takes the application down rather than leaving it half alive. That holds even if the worker only reports the failure once shutdown is under way, since when an error surfaces says nothing about what caused it; returning context.Canceled after cancellation is the one case that means nothing more than "I stopped".

Request scopes

dihttp.Middleware gives each request a child scope holding the *http.Request, attaches it to the request context, and stops it when the handler returns. It has the usual func(http.Handler) http.Handler shape, so a router's Use accepts it too.

import "github.com/floatdrop/di/dihttp"

srv := &http.Server{Handler: dihttp.Middleware(app)(mux)}

mux.HandleFunc("GET /hello", func(w http.ResponseWriter, r *http.Request) {
    req, _ := di.FromContext(r.Context())
    user := req.Get[*User]()
})

Services that depend on the request are declared once, in the root, as Scoped(); they are built per request, cached for its duration, and stopped with it:

app.Provide(func(s *di.Scope) *User {
    return &User{Name: s.Get[*http.Request]().Header.Get("X-User")}
}).Scoped()

di.WithScope and di.FromContext are the primitives if you are not using net/http. A complete service with a worker, a health endpoint, request scopes and graceful shutdown is in examples/app.

Graceful shutdown

Run is the main-function helper. It starts the scope, blocks until the context is cancelled, SIGINT or SIGTERM arrives, or Shutdown is called, then stops everything with a bounded context. A second signal during the stop cancels that context, so a hung hook cannot keep the process alive.

// Graceful shutdown of an HTTP server.
//
// Run starts the scope, waits for SIGINT/SIGTERM or a Shutdown call, then
// stops everything in reverse order with a bounded context. The server's
// OnDrain calls http.Server.Shutdown, which stops accepting connections and
// waits for in-flight requests until the stop context expires. Draining runs
// before anything is torn down, so those requests still have their scopes.
package main

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

	"github.com/floatdrop/di"
)

type DB struct{ dsn string }

func main() {
	app := di.New()

	app.Provide(func(*di.Scope) *DB { return &DB{dsn: "postgres://localhost/app"} }).
		OnStop(func(ctx context.Context, db *DB) error { log.Println("db closed"); return nil })

	app.Provide(func(s *di.Scope) http.Handler {
		db := s.Get[*DB]()
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			time.Sleep(2 * time.Second) // simulate slow work that must not be cut short
			fmt.Fprintln(w, "served by", db.dsn)
		})
	})

	app.Provide(func(s *di.Scope) *http.Server {
		return &http.Server{Addr: ":8080", Handler: s.Get[http.Handler]()}
	}).
		Eager().
		OnStart(func(ctx context.Context, srv *http.Server) error {
			// Bind synchronously so a busy port fails Start; serve in the background.
			ln, err := net.Listen("tcp", srv.Addr)
			if err != nil {
				return err
			}
			log.Println("listening on", ln.Addr())
			go func() {
				if err := srv.Serve(ln); !errors.Is(err, http.ErrServerClosed) {
					app.Shutdown(err) // the listener died: stop the whole application
				}
			}()
			return nil
		}).
		// OnDrain runs before anything is stopped, so handlers that are
		// still running keep their scopes and dependencies.
		OnDrain(func(ctx context.Context, srv *http.Server) error {
			log.Println("draining")
			return srv.Shutdown(ctx) // waits for in-flight requests, bounded by StopTimeout
		}).
		OnStop(func(ctx context.Context, srv *http.Server) error { return srv.Close() })

	// Blocks until Ctrl-C, SIGTERM, or app.Shutdown. A second signal cancels
	// the stop context so a hung hook cannot keep the process alive.
	if err := app.Run(context.Background(), di.StopTimeout(10*time.Second)); err != nil {
		log.Fatal(err)
	}
}

Observability

app.Observe(func(ev di.Event) {
    if ev.Kind == di.EventBuild {
        buildDuration.WithLabelValues(ev.Service).Observe(ev.Duration.Seconds())
    }
})

Observers receive an Event for every constructor and every OnStart, OnDrain and OnStop hook in the scope and its descendants, plus one per Shutdown. Each event names the service, its scope, the registration site, the duration and the error, if any.

Testing your application

di.Test wires the production graph into a fresh scope and stops it when the test ends, failing the test if a stop hook errors. Override what you need before anything is resolved.

package app

import (
	"testing"

	"github.com/floatdrop/di"
)

func TestRepo(t *testing.T) {
	s := di.Test(t, Wire)                // production graph, stopped when the test ends
	s.Value(&DB{DSN: "sqlite://memory"}) // later registration wins: replaces the production *DB

	repo := s.Get[*Repo]() // built against the fake DB
	if repo.DB.DSN != "sqlite://memory" {
		t.Fatalf("got %q", repo.DB.DSN)
	}
}

Design notes

Why generic methods. Before Go 1.27 a typed container had to expose package-level functions such as do.Invoke[T](injector), and every variation became another function. With generic methods the whole API lives on one concrete type and reads left to right. The trade-off is that generic methods cannot appear on interfaces, so *di.Scope is concrete; substitute dependencies through scopes rather than by mocking the container.

Concurrency. Resolution is safe from many goroutines, including goroutines a constructor starts for itself. Each singleton is built at most once however many resolutions race for it, and the resolution path is an immutable linked list, so parallel branches share nothing. Once the scope is running, a resolution returns only a service whose OnStart has finished, waiting if another goroutine is starting it. A cycle is reported as di.ErrCycle even when the two halves are being built concurrently, which needs a wait-for graph rather than the per-branch path alone.

Three re-entrancy limits apply. In a goroutine a constructor started, use Resolve rather than Get: Get reports failure by panicking, and that panic has no enclosing call to unwind to from another goroutine. An OnStart hook must not resolve a service that depends on the one being started, which would be a wait on itself. And no hook may call Stop on its own scope or an ancestor, for the same reason; Shutdown never blocks.

Known limitations. The dependency graph is only known once constructors run, so a missing dependency of a lazy service surfaces on first resolution, or at Start if the service is eager; there is no whole-graph validation (#3). Stop is synchronous with one exception: when its own context expires while a hook is still running, the missed deadline is reported to the caller and the release finishes on a goroutine of its own, reaching observers. A build that completes after its scope stopped is undone the same way.

Performance

benchmarks/ is a separate module comparing this package with samber/do on the same four-service graph, so the library itself stays dependency-free. On an Apple M3 Max:

	Warm resolve	Cold register and build
di	45 ns, 2 allocs	3.8 µs, 67 allocs
do v2.1	140 ns, 6 allocs	6.2 µs, 120 allocs

cd benchmarks && go test -bench . -benchmem

Versioning

While the major version is 0, a minor bump may change behaviour. Every entry in CHANGELOG.md and on the releases page says whether an upgrade can break a caller.

Contributing

Alongside one regression test per historical defect, generative suites guard the parts that proved easiest to get wrong: a property test over random registration sequences, a model-based test over random operation sequences checked against documented invariants and a lifecycle model, the same operations run in parallel lanes under the race detector, and fuzz targets over both.

go test -race ./...
go test -run '^$' -fuzz 'FuzzMachine$' -fuzztime 2m .
go test -race -run '^$' -fuzz FuzzMachineConcurrent -fuzztime 2m .

The code blocks in this README are embedded from examples/ with embedmd. After editing an example:

gofmt -w examples/ && go run github.com/campoy/embedmd@v1.0.0 -w README.md

License

MIT

Documentation

Overview

Package di is a dependency-injection container for Go 1.27+ built on generic methods.

Services are registered on a Scope and resolved from it by type:

app := di.New()
app.Value(Config{DSN: "postgres://localhost/app"})
app.Provide(func(s *di.Scope) *DB { return s.Must(sql.Open("postgres", s.Get[Config]().DSN)) }).
	OnStop(func(ctx context.Context, db *DB) error { return db.Close() })
app.Provide(func(s *di.Scope) *Repo { return &Repo{db: s.Get[*DB]()} })

repo, err := app.Resolve[*Repo]()

Keys are Go types, so there is no naming scheme and no collisions between packages. Constructors return T rather than (T, error): inside a constructor, Scope.Get and Scope.Must abort on failure and the error surfaces from the enclosing Scope.Resolve, Scope.Start or Scope.Run with the dependency path and the registration site.

Lifetimes

A binding is a singleton by default, cached in the scope that registered it. Binding.Scoped makes it one instance per resolving scope, built there so it can see that scope's values, which is how request-scoped services are declared once in the root. Binding.Group and Scope.All handle groups, and Scope.Maybe resolves optional dependencies. An interface is served by a constructor that returns the implementation: s.Provide(func(s *Scope) Reader { return s.Get[*Repo]() }).

Scopes

Scope.Child creates a scope that resolves through its parent, reuses the parent's singletons and owns the lifecycle of what it builds. The last registration of a key wins, which is the test seam: wire the production graph into a fresh scope, then re-register what you want faked before anything is resolved (Test does the bookkeeping). For HTTP, github.com/floatdrop/di/dihttp.Middleware gives each request a child scope holding the *http.Request, reachable through FromContext.

Lifecycle

Binding.OnStart, Binding.OnDrain and Binding.OnStop are typed hooks. Scope.Start builds Binding.Eager bindings and runs start hooks in build order, rolling back on failure; services built later start as part of being built. Scope.Stop first drains, which lets work already in flight finish while the scope still resolves, then stops child scopes, then services in reverse build order, and afterwards the scope refuses to resolve anything. Binding.Worker runs a long-lived function that is cancelled on stop. Scope.Run ties it together for a main function: start, wait for a signal or Scope.Shutdown, stop with a deadline. Scope.Observe reports every step for logging and metrics.

Concurrency

A Scope is safe to use from many goroutines, including from goroutines a constructor starts for itself: the resolution path is immutable, so branches that run in parallel share nothing. A constructor may also keep the Scope it was handed and resolve through it later, once its own service is built; the finished part of that path is no longer a dependency, so such a resolution is not a cycle. A service is built once however many resolutions race for it, and a resolution of a running scope returns only a service whose start step has finished. A cycle is reported as ErrCycle even when the two halves are being built concurrently.

Three re-entrancy limits apply. A goroutine started by a constructor must use Scope.Resolve rather than Scope.Get, because Get reports failure by panicking and that panic cannot unwind to the enclosing call from another goroutine. An Binding.OnStart hook must not resolve a service that depends on the one being started: the hook already holds the value, and waiting for itself cannot make progress. And no hook may call Scope.Stop on its own scope or an ancestor, because Stop waits for the very step the hook is running; call Scope.Shutdown, which never blocks.

Example

package main

import (
	"context"
	"fmt"

	"github.com/floatdrop/di"
)

type Server struct{ repo *Repo }

func main() {
	app := di.New()
	app.Value(Config{DSN: "pg://primary"})
	app.Provide(func(s *di.Scope) *DB { return &DB{dsn: s.Get[Config]().DSN} }).
		OnStop(func(ctx context.Context, db *DB) error { fmt.Println("close", db.dsn); return nil })
	app.Provide(func(s *di.Scope) *Repo { return &Repo{db: s.Get[*DB]()} })
	app.Provide(func(s *di.Scope) Reader { return s.Get[*Repo]() })
	app.Provide(func(s *di.Scope) *Server { return &Server{repo: s.Get[*Repo]()} }).Eager().
		OnStart(func(context.Context, *Server) error { fmt.Println("listening"); return nil }).
		OnStop(func(context.Context, *Server) error { fmt.Println("stopped"); return nil })

	if err := app.Start(context.Background()); err != nil {
		panic(err)
	}
	fmt.Println("read:", app.Get[Reader]().Read())
	_ = app.Stop(context.Background())
}

Output:
listening
read: pg://primary
stopped
close pg://primary

Index

• Variables
• func WithScope(ctx context.Context, s *Scope) context.Context
• type Binding
  • func (b Binding[T]) Eager() Binding[T]
  • func (b Binding[T]) Group() Binding[T]
  • func (b Binding[T]) OnDrain(f func(context.Context, T) error) Binding[T]
  • func (b Binding[T]) OnStart(f func(context.Context, T) error) Binding[T]
  • func (b Binding[T]) OnStop(f func(context.Context, T) error) Binding[T]
  • func (b Binding[T]) Scoped() Binding[T]
  • func (b Binding[T]) Worker(f func(context.Context, T) error) Binding[T]
• type Event
• type EventKind
• type RunOption
  • func StopTimeout(d time.Duration) RunOption
• type Scope
  • func FromContext(ctx context.Context) (*Scope, bool)
  • func New() *Scope
  • func Test(tb TB, wire ...func(*Scope)) *Scope
  • func (s *Scope) All[T any]() []T
  • func (s *Scope) Child(name string) *Scope
  • func (s *Scope) Context() context.Context
  • func (s *Scope) Get[T any]() T
  • func (s *Scope) Maybe[T any]() (T, bool)
  • func (s *Scope) Must[T any](v T, err error) T
  • func (s *Scope) Observe(fn func(Event))
  • func (s *Scope) Provide[T any](ctor func(*Scope) T) Binding[T]
  • func (s *Scope) Resolve[T any]() (v T, err error)
  • func (s *Scope) Run(ctx context.Context, opts ...RunOption) error
  • func (s *Scope) Shutdown(cause error)
  • func (s *Scope) Start(ctx context.Context) error
  • func (s *Scope) Stop(ctx context.Context) error
  • func (s *Scope) Value[T any](v T) Binding[T]
• type TB

Examples

• Package
• Binding.Scoped
• Binding.Worker
• Scope.Observe

Variables

var (
	ErrNotProvided = errors.New("not provided")
	ErrCycle       = errors.New("dependency cycle")
	ErrStopped     = errors.New("scope stopped")
)

Functions

func WithScope

func WithScope(ctx context.Context, s *Scope) context.Context

WithScope attaches s to ctx so handlers and their callees can reach it with FromContext.

Types

type Binding

type Binding[T any] struct {
	// contains filtered or unexported fields
}

Binding is the typed handle returned by Provide/Value. Its methods refine the registration; they must be called before the first resolution from this scope.

func (Binding[T]) Eager

func (b Binding[T]) Eager() Binding[T]

Eager builds the service during Start rather than on first use.

Eagerness belongs to the key, not the registration: it means the service exists by the time Start returns. Overriding an eager binding therefore keeps the key eager and builds the replacement; a replacement with a per-scope lifetime, which cannot be built once at Start, is rejected.

func (Binding[T]) Group

func (b Binding[T]) Group() Binding[T]

Group makes the binding a member of the multi-binding group for T instead of the binding for T: it neither shadows nor is shadowed by another registration of T, and the members are read back together with s.All[T](). A member keeps its own lifetime and hooks.

func (Binding[T]) OnDrain

func (b Binding[T]) OnDrain(f func(context.Context, T) error) Binding[T]

OnDrain runs before anything is stopped: Stop drains the whole tree, from the innermost scope outwards and in reverse build order, while every scope still resolves normally. It is where a service stops accepting new work and waits for the work it already has, such as an HTTP server that must finish in-flight requests whose handlers still need their request scope. Anything those handlers build, including a request scope of their own, is drained before the phase ends. Use OnStop for the release that follows.

func (Binding[T]) OnStart

func (b Binding[T]) OnStart(f func(context.Context, T) error) Binding[T]

Typed lifecycle hooks: no interface sniffing, no reflection.

OnStart runs once the service is built, and only a hook that returns normally starts it: one that panics fails the start step, like a panicking constructor, and the service is never served.

func (Binding[T]) OnStop

func (b Binding[T]) OnStop(f func(context.Context, T) error) Binding[T]

func (Binding[T]) Scoped

func (b Binding[T]) Scoped() Binding[T]

Scoped makes the binding one-per-scope: each scope that resolves it gets its own instance, built in that scope (so it can see that scope's values) and stopped with it. Declare request-scoped services once in the root and resolve them through the request scope.

Example

package main

import (
	"context"
	"fmt"

	"github.com/floatdrop/di"
)

type Session struct{ ID string }

func main() {
	app := di.New()
	// Declared once in the root, built once per scope that resolves it.
	app.Provide(func(s *di.Scope) *Session { return &Session{ID: s.Get[string]()} }).Scoped()

	for _, id := range []string{"a1", "b2"} {
		req := app.Child("request")
		req.Value(id)
		first, again := req.Get[*Session](), req.Get[*Session]()
		fmt.Println(first.ID, first == again)
		_ = req.Stop(context.Background())
	}
}

Output:
a1 true
b2 true

func (Binding[T]) Worker

func (b Binding[T]) Worker(f func(context.Context, T) error) Binding[T]

Worker registers a long-running function for T, such as a consumer loop. It is started in its own goroutine once the service starts and its context is cancelled when the service stops; Stop waits for it to return, bounded by its own context. A hook that outlasts that deadline is reported by Stop, and OnStop then waits for it rather than releasing the value underneath a worker still reading it.

Returning a non-nil error calls Shutdown with it, stopping the application, even if the scope was already stopping: a worker may fail, flush while the scope winds down, and only then report. The exception is context.Canceled from a hook that was already cancelled, which is a worker reporting the cancellation and nothing else. A hook that wants to stay quiet during shutdown should return nil.

Example

package main

import (
	"context"
	"fmt"

	"github.com/floatdrop/di"
)

type Queue struct{ jobs chan string }

func main() {
	app := di.New()
	done := make(chan string, 1)
	app.Provide(func(*di.Scope) *Queue { return &Queue{jobs: make(chan string, 1)} }).Eager().
		Worker(func(ctx context.Context, q *Queue) error {
			for {
				select {
				case job := <-q.jobs:
					done <- "processed " + job
				case <-ctx.Done():
					return nil // cancelled by Stop
				}
			}
		})

	ctx := context.Background()
	if err := app.Start(ctx); err != nil {
		panic(err)
	}
	app.Get[*Queue]().jobs <- "email"
	fmt.Println(<-done)
	fmt.Println("stop:", app.Stop(ctx)) // waits for the worker to return
}

Output:
processed email
stop: <nil>

type Event

type Event struct {
	Kind     EventKind
	Service  string // the service, e.g. "*github.com/acme/app.DB"; empty for shutdown
	Scope    string // name of the scope that owns the instance
	Site     string // file:line of the registration; empty for shutdown
	Duration time.Duration
	Err      error
}

Event describes one lifecycle step. Observers receive it after the step completes, with its duration and error if any.

type EventKind

type EventKind string

EventKind classifies an Event.

const (
	EventBuild    EventKind = "build"    // a constructor ran
	EventStart    EventKind = "start"    // an OnStart hook ran
	EventDrain    EventKind = "drain"    // an OnDrain hook ran
	EventStop     EventKind = "stop"     // a Worker hook was cancelled and/or an OnStop hook ran
	EventShutdown EventKind = "shutdown" // Shutdown was called
)

type RunOption

type RunOption func(*runConfig)

RunOption configures Run.

func StopTimeout

func StopTimeout(d time.Duration) RunOption

StopTimeout bounds how long Stop may take once Run decides to exit. The default is 15 seconds.

type Scope

type Scope struct {
	// contains filtered or unexported fields
}

Scope is a container. A Scope value handed to a constructor is a view over the same state that carries the current resolution path.

func FromContext

func FromContext(ctx context.Context) (*Scope, bool)

FromContext returns the scope attached with WithScope, if any.

func New

func New() *Scope

func Test

func Test(tb TB, wire ...func(*Scope)) *Scope

Test returns a scope for a test: the wire functions register the graph under test, and the scope is stopped when the test ends, failing it if a stop hook errors. Override what you need faked after wiring and before resolving; the last registration wins.

s := di.Test(t, app.Wire)
s.Value(&DB{DSN: "sqlite://memory"})
repo := s.Get[*Repo]()

func (*Scope) All

func (s *Scope) All[T any]() []T

All resolves the multi-binding group for T across the scope chain. Members are singletons (or Scoped if so marked) with the same lifecycle as any other binding.

func (*Scope) Child

func (s *Scope) Child(name string) *Scope

Child creates a scope that resolves through s. Stopping s stops its children first.

A child made inside a constructor carries that constructor's resolution path, so a cycle through it is reported rather than deadlocking. The path goes inert when the constructor returns (see resolver.done), so a child kept for later, such as a request scope, resolves as an independent branch.

func (*Scope) Context

func (s *Scope) Context() context.Context

Context returns the context passed to Start (or Run) on this scope or the nearest started ancestor, so constructors can dial with a deadline. Before Start it returns context.Background().

func (*Scope) Get

func (s *Scope) Get[T any]() T

Get resolves T. Inside a constructor, failure unwinds to the enclosing Resolve/Start call and becomes an error; at top level it panics. In a goroutine a constructor started, use Resolve instead: that panic has no enclosing call to unwind to and would take the process down.

func (*Scope) Maybe

func (s *Scope) Maybe[T any]() (T, bool)

Maybe resolves T if it is provided anywhere in the scope chain.

func (*Scope) Must

func (s *Scope) Must[T any](v T, err error) T

Must unwraps a (value, error) pair inside a constructor:

db := s.Must(sql.Open("postgres", dsn))

A non-nil error aborts the constructor and surfaces from the enclosing Resolve, Start or Run. Outside a constructor it panics with the error.

func (*Scope) Observe

func (s *Scope) Observe(fn func(Event))

Observe registers fn to receive lifecycle events from this scope and every scope under it. Use it for logging and metrics.

Example

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/floatdrop/di"
)

type Cache struct{}

func main() {
	app := di.New()
	app.Observe(func(ev di.Event) {
		fmt.Println(ev.Kind, ev.Service, ev.Err)
	})
	app.Provide(func(*di.Scope) *Cache { return &Cache{} }).
		OnStop(func(context.Context, *Cache) error { return errors.New("flush failed") })

	app.Get[*Cache]()
	_ = app.Stop(context.Background())
}

Output:
build *github.com/floatdrop/di_test.Cache <nil>
stop *github.com/floatdrop/di_test.Cache di: stopping *github.com/floatdrop/di_test.Cache: flush failed

func (*Scope) Provide

func (s *Scope) Provide[T any](ctor func(*Scope) T) Binding[T]

Provide registers a lazily built singleton. T is inferred from the constructor's return type; dependencies are pulled with s.Get[...]().

func (*Scope) Resolve

func (s *Scope) Resolve[T any]() (v T, err error)

Resolve is the error-returning entry point.

func (*Scope) Run

func (s *Scope) Run(ctx context.Context, opts ...RunOption) error

Run starts the scope and blocks until ctx is cancelled, a termination signal arrives, or Shutdown is called. It then stops the scope with a bounded context; a second signal during the stop cancels that context so a hung hook cannot keep the process alive. Run returns the Start error, the error passed to Shutdown, and any Stop errors, joined. A worker that died on its own is reported once, whether it reached Run as the cause or as a Stop error.

func (*Scope) Shutdown

func (s *Scope) Shutdown(cause error)

Shutdown asks a running Run to stop and records the cause it should return. It never blocks, may be called from any goroutine, and the first call wins. It propagates to ancestor scopes, so a service in a child scope can stop the application.

func (*Scope) Start

func (s *Scope) Start(ctx context.Context) error

Start builds every Eager binding in registration order, then runs the start step of everything built so far, in build order. If a constructor or a start step fails, the scope is stopped, which rolls back exactly the services that did start, child scopes included. A service that was built but never started is not stopped, so acquire resources in OnStart rather than in the constructor when the binding declares one.

After Start returns, a service built later runs its start step as part of being built, so lazily resolved services start too. Start may be called once, and builds only this scope's own Eager bindings: a child scope's are built by that child's Start.

func (*Scope) Stop

func (s *Scope) Stop(ctx context.Context) error

Stop winds the scope down in three phases. First it drains: OnDrain hooks run from the innermost scope outwards, in reverse build order, while every scope still resolves, so work already in flight can finish and still reach its dependencies. A service or child scope that phase brings into being is drained too, before anything is marked stopped. Then the scope is marked stopped and child scopes are stopped. Then OnStop hooks run in reverse build order (dependents first).

A service is stopped only if it started, or if it declares no OnStart, in which case OnStop is a plain destructor. Every failure is reported.

Stop is synchronous. It waits out whatever another goroutine is still running for a service it is tearing down -- a start step in flight, a drain hook another Stop began, a Worker hook being cancelled -- so when it returns, the teardown has happened and its failures are in the error. A teardown outlives the call in one case, when ctx expires first: the missed deadline is reported here, and the release is finished once the outstanding step returns, on a goroutine of its own, reaching observers rather than this caller. A constructor that finishes after the scope has stopped is likewise undone by whichever goroutine was resolving it.

Afterwards the scope and its descendants refuse to resolve anything, with ErrStopped; that includes a resolution that was already waiting when the scope stopped, so a closed service is never handed out. Stopping a child scope also detaches it from its parent, so per-request scopes are released once stopped.

Stop is idempotent, and concurrent calls are safe: only the first tears the scope down, and the others wait for it and report its result, bounded by their own context. Two Stop calls that meet at one scope, as a child and its parent do, wait for each other phase by phase, so neither starts releasing what the other's hooks are still using.

Because Stop waits, a hook must not call Stop on its own scope or an ancestor: it would be waiting for the step it is itself running. Stopping a sibling, or a scope below the hook's own, is allowed. A hook that passes on the context it was given gets an error saying so; one that passes a context of its own is not recognised, and waits until that context expires. Call Shutdown, which never blocks.

func (*Scope) Value

func (s *Scope) Value[T any](v T) Binding[T]

Value registers an already-built instance.

type TB

type TB interface {
	Helper()
	Cleanup(func())
	Errorf(format string, args ...any)
}

TB is the subset of testing.TB that Test needs.