479 lines
18 KiB
Markdown
479 lines
18 KiB
Markdown
# Wiring Conventions
|
|
|
|
> Forging a service is mostly wiring. Do it the same way every time.
|
|
|
|
This is not an Einherjar *module* — it is the canonical *application* shape that uses
|
|
Einherjar modules. Apps live in their own repository with an `internal/wire/` package that
|
|
mirrors this template. The conventions here are distilled from production services built on
|
|
Einherjar v1 (`iron-dough-api`, `pei-api`) and describe the **one opinionated minimum** a
|
|
scaffolded app should have. You *can* hand-roll something else — but then it is yours to
|
|
maintain, and it will not match what the rest of the ecosystem reads at a glance.
|
|
|
|
## The opinionated minimum
|
|
|
|
Every scaffolded Einherjar application has, at minimum:
|
|
|
|
1. **A clean `main.go`** — nothing but `.env` autoload and a call to `wire.Run()`.
|
|
2. **An `internal/wire/` package** — one file per feature plus `wire.go`, which assembles everything.
|
|
3. **An `internal/config/config.go`** — one global `Config` that *composes* the framework's
|
|
component configs, loaded from the environment with `caarlos0/env`.
|
|
4. **A `.env.example`** kept in lock-step with that config (see *Config & .env.example*).
|
|
|
|
Anything a developer freely chooses — how migrations run, how the first admin is seeded, an
|
|
init-by-endpoint/webhook/email flow — is **not** part of this convention and is left to the app.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
cmd/<app>/main.go one-line entrypoint: godotenv autoload + wire.Run()
|
|
internal/wire/wire.go Run() — loads config, builds infra, registers feature hooks
|
|
internal/wire/<feature>.go one file per feature, hosts a with<Feature> hook
|
|
internal/wire/middleware.go authz, skipPublicPaths, skipMethodPath helpers
|
|
internal/config/config.go global Config composing framework component configs
|
|
.env.example every env var the config reads, documented, in sync
|
|
internal/<feature>/dto/ request/response DTOs
|
|
internal/<feature>/handler/ HTTP handlers
|
|
internal/<feature>/repository/ data access
|
|
internal/<feature>/service/ domain logic
|
|
```
|
|
|
|
## main.go
|
|
|
|
`cmd/<app>/main.go` contains **nothing** but the `.env` autoload and the call to `wire.Run()`.
|
|
The blank import `_ "github.com/joho/godotenv/autoload"` is the standard, documented way to load
|
|
a local `.env` — it never overrides variables already set in the real environment, and a missing
|
|
file is not an error, so deployments (vars injected by the platform, no `.env`) are unaffected.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
"os"
|
|
|
|
_ "github.com/joho/godotenv/autoload"
|
|
|
|
"myapp/internal/wire"
|
|
)
|
|
|
|
func main() {
|
|
if err := wire.Run(); err != nil {
|
|
fmt.Fprintln(os.Stderr, "fatal:", err)
|
|
os.Exit(1)
|
|
}
|
|
}
|
|
```
|
|
|
|
No config parsing, no component construction, no logging setup — all of that lives in
|
|
`internal/wire/`. A `main.go` that builds anything itself is the single most common scaffolding
|
|
mistake.
|
|
|
|
## Config
|
|
|
|
`internal/config/config.go` is **one** `Config` struct that *composes* the framework's component
|
|
configs as nested fields, alongside the app's own settings. `caarlos0/env` recurses into the
|
|
nested fields, so each Einherjar component's `EINHERJAR_*` env tags load automatically next to
|
|
the app-owned fields. App-owned fields use the `APP_*` prefix so they never collide with the
|
|
framework's `EINHERJAR_*` namespace. There is exactly one `Load()`.
|
|
|
|
```go
|
|
package config
|
|
|
|
import (
|
|
"time"
|
|
|
|
"github.com/caarlos0/env/v11"
|
|
|
|
"code.nochebuena.dev/einherjar/core/logz"
|
|
"code.nochebuena.dev/einherjar/db-postgres"
|
|
"code.nochebuena.dev/einherjar/web/server"
|
|
)
|
|
|
|
// JWTConfig is app-owned: the secret is handed to the signer in code, not consumed
|
|
// by a framework component, so it carries no EINHERJAR_ prefix.
|
|
type JWTConfig struct {
|
|
Secret string `env:"APP_JWT_SECRET,required,notEmpty"`
|
|
Issuer string `env:"APP_JWT_ISSUER" envDefault:"myapp"`
|
|
AccessTTL time.Duration `env:"APP_JWT_ACCESS_TTL" envDefault:"1h"`
|
|
RefreshTTL time.Duration `env:"APP_JWT_REFRESH_TTL" envDefault:"168h"`
|
|
}
|
|
|
|
// Config is the fully-resolved startup configuration. Einherjar component configs
|
|
// are nested fields; caarlos0/env recurses into them, populating their
|
|
// EINHERJAR_SERVER_* / EINHERJAR_PG_* tags from the environment.
|
|
type Config struct {
|
|
AppEnv string `env:"APP_ENV" envDefault:"local"`
|
|
|
|
JWT JWTConfig
|
|
|
|
// Framework component configs — composed verbatim. Their own EINHERJAR_* tags
|
|
// load through this one env.Parse call.
|
|
Log logz.Config // EINHERJAR_LOG_*
|
|
Server server.Config // EINHERJAR_SERVER_* (incl. EINHERJAR_SERVER_CORS_ORIGINS)
|
|
PG postgres.Config // EINHERJAR_PG_*
|
|
}
|
|
|
|
func Load() (Config, error) {
|
|
var cfg Config
|
|
if err := env.Parse(&cfg); err != nil {
|
|
return Config{}, err
|
|
}
|
|
return cfg, nil
|
|
}
|
|
```
|
|
|
|
Never read framework env vars (`EINHERJAR_*`) with `os.Getenv` — compose the component's `Config`
|
|
type and let `caarlos0/env` load it. A raw `os.Getenv("EINHERJAR_PG_HOST")` in application code is
|
|
the mistake this convention removes.
|
|
|
|
## Config & .env.example
|
|
|
|
Every environment variable the `config` package reads **must** also appear in `.env.example` at
|
|
the repo root, documented. The two are kept in **lock-step**: when a feature introduces a new env
|
|
var, the same change adds its `env:"..."` tag to `config` **and** a documented line to
|
|
`.env.example`. This is not optional bookkeeping — it is what stops a long feature from shipping
|
|
and then failing at boot because nobody knew which variables to set.
|
|
|
|
**Two kinds of var, two ways to keep them honest:**
|
|
|
|
- **Framework component vars (`EINHERJAR_*`)** — when you compose a new component later (e.g.
|
|
`cachevalkey.Config`, `minio.Config`, `smtp.Config`), the MCP knows its real vars: call
|
|
`get_config_env("<module>")` for the exact set (name, required, default) and add each to
|
|
`.env.example`. The `config.unknown-env-var` rule rejects any `EINHERJAR_*` tag the framework
|
|
doesn't declare, so a typo like `EINHERJAR_PG_DATABASE` is caught at `validate_snippet` time.
|
|
- **App-owned vars (`APP_*`)** — like `APP_JWT_SECRET` above: the framework can't know these, so
|
|
keeping them in `.env.example` is your discipline, not something it can name-check.
|
|
|
|
After you compose a component, run **`check_env`** with what the app composes: it flags
|
|
`EINHERJAR_*` names that don't exist, required vars you forgot to document, and vars set for a
|
|
config you don't actually compose (dead vars). Prefer the **`composes`** input (exact struct
|
|
selectors like `web/server/Config`) over `modules` — it catches struct-level dead vars (e.g.
|
|
`EINHERJAR_HEALTH_CHECK_TIMEOUT` lives on `web/health.Config`, so it is dead if you compose
|
|
`web/server/Config` but not the health config). `get_scaffold` already emits a `.env.example`
|
|
derived from these same tags, so the starting point is correct by construction.
|
|
|
|
```bash
|
|
# .env.example — copy to .env for local dev. Every var the app reads lives here.
|
|
|
|
# ── App ───────────────────────────────────────────────────────────────────
|
|
APP_ENV=local
|
|
# CORS: local uses mw.CORSAllowAll(); non-local reads EINHERJAR_SERVER_CORS_ORIGINS (below).
|
|
APP_JWT_SECRET=change-me
|
|
APP_JWT_ISSUER=myapp
|
|
|
|
# ── Einherjar: logging (EINHERJAR_LOG_*) ──────────────────────────────────
|
|
# EINHERJAR_LOG_LEVEL=INFO
|
|
# EINHERJAR_LOG_JSON=false
|
|
|
|
# ── Einherjar: HTTP server (EINHERJAR_SERVER_*) ───────────────────────────
|
|
EINHERJAR_SERVER_HOST=0.0.0.0
|
|
EINHERJAR_SERVER_PORT=8080
|
|
# EINHERJAR_SERVER_CORS_ORIGINS — explicit origins for non-local envs (comma-separated).
|
|
# "*" is rejected by mw.CORS; local dev uses mw.CORSAllowAll() and ignores this.
|
|
# EINHERJAR_SERVER_CORS_ORIGINS=
|
|
|
|
# ── Einherjar: PostgreSQL (EINHERJAR_PG_*) ────────────────────────────────
|
|
EINHERJAR_PG_HOST=localhost
|
|
EINHERJAR_PG_PORT=5432
|
|
EINHERJAR_PG_USER=postgres
|
|
EINHERJAR_PG_PASSWORD=postgres
|
|
EINHERJAR_PG_NAME=myapp
|
|
```
|
|
|
|
To discover the full set for any component you compose, use `get_config_env("<module>")` rather
|
|
than reading source by hand; every var it returns belongs in `.env.example`, and `check_env`
|
|
confirms none are missing, misspelled, or dead.
|
|
|
|
## wire.go — Run()
|
|
|
|
The application entry point. The order below is load-bearing: configuration first, observability
|
|
second, infrastructure third, cross-cutting helpers fourth, then the launcher with every component
|
|
appended, then feature hooks, then `lc.Run()`.
|
|
|
|
**`web.New` vs `server.New` — pick the right tier:**
|
|
|
|
- **`web.New(logger, web.Config{Server: cfg.Server})`** — batteries-included. It pre-wires the
|
|
recommended middleware stack (Recover → RequestID → RequestLogger) and applies `mw.CORS` from
|
|
`EINHERJAR_SERVER_CORS_ORIGINS` automatically (explicit origins only; empty ⇒ CORS off + a log
|
|
line). Use it for a plain service that just needs the defaults. It does **not** support allow-all
|
|
CORS or a custom middleware order.
|
|
- **`server.New(logger, cfg.Server, server.WithMiddleware(...))`** — full control. You compose the
|
|
middleware list yourself. Use it when you need a **custom middleware order**, extra middleware
|
|
(auth, enrichment), a custom request-ID generator, or **allow-all CORS in local dev**
|
|
(`mw.CORSAllowAll`, gated by `AppEnv` — see below). The starter below uses `server.New` precisely
|
|
because it inserts JWT auth + enrichment into the stack.
|
|
|
|
Whichever tier you pick, CORS origins always come from the framework var
|
|
`EINHERJAR_SERVER_CORS_ORIGINS` (`cfg.Server.CORSOrigins`) — never invent an app-owned CORS var.
|
|
|
|
```go
|
|
package wire
|
|
|
|
import (
|
|
"github.com/google/uuid"
|
|
|
|
authjwt "code.nochebuena.dev/einherjar/auth-jwt"
|
|
"code.nochebuena.dev/einherjar/auth/authmw"
|
|
"code.nochebuena.dev/einherjar/auth/rbac"
|
|
"code.nochebuena.dev/einherjar/core/launcher"
|
|
"code.nochebuena.dev/einherjar/core/logz"
|
|
"code.nochebuena.dev/einherjar/core/valid"
|
|
"code.nochebuena.dev/einherjar/db-postgres"
|
|
"code.nochebuena.dev/einherjar/web/mw"
|
|
"code.nochebuena.dev/einherjar/web/server"
|
|
|
|
"myapp/internal/config"
|
|
)
|
|
|
|
func Run() error {
|
|
cfg, err := config.Load()
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
// logz.Config is composed in config, so EINHERJAR_LOG_LEVEL / _JSON load from
|
|
// the environment; StaticArgs are set here (they carry no env tag).
|
|
logCfg := cfg.Log
|
|
logCfg.StaticArgs = []any{"service", "myapp", "env", cfg.AppEnv}
|
|
logger := logz.New(logCfg)
|
|
|
|
signer := authjwt.NewHMACSigner([]byte(cfg.JWT.Secret))
|
|
|
|
publicPaths := []string{
|
|
"/health",
|
|
"/api/v1/auth/login",
|
|
"/api/v1/auth/refresh",
|
|
}
|
|
|
|
db := postgres.New(logger, cfg.PG)
|
|
|
|
// CORS convention: allow-all in local dev, explicit origins everywhere else.
|
|
// Origins come from the framework's own EINHERJAR_SERVER_CORS_ORIGINS
|
|
// (cfg.Server.CORSOrigins) — never invent an APP_CORS_ORIGINS var. mw.CORS panics
|
|
// on "*" (it matches no real origin) — allow-all is mw.CORSAllowAll, never a "*".
|
|
corsMW := mw.CORSAllowAll()
|
|
if !strings.EqualFold(cfg.AppEnv, "local") {
|
|
corsMW = mw.CORS(cfg.Server.CORSOrigins)
|
|
}
|
|
|
|
srv := server.New(logger, cfg.Server,
|
|
server.WithMiddleware(
|
|
mw.RequestID(uuid.NewString),
|
|
mw.Recover(logger),
|
|
corsMW,
|
|
mw.RequestLogger(logger),
|
|
authjwt.AuthMiddleware(logger, signer, publicPaths),
|
|
authmw.EnrichmentMiddleware(logger, &claimsEnricher{}),
|
|
),
|
|
)
|
|
|
|
v := valid.New(valid.WithMessageProvider(valid.SpanishMessages))
|
|
provider := rbac.NewClaimsPermissionProvider("masks", claimsFromCtx)
|
|
|
|
lc := launcher.New(logger)
|
|
lc.Append(db, srv)
|
|
|
|
withHealth(lc, srv, logger, db)
|
|
withUsers(lc, srv, db, logger, provider, v)
|
|
// … one withFeature(...) call per feature in your domain.
|
|
|
|
return lc.Run()
|
|
}
|
|
```
|
|
|
|
## Feature hook
|
|
|
|
One file per feature in `internal/wire/`. The function signature is fixed:
|
|
`launcher.Launcher` first, `server.Server` second when registering routes, deps last. The body is
|
|
*one* call to `lc.BeforeStart`. Everything else — repository, service, handler construction, route
|
|
registration — lives inside the closure.
|
|
|
|
```go
|
|
package wire
|
|
|
|
import (
|
|
"code.nochebuena.dev/einherjar/contracts/logging"
|
|
"code.nochebuena.dev/einherjar/contracts/security"
|
|
"code.nochebuena.dev/einherjar/core/launcher"
|
|
"code.nochebuena.dev/einherjar/core/valid"
|
|
"code.nochebuena.dev/einherjar/db-postgres"
|
|
"code.nochebuena.dev/einherjar/web/server"
|
|
|
|
"myapp/internal/domains"
|
|
userhandler "myapp/internal/user/handler"
|
|
userrepo "myapp/internal/user/repository"
|
|
usersvc "myapp/internal/user/service"
|
|
)
|
|
|
|
func withUsers(
|
|
lc launcher.Launcher,
|
|
srv server.Server,
|
|
db postgres.Provider,
|
|
logger logging.Logger,
|
|
provider security.PermissionProvider,
|
|
v valid.Validator,
|
|
) {
|
|
lc.BeforeStart(func() error {
|
|
repo := userrepo.New(db)
|
|
uow := postgres.NewUnitOfWork(logger, db)
|
|
svc := usersvc.New(repo, uow)
|
|
h := userhandler.New(svc, v)
|
|
|
|
// Literal-segment routes register BEFORE parametrised siblings.
|
|
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
|
|
|
|
srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
|
|
Get("/api/v1/users", h.ListUsers)
|
|
srv.With(authz(provider, domains.ResourceUsers, domains.GrantCreateUser)).
|
|
Post("/api/v1/users", h.CreateUser)
|
|
srv.With(authz(provider, domains.ResourceUsers, domains.GrantUpdateUser)).
|
|
Put("/api/v1/users/{user_id}", h.UpdateUser)
|
|
|
|
return nil
|
|
})
|
|
}
|
|
```
|
|
|
|
## Route ordering
|
|
|
|
chi matches paths in registration order. Always register literal-segment routes before
|
|
parametrised-segment routes that share the same prefix.
|
|
|
|
✅ Correct:
|
|
|
|
```go
|
|
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
|
|
srv.Put("/api/v1/users/{user_id}", h.UpdateUser)
|
|
```
|
|
|
|
❌ Wrong — chi binds `me` to `{user_id}` and the literal route is unreachable:
|
|
|
|
```go
|
|
srv.Put("/api/v1/users/{user_id}", h.UpdateUser)
|
|
srv.Put("/api/v1/users/me/password", h.ChangeOwnPassword)
|
|
```
|
|
|
|
## Authorization
|
|
|
|
Every protected route registers with `.With(authz(provider, resource, grant))`:
|
|
|
|
```go
|
|
srv.With(authz(provider, domains.ResourceUsers, domains.GrantReadUser)).
|
|
Get("/api/v1/users", h.ListUsers)
|
|
```
|
|
|
|
Resource constants and grant bits live in `internal/domains/`. Routes that the caller owns
|
|
(`/me/...`) intentionally skip authz — they are reachable to any authenticated user.
|
|
|
|
## Middleware helpers
|
|
|
|
These belong in `internal/wire/middleware.go` and are used across every feature hook.
|
|
|
|
```go
|
|
// authz returns a per-route authorization middleware that checks one bit.
|
|
func authz(p security.PermissionProvider, resource string, bit int) func(http.Handler) http.Handler {
|
|
return authmw.AuthzMiddleware(nil, p, resource, security.Permission(bit))
|
|
}
|
|
|
|
// skipPublicPaths wraps mw so it is bypassed for any path that matches publicPaths.
|
|
// Use this for middleware that must not run on unauthenticated endpoints
|
|
// (e.g. EnrichmentMiddleware).
|
|
func skipPublicPaths(publicPaths []string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
|
|
return func(next http.Handler) http.Handler {
|
|
inner := mw(next)
|
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
|
for _, p := range publicPaths {
|
|
if matched, _ := path.Match(p, r.URL.Path); matched {
|
|
next.ServeHTTP(w, r)
|
|
return
|
|
}
|
|
}
|
|
inner.ServeHTTP(w, r)
|
|
})
|
|
}
|
|
}
|
|
|
|
// skipMethodPath bypasses mw only when BOTH method and path match. Use this to
|
|
// expose ONE method on an otherwise-authenticated path (e.g. GET /api/v1/config
|
|
// public while PUT is not). Adding such a path to publicPaths would silently
|
|
// strip identity from context on the protected methods, breaking authz().
|
|
func skipMethodPath(method, pathPattern string, mw func(http.Handler) http.Handler) func(http.Handler) http.Handler {
|
|
return func(next http.Handler) http.Handler {
|
|
inner := mw(next)
|
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
|
if r.Method == method {
|
|
if matched, _ := path.Match(pathPattern, r.URL.Path); matched {
|
|
next.ServeHTTP(w, r)
|
|
return
|
|
}
|
|
}
|
|
inner.ServeHTTP(w, r)
|
|
})
|
|
}
|
|
}
|
|
```
|
|
|
|
## Adapters at the wire boundary
|
|
|
|
When a framework type does not match a service-layer port, write a small typed adapter in
|
|
`internal/wire/`. Always compile-time assert with `var _ TargetIface = (*adapter)(nil)`.
|
|
|
|
The framework intentionally exposes only `Signer.Sign(claims) (string, error)` — **the framework
|
|
gives you a signing primitive; the access/refresh strategy, claim layout, and response shape are
|
|
application concerns.** A "helper" that returned a fixed `{access, refresh, type, expiresIn}` struct
|
|
would silently decide for every app whether refresh tokens exist, what fields to expose, and what
|
|
casing to use. Those are wire-format choices the app owns.
|
|
|
|
```go
|
|
import (
|
|
"time"
|
|
|
|
"github.com/golang-jwt/jwt/v5"
|
|
"github.com/google/uuid"
|
|
|
|
authjwt "code.nochebuena.dev/einherjar/auth-jwt"
|
|
)
|
|
|
|
type tokenSignerAdapter struct {
|
|
signer authjwt.Signer
|
|
cfg authjwt.TokenConfig
|
|
}
|
|
|
|
var _ authsvc.TokenSigner = (*tokenSignerAdapter)(nil)
|
|
|
|
func (a *tokenSignerAdapter) IssueTokenPair(subject string, custom map[string]any) (authdto.TokenPairResponse, error) {
|
|
now := time.Now()
|
|
|
|
access := jwt.MapClaims{
|
|
"sub": subject,
|
|
"iss": a.cfg.Issuer,
|
|
"iat": now.Unix(),
|
|
"exp": now.Add(a.cfg.AccessTTL).Unix(),
|
|
}
|
|
for k, v := range custom {
|
|
access[k] = v
|
|
}
|
|
accessToken, err := a.signer.Sign(access)
|
|
if err != nil {
|
|
return authdto.TokenPairResponse{}, err
|
|
}
|
|
|
|
refreshToken, err := a.signer.Sign(jwt.MapClaims{
|
|
"sub": subject,
|
|
"jti": uuid.NewString(),
|
|
"iat": now.Unix(),
|
|
"exp": now.Add(a.cfg.RefreshTTL).Unix(),
|
|
})
|
|
if err != nil {
|
|
return authdto.TokenPairResponse{}, err
|
|
}
|
|
|
|
return authdto.TokenPairResponse{
|
|
AccessToken: accessToken,
|
|
RefreshToken: refreshToken,
|
|
TokenType: "Bearer",
|
|
ExpiresIn: int(a.cfg.AccessTTL.Seconds()),
|
|
}, nil
|
|
}
|
|
```
|