netquality

README

netquality

Measure the capacity, latency and responsiveness of a network path by running the IETF Responsiveness under Working Conditions test (draft-ietf-ippm-responsiveness-09) against Apple's, Cloudflare's, or your own server. Ships as three things: a Go library, the nq client, and nqserver, a reference server you can host yourself.

• Windows, macOS and Linux on amd64 and arm64, supported as measurement targets rather than just build targets: where a platform's defaults would distort a number, the library works around them.
• Standard library only, no CGO, so it adds nothing to your build. Requires Go 1.26+ (older lines no longer receive TLS/HTTP security fixes).
• Every run is bounded by time and connection count before it starts — and by bytes too when you say the link is metered — and every number in the result says how it was obtained.
• Sends nothing over the network except the test itself.

$ nq --target apple
Target     mensura.cdn-apple.com (HTTP/2.0) 17.253.24.71
Idle       102.2ms median, 131.8ms p80, jitter 32.5ms (5 probes)
Download      178.3 Mbps    365 RPM  loaded 185.2ms median, 512.6ms p99  [8 flows, high/high confidence]
Upload        125.9 Mbps    311 RPM  (>= 121.4 Mbps, <= 330 RPM over 4s)  loaded 160.7ms median, 471.0ms p99  [8 flows, medium/low confidence, TRUNCATED: duration_cap]
Cost       370.5 MB moved in 21.0s

What it measures

1. Discovery – fetches the server's JSON config (/.well-known/nq or a vendor path) to learn the small-download, large-download and upload URLs.
2. Idle latency – IdleProbes sequential GETs of the 1-byte resource, each on a fresh connection, so a sample includes DNS + TCP + TLS + HTTP. Per-stage medians are reported via net/http/httptrace.
3. Download under load, then upload under load (sequentially, so the two loaded-latency figures are distinct). Each phase:
   • opens one HTTP/2 connection to the large resource and adds one more every interval (1 s) up to MaxFlows;
   • meanwhile fires foreign probes (fresh connections) and self probes (multiplexed on a random load connection), interleaved, at up to MaxProbesPerSecond and never more than 5 % of measured capacity;
   • declares throughput stable when the standard deviation of the last four moving averages is under 5 % of the current one, then does the same for responsiveness and stops.
4. Responsiveness (RPM) – "round trips per minute", 60000 / RTT_ms. Following the draft: foreign = 60000 / mean(TM(tcp), TM(tls per RTT), TM(http)), self = 60000 / TM(http_on_loaded_connection), RPM = (foreign+self)/2, where TM is the single-sided trimmed mean at the 95th percentile over the last four intervals. Roughly: < 300 RPM poor, > 1000 good, > 6000 excellent.
5. Jitter – mean absolute deviation of the samples from their mean, reported for idle and loaded sets. Percentiles (p80/p90/p95/p99) appear only when there are enough samples for them to differ from the maximum (5/10/20/100 under nearest rank), so the default five idle probes yield p80, never a fake p95.
6. Cost – bytes moved and wall time per phase.

Library

import "github.com/korya/netquality"

res, err := netquality.Run(ctx, netquality.Cloudflare, netquality.Options{
    MaxDuration: 10 * time.Second, // per direction; the budget
    MaxBytes:    100 << 20,        // optional: only on metered links
    MaxFlows:    8,
})
if err != nil { /* discovery failed, or ctx cancelled (res is then partial) */ }
fmt.Println(res.Download.RPM, res.Download.ThroughputBPS, res.Download.Truncated)

Result.Target records the server IPs the flows reached (resolved_ips) and the local source addresses they went out on (local_ips), so a stored result can be tied to the interface or network it was measured on. Both are present on cancelled partial results too, and both stay in the result if you share it.

Targets: netquality.Apple, netquality.Cloudflare, netquality.WellKnown("host:port"), or netquality.Target{ConfigURL: "..."}.

RunWithEvents takes a func(Event) sink for progress bars. Proxies and TLS settings come through Options.HTTPClient (its *http.Transport is cloned per flow so each flow owns a connection). Options.Logger accepts a *slog.Logger.

Result marshals to JSON with stable snake_case names; the CLI's --json output is exactly that struct. schema_version (currently 1) is its first field: it changes only when a field is renamed, removed, retyped, or changes meaning — never for additions — so stored documents stay interpretable. Directions that did not run are omitted, not zero. Each DirectionResult carries truncated, reason (bytes_cap | duration_cap | cancelled | flow_error) and the draft's throughput_confidence / responsiveness_confidence (low | medium | high). Whenever four consecutive intervals agreed, a direction also carries throughput_lower_bound_bps — a conservative figure that holds even when the estimate did not converge — with its lower_bound_window and rpm_upper_bound (LOAD-13).

CLI

nq                                   # Cloudflare, both directions
nq --target apple
nq --well-known nq.example.com:8443 [--insecure]
nq --config-url https://host/path/config
nq --download-only | --upload-only
nq --max-duration 8s --max-flows 8          # time is the budget
nq --max-bytes 100MB                         # metered link: add a byte cap
nq --json                            # Result as one JSON document on stdout
nq --events                          # JSON-lines progress on stderr
nq version

Exit codes: 0 ok, 1 the test failed or was cancelled, 2 bad usage.

Build with version info:

go build -ldflags "-X github.com/korya/netquality/internal/buildinfo.Version=v0.1.0 \
  -X github.com/korya/netquality/internal/buildinfo.Commit=$(git rev-parse HEAD)" ./cmd/nq

Self-hosting nqserver

go run ./cmd/nqserver --self-signed --listen :8443
nq --well-known localhost:8443 --insecure

For real deployments pass --cert/--key; --base-url sets the advertised URL prefix when behind a load balancer, --test-endpoint advertises a specific host. The server needs HTTP/2 end to end and must not compress or redirect.

Access control. With a real certificate the server refuses to start anonymously; give it a token and give the client the same one:

NQSERVER_AUTH_TOKEN=s3cret nqserver --cert c.pem --key k.pem
NQ_AUTH_TOKEN=s3cret nq --well-known nq.example.com

(--auth-token works on both; the environment keeps the secret out of ps.) Every endpoint, config included, answers 401 without the token. Library callers set Options.Header. --allow-anonymous opts out explicitly; --self-signed implies it for local development.

Load limits protect egress without biasing measurements — they gate whether a request may start, never slow one down:

Flag	Default	Effect
--client-bytes / --client-window	8 GiB / 10 min (unlimited with --self-signed)	per client IP; a refused request gets 429 + Retry-After
--upload-size	16 GiB	bytes accepted by one upload
--large-size	8 GiB	bytes served by one download
--max-connections	256	extra connections wait in the accept queue
--idle-timeout	2 min	closes a connection with no request in flight; HTTP/2 peers are pinged after 30 s of silence; transfers are never cut

Behind a load balancer the client key is the balancer's address; the server deliberately does not trust X-Forwarded-For — use signed URLs with a subject (below) to key budgets per device instead.

Signed URLs — no secret on clients. Your backend serves the config document with test URLs it has signed; nqserver verifies them and the laptop never holds a reusable credential:

nqserver sign --new-key                       # once: a 32-byte key, keep it on the backend and the server
NQSERVER_SIGNING_KEY=<key> nqserver --cert c.pem --key k.pem
nqserver sign --key <key> --ttl 10m --sub laptop-7 https://nq.example.com/nq/small \
    https://nq.example.com/nq/large https://nq.example.com/nq/upload

Put the three signed URLs in a config document served by your backend and point the client at it (Target{ConfigURL: "https://backend/nq-config"}). The client needs no flags. The signature covers only the path, exp and sub — sig = base64url(HMAC-SHA256(key, path + "\n" + exp + "\n" + sub)) — so any language can issue it, parameter order is irrelevant, and unsigned parameters are deliberately unprotected (never let a server trust them). Validity is exp + 30 s leeway, at most 24 h — keep issuer and server clocks in sync, a server clock behind the issuer refuses everything as "issued too far ahead". Sign the decoded path (/nq/large, not /nq/%6Carge), percent‑encode sub (a raw + decodes to a space and fails closed), and emit sig in any base64 flavour. sub keys the per-client budget, so ten laptops behind one NAT get ten budgets. Repeat --signing-key to rotate. Go backends can call server.SignURL.

mTLS works today without a flag: wrap server.Handler in your own http.Server with TLSConfig.ClientAuth = tls.RequireAndVerifyClientCert and ClientCAs, and give the client its certificate via Options.HTTPClient.Transport.TLSClientConfig.Certificates. A --client-ca flag is tracked in issue #10.

Proxies

Corporate laptops often sit behind proxies, in which case the test measures the laptop→proxy leg, not the path to the server. The result says so rather than reporting plausible-but-wrong numbers:

• Explicit proxy (HTTPS_PROXY, PAC, or Transport.Proxy on the client you pass in): target.proxy.explicit=true with the proxy url (credentials stripped). HTTP/2 still works through CONNECT tunnels. test_endpoint cannot be honoured, and a warning says so.
• TLS interception (Zscaler, Netskope, and similar): the certificate chain verifies against the corporate root, but the leaf carries no Certificate Transparency SCTs, which every publicly trusted certificate has had since 2018. target.proxy.tls_interception=true with the issuer and a reason. A self-hosted nqserver behind a private CA triggers the same flag, since the trust situation is identical; the wording says "proxy or private CA". --insecure skips verification and therefore never triggers it.

Both cases add a warning. Confidence scores are unaffected: the algorithm converged on a real measurement, just of a shorter path. Not detected: proxies that re-issue publicly trusted certificates (not possible without a CA compromise) and transparent TCP-level proxies that pass TLS through untouched (those are not altering the measurement).

Safety limits

Limit	Default	Effect
MaxDuration	12 s per direction	the budget: phase ends; if not yet stable → truncated, reason=duration_cap. Cost ≤ rate × 12 s
MaxBytes	none (opt-in)	set on metered links; phase ends → reason=bytes_cap
MaxFlows	16	never more concurrent load connections
ctx cancellation	–	all flows stop within ~200 ms; partial result, cancelled=true

There are no retries, no background goroutines after Run returns, and no telemetry.

Deviations from the draft

Item	Draft	Here	Why
Interval (ID)	5 s	1 s	4 intervals must complete before stability can be declared; with the 12 s per-direction budget a 5 s interval could never stabilise. Earlier drafts and shipping tools use 1 s. Configurable via Stability.Interval.
Time budget	"implementations may" limit	mandatory MaxDuration; MaxBytes opt-in	Runs on other people's machines and networks; a time bound makes cost proportional to the link instead of unbounded.
Byte cap default	(handoff spec: 250 MB)	none	A fixed byte cap starves fast links of the intervals a confident RPM needs (≈ 8 × rate); the caller knows which networks are metered, the library cannot.
Flow error	abort the test	abort the phase, report reason=flow_error, keep other results	Partial data with a flag beats none.
Self probes on HTTP/1.1	use TCP RTT estimate	omitted; RPM from foreign probes only, warning recorded	TCP_INFO is not portable in pure Go.
Flow addition	one per interval	doubling each interval while a step gains ≥ 10 % goodput, up to MaxFlows	Reaches saturation in ≤ 5 intervals instead of 16, so a 10 Gbps or high-RTT link still settles inside the 12 s budget; a slow link stops after one exploratory flow.
Responsiveness tracking	after goodput stability	from the end of the ramp; stability judged on the windowed values, not on averages of them	Removes 3–4 s of latency from every run; the phase still ends only with both series stable.
Upload byte accounting	–	intervals inflated by the HTTP/2 send window of new flows are excluded	Bytes are counted when the transport takes them; on a 20 Mbps link the 4 MiB credit otherwise reports 53 Mbps with high confidence.
Capacity change	–	a > 25 % goodput drop restarts stability tracking	The draft averages across the change.
Responsiveness window	last MAD intervals	every sample since throughput became stable (loaded_window)	Foreign probes are sparse (a TLS handshake each); a fixed 4-tick window could hold self samples and no foreign ones, which read as "no fresh connection ever succeeded". Stability is still judged on the draft's window.
Probe byte accounting	–	foreign 5000 B, self 1000 B (draft's estimates)	Counted against MaxBytes and the 5 % capacity rule.
Config version	must be 1	1 or "1" accepted	Lenient on the wire, strict on everything else (duplicates, hosts, scheme).
Config field names	*_download_url, upload_url	also accepts Apple/Cloudflare *_https_* names, preferring them	Interop with deployed servers.
Cloudflare target	mach hardcodes h3.speed.cloudflare.com URLs	uses aim.cloudflare.com/responsiveness/api/v1/config, which returns the same URLs	Keeps discovery uniform.

Other constants: IdleProbes=5 (enough for a median, cheap), ConfigTimeout=10s, in-flight probe cap 64 (bounds goroutines on high-RTT links), TLS handshake normalised to 1 RTT for TLS 1.3 and 2 for TLS 1.2.

Testing

go test ./...            # unit + end-to-end against an in-process nqserver
NQ_LIVE=1 go test -run TestLive -v .   # hits Apple and Cloudflare

docs/test-matrix.md maps every feature and use case to the test that exercises it; TestMatrix fails if a row names a missing test or a test is missing from the matrix. Behaviours only observable on real networks (stability under bufferbloat, probe throttling on slow links) run in the nightly Live workflow, which never blocks merges.

Releasing

1. Move the [Unreleased] items in CHANGELOG.md under a new ## [X.Y.Z] - date heading.
2. Commit, then git tag -a vX.Y.Z -m "netquality vX.Y.Z" && git push origin master vX.Y.Z.

The Release workflow runs the tests, builds nq and nqserver for all six platforms, and publishes a GitHub release whose notes are that changelog section. It fails if the section is missing.

Licence

Apache-2.0. Written from the draft and Apple's MIT-licensed SERVER_SPEC.md; no code from GPL implementations (e.g. goresponsiveness) is included.

Documentation

Overview

Package netquality measures download/upload capacity, idle and loaded latency, jitter and responsiveness (RPM) of a network path by running the IETF "Responsiveness under Working Conditions" test (draft-ietf-ippm-responsiveness) against a compatible server.

The library depends only on the standard library, emits no traffic besides the test itself, and bounds every run by duration, bytes and flow count before it starts. See Options for the limits and Result for how each number was obtained.

Typical use:

res, err := netquality.Run(ctx, netquality.Cloudflare, netquality.Options{})
if err != nil { ... }
fmt.Printf("%.0f RPM, %.1f Mbps down\n", res.Download.RPM, res.Download.ThroughputBPS/1e6)

Example

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/korya/netquality"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	res, err := netquality.Run(ctx, netquality.WellKnown("nq.example.com"), netquality.Options{
		MaxDuration: 10 * time.Second,
		MaxBytes:    100 << 20,
		MaxFlows:    8,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("idle %v, down %.1f Mbps / %.0f RPM (truncated=%v), up %.1f Mbps / %.0f RPM\n",
		res.Idle.Median, res.Download.ThroughputBPS/1e6, res.Download.RPM, res.Download.Truncated,
		res.Upload.ThroughputBPS/1e6, res.Upload.RPM)
}

Index

• Constants
• Variables
• type Confidence
• type DirectionResult
• type Directions
  • func (d Directions) MarshalJSON() ([]byte, error)
  • func (d Directions) String() string
• type Event
• type EventKind
• type IntervalWindow
• type LatencySample
• type LatencyStats
• type LoadedLatency
• type Options
• type ProxyInfo
• type ResolvedTarget
• type Result
  • func Run(ctx context.Context, t Target, o Options) (*Result, error)
  • func RunWithEvents(ctx context.Context, t Target, o Options, sink func(Event)) (*Result, error)
• type ServerConfig
  • func ParseServerConfig(data []byte) (*ServerConfig, error)
• type StabilityParams
  • func DefaultStabilityParams() StabilityParams
• type StageMedians
• type Target
  • func WellKnown(host string) Target
• type TruncationReason

Examples

• Package

Constants

const (
	DefaultMaxDuration = 12 * time.Second
	// DefaultMaxBytes is 0: no byte cap by default. Time is the budget —
	// cost is at most rate × MaxDuration per direction — so a confident
	// result is reachable at any link speed. Callers on metered links set
	// MaxBytes explicitly.
	DefaultMaxBytes = 0
	DefaultMaxFlows = 16
	// DefaultUploadSendBuffer is the per-flow credit assumed for uploads: Go's
	// HTTP/2 stream window, which the transport fills before bytes reach the
	// wire (StabilityParams.SendBufferBytes).
	DefaultUploadSendBuffer = 4 << 20
	DefaultIdleProbes       = 5
	// DefaultConfigTimeout bounds config discovery, which happens before the
	// per-direction budgets apply.
	DefaultConfigTimeout = 10 * time.Second
)

Default safety limits and probe counts.

const (
	ConfidenceLow    = engine.ConfidenceLow
	ConfidenceMedium = engine.ConfidenceMedium
	ConfidenceHigh   = engine.ConfidenceHigh
)

Confidence levels.

const ResultSchemaVersion = 1

ResultSchemaVersion identifies the JSON shape of Result. It is bumped when a field is renamed, removed, retyped, or changes meaning; adding fields never bumps it. Each bump is noted in the CHANGELOG.

Variables

var (
	// Apple is Apple's public responsiveness server (used by macOS `networkQuality`).
	Apple = Target{ConfigURL: "https://mensura.cdn-apple.com/api/v1/gm/config"}
	// Cloudflare is Cloudflare's public responsiveness server. Its `mach` CLI
	// hardcodes the h3.speed.cloudflare.com URLs; this config document returns
	// the same URLs.
	Cloudflare = Target{ConfigURL: "https://aim.cloudflare.com/responsiveness/api/v1/config"}
)

Well-known public targets.

var ErrInvalidConfig = errors.New("netquality: invalid server configuration")

ErrInvalidConfig is returned (wrapped) when a configuration document must be ignored per draft Section 8.1.

Types

type Confidence

type Confidence = engine.Confidence

Confidence is the draft's Section 5.4.1 confidence score.

type DirectionResult

type DirectionResult struct {
	Direction string `json:"direction"`
	// ThroughputBPS is the moving-average goodput (bits/s) over the last MAD
	// intervals at the end of the phase.
	ThroughputBPS float64 `json:"throughput_bps"`
	// PeakThroughputBPS is the highest single-interval goodput observed.
	PeakThroughputBPS float64 `json:"peak_throughput_bps"`
	// MeanThroughputBPS is Bytes*8/Duration over the whole phase, ramp-up
	// included. It is the only throughput figure when no interval completed.
	MeanThroughputBPS float64 `json:"mean_throughput_bps"`
	// Bytes moved by this phase (payload of load flows plus probe bodies).
	Bytes int64 `json:"bytes"`
	// Duration is the wall time of the phase.
	Duration time.Duration `json:"duration_ns"`
	// Flows is the number of load-generating connections in use at the end.
	Flows int `json:"flows"`
	// Intervals is the number of stability intervals that completed.
	Intervals int `json:"intervals"`
	// ThroughputStable / ResponsivenessStable report whether the draft's stability
	// criterion was met for each series.
	ThroughputStable     bool `json:"throughput_stable"`
	ResponsivenessStable bool `json:"responsiveness_stable"`
	// ThroughputConfidence / ResponsivenessConfidence per draft Section 5.4.1.
	ThroughputConfidence     Confidence `json:"throughput_confidence"`
	ResponsivenessConfidence Confidence `json:"responsiveness_confidence"`
	// Truncated is true when a limit ended the phase before both series were
	// stable; Reason says which limit.
	Truncated bool             `json:"truncated"`
	Reason    TruncationReason `json:"reason,omitempty"`
	// Loaded latency statistics gathered while the link was under load, over
	// LoadedWindow: every interval since throughput became stable, or the
	// last MovingAverageDistance intervals when it never did (LOAD-5). A
	// probe series with samples in the phase but none in the window is
	// omitted and explained in Warnings.
	Loaded       LoadedLatency   `json:"loaded"`
	LoadedWindow *IntervalWindow `json:"loaded_window,omitempty"`
	// ThroughputLowerBoundBPS is a conservative figure that holds even when
	// the estimate has not converged: the lowest goodput of the latest
	// sustained window of measured intervals (LOAD-13). Absent when no such
	// window formed (a run cut short). LowerBoundWindow says which window.
	ThroughputLowerBoundBPS float64         `json:"throughput_lower_bound_bps,omitempty"`
	LowerBoundWindow        *IntervalWindow `json:"lower_bound_window,omitempty"`
	// RPMUpperBound is the responsiveness over the lower-bound window. Queues
	// may not have been full there, so the loaded RPM is at most this.
	RPMUpperBound float64 `json:"rpm_upper_bound,omitempty"`
	// RPM is the draft's Responsiveness score: the mean of ForeignRPM and SelfRPM
	// (or ForeignRPM alone when self probes were unavailable).
	RPM float64 `json:"rpm"`
	// ForeignRPM = 60000 / mean(TM(tcp_f), TM(tls_f), TM(http_f)).
	ForeignRPM float64 `json:"foreign_rpm"`
	// SelfRPM = 60000 / TM(http_l). 0 when no self probes were possible.
	SelfRPM float64 `json:"self_rpm"`
	// HTTPVersion negotiated by this phase's flows.
	HTTPVersion string `json:"http_version,omitempty"`
	// FlowErrors counts load flows that ended with an error.
	FlowErrors int `json:"flow_errors"`
}

DirectionResult is the outcome of one load phase.

type Directions

type Directions int

Directions selects which load phases run. Phases always run sequentially.

const (
	// Both runs download then upload (default).
	Both Directions = iota
	// Download runs only the download phase.
	Download
	// Upload runs only the upload phase.
	Upload
)

func (Directions) MarshalJSON

func (d Directions) MarshalJSON() ([]byte, error)

MarshalJSON keeps Directions readable in JSON output.

func (Directions) String

func (d Directions) String() string

type Event

type Event struct {
	Time      time.Time `json:"time"`
	Kind      EventKind `json:"kind"`
	Phase     string    `json:"phase"` // "discover", "idle", "download", "upload", "done"
	Direction string    `json:"direction,omitempty"`
	Message   string    `json:"message,omitempty"`
	// Interval fields.
	Interval      int     `json:"interval,omitempty"`
	Flows         int     `json:"flows,omitempty"`
	ThroughputBPS float64 `json:"throughput_bps,omitempty"`
	Bytes         int64   `json:"bytes,omitempty"`
	RPM           float64 `json:"rpm,omitempty"`
	// Hold marks an interval no flow was added into (LOAD-13).
	Hold bool `json:"hold,omitempty"`
	// Probe fields.
	ProbeKind string        `json:"probe_kind,omitempty"` // "idle", "foreign", "self"
	Latency   time.Duration `json:"latency_ns,omitempty"`
}

Event is a progress notification delivered to RunWithEvents' sink. Sinks are called synchronously from the flow and probe goroutines, so calls can and do overlap: a sink must be safe for concurrent use and must return promptly (RES-8).

type EventKind

type EventKind string

EventKind classifies an Event.

const (
	// EventPhase marks a phase boundary; Phase names it, Message may add detail.
	EventPhase EventKind = "phase"
	// EventInterval reports the moving-average throughput after each interval.
	EventInterval EventKind = "interval"
	// EventProbe reports one latency sample.
	EventProbe EventKind = "probe"
	// EventFlow reports a flow being added (Flows is the new count).
	EventFlow EventKind = "flow"
	// EventWarning carries a warning as it is discovered.
	EventWarning EventKind = "warning"
)

type IntervalWindow

type IntervalWindow struct {
	Start     time.Duration `json:"start_ns"`
	Duration  time.Duration `json:"duration_ns"`
	Intervals int           `json:"intervals"`
}

IntervalWindow locates the intervals a figure was computed over, as an offset from the phase start and a length, in nominal intervals.

type LatencySample

type LatencySample = engine.LatencySample

LatencySample is one probe measurement.

type LatencyStats

type LatencyStats = engine.LatencyStats

LatencyStats summarises a set of latency samples (see engine.LatencyStats).

type LoadedLatency

type LoadedLatency struct {
	// Foreign: fresh-connection probes (TCP+TLS+HTTP, like idle probes).
	Foreign *LatencyStats `json:"foreign,omitempty"`
	// Self: probes multiplexed on load-generating HTTP/2 connections.
	Self *LatencyStats `json:"self,omitempty"`
	// Combined: all probes, with foreign probes counted by their HTTP time
	// (http_f) so both kinds measure "request to full response".
	Combined *LatencyStats `json:"combined,omitempty"`
}

LoadedLatency groups latency samples taken under load.

type Options

type Options struct {
	// MaxDuration bounds each direction's load phase (default 12s). A phase that
	// has not stabilised when the bound hits is reported as truncated.
	MaxDuration time.Duration
	// MaxBytes, if > 0, bounds the bytes moved by each direction's load
	// phase, probes included; hitting it truncates the phase with
	// reason=bytes_cap. 0 (the default) means no byte cap: MaxDuration alone
	// bounds the run. Set it on metered links.
	MaxBytes int64
	// MaxFlows caps the number of concurrent load-generating connections
	// (default 16, draft MNP).
	MaxFlows int
	// Directions selects the phases to run (default Both).
	Directions Directions
	// IdleProbes is the number of fresh-connection probes for idle latency
	// (default 5). 0 uses the default; negative skips idle measurement.
	IdleProbes int
	// Stability holds the draft's algorithm parameters; zero fields use
	// defaults. SendBufferBytes applies to upload phases only and defaults to
	// DefaultUploadSendBuffer there; set it negative to disable.
	Stability StabilityParams
	// HTTPClient supplies the base transport (proxy, TLS config, dialer). Only
	// its Transport is used; each load flow gets its own clone so flows do not
	// share a connection. If the Transport is not an *http.Transport it is used
	// as-is and flows may share connections (a warning is recorded).
	HTTPClient *http.Client
	// Logger receives debug logs; nil discards them.
	Logger *slog.Logger
	// ConfigTimeout bounds config discovery (default 10s).
	ConfigTimeout time.Duration
	// Header is added to every request the test sends (config fetch, probes,
	// load flows): credentials for a protected server, for example
	// Authorization: Bearer <token>. Keys set here override the defaults.
	// It is read from every flow and probe goroutine, so it must not be
	// mutated while Run is in flight.
	Header http.Header
	// contains filtered or unexported fields
}

Options configures a test run. The zero value is valid and uses the defaults.

type ProxyInfo

type ProxyInfo struct {
	// Explicit is true when the HTTP transport routed requests via a proxy.
	Explicit bool `json:"explicit"`
	// URL of the explicit proxy, credentials removed.
	URL string `json:"url,omitempty"`
	// TLSInterception is true when the server certificate chain verified but
	// the leaf is not publicly trusted (no Certificate Transparency SCTs): a
	// TLS-inspecting proxy or a private CA re-issued it.
	TLSInterception bool `json:"tls_interception"`
	// Issuer of the intercepted leaf certificate.
	Issuer string `json:"issuer,omitempty"`
	// Reason is a human-readable explanation of the detection.
	Reason string `json:"reason,omitempty"`
}

ProxyInfo describes a detected proxy. Explicit and TLSInterception may both be set.

type ResolvedTarget

type ResolvedTarget struct {
	ConfigURL    string   `json:"config_url"`
	Host         string   `json:"host"`
	TestEndpoint string   `json:"test_endpoint,omitempty"`
	ResolvedIPs  []string `json:"resolved_ips,omitempty"`
	// LocalIPs are the source addresses the test's connections went out on,
	// deduplicated, ports stripped, IPv6 zone IDs kept. They identify the
	// interface/network a stored result was taken on. Under an explicit proxy
	// this is the address used toward the proxy. Empty with a custom
	// RoundTripper or DialTLSContext, which bypass the library's dialer.
	LocalIPs []string `json:"local_ips,omitempty"`
	// HTTPVersion is the protocol negotiated by load flows ("HTTP/2.0", "HTTP/1.1").
	HTTPVersion string       `json:"http_version,omitempty"`
	Config      ServerConfig `json:"config"`
	// Proxy is set when the measured path involves a proxy: an explicit one
	// from the transport's Proxy function, or TLS interception inferred from
	// the certificate chain. Nil when nothing was detected. Numbers are still
	// valid measurements, but of the client→proxy leg.
	Proxy *ProxyInfo `json:"proxy,omitempty"`
}

ResolvedTarget describes the server actually used.

type Result

type Result struct {
	// SchemaVersion is ResultSchemaVersion at the time the result was produced.
	SchemaVersion int            `json:"schema_version"`
	Target        ResolvedTarget `json:"target"`
	StartedAt     time.Time      `json:"started_at"`
	Duration      time.Duration  `json:"duration_ns"`
	// Idle is the idle latency measured on fresh connections before any load.
	// Nil when IdleProbes < 0 or no probe succeeded.
	Idle *LatencyStats `json:"idle,omitempty"`
	// Download / Upload are nil when the direction was not requested.
	Download *DirectionResult `json:"download,omitempty"`
	Upload   *DirectionResult `json:"upload,omitempty"`
	// Cancelled is true when the context was cancelled; the result is partial.
	Cancelled bool     `json:"cancelled"`
	Warnings  []string `json:"warnings,omitempty"`
}

Result is the outcome of a run. It serialises to JSON with stable snake_case names; the CLI's --json output is exactly this struct.

func Run

func Run(ctx context.Context, t Target, o Options) (*Result, error)

Run executes the responsiveness test against t and returns the Result.

If ctx is cancelled mid-run, Run returns the partial Result (Cancelled=true) together with ctx.Err(). If a load phase fails before completing an interval, Run returns the partial Result (that direction flagged reason=flow_error, everything measured before it intact) together with the error. Only discovery failures return a nil Result.

func RunWithEvents

func RunWithEvents(ctx context.Context, t Target, o Options, sink func(Event)) (*Result, error)

RunWithEvents is Run with a progress sink. sink may be nil; otherwise it must be safe for concurrent use, because flow and probe goroutines call it (see Event).

type ServerConfig

type ServerConfig struct {
	Version          int    `json:"version"`
	TestEndpoint     string `json:"test_endpoint,omitempty"`
	SmallDownloadURL string `json:"small_download_url"`
	LargeDownloadURL string `json:"large_download_url"`
	UploadURL        string `json:"upload_url"`
}

ServerConfig is the parsed JSON configuration document served by a target.

func ParseServerConfig

func ParseServerConfig(data []byte) (*ServerConfig, error)

ParseServerConfig parses a configuration document. It accepts both the draft field names (small_download_url, large_download_url, upload_url) and the older Apple/Cloudflare *_https_* names, preferring the https-prefixed ones when both are present. Unknown fields are ignored. Duplicate keys, a missing mandatory field, a version other than 1, or mismatched hosts make the document invalid.

type StabilityParams

type StabilityParams = engine.StabilityParams

StabilityParams are the draft's algorithm parameters (Section 5.2); see the engine package for field documentation.

func DefaultStabilityParams

func DefaultStabilityParams() StabilityParams

DefaultStabilityParams returns the draft-09 defaults, except Interval, which is 1s instead of 5s so that a phase can stabilise within the 12s MaxDuration budget (see README "Deviations").

type StageMedians

type StageMedians = engine.StageMedians

StageMedians holds per-stage medians from net/http/httptrace.

type Target

type Target struct {
	// ConfigURL is the URL of the JSON configuration document, e.g.
	// https://example.com/.well-known/nq or a vendor-specific path.
	ConfigURL string `json:"config_url"`
}

Target identifies a responsiveness server by its configuration URL.

func WellKnown

func WellKnown(host string) Target

WellKnown returns a Target for host's /.well-known/nq document (draft Section 8.1). host may include a port.

type TruncationReason

type TruncationReason string

TruncationReason says why a phase ended before stabilising.

const (
	ReasonNone        TruncationReason = ""
	ReasonBytesCap    TruncationReason = "bytes_cap"
	ReasonDurationCap TruncationReason = "duration_cap"
	ReasonCancelled   TruncationReason = "cancelled"
	ReasonFlowError   TruncationReason = "flow_error"
)