Documentation
¶
Overview ¶
Package fault defines the fault primitives that rules execute when they fire. Each fault implements Apply(ctx); a non-nil error short-circuits the adapter's Action.Before chain and is delivered to the caller in the adapter's native error model.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrConnDrop = errors.New("chaotic: connection drop")
ErrConnDrop is the sentinel returned by ConnDrop's Apply. Each adapter detects this sentinel via errors.Is and substitutes its native connection-drop error (driver.ErrBadConn, status.Unavailable, etc.).
Functions ¶
This section is empty.
Types ¶
type Fault ¶
Fault is one chaos primitive. Apply may sleep, return an error, or panic. A return of nil means the fault completed without affecting the call.
func ConnDrop ¶
func ConnDrop() Fault
ConnDrop returns ErrConnDrop. Each adapter detects this sentinel and substitutes its native connection-drop error.
Example ¶
package main
import (
"context"
"errors"
"fmt"
"github.com/ag4r/chaotic/fault"
)
func main() {
// ConnDrop returns a sentinel each adapter maps to its native
// connection-drop error (driver.ErrBadConn, codes.Unavailable, ...).
f := fault.ConnDrop()
err := f.Apply(context.Background())
fmt.Println(errors.Is(err, fault.ErrConnDrop))
}
Output: true
func Error ¶
Error returns err verbatim from Apply. The adapter is responsible for wrapping it into its native error model (e.g., &url.Error{Op: "chaos"} for http). A nil err makes Apply a no-op.
Example ¶
package main
import (
"context"
"errors"
"fmt"
"github.com/ag4r/chaotic/fault"
)
func main() {
f := fault.Error(errors.New("upstream unavailable"))
fmt.Println(f.Apply(context.Background()))
}
Output: upstream unavailable
func Jittered ¶
Jittered sleeps for a uniformly random duration in [min, max]. Negative or zero values are treated as "no sleep". If max <= min, sleeps for min.
func JitteredSeed ¶ added in v1.4.0
JitteredSeed is like Jittered but draws from a seeded PCG source, so the sequence of sleep durations is reproducible across runs with the same seed. Use it when a chaos test must be deterministically replayable. The draw is mutex-guarded. The fault is safe for concurrent use.
Example ¶
package main
import (
"context"
"time"
"github.com/ag4r/chaotic/fault"
)
func main() {
// JitteredSeed draws sleep durations from a seeded source, so a chaos test
// replays the same delays across runs. No Output: the delays are time-based
// and intentionally not printed.
f := fault.JitteredSeed(10*time.Millisecond, 50*time.Millisecond, 42)
_ = f.Apply(context.Background())
}
Output:
func Latency ¶
Latency sleeps for d. Returns ctx.Err() if the context is canceled first. A non-positive d returns immediately.
Example (ContextCancellation) ¶
package main
import (
"context"
"fmt"
"time"
"github.com/ag4r/chaotic/fault"
)
func main() {
// A canceled context makes a latency fault return immediately with the
// context error instead of sleeping.
ctx, cancel := context.WithCancel(context.Background())
cancel()
f := fault.Latency(time.Hour)
fmt.Println(f.Apply(ctx))
}
Output: context canceled
func Panic ¶
Panic calls panic(v) from Apply. The panic propagates through the action, through the adapter, out to the caller. Recovery is the caller's responsibility.
Example ¶
package main
import (
"context"
"fmt"
"github.com/ag4r/chaotic/fault"
)
func main() {
f := fault.Panic("boom")
defer func() {
fmt.Println("recovered:", recover())
}()
_ = f.Apply(context.Background())
}
Output: recovered: boom
Source Files