@goozt/gospeed-server

v1.3.8

Published

2 months ago

Speed test server for gospeed

Downloads

0High
0Medium
0Low

A fast, zero-dependency network speed testing tool written in Go. Client-server architecture for accurate network performance measurement.

Features

9 test types: TCP/UDP throughput, latency, jitter, bufferbloat (RPM), path MTU discovery, DNS resolution, TCP connect time, bidirectional throughput
Scientifically grounded: Based on RFC 6349, RFC 2544, ITU-T Y.1564
Multi-client server: Handles concurrent clients
Quality grades: A-F ratings for each metric with color-coded terminal output
Multiple output formats: Table (default), JSON (--json), CSV (--csv)
Test history: Local JSONL storage with trend tracking (--history)
Cross-platform: Native Windows, macOS, Linux, FreeBSD support
Zero dependencies: Pure Go standard library — no external packages
TLS support: Optional encrypted connections
Docker ready: Multi-stage Dockerfile and docker-compose included

Installation

Quick install

# Linux / macOS / FreeBSD
curl -fsSL https://gospeed.goozt.org/install.sh | bash

# Include server binary
curl -fsSL https://gospeed.goozt.org/install.sh | bash -s -- --server

# Windows (PowerShell)
irm https://gospeed.goozt.org/install.ps1 | iex

Binary download

Download pre-built binaries from the releases page. Each platform archive bundles both gospeed and gospeed-server.

Go install

go install github.com/goozt/gospeed/cmd/gospeed@latest
go install github.com/goozt/gospeed/cmd/gospeed-server@latest

npm

npm install -g @goozt/gospeed
npm install -g @goozt/gospeed-server

Homebrew (macOS / Linux)

brew install goozt/org/gospeed   # installs both binaries

Scoop (Windows)

scoop bucket add goozt https://github.com/goozt/scoop-bucket
scoop install goozt/gospeed

Winget (Windows)

winget install goozt.gospeed
winget install goozt.gospeed-server

AUR (Arch Linux)

yay -S gospeed-bin           # client
yay -S gospeed-server-bin    # server (with systemd unit)

Nix (NUR)

nix run github:goozt/nur-packages#gospeed

apt / yum / apk (Fury.io)

Repos are GPG-signed; the apt/yum snippets below import the public key and verify every install.

# Debian / Ubuntu
curl -fsSL https://apt.fury.io/nikhiljohn10/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nikhiljohn10-fury.gpg
echo "deb [signed-by=/usr/share/keyrings/nikhiljohn10-fury.gpg] https://apt.fury.io/nikhiljohn10/ /" | sudo tee /etc/apt/sources.list.d/nikhiljohn10.list
sudo apt update && sudo apt install gospeed gospeed-server

# RHEL / Fedora
sudo rpm --import https://yum.fury.io/nikhiljohn10/gpg.key
sudo tee /etc/yum.repos.d/nikhiljohn10.repo <<'EOF'
[nikhiljohn10]
name=nikhiljohn10
baseurl=https://yum.fury.io/nikhiljohn10/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://yum.fury.io/nikhiljohn10/gpg.key
EOF
sudo dnf install gospeed gospeed-server

# Alpine (signing for Gemfury Alpine repos isn't published yet — use --allow-untrusted)
echo "https://alpine.fury.io/nikhiljohn10/" | sudo tee -a /etc/apk/repositories
sudo apk update && sudo apk add gospeed gospeed-server --allow-untrusted

PyPI (pipx / pip)

pipx install --index-url https://pypi.fury.io/nikhiljohn10/ gospeed
# exposes `gospeed` and `gospeed-server` commands

mise

mise use gospeed
mise use gospeed-server

Docker (server only)

docker compose up -d

Kubernetes

Plain manifests, Helm chart, and Kustomize overlays are provided in the k8s/ directory. See k8s/README.md for full details.

# Plain manifests
kubectl apply -f k8s/manifests/

# Helm
helm install gospeed k8s/helm/gospeed/

# Kustomize (dev / prod)
kubectl apply -k k8s/kustomize/overlays/prod/

Usage

Server

# Start server on default port 9000
gospeed-server

# Custom address
gospeed-server --addr :8080

# With TLS (self-signed, auto-generated)
gospeed-server --tls-self-signed

# With TLS (your own certificate)
gospeed-server --tls-cert cert.pem --tls-key key.pem

# With TLS (Let's Encrypt ACME)
gospeed-server --tls-acme --domain speed.example.com --email [email protected]

Server Options

-a, --addr string       Listen address (host:port)
-h, --host string       Specific host address
-p, --port int          Listening port (default 9000)
-v, --version           Print version and exit
    --tls-cert string   TLS certificate file
    --tls-key string    TLS key file
    --tls-self-signed   Use auto-generated self-signed certificate
    --tls-acme          Use Let's Encrypt ACME for certificate provisioning
    --domain string     Domain name for ACME certificate (required with --tls-acme)
    --email string      Email address for ACME account (required with --tls-acme)
    --cert-dir string   Directory to cache ACME certificates
    --health int        Start HTTP health check server on given port

Client

# Run default test suite against a server
gospeed -s speed.example.com

# Use environment variable instead of -s flag
export GOSPEED_SERVER_ADDR=speed.example.com:9000
gospeed

# Default: localhost:9000
gospeed

Test selection

# Run specific tests
gospeed -s host:9000 --latency
gospeed -s host:9000 --tcp --udp
gospeed -s host:9000 --bufferbloat

# Run all tests
gospeed -s host:9000 --all

# Default test suite (when no test flags given):
# MTU → Latency → TCP Throughput → Bufferbloat → UDP+Loss → Jitter

Output formats

# JSON output (for scripting)
gospeed -s host:9000 --json

# CSV output
gospeed -s host:9000 --csv

# View test history with trends
gospeed --history

Options

-s, --server string   Server address (host:port)
-t, --streams int     Number of parallel streams (default 4)
-d, --duration int    Test duration in seconds (default 10)
-h, --history         Show previous results with trends
-v, --version         Print version and exit
    --json            Output as JSON
    --csv             Output as CSV
    --tls             Use TLS connection
    --tls-skip-verify Skip TLS certificate verification
    --ping            Ping server before tests to check connectivity and exits

Test flags:
    --latency         Unloaded latency (RTT)
    --mtu             Path MTU discovery
    --tcp             TCP throughput
    --udp             UDP throughput + packet loss
    --jitter          Jitter measurement
    --bufferbloat     Bufferbloat detection (RPM)
    --dns             DNS resolution latency
    --connect         TCP connection setup time
    --bidir           Bidirectional throughput
-a, --all             Run all tests

Test descriptions

| Test | Protocol | What it measures | Key metric | |------|----------|------------------|------------| | Latency | TCP | Round-trip time (20 samples) | min/avg/p95/max ms | | MTU | UDP (DF bit) | Path Maximum Transmission Unit | bytes | | TCP Throughput | TCP | Bandwidth with BDP-aware buffers | Mbps/Gbps | | UDP Throughput | UDP | Bandwidth + packet loss + reordering | Mbps, loss % | | Jitter | UDP | Inter-packet delay variation (RFC 3550) | ms | | Bufferbloat | TCP+UDP | Latency under load → responsiveness | RPM | | DNS | UDP/53 | DNS resolution latency | ms | | Connect | TCP | SYN→established handshake time | ms | | Bidirectional | TCP | Simultaneous upload + download | Mbps each |

Grading

| Metric | A | B | C | D | F | |--------|---|---|---|---|---| | Latency | <20ms | <50ms | <100ms | <200ms | ≥200ms | | Packet Loss | <0.1% | <0.5% | <1% | <2.5% | ≥2.5% | | Jitter | <5ms | <10ms | <20ms | <50ms | ≥50ms | | Bufferbloat (RPM) | ≥400 | ≥200 | ≥100 | ≥50 | <50 | | Throughput | ≥100Mbps | ≥50Mbps | ≥25Mbps | ≥10Mbps | <10Mbps |

Comparison with iperf3

| Feature | gospeed | iperf3 | |---------|---------|--------| | Concurrent clients | Yes | No (one at a time) | | Windows support | Native | Cygwin-dependent | | JSON output | Reliable | Broken with parallel/bidir | | Bufferbloat detection | Built-in (RPM) | Not available | | Unified metrics | Single run | Separate tools needed | | Quality grading | A-F grades | Raw numbers only | | Test history | Built-in trends | Not available | | NAT-friendly | All client-initiated | Requires reverse mode | | Dependencies | Zero | libssl, etc. |

Architecture

┌─────────────┐     Control (TCP, JSON-framed)       ┌────────────────┐
│   gospeed   │◄────────────────────────────────────►│ gospeed-server │
│   (client)  │      Data (TCP/UDP streams)          │    (server)    │
│             │◄────────────────────────────────────►│                │
└─────────────┘                                      └────────────────┘

Control channel: Length-prefixed JSON over TCP for handshake, test negotiation, and results
Data channels: Raw TCP/UDP streams with sequence numbers and timestamps
Session correlation: Client-initiated data connections identified by 16-byte session UUID

Building from source

go install github.com/go-task/task/v3/cmd/task@latest

task build              # Build both binaries
task test               # Run tests
task docker             # Build Docker image
task release-snapshot   # Test GoReleaser locally
task bump VERSION=1.3.6 # Tag and push a release

License

MIT