runner

README

runner

Bootstrap a server process in one call: JSON logger, OS signal handling, and graceful shutdown via task.

Stability

v1.x releases make no breaking changes to exported APIs. New functionality may be added in minor releases; patches are bug fixes, or administrative work only.

Installation

Go 1.26.2 or later.

go get github.com/wood-jp/runner

Usage

Implement a Runnable and pass it to Run:

const serviceName = "my-service"

func main() {
    runner.Run(serviceName, run)
}

func run(tm runner.Runner, logger *slog.Logger) error {
    return tm.Run(myTask{})
}

Run creates a JSON logger tagged with serviceName, starts an OS signal handler (SIGINT, SIGTERM, SIGQUIT), calls the Runnable, then waits for all tasks to finish. On error it calls os.Exit(1), so main() can be a single call.

The LOG_LEVEL environment variable overrides the log level (e.g. LOG_LEVEL=debug). It defaults to INFO.

The Runner interface exposes the subset of task.Manager that a Runnable needs:

type Runner interface {
    Run(tasks ...task.Task) error
    RunEphemeral(tasks ...task.Task) error
    Cleanup(f func() error)
    Context() context.Context
}

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

Attribution

This library is a simplified fork of one written by wood-jp at Zircuit. The original code is available here: zkr-go-common-public/runner

Documentation

Overview

Package runner provides boilerplate-free bootstrapping for server processes: logger creation, task manager setup, OS signal handling, and graceful shutdown.

Index

• func Run(serviceName string, runnable Runnable)
• type Runnable
• type Runner

Functions

func Run

func Run(serviceName string, runnable Runnable)

Run bootstraps a server process: creates a JSON logger tagged with serviceName, wires up an OS signal handler, calls runnable, then waits for all tasks to complete. Calls os.Exit on error; main() can be a single call.

Types

type Runnable

type Runnable func(tm Runner, logger *slog.Logger) error

Runnable is the server logic function signature. It sets up tasks and returns; the runner waits for all tasks to complete.

type Runner

type Runner interface {
	Run(tasks ...task.Task) error
	RunEphemeral(tasks ...task.Task) error
	Cleanup(f func() error)
	Context() context.Context
}

Runner limits the task.Manager surface exposed to a Runnable.