Panic Policy and Boundaries

## What the boundary is for A panic in Go is not an exception you catch at a convenient place. It unwinds the goroutine's stack, running deferred functions as it goes, and if nothing stops it the whole **process** exits with a traceback. A recovery boundary is the one place where you deliberately stop that unwinding and turn the failure into a value the surrounding code already knows how to handle: an `error`. ## The three ingredients ### 1. A named result parameter ```go func Reconcile(k Key) (err error) { ... } ``` `err` here is a real variable that lives for the whole call, not just a type in the signature. A deferred closure can read and write it. If the signature were `func Reconcile(k Key) error`, the result would be anonymous — the closure has nothing to name, so it cannot change what the caller receives. This is the single most common mistake when writing the pattern for the first time: the recovery runs, the panic is stopped, and the function returns `nil` because nobody could assign to the result. ### 2. A deferred closure, registered before the risky work ```go defer func() { if r := recover(); r != nil { err = fmt.Errorf("reconcile %v: recovered panic: %v", k, r) } }() ``` Only functions that were already deferred when the panic happened get to run during unwinding. A `defer` placed after the call that panics is never registered, so it never runs. Put the recovery closure at the top of the function body. A related subtlety: deferred calls run last-in-first-out. If the function also defers cleanup that sets `err` (closing a file, committing or rolling back), registering the recovery closure **first** means it runs **last**, so it sees and can overwrite whatever the cleanup put in `err`. That ordering is usually what you want at a boundary. ### 3. Checking the recovered value `recover()` returns the value passed to `panic`, typed as `any`. It is `nil` when the goroutine is not panicking, so the `if r := recover(); r != nil` guard is what distinguishes a normal return from a recovered one. The value can be anything — a string, an `error`, a custom type — so format it with `%v` rather than assuming it is an `error`, or type-switch on it if you care. ## What the resulting error should say A converted panic is a bug, not an expected outcome, and the error should read that way. `fmt.Errorf("reconcile %v: recovered panic: %v", k, r)` tells a reader three things: which unit of work failed, that the failure was a panic rather than a returned error, and what the panic value was. If callers need to branch on it, define a small error type that carries the recovered value (and, for a real service, the stack captured at the same moment) instead of flattening everything into a string. ## Where the boundary belongs One boundary per *unit of work that must not take the process down*: the top of each goroutine you start, an exported entry point of a library that must not panic into a caller's code, the per-item step of a loop that processes many independent items. Not inside every helper. Blanket recovery deep in the call tree converts programming bugs into vague errors far from where they happened and lets the program continue on state that a half-finished function left behind. Equally, never recover into silence. `defer func() { recover() }()` compiles, stops the panic, and returns the zero values — a function that reports success after a crash is worse than one that crashes. ## Worked shape ```go func Reconcile(k Key) (err error) { defer func() { if r := recover(); r != nil { err = fmt.Errorf("reconcile %v: recovered panic: %v", k, r) } }() return apply(k) // may panic deep inside } ``` If `apply` panics, the deferred closure runs while the stack unwinds, `recover` hands back the panic value, `err` is assigned, unwinding stops at this frame, and `Reconcile` returns to its caller like any other failing function. If `apply` returns an error normally, `recover` returns `nil`, the closure leaves `err` alone, and the caller gets exactly what `apply` produced. ## Summary Named result, defer first, check `recover()` for non-nil, assign a self-describing error. Place it where a failure must be contained, say in the message that it was a panic, and resist the urge to install one everywhere.