lifecycle

lifecycle

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 provide a standard, leak-free way to handle CLI interruptions (Ctrl+C) and graceful shutdowns across Go CLI applications, handling OS idiosyncrasies (especially Windows CONIN$) transparently.

Installation

go get github.com/aretw0/lifecycle

Features

• SignalContext: Differentiates between SIGINT (User Interrupt) and SIGTERM (System Shutdown).
  • SIGINT: Captured but doesn't cancel context immediately (allows "Wait, are you sure?" logic).
  • SIGTERM: Cancels context immediately (standard graceful shutdown).
• TermIO:
  • InterruptibleReader: Wraps io.Reader to allow Read() calls to be abandoned when a context is cancelled (avoids goroutine leaks).
  • Platform Aware: Automatically uses CONIN$ on Windows.
    • Why? On Windows, standard os.Stdin closes immediately upon receiving a signal (like Ctrl+C), causing a fatal EOF before the application can gracefully handle the signal. lifecycle switches to CONIN$, which keeps the handle open, allowing the SignalContext to process the event.
  • UpgradeTerminal: Helper to upgrade an arbitrary existing io.Reader (if it identifies as a terminal) to the safe platform-specific reader.
• Observability & Safety:
  • Metrics: Built-in provider interface (IncHookExecuted, ObserveHookDuration) to track shutdown health.
  • Stall Detection: Automatically detects and logs warnings if a shutdown hook is stalled (runs > 5s).

Usage

Signal Context

package main

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

func main() {
    // captures SIGINT/SIGTERM
    ctx := lifecycle.NewSignalContext(context.Background())
    defer ctx.Cancel() 

    // Register cleanup hooks (LIFO execution)
    ctx.OnShutdown(func() {
        fmt.Println("Cleanup: Database closed")
    })
    ctx.OnShutdown(func() {
        fmt.Println("Cleanup: HTTP server stopped")
    })

    <-ctx.Done()
    
    // Check why we stopped
    if sig := ctx.Signal(); sig != nil {
        fmt.Printf("Stopped by signal: %v\n", sig)
    }

    // IMPORTANT: Wait for hooks to finish!
    ctx.Wait()
}

Interruptible I/O

package main

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

func main() {
    ctx := context.Background() // or SignalContext
    
    // Smart Open (handles Windows CONIN$)
    reader, _ := lifecycle.OpenTerminal()
    
    // Wrap to respect context cancellation
    r := lifecycle.NewInterruptibleReader(reader, ctx.Done())

    buf := make([]byte, 1024)
    n, err := r.Read(buf)
    if lifecycle.IsInterrupted(err) {
        fmt.Println("Read cancelled!")
        return
    }
    fmt.Printf("Read: %s\n", buf[:n])
}

Caveats

Interruptible I/O & Data Loss

The InterruptibleReader uses a "Peek & Abandon" strategy to allow unblocking a read.

• Risk: If data arrives from the OS exactly when the context is cancelled, that data is discarded to prioritize the cancellation.
• Impact: This is acceptable for interactive CLIs (user hits Ctrl+C, we discard the "y" they just typed), but NOT suitable for critical binary streams where every byte matters.

Documentation

• PRODUCT: Vision & Mission.
• TECHNICAL: Architecture & Design (with Diagrams).
• PLANNING: Roadmap & Backlog.