Repository files navigation

The fault package provides go http middleware that makes it easy to inject faults into your service. Use the fault package to reject incoming requests, respond with an HTTP error, inject latency into a percentage of your requests, or inject any of your own custom faults.

The fault package works throughstandard go http middleware. You first create anInjector, which is a middleware with the code to be run on injection. Then you wrap thatInjector in aFault which handles logic about when to run yourInjector.

There are currently three kinds of injectors:SlowInjector,ErrorInjector, andRejectInjector. Each of these injectors can be configured through aFault to run on a small percent of your requests. You can also configure theFault to blocklist/allowlist certain paths.

See the usage section below for an example of how to get started and thegodoc for further documentation.

This package is useful for safely testing failure scenarios in go services that can make use ofnet/http handlers/middleware.

One common failure scenario that we cannot perfectly simulate is dropped requests. TheRejectInjector will always return immediately to the user, but in many cases requests can be dropped without ever sending a response. The best way to simulate this scenario using the fault package is to chain aSlowInjector with a very long wait time in front of an eventualRejectInjector.

This project is in a stable and supported state. There are no plans to introduce significant new features however we welcome and encourage any ideas and contributions from the community. Contributions should follow the guidelines in ourCONTRIBUTING.md.

// main.gopackage mainimport ("net/http""time""github.com/lingrino/go-fault")varmainHandler=http.HandlerFunc(func(w http.ResponseWriter,r*http.Request) {http.Error(w,http.StatusText(http.StatusOK),http.StatusOK)})funcmain() {slowInjector,_:=fault.NewSlowInjector(time.Second*2)slowFault,_:=fault.NewFault(slowInjector,fault.WithEnabled(true),fault.WithParticipation(0.25),fault.WithPathBlocklist([]string{"/ping","/health"}),        )// Add 2 seconds of latency to 25% of our requestshandlerChain:=slowFault.Handler(mainHandler)http.ListenAndServe("127.0.0.1:3000",handlerChain)}

This package uses standard go tooling for testing and development. Thego language is all you need to contribute. Tests use the populartestify/assert which will be downloaded automatically the first time you run tests. GitHub Actions will also run a linter usinggolangci-lint after you push. You can also download the linter and usegolangci-lint run to run locally.

The fault package has extensive tests that are run inGitHub Actions on every push. Code coverage is 100% and is published as an artifact on every Actions run.

You can also run tests locally:

$ gotest -v -cover -race ./...[...]PASScoverage: 100.0% of statementsok      github.com/lingrino/go-fault      0.575s

The fault package is safe to leave implemented even when you are not running a fault injection. While the fault is disabled there is negligible performance degradation compared to removing the package from the request path. While enabled there may be minor performance differences, but this will only be the casewhile you are already injecting faults.

Benchmarks are provided to compare without faults, with faults disabled, and with faults enabled. Benchmarks are uploaded as artifacts in GitHub Actions and you can download them from anyValidate Workflow.

You can also run benchmarks locally (example output):

$ gotest -run=XXX -bench=.goos: darwingoarch: amd64pkg: github.com/lingrino/go-faultBenchmarkNoFault-8                        684826              1734 ns/opBenchmarkFaultDisabled-8                  675291              1771 ns/opBenchmarkFaultErrorZeroPercent-8          667903              1823 ns/opBenchmarkFaultError100Percent-8           663661              1833 ns/opPASSok      github.com/lingrino/go-fault      8.814s

@lingrino

@mrfaizal@vroldanbet@fatih

This project is licensed under theMIT License.