Documentation
¶
Overview ¶
Package app is forge's framework-style service bootstrap. A single app.Run(opts...) call composes the kit's standard fx modules with the caller's modules and blocks until SIGINT / SIGTERM.
Minimal HTTP service:
func main() {
app.Run(
app.WithName("auth"),
app.WithVersion(buildinfo.Version),
gormpg.FxModule(),
internal.FxModule(),
)
}
Defaults are intentionally small — only monitoring (logger + tracer) and HTTP (rest.FxModule) ship in. DB, auth, NATS, gRPC, outbox are all opt-in via the kit's existing FxModule() constructors.
Option is an alias for fx.Option, so any third-party fx module passes through unchanged.
Index ¶
- func Run(opts ...Option)
- func RunContext(ctx context.Context, opts ...Option) error
- func RunContextWithConfig[T any](ctx context.Context, cfg *T, opts ...Option) error
- func RunContextWorker(ctx context.Context, opts ...Option) error
- func RunWithConfig[T any](cfg *T, opts ...Option)
- func RunWorker(opts ...Option)
- type CommandDef
- type Info
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
func Run(opts ...Option)
Run boots a forge service with the kit's standard defaults and the caller-supplied modules, then blocks until SIGINT / SIGTERM.
Defaults are intentionally small — DB / auth / NATS / gRPC are all opt-in via the kit's existing FxModule() constructors passed in alongside internal.FxModule().
func RunContext ¶
RunContext is Run with a caller-supplied context. When the context cancels, the fx app shuts down — useful for tests that need to drive the lifecycle without sending real OS signals.
func RunContextWithConfig ¶
RunContextWithConfig is RunContext + envconfig loading.
func RunContextWorker ¶
RunContextWorker is RunWorker with a caller-supplied context — the test/lifecycle-driven counterpart to RunContext.
func RunWithConfig ¶
RunWithConfig is the common-case shorthand for services that load a typed config struct from env vars at startup. The pointer's contents are populated via envconfig.Process before fx wiring begins, then the same pointer is supplied to the fx graph so handlers can inject *T.
func RunWorker ¶
func RunWorker(opts ...Option)
RunWorker is Run with HTTP disabled. Use it for background workers — services that consume queues or run cron jobs but don't serve requests. Equivalent to app.Run(append(opts, app.WithoutHTTP())...) but the dedicated entry point makes intent obvious at the call site.
Types ¶
type CommandDef ¶
CommandDef is a single admin command registered against a service binary. When the binary is invoked with `./svc <name>` instead of the bare `./svc`, the matching command runs to completion (full fx graph + lifecycle) and the process exits — no HTTP server.
Invoke is anything fx.Invoke accepts: the kit hands it to fx verbatim. Inside the function, declare whatever deps you need as parameters (fx resolves them) and use fx.Lifecycle to schedule the actual work after Start so OnStart hooks of upstream modules (DB connect, NATS subscribe, …) have already fired.
app.Command("backfill-emails", "re-run normalisation across users",
func(lc fx.Lifecycle, db *sql.DB) {
lc.Append(fx.Hook{
OnStart: func(ctx context.Context) error {
return backfill.RunEmails(ctx, db)
},
})
})
func Command ¶
func Command(name, summary string, fn any) CommandDef
Command is the constructor for CommandDef — kept as a helper so the call site reads naturally.
type Info ¶
Info is the service-identity record provided to the fx graph so any component (logger, tracer, OpenAPI spec, custom commands) can pull the service name and version without re-deriving them.
type Option ¶
Option is the unit of app configuration. Every Option is just an fx.Option so any third-party fx module composes seamlessly:
app.Run(
app.WithName("auth"),
gormpg.FxModule(), // any fx.Option works as an Option
internal.FxModule(),
)
func WithCommands ¶
func WithCommands(cmds ...CommandDef) Option
WithCommands registers admin commands on the service binary. Each command becomes invokable via `./svc <name>`; the bare binary still boots the HTTP server by default.
Reserved names ("help", "-h", "--help") are rejected at boot via panic; help output is auto-generated.
func WithModules ¶
WithModules is a convenience for grouping several fx.Options inline; rarely needed since each fx.Option can be passed directly to Run.
func WithName ¶
WithName sets the service name. Surfaces in the logger ("svc" field), tracer (service.name attribute), and the app.Info value provided to the fx graph.
func WithOpenAPI ¶
WithOpenAPI activates OpenAPI 3.1 spec generation by threading the given openapi.SpecOpt values through rest.WithOpenAPI.
Calling multiple times is additive; the SpecConfig builds up across calls.
func WithVersion ¶
WithVersion sets the service version. Surfaces alongside the name in observability and OpenAPI info.
func WithoutHTTP ¶
func WithoutHTTP() Option
WithoutHTTP skips the default rest.FxModule. Used by background workers and other non-HTTP services that don't need a server.
func WithoutTelemetry ¶
func WithoutTelemetry() Option
WithoutTelemetry skips the default monitoring.FxModule. Rare; used only by trivial scripts where the logger/tracer overhead isn't wanted.
Source Files