fault

package
v1.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package fault provides pipes that make a mock answer wrong, to test how a client handles a server that fails: no answer at all, a malformed one, garbage, a reset connection, a body that trickles in, a slow or distant network.

A fault is a vlatte.Pipe. Most write what isn't HTTP, so they need the bytes of the whole answer: they go with github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, over HTTP/1.x.

m.MustMock(mockhttp.Getf("/users").WirePipe(fault.ConnectionResetByPeer()).Reply(mockhttp.OK()))

ChunkedDribbleDelay changes when the body arrives, not what it is: it goes with github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe, over any protocol.

Those that act as a bad network does go with either: Latency, Bandwidth, Slicer, SlowClose, Timeout, LimitData and ConnectionResetByPeerAfter. With Pipe they act on the body; with WirePipe, on every byte of the answer, its head included. A reset with Pipe over HTTP/2 cuts the stream, as HTTP/2 has no connection of its own to reset.

m.MustMock(mockhttp.Getf("/report").Pipe(fault.Bandwidth(fault.Bandwidth3G)).Reply(mockhttp.OK().BodyFile("report.csv")))

A fault that ends the answer aborts its flow: the mock still counts the call, and runs its callbacks and events, before the connection ends.

Mock files declare faults as objects, such as {"type": "bandwidth", "rate": "3g"}, under pipes, wire_pipes and upstream_pipes: see github.com/caffeine-projects/vlatte/fault/faultbuild. Each fault describes itself as the object that builds it.

Index

Examples

Constants

View Source
const (
	BandwidthGPRS   = 50 * _kbps     // 50 kbit/s, GPRS
	BandwidthDialUp = 56 * _kbps     // 56 kbit/s, a dial-up modem
	Bandwidth2G     = 250 * _kbps    // 250 kbit/s, a regular 2G (EDGE) link
	BandwidthGood2G = 450 * _kbps    // 450 kbit/s, a good 2G link
	Bandwidth3G     = 750 * _kbps    // 750 kbit/s, a regular 3G link
	BandwidthGood3G = 1500 * _kbps   // 1.5 Mbit/s, a good 3G link
	BandwidthDSL    = 2000 * _kbps   // 2 Mbit/s, DSL
	Bandwidth4G     = 4000 * _kbps   // 4 Mbit/s, a regular 4G link
	BandwidthWiFi   = 30000 * _kbps  // 30 Mbit/s, Wi-Fi
	BandwidthFiber  = 100000 * _kbps // 100 Mbit/s, fiber
)

Common bandwidths, in bytes per second, for Bandwidth: those of the network throttling presets of browser developer tools, and of other common links.

View Source
const RandomDataSize = 1 << 10

RandomDataSize is how many random bytes RandomDataThenClose sends.

Variables

This section is empty.

Functions

func Bandwidth

func Bandwidth(bytesPerSecond int) vlatte.Pipe

Bandwidth returns a pipe that limits what passes to bytesPerSecond, such as Bandwidth3G, to test a client against a slow link: it sends each write in flushed pieces of a tenth of a second's worth of bytes, each once the time its bytes take at that rate passed since the write began, so a write of n bytes ends n/bytesPerSecond seconds later. The writer waits for it, as it would on a slow connection. The time between writes isn't counted: a write never goes faster for an earlier pause.

It goes with github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe, to slow the body, or with github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, to slow the whole answer. It panics when bytesPerSecond is less than 1.

func ChunkedDribbleDelay

func ChunkedDribbleDelay(chunks int, total time.Duration) vlatte.Pipe

ChunkedDribbleDelay returns a body pipe that sends the body in parts over total, chunks of them, to test a client against a slow network, deterministically: it holds the whole body until the reply wrote it, then sends part k, flushed, at k·total/chunks, and ends the body at total. Parts differ in size by a byte at most, and a body shorter than chunks has empty parts, which send nothing. An empty body ends at total.

It holds the body whole, so a stream that doesn't end, such as server-sent events, never goes out. It panics when chunks is less than 1, or total is negative.

func ConnectionResetByPeer

func ConnectionResetByPeer() vlatte.Pipe

ConnectionResetByPeer returns a wire pipe that resets the connection: at the first byte of the answer, or at its end, it aborts the flow with vlatte.ErrReset, so the connection closes with a TCP reset before a status line. The client reads a reset, such as syscall.ECONNRESET, not an end.

Example
package main

import (
	"errors"
	"fmt"
	"net/http"
	"syscall"

	"github.com/caffeine-projects/vlatte/fault"
	"github.com/caffeine-projects/vlatte/mockhttp"
)

func main() {
	m := mockhttp.MustNew(mockhttp.Setup().Silent())
	m.MustStart()
	defer m.Close()

	// A fault that writes what isn't HTTP goes with WirePipe.
	m.MustMock(mockhttp.Getf("/users").WirePipe(fault.ConnectionResetByPeer()).Reply(mockhttp.OK()))

	_, err := http.Get(m.URL("/users"))

	fmt.Println(errors.Is(err, syscall.ECONNRESET))
}
Output:
true

func ConnectionResetByPeerAfter

func ConnectionResetByPeerAfter(d time.Duration) vlatte.Pipe

ConnectionResetByPeerAfter returns a pipe that passes the answer on as it is, then resets the connection after d: it aborts the flow with vlatte.ErrReset d after it opened, as the answer began, to test a client that a reset meets while it reads. An answer that ends before d is flushed whole, then waits for the reset, so a client that reads until the end reads a reset. A d of 0 resets at once, as ConnectionResetByPeer does.

It goes with github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, or with github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe over HTTP/1, where a reset resets the connection too. It panics when d is negative.

func EmptyResponse

func EmptyResponse() vlatte.Pipe

EmptyResponse returns a wire pipe that sends nothing: at the first byte of the answer, or at its end, it aborts the flow, so the connection closes before a status line. The client reads the end of the connection where it waits for an answer.

func Latency

func Latency(d vlatte.Delay) vlatte.Pipe

Latency delays each write and flush by a duration chosen by d, preserving their order. The writer does not wait: the answer keeps its pace, only later. The end waits for the queued writes. Nil adds no delay. Evaluation errors are returned by Write or Flush. It goes with a mock's body Pipe or WirePipe to include the response headers.

func LimitData

func LimitData(n int) vlatte.Pipe

LimitData returns a pipe that passes the first n bytes of the answer on, flushed, then aborts the flow, so the connection closes, to test a client against an answer cut short. An answer of fewer than n bytes passes whole, and ends as it would; a longer one, or one of n bytes, is cut once its n-th byte went out. A limit of 0 cuts the answer at its first byte.

With github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe, n counts the bytes of the body. With github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, it counts every byte of the answer, its status line, headers and framing included. It panics when n is negative.

Example
package main

import (
	"errors"
	"fmt"
	"io"
	"net/http"

	"github.com/caffeine-projects/vlatte/fault"
	"github.com/caffeine-projects/vlatte/mockhttp"
)

func main() {
	m := mockhttp.MustNew(mockhttp.Setup().Silent())
	m.MustStart()
	defer m.Close()

	// With Pipe, the limit counts the bytes of the body: the client gets the head, then 5 bytes of 11.
	m.MustMock(mockhttp.Getf("/report").Pipe(fault.LimitData(5)).Reply(mockhttp.OK().PlainText("hello world")))

	res, err := http.Get(m.URL("/report"))
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)

	fmt.Println(res.StatusCode, string(body))
	fmt.Println(errors.Is(err, io.ErrUnexpectedEOF))
}
Output:
200 hello
true

func MalformedResponseChunk

func MalformedResponseChunk() vlatte.Pipe

MalformedResponseChunk returns a wire pipe that breaks the body of a chunked answer: it passes the status line and the headers on, with the mock's own status, then sends garbage in place of the first chunk, and aborts the flow, so the connection closes. The client reads a valid head, then fails to read the body. It breaks the answer after the first head, an informational one, such as 103 Early Hints, included. The body of an HTTP/1.0 answer isn't chunked: the client reads the garbage as the body.

func RandomDataThenClose

func RandomDataThenClose() vlatte.Pipe

RandomDataThenClose returns a wire pipe that sends RandomDataSize random bytes in place of the answer, then aborts the flow, so the connection closes: at the first byte of the answer, or at its end. The client reads garbage where it waits for a status line.

func Slicer

func Slicer(averageSize, sizeVariation int, delay time.Duration) vlatte.Pipe

Slicer returns a pipe that slices each write into flushed slices of averageSize bytes, give or take sizeVariation, at random, and waits delay before each slice, to test a client that takes one read for a whole message: the client reads the answer in many small reads. The bytes, and their order, don't change. The writer waits for its slices. TCP can join slices that come close together: a delay keeps them apart.

It goes with github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe, to slice the body, or with github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, to slice the whole answer, its head included. It panics when averageSize is less than 1, sizeVariation is negative or not less than averageSize, or delay is negative.

func SlowClose

func SlowClose(delay time.Duration) vlatte.Pipe

SlowClose returns a pipe that delays the end of the answer by delay, as a server slow to close its connection does: it passes the answer on as it is, flushes it at its end, then waits delay before it ends it. The client has every byte by then, and waits only when it reads until the end.

With github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe, the end of the body waits: the last chunk of a chunked body. With github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, the close of the connection waits, after the last chunk: a body that ends with the connection, as over HTTP/1.0, waits for it. It panics when delay is negative.

func Timeout

func Timeout(timeout time.Duration) vlatte.Pipe

Timeout returns a pipe that sends nothing, then ends the answer after timeout, to test a client's read timeout against a server that hangs: it drops every write and flush, and aborts the flow timeout after it opened, as the answer began, so the connection closes. The writer doesn't wait for it, but the end of the answer does. A timeout of 0 never ends it: the answer hangs until the flow's context ends, as when the client leaves, with Pipe, or the server closes.

With github.com/caffeine-projects/vlatte/mockhttp.Builder.WirePipe, the client gets no byte, not even a status line. With github.com/caffeine-projects/vlatte/mockhttp.Builder.Pipe, the server sends the head as it cuts the answer: the client waits, then reads a head and the end of the connection where the body should be. It panics when timeout is negative.

Example
package main

import (
	"errors"
	"fmt"
	"net"
	"net/http"
	"time"

	"github.com/caffeine-projects/vlatte/fault"
	"github.com/caffeine-projects/vlatte/mockhttp"
)

func main() {
	m := mockhttp.MustNew(mockhttp.Setup().Silent())
	m.MustStart()
	defer m.Close()

	// A timeout of 0 hangs until the server closes: the client's own timeout ends the wait.
	m.MustMock(mockhttp.Getf("/slow").WirePipe(fault.Timeout(0)).Reply(mockhttp.OK()))

	client := &http.Client{Timeout: 50 * time.Millisecond}

	_, err := client.Get(m.URL("/slow"))

	netErr, ok := errors.AsType[net.Error](err)
	fmt.Println(ok && netErr.Timeout())
}
Output:
true

Types

This section is empty.

Directories

Path Synopsis
Package faultbuild builds the faults of package github.com/caffeine-projects/vlatte/fault from the fault specs of mock files: an object whose type names the fault and whose other keys are its parameters, such as {"type": "latency", "delay": {"type": "jitter", "latency": "300ms", "jitter": "60ms"}}.
Package faultbuild builds the faults of package github.com/caffeine-projects/vlatte/fault from the fault specs of mock files: an object whose type names the fault and whose other keys are its parameters, such as {"type": "latency", "delay": {"type": "jitter", "latency": "300ms", "jitter": "60ms"}}.

Jump to

Keyboard shortcuts

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