lifecycle

Go Report Card Go Reference License Release

lifecycle is a Go library for managing application shutdown signals and interactive terminal I/O robustly. It centralizes the “Dual Signal” logic and “Interruptible I/O” patterns originally extracted from Trellis and designed for any tool needing robust signal handling.

Vision

To be the standard Control Plane for Infrastructure-Aware Applications (Services, Agents, CLIs).

Project Status & Versioning

[!IMPORTANT] v1.5+ (Current): Provides the Application Control Plane, generalizing “Signals” into “Events” (Hot Reload, Health Checks, Input Commands). Contains breaking changes from v1.4 - see MIGRATION.md.

v1.0-v1.4 (LTS): Focuses strictly on Death Management (Graceful Shutdown, Signals, Leak Prevention).

Installation

go get github.com/aretw0/lifecycle

Features (Foundation v1)

Control Plane Features

The Control Plane provides event-driven orchestration for modern Go applications:

Managed Concurrency

lifecycle now provides primitives to manage goroutines safely, ensuring they respect shutdown signals and provide visibility.

lifecycle.Run(func(ctx context.Context) error {
    // Fire-and-forget but tracked and panic-safe
    lifecycle.Go(ctx, func(ctx context.Context) error {
        // ...
        return nil
    })
    return nil
})

Quick Start (The Golden Path)

For 99% of CLI applications, you just need lifecycle.Run. It handles signals, context cancellation, and cleanup automatically.

package main

import (
    "context"
    "fmt"
    "time"
    "github.com/aretw0/lifecycle"
)

func main() {
    // 1. Wrap your logic in a Job
    // 2. lifecycle.Run manages the boring "Death Management" stuff
    lifecycle.Run(lifecycle.Job(func(ctx context.Context) error {
        fmt.Println("App started. Press Ctrl+C to exit.")
        
        // 3. Use lifecycle.Go to spawn safe, tracked background tasks
        task := lifecycle.Go(ctx, func(ctx context.Context) error {
            // This goroutine is automatically tracked and waited for on shutdown
            return doWork(ctx)
        }, lifecycle.WithErrorHandler(func(err error) {
            fmt.Printf("Task failed: %v\n", err)
        }))

        // Optional: Wait for a specific task manually
        // err := task.Wait()

        // 4. Wait for interrupt
        <-ctx.Done()
        fmt.Println("Shutting down...")
        return nil
    }))
}

Basic Patterns (CLI & Automation)

1. Robust Input (Windows Safe)

Reading from Stdin on Windows is tricky. lifecycle solves the “Ctrl+C kills the prompt” problem by automatically using CONIN$.

// Smart Open (handles Windows CONIN$)
reader, _ := lifecycle.OpenTerminal()
defer reader.Close()

// Wrap to respect context cancellation (prevents blocked Read calls)
r := lifecycle.NewInterruptibleReader(reader, ctx.Done())

buf := make([]byte, 1024)
n, err := r.Read(buf)
if lifecycle.IsInterrupted(err) {
    return // Clean exit
}

2. Graceful Hooks

Register cleanup functions that run after the context is cancelled but before the process exits.

lifecycle.OnShutdown(ctx, func() {
    db.Close()
    fmt.Println("Cleanup done locally")
})

Advanced Patterns (Control Plane v1.5+)

For complex long-running services/agents that need dynamic behavior (Hot Reload, Supervisors).

1. Managed Concurrency & Global Fallback

lifecycle.Go(ctx, fn) is designed to work within lifecycle.Run. However, if you use it in a standalone script, it safely falls back to a Global Task Tracker.

func main() {
    ctx := context.Background()
    
    // Works safely even without lifecycle.Run
    lifecycle.Go(ctx, func(ctx context.Context) error {
        // ...
        return nil
    })
    
    // Explicitly wait for global tasks (required without Run)
    lifecycle.WaitForGlobal()
}

2. Supervisor & Workers

Manage long-running processes, containers, or goroutines with restarts and hygiene.

// Create a Supervisor with a "OneForOne" restart strategy
sup := lifecycle.NewSupervisor("agent", lifecycle.SupervisorStrategyOneForOne,
    lifecycle.NewProcessWorker("pinger", "ping", "1.1.1.1"),
    lifecycle.NewWorkerFromFunc("metrics", metricsLoop),
)

sup.Start(ctx)
<-ctx.Done()
sup.Stop(context.Background())

3. System Introspection

Generate live architecture diagrams of your running application.

// Generate Mermaid Dashboard
diagram := lifecycle.SystemDiagram(ctx.State(), supervisor.State())
fmt.Println(diagram)

Metrics Palette

The library uses a consistent color palette for all generated diagrams:

I/O Safety

The library implements Context-Aware I/O to balance data preservation and responsiveness:

Documentation

Development & Contribution

Local Development (Multi-Module)

If you are developing lifecycle and procio simultaneously (e.g. adding features to procio that lifecycle needs), you can use the provided Makefile helpers to toggle a local go.work file:

# Enable local development (uses ../procio by default)
make work-on

# Enable local development with custom path
make work-on WORK_PATH=../../my-fork/procio

# Disable local development (return to published module)
make work-off
This site is open source. Improve this page.