chaos

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: May 25, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package chaos lets tests deliberately fail or slow down CloudEmu services in controlled, time-bounded ways — so app code that handles cloud failure can be exercised without waiting for real cloud to misbehave.

Typical usage: 

engine := chaos.New(config.RealClock{})
defer engine.Stop()

// Wrap a driver before handing it to the portable API or HTTP server
chaosS3 := chaos.WrapBucket(aws.S3, engine)
srv := awsserver.New(awsserver.Drivers{S3: chaosS3})

// Inject a failure scenario
engine.Apply(chaos.ServiceOutage("storage", 5*time.Second))

// SDK calls now fail for 5s, then recover automatically

Index

Constants

This section is empty.

Variables

View Source 
var ErrChaosInjected = errors.New("chaos: injected failure")

ErrChaosInjected is the sentinel-style error type the engine wraps when a scenario provides no specific error. Callers can errors.Is against it.

Functions

func WrapBucket 

func WrapBucket(inner storagedriver.Bucket, engine *Engine) storagedriver.Bucket

WrapBucket returns a storage driver that consults engine on the most-used data-plane operations. Less-used ops (lifecycle, multipart, tagging, versioning, CORS, encryption, policies, presigned URLs) delegate through without chaos for now — Phase 2 can broaden coverage.

func WrapCache 

func WrapCache(inner cachedriver.Cache, engine *Engine) cachedriver.Cache

WrapCache returns a cache driver that consults engine on data-plane calls.

func WrapCompute 

func WrapCompute(inner computedriver.Compute, engine *Engine) computedriver.Compute

WrapCompute returns a compute driver that consults engine on instance ops.

func WrapContainerRegistry 

func WrapContainerRegistry(inner regdriver.ContainerRegistry, engine *Engine) regdriver.ContainerRegistry

WrapContainerRegistry returns a container registry driver that consults engine on repository and image data-plane calls.

func WrapDNS 

func WrapDNS(inner dnsdriver.DNS, engine *Engine) dnsdriver.DNS

WrapDNS returns a DNS driver that consults engine on zone and record calls.

func WrapDatabase 

func WrapDatabase(inner dbdriver.Database, engine *Engine) dbdriver.Database

WrapDatabase returns a database driver that consults engine on item ops.

func WrapEventBus 

func WrapEventBus(inner ebdriver.EventBus, engine *Engine) ebdriver.EventBus

WrapEventBus returns an event bus driver that consults engine on bus, rule, and event publishing calls.

func WrapIAM 

func WrapIAM(inner iamdriver.IAM, engine *Engine) iamdriver.IAM

WrapIAM returns an IAM driver that consults engine on principal/policy management and permission checks.

func WrapLoadBalancer 

func WrapLoadBalancer(inner lbdriver.LoadBalancer, engine *Engine) lbdriver.LoadBalancer

WrapLoadBalancer returns a load balancer driver that consults engine on LB / target-group / target operations.

func WrapLogging 

func WrapLogging(inner logdriver.Logging, engine *Engine) logdriver.Logging

WrapLogging returns a logging driver that consults engine on log-group and event-ingest/query calls.

func WrapMessageQueue 

func WrapMessageQueue(inner mqdriver.MessageQueue, engine *Engine) mqdriver.MessageQueue

WrapMessageQueue returns a message queue driver that consults engine on queue and message data-plane calls.

func WrapMonitoring 

func WrapMonitoring(inner mondriver.Monitoring, engine *Engine) mondriver.Monitoring

WrapMonitoring returns a monitoring driver that consults engine on metric and alarm calls.

func WrapNetworking 

func WrapNetworking(inner netdriver.Networking, engine *Engine) netdriver.Networking

WrapNetworking returns a networking driver that consults engine on VPC/ Subnet/SecurityGroup data-plane and rule-mutation calls.

func WrapNotification 

func WrapNotification(inner notifdriver.Notification, engine *Engine) notifdriver.Notification

WrapNotification returns a notification driver that consults engine on every call.

func WrapSecrets 

func WrapSecrets(inner secretsdriver.Secrets, engine *Engine) secretsdriver.Secrets

WrapSecrets returns a secrets driver that consults engine on every call.

func WrapServerless 

func WrapServerless(inner serverlessdriver.Serverless, engine *Engine) serverlessdriver.Serverless

WrapServerless returns a serverless driver that consults engine on function lifecycle and invocation calls.

Types

type Active 

type Active struct {
	// contains filtered or unexported fields
}

Active is a handle returned by Apply that lets a caller cancel a scenario before its natural expiry.

func (*Active) Stop 

func (a *Active) Stop()

Stop removes the scenario from the engine. Safe to call multiple times.

type Effect 

type Effect struct {
	Latency time.Duration
	Error   error
}

Effect is what a chaos scenario produces for a given call. Either field may be the zero value (no latency / no error). When both are zero, the call proceeds normally.

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine is the registry and dispatcher of active scenarios. It's safe for concurrent use.

func New 

func New(clock config.Clock) *Engine

New returns an engine that uses clock for time-based scenario activation. Pass a config.FakeClock for deterministic tests.

func (*Engine) Apply 

func (e *Engine) Apply(s Scenario) *Active

Apply registers a scenario. The returned Active can be used to stop it before it expires.

func (*Engine) Check 

func (e *Engine) Check(service, operation string) Effect

Check is what driver wrappers call on every operation. It returns the merged effect from every active scenario:

  • latencies sum (worst case)
  • the first non-nil error wins

Expired scenarios are dropped lazily here.

func (*Engine) Recorded 

func (e *Engine) Recorded() []Recorded

Recorded returns a snapshot of every chaos event the engine has seen since the last Reset. Useful for post-test assertions.

func (*Engine) Reset 

func (e *Engine) Reset()

Reset clears the recorded events buffer. Active scenarios are untouched.

func (*Engine) Stop 

func (e *Engine) Stop()

Stop removes every active scenario. Idiomatic to defer at test setup.

type Recorded 

type Recorded struct {
	When      time.Time
	Service   string
	Operation string
	Effect    Effect
}

Recorded captures one chaos event for post-test inspection.

type Scenario 

type Scenario interface {
	// EffectOn returns the effect to apply to a given service+operation call
	// at this moment, or a zero Effect if the scenario doesn't apply.
	EffectOn(now time.Time, service, operation string) Effect

	// Active returns true while the scenario is in its effective window.
	// Once Active returns false, the engine drops it.
	Active(now time.Time) bool
}

Scenario describes a chaos pattern. It's queried by the engine on every driver call to decide what (if anything) should happen to it.

func Composite 

func Composite(scenarios ...Scenario) Scenario

Composite combines several scenarios into one. The merged Effect adds latencies and uses the first non-nil error.

func LatencySpike 

func LatencySpike(svc string, extra, duration time.Duration) Scenario

LatencySpike makes every call to service svc take an extra extra duration for the next duration window. Useful for testing client-side timeouts.

func ProbabilisticFailure 

func ProbabilisticFailure(svc, op string, err error, p float64, duration time.Duration) Scenario

ProbabilisticFailure injects err on a fraction p (0.0–1.0) of calls to service.operation, for the next duration window. If op is empty, applies to every operation on the service.

func ServiceOutage 

func ServiceOutage(svc string, duration time.Duration) Scenario

ServiceOutage simulates service svc being completely down for duration. Every call to it returns a ServiceUnavailable error during the window; after the window, calls succeed normally again.

func Throttle 

func Throttle(svc, op string, qps int, duration time.Duration) Scenario

Throttle simulates rate-limit pressure on service.operation: once qps calls are seen in any given 1-second wall-clock bucket, further calls in that bucket return Throttled. Resets each second. Active for duration.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.