Documentation
¶
Index ¶
- Constants
- Variables
- func Client(c *http.Client) func(*Attacker)
- func Connections(n int) func(*Attacker)
- func H2C(enabled bool) func(*Attacker)
- func HTTP2(enabled bool) func(*Attacker)
- func KeepAlive(keepalive bool) func(*Attacker)
- func LocalAddr(addr net.IPAddr) func(*Attacker)
- func MaxBody(n int64) func(*Attacker)
- func MaxWorkers(n uint64) func(*Attacker)
- func Proxy(proxy func(*http.Request) (*url.URL, error)) func(*Attacker)
- func Redirects(n int) func(*Attacker)
- func TLSConfig(c *tls.Config) func(*Attacker)
- func Timeout(d time.Duration) func(*Attacker)
- func UnixSocket(socket string) func(*Attacker)
- func Workers(n uint64) func(*Attacker)
- type Attacker
- type Buckets
- type ByteMetrics
- type Closer
- type ConstantPacer
- type Decoder
- type DecoderFactory
- type Encoder
- type Histogram
- type LatencyMetrics
- type Metrics
- type Pacer
- type PacerFunc
- type Rate
- type Report
- type Reporter
- type Result
- type Results
- type SinePacer
- type Target
- type TargetEncoder
- type Targeter
Constants ¶
const ( // DefaultRedirects is the default number of times an Attacker follows // redirects. DefaultRedirects = 10 // DefaultTimeout is the default amount of time an Attacker waits for a request // before it times out. DefaultTimeout = 30 * time.Second // DefaultConnections is the default amount of max open idle connections per // target host. DefaultConnections = 10000 // DefaultWorkers is the default initial number of workers used to carry an attack. DefaultWorkers = 10 // DefaultMaxWorkers is the default maximum number of workers used to carry an attack. DefaultMaxWorkers = math.MaxUint64 // DefaultMaxBody is the default max number of bytes to be read from response bodies. // Defaults to no limit. DefaultMaxBody = int64(-1) // NoFollow is the value when redirects are not followed but marked successful NoFollow = -1 )
const ( // MeanUp is a SinePacer Offset that causes the attack to start // at the Mean attack rate and increase towards the peak. MeanUp float64 = 0 // Peak is a SinePacer Offset that causes the attack to start // at the peak (maximum) attack rate and decrease towards the Mean. Peak = math.Pi / 2 // MeanDown is a SinePacer Offset that causes the attack to start // at the Mean attack rate and decrease towards the trough. MeanDown = math.Pi // Trough is a SinePacer Offset that causes the attack to start // at the trough (minimum) attack rate and increase towards the Mean. Trough = 3 * math.Pi / 2 )
const ( // HTTPTargetFormat is the human readable identifier for the HTTP target format. HTTPTargetFormat = "http" // JSONTargetFormat is the human readable identifier for the JSON target format. JSONTargetFormat = "json" )
Variables ¶
var ( // DefaultLocalAddr is the default local IP address an Attacker uses. DefaultLocalAddr = net.IPAddr{IP: net.IPv4zero} // DefaultTLSConfig is the default tls.Config an Attacker uses. DefaultTLSConfig = &tls.Config{InsecureSkipVerify: true} )
var ( // ErrNoTargets is returned when not enough Targets are available. ErrNoTargets = errors.New("no targets to attack") // ErrNilTarget is returned when the passed Target pointer is nil. ErrNilTarget = errors.New("nil target") // ErrNoMethod is returned by JSONTargeter when a parsed Target has // no method. ErrNoMethod = errors.New("target: required method is missing") // ErrNoURL is returned by JSONTargeter when a parsed Target has no // URL. ErrNoURL = errors.New("target: required url is missing") // TargetFormats contains the canonical list of the valid target // format identifiers. TargetFormats = []string{HTTPTargetFormat, JSONTargetFormat} )
Functions ¶
func Connections ¶
Connections returns a functional option which sets the number of maximum idle open connections per target host.
func H2C ¶
H2C returns a functional option which enables H2C support on requests performed by an Attacker
func HTTP2 ¶
HTTP2 returns a functional option which enables or disables HTTP/2 support on requests performed by an Attacker.
func KeepAlive ¶
KeepAlive returns a functional option which toggles KeepAlive connections on the dialer and transport.
func LocalAddr ¶
LocalAddr returns a functional option which sets the local address an Attacker will use with its requests.
func MaxBody ¶
MaxBody returns a functional option which limits the max number of bytes read from response bodies. Set to -1 to disable any limits.
func MaxWorkers ¶
MaxWorkers returns a functional option which sets the maximum number of workers an Attacker can use to hit its targets.
func Proxy ¶
Proxy returns a functional option which sets the `Proxy` field on the http.Client's Transport
func Redirects ¶
Redirects returns a functional option which sets the maximum number of redirects an Attacker will follow.
func TLSConfig ¶
TLSConfig returns a functional option which sets the *tls.Config for a Attacker to use with its requests.
func Timeout ¶
Timeout returns a functional option which sets the maximum amount of time an Attacker will wait for a request to be responded to and completely read.
func UnixSocket ¶
UnixSocket changes the dialer for the attacker to use the specified unix socket file
Types ¶
type Attacker ¶
type Attacker struct {
// contains filtered or unexported fields
}
Attacker is an attack executor which wraps an http.Client
func NewAttacker ¶
NewAttacker returns a new Attacker with default options which are overridden by the optionally provided opts.
func (*Attacker) Attack ¶
Attack reads its Targets from the passed Targeter and attacks them at the rate specified by the Pacer. When the duration is zero the attack runs until Stop is called. Results are sent to the returned channel as soon as they arrive and will have their Attack field set to the given name.
type Buckets ¶
Buckets represents an Histogram's latency buckets.
func (*Buckets) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
type ByteMetrics ¶
type ByteMetrics struct {
// Total is the total number of flowing bytes in an attack.
Total uint64 `json:"total"`
// Mean is the mean number of flowing bytes per hit.
Mean float64 `json:"mean"`
}
ByteMetrics holds computed byte flow metrics.
type Closer ¶
type Closer interface {
// Close permantently closes a Report, running any necessary book keeping.
Close()
}
Closer wraps the optional Report Close method.
type ConstantPacer ¶
type ConstantPacer struct {
Freq int // Frequency (number of occurrences) per ...
Per time.Duration // Time unit, usually 1s
}
A ConstantPacer defines a constant rate of hits for the target.
func (ConstantPacer) String ¶
func (cp ConstantPacer) String() string
String returns a pretty-printed description of the ConstantPacer's behaviour:
ConstantPacer{Freq: 1, Per: time.Second} => Constant{1 hits/1s}
type Decoder ¶
A Decoder decodes a Result and returns an error in case of failure.
func DecoderFor ¶
DecoderFor automatically detects the encoding of the first few bytes in the given io.Reader and then returns the corresponding Decoder or nil in case of failing to detect a supported encoding.
func NewCSVDecoder ¶
NewCSVDecoder returns a Decoder that decodes CSV encoded Results.
func NewDecoder ¶
NewDecoder returns a new gob Decoder for the given io.Reader.
func NewJSONDecoder ¶
NewJSONDecoder returns a Decoder that decodes JSON encoded Results.
func NewRoundRobinDecoder ¶
NewRoundRobinDecoder returns a new Decoder that round robins across the given Decoders on every invocation or decoding error.
type DecoderFactory ¶
A DecoderFactory constructs a new Decoder from a given io.Reader.
type Encoder ¶
An Encoder encodes a Result and returns an error in case of failure.
func NewCSVEncoder ¶
NewCSVEncoder returns an Encoder that dumps the given *Result as a CSV record. The columns are: UNIX timestamp in ns since epoch, HTTP status code, request latency in ns, bytes out, bytes in, response body, and lastly the error.
func NewEncoder ¶
NewEncoder returns a new Result encoder closure for the given io.Writer
func NewJSONEncoder ¶
NewJSONEncoder returns an Encoder that dumps the given *Results as a JSON object.
type Histogram ¶
Histogram is a bucketed latency Histogram.
func (*Histogram) Add ¶
Add implements the Add method of the Report interface by finding the right Bucket for the given Result latency and increasing its count by one as well as the total count.
func (*Histogram) MarshalJSON ¶
MarshalJSON returns a JSON encoding of the buckets and their counts.
type LatencyMetrics ¶
type LatencyMetrics struct {
// Total is the total latency sum of all requests in an attack.
Total time.Duration `json:"total"`
// Mean is the mean request latency.
Mean time.Duration `json:"mean"`
// P50 is the 50th percentile request latency.
P50 time.Duration `json:"50th"`
// P95 is the 95th percentile request latency.
P95 time.Duration `json:"95th"`
// P99 is the 99th percentile request latency.
P99 time.Duration `json:"99th"`
// Max is the maximum observed request latency.
Max time.Duration `json:"max"`
// contains filtered or unexported fields
}
LatencyMetrics holds computed request latency metrics.
func (*LatencyMetrics) Add ¶
func (l *LatencyMetrics) Add(latency time.Duration)
Add adds the given latency to the latency metrics.
type Metrics ¶
type Metrics struct {
// Latencies holds computed request latency metrics.
Latencies LatencyMetrics `json:"latencies"`
// Histogram, only if requested
Histogram *Histogram `json:"buckets,omitempty"`
// BytesIn holds computed incoming byte metrics.
BytesIn ByteMetrics `json:"bytes_in"`
// BytesOut holds computed outgoing byte metrics.
BytesOut ByteMetrics `json:"bytes_out"`
// Earliest is the earliest timestamp in a Result set.
Earliest time.Time `json:"earliest"`
// Latest is the latest timestamp in a Result set.
Latest time.Time `json:"latest"`
// End is the latest timestamp in a Result set plus its latency.
End time.Time `json:"end"`
// Duration is the duration of the attack.
Duration time.Duration `json:"duration"`
// Wait is the extra time waiting for responses from targets.
Wait time.Duration `json:"wait"`
// Requests is the total number of requests executed.
Requests uint64 `json:"requests"`
// Rate is the rate of sent requests per second.
Rate float64 `json:"rate"`
// Throughput is the rate of successful requests per second.
Throughput float64 `json:"throughput"`
// Success is the percentage of non-error responses.
Success float64 `json:"success"`
// StatusCodes is a histogram of the responses' status codes.
StatusCodes map[string]int `json:"status_codes"`
// Errors is a set of unique errors returned by the targets during the attack.
Errors []string `json:"errors"`
// contains filtered or unexported fields
}
Metrics holds metrics computed out of a slice of Results which are used in some of the Reporters
type Pacer ¶
A Pacer defines the rate of hits during an Attack by returning the duration an Attacker should wait until hitting the next Target. If the second return value is true, the attack will terminate.
type Rate ¶
type Rate = ConstantPacer
Rate is a type alias for ConstantPacer for backwards-compatibility.
type Report ¶
type Report interface {
// Add adds a given *Result to a Report.
Add(*Result)
}
A Report represents the state a Reporter uses to write out its reports.
type Reporter ¶
A Reporter function writes out reports to the given io.Writer or returns an error in case of failure.
func NewHDRHistogramPlotReporter ¶
NewHDRHistogramPlotReporter returns a Reporter that writes out latency metrics in a format plottable by http://hdrhistogram.github.io/HdrHistogram/plotFiles.html.
func NewHistogramReporter ¶
NewHistogramReporter returns a Reporter that writes out a Histogram as aligned, formatted text.
func NewJSONReporter ¶
NewJSONReporter returns a Reporter that writes out Metrics as JSON.
func NewTextReporter ¶
NewTextReporter returns a Reporter that writes out Metrics as aligned, formatted text.
type Result ¶
type Result struct {
Attack string `json:"attack"`
Seq uint64 `json:"seq"`
Code uint16 `json:"code"`
Timestamp time.Time `json:"timestamp"`
Latency time.Duration `json:"latency"`
BytesOut uint64 `json:"bytes_out"`
BytesIn uint64 `json:"bytes_in"`
Error string `json:"error"`
Body []byte `json:"body"`
}
Result contains the results of a single Target hit.
type Results ¶
type Results []Result
Results is a slice of Result type elements.
func (*Results) Add ¶
Add implements the Add method of the Report interface by appending the given Result to the slice.
type SinePacer ¶
type SinePacer struct {
// The period of the sine wave, e.g. 20*time.Minute
// MUST BE > 0
Period time.Duration
// The mid-point of the sine wave in freq-per-Duration,
// MUST BE > 0
Mean Rate
// The amplitude of the sine wave in freq-per-Duration,
// MUST NOT BE EQUAL TO OR LARGER THAN MEAN
Amp Rate
// The offset, in radians, for the sine wave at t=0.
StartAt float64
}
SinePacer is a Pacer that describes attack request rates with the equation:
R = MA sin(O+(2𝛑/P)t)
Where:
R = Instantaneous attack rate at elapsed time t, hits per nanosecond M = Mean attack rate over period P, sp.Mean, hits per nanosecond A = Amplitude of sine wave, sp.Amp, hits per nanosecond O = Offset of sine wave, sp.StartAt, radians P = Period of sine wave, sp.Period, nanoseconds t = Elapsed time since attack start, nanoseconds
Many thanks to http://ascii.co.uk/art/sine and "sps" for the ascii here :-)
Mean -| ,-'''-.
+Amp | ,-' | `-.
| ,' | `. O=𝛑
| ,' O=𝛑/2 `. MeanDown
| / Peak \ /
|/ \ /
Mean -+-------------------------\--------------------------> t
|\ \ /
| \ \ O=3𝛑/2 /
| O=0 `. Trough ,'
| MeanUp `. | ,'
Mean | `-. | ,-'
-Amp -| `-,,,-'
|<-------------------- Period --------------------->|
This equation is integrated with respect to time to derive the expected number of hits served at time t after the attack began:
H = Mt - (AP/2𝛑)cos(O+(2𝛑/P)t) + (AP/2𝛑)cos(O)
Where:
H = Total number of hits triggered during t
type Target ¶
type Target struct {
Method string `json:"method"`
URL string `json:"url"`
Body []byte `json:"body,omitempty"`
Header http.Header `json:"header,omitempty"`
}
Target is an HTTP request blueprint.
func ReadAllTargets ¶
ReadAllTargets eagerly reads all Targets out of the provided Targeter.
type TargetEncoder ¶
A TargetEncoder encodes a Target in a format that can be read by a Targeter.
func NewJSONTargetEncoder ¶
func NewJSONTargetEncoder(w io.Writer) TargetEncoder
NewJSONTargetEncoder returns a TargetEncoder that encods Targets in the JSON format.
func (TargetEncoder) Encode ¶
func (enc TargetEncoder) Encode(t *Target) error
Encode is a convenience method that calls the underlying TargetEncoder function.
type Targeter ¶
A Targeter decodes a Target or returns an error in case of failure. Implementations must be safe for concurrent use.
func NewHTTPTargeter ¶
NewHTTPTargeter returns a new Targeter that decodes one Target from the given io.Reader on every invocation. The format is as follows:
GET https://foo.bar/a/b/c Header-X: 123 Header-Y: 321 @/path/to/body/file POST https://foo.bar/b/c/a Header-X: 123
body will be set as the Target's body if no body is provided. hdr will be merged with the each Target's headers.
func NewJSONTargeter ¶
NewJSONTargeter returns a new targeter that decodes one Target from the given io.Reader on every invocation. Each target is one JSON object in its own line.
The method and url fields are required. If present, the body field must be base64 encoded. The generated [JSON Schema](lib/target.schema.json) defines the format in detail.
{"method":"POST", "url":"https://goku/1", "header":{"Content-Type":["text/plain"], "body": "Rk9P"}
{"method":"GET", "url":"https://goku/2"}
body will be set as the Target's body if no body is provided in each target definiton. hdr will be merged with the each Target's headers.
func NewStaticTargeter ¶
NewStaticTargeter returns a Targeter which round-robins over the passed Targets.
Source Files
Directories