Application Lifecycle

Nimbus follows a Laravel-inspired boot sequence. Understanding the lifecycle helps you know where to put configuration, middleware, routes, and plugin setup.

Entry point: main.go

main.go is the minimal bootstrap. It delegates everything to bin/server.go:

package main

import "myapp/bin"

func main() {
    app := bin.Boot()
    _ = app.Run()
}

Boot sequence: bin/server.go

package bin

import (
    "github.com/CodeSyncr/nimbus"
    "github.com/CodeSyncr/nimbus/database"
    "myapp/config"
    "myapp/start"
)

func Boot() *nimbus.App {
    config.Load()
    app := nimbus.New()

    // Register plugins
    app.Use(
        stripe.New(),
        analytics.New(),
    )

    start.RegisterMiddleware(app)
    start.RegisterRoutes(app)
    _, _ = database.Connect(config.Database.Driver, config.Database.DSN)

    return app
}

What app.Run() does

When you call app.Run(), Nimbus executes the full lifecycle sequence:

app.Run()
  ├─ configureGOGCFromEnv()
  ├─ startPprofIfEnabled()
  ├─ app.WarmUp()                       — assembles app (idempotent)
  │    └─ app.Boot()
  │         1. Provider.Register()      — all providers bind services
  │         2. Plugin.Register()        — all plugins
  │            └─ HasBindings applied   — container bindings registered
  │         3. Plugin.DefaultConfig     — default configs collected
  │         4. Provider.Boot()          — all providers resolve deps
  │         5. Plugin.Boot()            — all plugins initialise
  │         6. Plugin capabilities:
  │            ├─ HasRoutes             → routes mounted on router
  │            ├─ HasMiddleware         → named middleware merged
  │            ├─ HasCommands           → CLI commands registered
  │            ├─ HasSchedule           → tasks added to scheduler
  │            ├─ HasEvents             → listeners registered on event bus
  │            └─ HasHealthChecks       → checks added to health checker
  │         7. App-level boot hooks     → OnBoot callbacks
  │    └─ Warmup hooks                  → OnWarmup callbacks
  │    └─ Dispatch events.AppWarmed     → payload: *App
  ├─ Start hooks                        → OnStart callbacks
  ├─ Scheduler.Start()                  → if tasks registered
  ├─ ListenAndServe()                   → accept connections
  └─ Dispatch events.AppReady           → payload: port

Shutdown (SIGINT/SIGTERM):
  └─ Server.Shutdown(ctx)               → graceful drain
  └─ Scheduler.Stop()                   → cancel background tasks
  └─ HasShutdown.Shutdown()             → each plugin (reverse order; skipped in ModeWarmup)
  └─ OnShutdown hooks                   → app-level cleanup

Functional Constructor Options

Configure your Nimbus application cleanly at initialization time using functional options:

// Create an app tailored for warmup or testing
app := nimbus.New(
    nimbus.WithMode(nimbus.ModeWarmup),
    nimbus.WithPort("8080"),
)

Warmup & Route Tooling

The WarmUp() phase assembles and boots the application without starting the HTTP listener, queue workers, or background crons. This is ideal for reading routes for client codegen, inspecting container bindings, or running tests.

app := bin.Boot()
app.SetMode(nimbus.ModeWarmup)

// Assembles providers, plugins, routes, and middleware
if err := app.WarmUp(); err != nil {
    log.Fatal(err)
}

// Programmatic route manifest generation (defaults to .nimbus-client)
if err := app.DumpRoutes(".nimbus-client"); err != nil {
    log.Fatal(err)
}

Application Modes

Nimbus applications run in one of four modes:

• nimbus.ModeRun (default) — Full application runtime including HTTP server and schedulers.
• nimbus.ModeWarmup — Inspection-only mode. app.Run() will reject execution, and plugin shutdown hooks are skipped.
• nimbus.ModeTest — Tailored for HTTP and integration testing.
• nimbus.ModeCli — For artisan-style CLI command execution.

Lifecycle hooks

Register callbacks at specific points in the lifecycle:

// After providers/plugins have booted, before warmup completes
app.OnBoot(func(a *nimbus.App) {
    log.Println("App booted with", len(a.Plugins()), "plugins")
})

// During the WarmUp phase, after boot and before start
app.OnWarmup(func(a *nimbus.App) {
    log.Println("App warmed up in mode:", a.GetMode())
})

// Right before the HTTP server begins serving
app.OnStart(func(a *nimbus.App) {
    log.Println("Server starting on port", a.Config.App.Port)
})

// During graceful shutdown
app.OnShutdown(func(a *nimbus.App) {
    log.Println("Cleaning up resources...")
})

Runtime configuration

• NIMBUS_GOGC — GC aggressiveness (50=aggressive, 100=default, 200=fewer cycles, off=disabled)
• NIMBUS_PPROF — enable pprof server (e.g. :6060 or 127.0.0.1:6060)

Request lifecycle

incoming request
  → server middleware (Logger, Recover, etc.)
  → route match
  → group middleware
  → named middleware (if assigned)
  → handler(ctx *http.Context) error
  → response