app

type Hooks[C any, D any] struct {
	// Name is used only for logging/diagnostics.
	Name string

	// LoadConfig must return both the core config (WAFFLE-level) and
	// the app-specific config. It typically calls waffle/config.Load
	// internally, plus any app-level config loading/validation.
	LoadConfig func(logger *zap.Logger) (*config.CoreConfig, C, error)

	// ValidateConfig can perform app-specific validation on the loaded
	// core and app config before any backends are connected. It may be
	// nil if the app doesn’t require extra validation. Returning an
	// error here will abort startup before any external resources are used.
	ValidateConfig func(core *config.CoreConfig, appCfg C, logger *zap.Logger) error

	// ConnectDB is responsible for connecting to any databases or backends
	// the app needs, using the core + app config. It should respect
	// cfg.DBConnectTimeout for its own timeouts.
	ConnectDB func(ctx context.Context, core *config.CoreConfig, appCfg C, logger *zap.Logger) (D, error)

	// EnsureSchema can run validators/index creation or other startup tasks
	// that depend on the DB being connected. It may be nil if the app
	// doesn’t need any schema bootstrapping.
	EnsureSchema func(ctx context.Context, core *config.CoreConfig, appCfg C, db D, logger *zap.Logger) error

	// Startup runs one-time application initialization after DBs and schemas
	// are ready, but before the HTTP handler is built and requests are served.
	// It may be nil if the app doesn’t need any extra initialization
	// beyond config, DB, and schema setup.
	Startup func(ctx context.Context, core *config.CoreConfig, appCfg C, db D, logger *zap.Logger) error

	// BuildHandler must construct the final http.Handler for the app:
	// this includes routers, Waffle middleware, app middleware, and routes.
	BuildHandler func(core *config.CoreConfig, appCfg C, db D, logger *zap.Logger) (http.Handler, error)

	// OnReady is called after the HTTP server starts listening but before
	// the main goroutine blocks. This is useful for signaling to load balancers
	// or orchestrators that the application is ready to accept traffic.
	// It may be nil if the app doesn't need readiness signaling.
	// Example uses:
	//   - Write a "ready" file for Kubernetes
	//   - Log "server ready" message
	//   - Start background workers
	OnReady func(core *config.CoreConfig, appCfg C, db D, logger *zap.Logger)

	// Shutdown is called after the HTTP server has stopped and the
	// shutdown context has been canceled. It is the app's opportunity
	// to gracefully tear down any resources created in ConnectDB
	// (databases, caches, external clients, etc.). It may be nil if
	// the app doesn't need explicit shutdown logic.
	Shutdown func(context.Context, *config.CoreConfig, C, D, *zap.Logger) error
}