Dependencies

Go Elemental's dependency line is bottom-up, no provider in a base, kept light.

Two repositories enforce the line with a depguard rule in their check, so an import outside it fails the check and CI: go-cli-sdk's rule holds the module to the standard library and go-core, and go-messaging's holds its base module to the standard library, go-core, sqlate, and sqlate's query package. Every other repository holds the line by discipline: planning states which module a new dependency enters, and review rejects an import no stated line covers.

This line bounds dependency weight. Which packages may import a provider at all is the separate import-boundary rule of the service tiers principle.

The line per tier

Sourcing

Write a capability in-house when it is generic to its layer and has no specification or security surface, so that its failure shows in a unit test you would think to write. Source an industry-standard library, as a pinned go.mod dependency, when the capability's correctness depends on a specification with known corner cases, a threat model, or cryptography. Never carry a dependency for what the standard library provides. The test for "trivial" is not line count: a request-ID middleware fails loudly, while a rate limiter fails by growing memory under an attacker's keys with answers that look right.

An industry-standard library shows these markers, in rough order of weight:

  1. It uses standard-library types at its boundary (http.Handler, context.Context, error), so it can be removed without touching callers.
  2. It has few or no transitive dependencies.
  3. The project that defines its ecosystem maintains or adopts it.
  4. It has a stable major version.
  5. It solves a specification or a threat model, not a preference. Convenience libraries for binding, rendering, or validation are preferences, and preferences stay in-house.

A sourced library enters as a pinned go.mod entry, never copied into the tree, and its weight is isolated by module: a capability sub-module of an application SDK or a provider sub-module of an infrastructure library, which the base module never imports, unless the repository states an exception for its base module, as go-observability does for otelhttp. A repository that admits a sourced library states its line beside its link to the standard: the category it admits and the library taken under it. A capability that collaborates with an infrastructure service lives in that service's library, over standard-library types, never in an application SDK.

go-web-sdk is the worked case for a capability sub-module. Its README lets a middleware sub-module admit a sourced dependency in one category, a specification surface or a threat model, under the organization's markers, and keeps cryptography out of the SDK. middleware/rate-limit takes github.com/go-chi/httprate under the threat-model category, pinned in its own go.mod; the base module requires go-core alone. go-observability is the worked case for a stated exception: its README admits otelhttp, from a contrib repository that has never released its instrumentation modules past v0, as a stated v0 exception that passes every other marker. go-storage's README admits s3's feature/s3/transfermanager as a stated v0 exception in a provider sub-module, sourced under the specification category: S3's multipart upload protocol.

Peers compose in the application

Application SDKs and infrastructure libraries are peers on the core SDK. An application SDK never imports an infrastructure library, neither its base module nor a provider, and an infrastructure library never imports an application SDK's vocabulary into its contract. Their composition happens in the application: the SDK exposes an extension point, and the application declares the policy at its composition root. The web SDK's error writing is the worked case: the SDK defines the error-returning handler and the writer, and the application supplies the matchers that map the database library's error types to HTTP statuses, so a new infrastructure library costs the SDK nothing and its errors are one more matcher.

HTTP middleware composes the same way. A library with no HTTP concern supplies a collaborator, such as a logger, and the transport's middleware uses it. A library whose concern is HTTP-shaped, such as tracing or token verification, exposes its middleware as a func(http.Handler) http.Handler built from net/http types alone. That type is structurally the web SDK's web.Middleware, so the middleware composes into any service built on the SDK while the library never imports the SDK. go-observability's NewMiddleware is the worked case. The arrangement works because every layer builds on the standards and the standard library, which every layer above depends on too. A lower layer plugs into a higher one through those shared types without depending on it.

A provider is selected by construction

A consumer selects a provider in its composition root by importing it and calling its typed constructor. The organization's libraries keep no runtime registry and no registration call, and importing one of their packages registers nothing of theirs. Adding a provider is one new import at the composition root and no change to the base module.

Integration is structural where it can be

A library integrates with go-core by implementing its contracts rather than by importing more of it than it uses. The configuration contract is imported where a module's configuration block joins the layered load. Lifecycle integration is structural: a module's start, shutdown, and readiness methods match the coordinator's hook signatures, and the composition root registers them, so the module itself needs no lifecycle import to integrate; go-web-sdk imports it only because its readiness probe reports the coordinator's checks. Integration is also optional per layer: a composition-root layer with nothing that starts, stops, or reports readiness, the Elemental Architecture's Domain Service composition among them, registers nothing and needs no lifecycle import either.

Keyboard shortcuts

Settings