safego

Documentation

Overview

Package safego provides goroutine launchers with built-in panic recovery.

A panic in any goroutine that is not handled within that goroutine will crash the entire process, which for a long-running interactive TUI is the worst possible failure mode (the user loses unsaved input, in-flight LLM streams, IM connections, etc.). Wrapping each goroutine in safego.Go ensures that bugs in one subsystem don't take the whole agent down.

The recovered panic is logged via internal/debug, including a full stack trace, so the bug remains diagnosable.

Index

• Variables
• func Go(name string, fn func())
• func Recover(name string)
• func Run(name string, fn func())
• func SetLogger(fn func(category, format string, args ...any))

Variables

var PanicHook func(name string, recovered any, stack []byte)

PanicHook, when non-nil, is invoked once with the recovered value and the full stack trace each time Go() catches a panic. It runs synchronously in the recovering goroutine. The TUI can install a hook to surface a non-fatal error message to the user; servers can install a hook to ship the stack to a sink. It must not panic.

Functions

func Go

func Go(name string, fn func())

Go launches fn in a new goroutine with panic recovery. The name is used only in log output to identify the goroutine in case of a panic.

Use this for any goroutine whose failure should not be allowed to crash the process: stream readers, batch flushers, IM listeners, background fetchers, watchdogs, etc.

func Recover

func Recover(name string)

Recover is a deferred-friendly helper. Call as `defer safego.Recover("name")` at the top of any goroutine body you want to protect. It logs the panic via internal/debug (with full stack) and invokes PanicHook if set, then swallows the panic so the goroutine exits cleanly.

func Run

func Run(name string, fn func())

Run invokes fn synchronously in the current goroutine with panic recovery. Useful when wrapping the body of a goroutine you've already launched yourself, or when running code in main that must not crash.

func SetLogger

func SetLogger(fn func(category, format string, args ...any))

SetLogger installs the debug log function. Called once at startup by internal/debug to wire up the dependency without creating an import cycle.