chaos

Documentation

Overview

Package chaos provides explicit injection points: chaos.Point(ctx, name) consults the engine bound to ctx and returns a fault error (or nil) at a place no adapter wraps - between two pure functions, inside a goroutine, at a state-machine transition.

Bind an engine once near a test or request boundary:

ctx = chaos.WithEngine(ctx, eng)

then place points anywhere downstream:

if err := chaos.Point(ctx, "checkout.afterCommit"); err != nil {
	return err
}

A Point on a context with no engine bound (or a disabled engine) is a silent, allocation-free no-op, so points are safe to leave in production code. Recommended naming is dotted and hierarchical ("checkout.afterCommit"). Names are free-form and matched by engine rules via MatchName.

Index

• func Point(ctx context.Context, name string) error
• func PointWith(ctx context.Context, name string, attrs map[string]string) error
• func WithEngine(ctx context.Context, eng *engine.Engine) context.Context

Examples

• Point
• PointWith

Functions

func Point

func Point(ctx context.Context, name string) error

Point consults the engine bound to ctx and returns either nil (no engine bound, chaos disabled, or no rule matched) or the fault error produced by a matching rule. Latency faults sleep inline before Point returns. A Panic fault panics.

Example

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/ag4r/chaotic/chaos"
	"github.com/ag4r/chaotic/engine"
	"github.com/ag4r/chaotic/fault"
)

func main() {
	eng := engine.New().AddRule(engine.NewRule(
		engine.MatchKind(engine.OpExplicit),
		engine.MatchName("checkout.afterCommit"),
		engine.Times(1),
		engine.WithFault(fault.Error(errors.New("downstream timeout"))),
	).Named("checkout"))
	ctx := chaos.WithEngine(context.Background(), eng)

	fmt.Println("attempt 1:", chaos.Point(ctx, "checkout.afterCommit"))
	fmt.Println("attempt 2:", chaos.Point(ctx, "checkout.afterCommit"))
	// A Point on a context with no engine bound is always nil (inert in prod).
	fmt.Println("unbound:", chaos.Point(context.Background(), "checkout.afterCommit"))
}

Output:
attempt 1: downstream timeout
attempt 2: <nil>
unbound: <nil>

func PointWith

func PointWith(ctx context.Context, name string, attrs map[string]string) error

PointWith is Point with an attribute bag, mirroring engine.Op.Attrs. Rules may match on these attrs via engine.MatchAttr. attrs may be nil.

Example

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/ag4r/chaotic/chaos"
	"github.com/ag4r/chaotic/engine"
	"github.com/ag4r/chaotic/fault"
)

func main() {
	eng := engine.New().AddRule(engine.NewRule(
		engine.MatchKind(engine.OpExplicit),
		engine.MatchAttr("tier", "premium"),
		engine.WithFault(fault.Error(errors.New("degraded"))),
	).Named("tiered"))
	ctx := chaos.WithEngine(context.Background(), eng)

	fmt.Println("premium:", chaos.PointWith(ctx, "lookup", map[string]string{"tier": "premium"}))
	fmt.Println("free:", chaos.PointWith(ctx, "lookup", map[string]string{"tier": "free"}))
}

Output:
premium: degraded
free: <nil>

func WithEngine

func WithEngine(ctx context.Context, eng *engine.Engine) context.Context

WithEngine returns a child context carrying eng. Point and PointWith consult the engine bound to the context they are given. Binding nil clears the engine for a sub-scope (Point becomes a no-op there).