gootstrap

README

gootstrap

Lightweight lifecycle helpers to bootstrap long-running Go services.

gootstrap uses a tiny abstraction (Runner) and a small set of composable helpers to manage process startup, coordinated shutdown, and OS signal handling.

Install

go get github.com/fulldump/gootstrap

Quick Start

package main

import (
	"net/http"

	"github.com/fulldump/gootstrap"
)

func main() {
	server := &http.Server{
		Addr: ":8080",
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			_, _ = w.Write([]byte("ok"))
		}),
	}

	gootstrap.Run(gootstrap.RunHTTPServer(server))
}

Core Concepts

Runner defines lifecycle in two functions:

• start() error starts a service and blocks while it runs
• stop() error gracefully stops it

Helpers:

• Run(...) starts services and stops on SIGINT/SIGTERM
• RunAll(...) composes multiple runners
• RunUntilSignal(...) allows custom signals
• RunHTTPServer(...) wraps a standard net/http server
• RunGracefulHttpServer(...) adds a graceful-drain window

Examples

Basic service (examples/basic-service/main.go) runs:

• an HTTP server
• a background worker
• signal-based graceful shutdown

Production-oriented service (examples/production-service/main.go) runs:

• API server + readiness/liveness endpoints
• separate metrics server
• background worker with cooperative shutdown
• drain mode before graceful stop

Run examples locally:

go run ./examples/basic-service
go run ./examples/production-service

Production Guide

See PRODUCTION_PATTERNS.md for practical patterns used in real deployments.

Stability and Versioning

The project follows semantic versioning. Release notes are tracked in CHANGELOG.md.

Release process is documented in RELEASING.md.

Contributing

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• SUPPORT.md

License

MIT, see LICENSE.

Documentation

Overview

Package gootstrap provides small, composable helpers to bootstrap long-lived Go services.

A Runner returns two blocking lifecycle functions:

• start, which starts and blocks while the service is running.
• stop, which gracefully stops the service.

Use Run for the common case (start and stop on SIGINT/SIGTERM), or combine multiple runners with RunAll.

Index

• func Run(runners ...Runner)
• func RunUntilSignal(run Runner, s ...os.Signal)
• type Runner
  • func RunAll(runners ...Runner) Runner
  • func RunGracefulHttpServer(server *http.Server) Runner
  • func RunHTTPServer(server *http.Server) Runner

Examples

• RunAll

Functions

func Run

func Run(runners ...Runner)

Run starts all runners and stops them on SIGTERM or SIGINT.

func RunUntilSignal

func RunUntilSignal(run Runner, s ...os.Signal)

RunUntilSignal starts a runner and waits for specified signals to stop it.

Types

type Runner

type Runner func() (start, stop func() error)

Runner defines a lifecycle factory that returns blocking start and stop functions for a long-lived process.

func RunAll

func RunAll(runners ...Runner) Runner

RunAll accepts a list of runners and returns a new runner that starts all of them on start and stops all of them on stop.

Example

worker := func(name string) Runner {
	return func() (func() error, func() error) {
		return func() error {
				fmt.Println("start", name)
				return nil
			}, func() error {
				fmt.Println("stop", name)
				return nil
			}
	}
}

runner := RunAll(worker("http"), worker("metrics"))
start, stop := runner()
_ = start()
_ = stop()

func RunGracefulHttpServer

func RunGracefulHttpServer(server *http.Server) Runner

RunGracefulHttpServer bootstraps an HTTP server with a graceful shutdown window that serves 503 responses for new requests before stopping.

func RunHTTPServer

func RunHTTPServer(server *http.Server) Runner

RunHTTPServer bootstraps a standard net/http server lifecycle.