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 ¶
- Constants
- func Bandwidth(bytesPerSecond int) vlatte.Pipe
- func ChunkedDribbleDelay(chunks int, total time.Duration) vlatte.Pipe
- func ConnectionResetByPeer() vlatte.Pipe
- func ConnectionResetByPeerAfter(d time.Duration) vlatte.Pipe
- func EmptyResponse() vlatte.Pipe
- func Latency(d vlatte.Delay) vlatte.Pipe
- func LimitData(n int) vlatte.Pipe
- func MalformedResponseChunk() vlatte.Pipe
- func RandomDataThenClose() vlatte.Pipe
- func Slicer(averageSize, sizeVariation int, delay time.Duration) vlatte.Pipe
- func SlowClose(delay time.Duration) vlatte.Pipe
- func Timeout(timeout time.Duration) vlatte.Pipe
Examples ¶
Constants ¶
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.
const RandomDataSize = 1 << 10
RandomDataSize is how many random bytes RandomDataThenClose sends.
Variables ¶
This section is empty.
Functions ¶
func Bandwidth ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
¶
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"}}. |