bench

type Distribution struct {
	Count int     `json:"count"`
	Min   float64 `json:"min"`
	Mean  float64 `json:"mean"`
	P50   float64 `json:"p50"`
	P90   float64 `json:"p90"`
	P95   float64 `json:"p95"`
	P99   float64 `json:"p99"`
	Max   float64 `json:"max"`
	// StdDev is reported so a reader can see whether a mean is describing
	// anything, rather than averaging a bimodal distribution into fiction.
	StdDev float64 `json:"stddev"`
}

type Options struct {
	// Socket is the sandbox boundary's SOCKS5 Unix socket. Empty measures the
	// same workload without the boundary, which is the baseline the mesh
	// numbers are only meaningful against.
	Socket string

	// UnixTarget dials the target over this Unix socket instead of resolving
	// its host. It is how the baseline reaches the node's own API without a
	// relay in between: putting one there, socat or otherwise, would add a
	// userspace hop to the baseline and quietly flatter everything measured
	// against it.
	UnixTarget string

	// Target is the URL to request, e.g. http://mesh.sam.alt/v1/models.
	Target string

	// Method and Body are the request to issue. An empty Method means GET.
	Method string
	Body   []byte

	// Header carries anything the target needs, such as a content type.
	Header http.Header

	// Requests is how many to issue in total, after warmup.
	Requests int

	// Concurrency is how many are in flight at once.
	Concurrency int

	// Warmup requests are issued and discarded before measurement starts, so
	// first-call costs (DHT lookup, provider discovery, connection setup) do
	// not contaminate the steady-state distribution. They are reported
	// separately rather than thrown away.
	Warmup int

	// NewFlowPerRequest opens a fresh boundary flow for every request instead
	// of reusing connections. This separates the cost of admitting a flow from
	// the cost of carrying one, which are different questions.
	NewFlowPerRequest bool

	// Timeout bounds a single request.
	Timeout time.Duration
}

type Report struct {
	Target            string        `json:"target"`
	ThroughBoundary   bool          `json:"through_boundary"`
	NewFlowPerRequest bool          `json:"new_flow_per_request"`
	Concurrency       int           `json:"concurrency"`
	Requests          int           `json:"requests"`
	Warmup            int           `json:"warmup"`
	Succeeded         int           `json:"succeeded"`
	Failed            int           `json:"failed"`
	Elapsed           float64       `json:"elapsed_seconds"`
	Throughput        float64       `json:"requests_per_second"`
	TTFB              Distribution  `json:"ttfb_ms"`
	Total             Distribution  `json:"total_ms"`
	WarmupTTFB        *Distribution `json:"warmup_ttfb_ms,omitempty"`

	// Errors counts failures by their message, so a run that mostly failed
	// cannot be mistaken for a fast one.
	Errors map[string]int `json:"errors,omitempty"`
}

type Sample struct {
	// TTFB is the time until the response headers were available, which is
	// what an agent waiting on a first token actually experiences.
	TTFB time.Duration

	// Total additionally includes reading the body to completion.
	Total time.Duration

	// Status is the HTTP status, or 0 if the request never got one.
	Status int

	// Err is set when the request did not complete.
	Err error
}

type Series struct {
	Name   string
	Labels map[string]string
	Value  float64
}

type Snapshot struct {
	Source string    `json:"source"`
	Taken  time.Time `json:"taken"`
	Series []Series  `json:"-"`
}