middleware

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package middleware provides ready-made state.Middleware implementations for common cross-cutting concerns.

Available Middleware

  • Log: logs each step's name, elapsed time, and outcome, escalating the level on cancellation and panic

Usage with AmbientDispatch

The typical pattern is to register middleware via WithAmbientMiddleware and run the pipeline with AmbientDispatch:

ctx = state.WithAmbientMiddleware(ctx, middleware.Log(slog.Default()))
state.Run(ctx, state.AmbientDispatch(step1, step2, step3))

Panics

This package deliberately ships no panic-recovery middleware. A panic in a step is a programming error, and controller runtimes generally install their own crash handler around the worker loop — one that logs the panic with its stack and then lets the process die. Recovering inside the pipeline would convert that loud, debuggable crash into a silently dropped reconcile.

state.Parallel branches run on their own goroutines, so their panics bypass such a handler when it wraps the pipeline from outside — recover cannot cross a goroutine boundary. To cover branches, register the crash handler as ambient middleware: state.CrashHandler accepts utilruntime.HandleCrashWithContext directly, and state.Parallel applies the ambient stack inside every branch. Observation hooks like Log's still close during the unwind, so the crashing step is logged on the way out.

Package middleware provides ready-made state.Middleware implementations for common cross-cutting concerns.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Log

func Log(logger *slog.Logger) state.Middleware

Log returns a Middleware that logs each step's name, elapsed time, and outcome after the step executes. It uses state.Named for the step name (empty string if the step was not annotated). Elapsed time is logged as duration_ms (float64, milliseconds); the outcome is logged as a stable label (continued, terminated, cancelled, panicked), plus the terminal operation's detail ("done", "requeued") and cause when recorded. The level escalates with the outcome: Info normally, Warn on cancellation or an error-carrying termination (an error requeue is a failed reconcile attempt), Error on panic — so the last line a crashing controller emits identifies the step that broke.

Log is built on state.Before and state.AfterOutcome, so it is a bracket (see FORMAL.md, "The Bracket Laws"): the log line is emitted on every outcome — including while a panic unwinds — and the measured duration covers only the wrapped step, not the downstream steps that CPS would otherwise run inline within the step's frame.

Typical controller usage:

ctx = state.WithAmbientMiddleware(ctx, middleware.Log(slog.Default()))

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL