Tero

Modern HTTP testing server for developers, QA engineers, and security researchers.
A drop-in httpbin replacement with WebSocket, SSE, chaos simulation, and request recording.

Features • Quick Start • Usage • API Reference • Architecture • Building

Why Tero?

httpbin is great, but it hasn't kept up with modern HTTP workflows. Tero fills the gap:

Single binary — download and run. No Python, no Docker, no config files.
httpbin-compatible — 55+ endpoints covering the full httpbin surface and beyond.
WebSocket support — Echo server and broadcast chat room for real-time testing.
Server-Sent Events — Configurable streaming with Last-Event-ID resume.
Chaos engineering — Unstable endpoints, rate limiting, slow responses, connection timeouts.
Request recording — Capture and replay HTTP requests with ring buffer storage.
Built with Go — fast startup, low memory, zero CGO, compiles everywhere.

Features

HTTP Methods & Inspection

Full httpbin compatibility: GET, POST, PUT, PATCH, DELETE, plus a catch-all /anything endpoint. Inspect headers, IP, User-Agent, and full request data as JSON.

Authentication

Test all major HTTP auth flows: Basic Auth, Hidden Basic Auth (404 on failure), Digest Auth (MD5), and Bearer token validation.

Status Codes

Return any HTTP status code. Supports comma-separated codes for random selection — useful for testing retry logic: /status/200,500,503

Cookies & Redirects

Full cookie management (set, read, delete) and redirect chains (relative, absolute, custom status codes) with configurable allowed domains.

Response Formats

HTML, JSON, XML, robots.txt, UTF-8 encoding, Base64 decode, link pages, and HTML forms.

Dynamic Data

Random bytes (seeded), streamed bytes, streamed JSON lines, delayed responses, drip responses, range requests with partial content, and UUID generation.

Compression

Test client decompression with gzip, deflate, and brotli encoded responses.

Images

Content-negotiated image responses in PNG, JPEG, SVG, and WebP formats.

Cache & Conditional Requests

Test If-Modified-Since, If-None-Match, Cache-Control, and ETag handling.

WebSocket

Echo server that returns messages with metadata (timestamp, sequence number) and a broadcast chat room for multi-client testing.

Server-Sent Events

Configurable SSE streaming with adjustable interval and Last-Event-ID resume support for testing EventSource clients.

Chaos Simulation

Battle-test your HTTP clients against real-world failure modes:

Endpoint	Behavior
`/slow/{kbps}`	Throttled bandwidth response
`/unstable`	Random 500 errors with configurable failure rate
`/timeout/{seconds}`	Connection drops after delay
`/rate-limit/{n}`	Token bucket rate limiting with standard headers

Request Recording

Capture requests to /record and replay them from /playback. Thread-safe ring buffer with configurable size. Useful for webhook testing.

JWT, CORS & Upload

Decode JWTs without verification, test CORS configurations with custom origins/methods/headers, and inspect multipart file upload metadata.

Health Probes

Kubernetes-ready /health and /ready endpoints for container orchestration.

Quick Start

Binary

go install github.com/garagon/tero/cmd/tero@latest
tero

Docker

docker run -p 8080:8080 garagon/tero

From source

git clone https://github.com/garagon/tero.git
cd tero
make build
./tero

Then open http://localhost:8080 to see all available endpoints.

Usage

tero [flags]

Flags:
  -p, --port int              HTTP listen port (default 8080)
      --tls                   Enable HTTPS
      --tls-cert string       Path to TLS certificate
      --tls-key string        Path to TLS key
      --prefix string         URL prefix for all endpoints
      --max-body int          Max request body size in bytes (default 1048576)
      --max-duration duration Max delay/drip/timeout duration (default 10s)
      --allowed-redirects string Allowed redirect domains (comma-separated)
      --record-size int       Max requests in recorder buffer (default 100)
  -v, --verbose               Enable verbose logging
  -h, --help                  Help for tero
      --version               Version for tero

API Reference

HTTP Methods

Endpoint	Description
`GET /get`	Returns request data
`POST /post`	Returns request data with body
`PUT /put`	Returns request data with body
`PATCH /patch`	Returns request data with body
`DELETE /delete`	Returns request data
`* /anything/{path}`	Accepts any method, returns everything

Request Inspection

Endpoint	Description
`GET /headers`	Returns request headers
`GET /ip`	Returns origin IP
`GET /user-agent`	Returns User-Agent string

Status Codes

Endpoint	Description
`* /status/{code}`	Returns the given HTTP status code

Supports comma-separated codes for random selection: /status/200,201,500

Authentication

Endpoint	Description
`GET /basic-auth/{user}/{passwd}`	HTTP Basic Auth
`GET /hidden-basic-auth/{user}/{passwd}`	Returns 404 on failure instead of 401
`GET /digest-auth/{qop}/{user}/{passwd}`	HTTP Digest Auth
`GET /bearer`	Validates Bearer token

Cookies

Endpoint	Description
`GET /cookies`	Returns current cookies
`GET /cookies/set?name=value`	Sets cookies via query params
`GET /cookies/delete?name`	Deletes cookies

Redirects

Endpoint	Description
`GET /redirect/{n}`	302 redirect n times then /get
`GET /redirect-to?url=...&status_code=307`	Redirect to URL
`GET /relative-redirect/{n}`	Relative 302 redirect n times
`GET /absolute-redirect/{n}`	Absolute 302 redirect n times

Response Formats

Endpoint	Description
`GET /html`	HTML page
`GET /json`	JSON response
`GET /xml`	XML response
`GET /robots.txt`	robots.txt
`GET /deny`	Denied by robots
`GET /encoding/utf8`	UTF-8 encoded body

Dynamic Data

Endpoint	Description
`GET /bytes/{n}`	Random bytes (optional `?seed=N`)
`GET /stream-bytes/{n}`	Streamed random bytes
`GET /stream/{n}`	Streamed JSON lines
`GET /delay/{n}`	Delays response by n seconds
`GET /drip`	Drips bytes over time (`?duration=2&numbytes=10&code=200&delay=0`)
`GET /range/{n}`	Range response (supports Range header)
`GET /uuid`	Random UUID

Compression

Endpoint	Description
`GET /gzip`	gzip-encoded response
`GET /deflate`	deflate-encoded response
`GET /brotli`	brotli-encoded response

Images

Endpoint	Description
`GET /image`	Content-negotiated image (Accept header)
`GET /image/png`	PNG image
`GET /image/jpeg`	JPEG image
`GET /image/svg`	SVG image
`GET /image/webp`	WebP image

Cache & Conditional Requests

Endpoint	Description
`GET /cache`	304 if conditional headers present, 200 otherwise
`GET /cache/{n}`	Sets Cache-Control max-age=n
`GET /etag/{etag}`	ETag conditional request handling
`GET /response-headers?key=val`	Sets custom response headers

Misc

Endpoint	Description
`GET /base64/{value}`	Decodes base64 string
`GET /links/{n}`	HTML page with n links
`GET /forms/post`	HTML form that POSTs to /post

WebSocket

Endpoint	Description
`GET /ws/echo`	Echoes messages back with metadata
`GET /ws/chat`	Broadcast chat room

Server-Sent Events

Endpoint	Description
`GET /sse/{n}`	Streams n events (`?interval=1`). Supports `Last-Event-ID` for resume

Chaos Simulation

Endpoint	Description
`GET /slow/{kbps}`	Throttled response at n kbps
`* /unstable`	Random 500 errors (`?failure_rate=0.5`)
`* /timeout/{seconds}`	Closes connection after n seconds
`* /rate-limit/{n}`	Allows n requests per window (`?window=60`)

Request Recording

Endpoint	Description
`POST /record`	Records the request
`GET /playback`	Returns all recorded requests
`GET /playback/{n}`	Returns nth recorded request
`DELETE /playback`	Clears all recordings

JWT, CORS & Upload

Endpoint	Description
`POST /jwt/decode`	Decodes JWT without verification
`GET /cors`	Configurable CORS headers (`?origin=*&methods=GET&headers=Content-Type`)
`POST /upload`	Returns metadata of uploaded files (multipart/form-data)

Health

Endpoint	Description
`GET /health`	Health check
`GET /ready`	Readiness probe

Architecture

cmd/tero/          CLI entry point (Cobra)
internal/
  handlers/        HTTP endpoint handlers
  middleware/      Recovery, CORS, logging
  recorder/        Thread-safe request recording ring buffer
  server/          Server config and graceful shutdown
  ui/              Embedded HTML landing page

Tech Stack

Layer	Technology
Language	Go 1.23+
Router	stdlib `net/http` (Go 1.22+ pattern matching)
Logging	`slog` (structured, JSON-capable)
WebSocket	`github.com/coder/websocket`
CLI	Cobra
CI	GitHub Actions (vet, test, lint)
Release	GoReleaser (linux/darwin/windows x amd64/arm64)

Building

make build        # Production binary
make test         # Tests with race detector
make lint         # golangci-lint
make dev          # Run with go run

Cross-compile

GOOS=linux GOARCH=amd64 make build
GOOS=darwin GOARCH=arm64 make build
GOOS=windows GOARCH=amd64 make build

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change. See CONTRIBUTING.md for development setup.

License

MIT

Built for developers who test HTTP.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
cmd/tero		cmd/tero
internal		internal
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
integration_test.go		integration_test.go

Folders and files

Latest commit

History

Repository files navigation

Tero

Why Tero?

Features

HTTP Methods & Inspection

Authentication

Status Codes

Cookies & Redirects

Response Formats

Dynamic Data

Compression

Images

Cache & Conditional Requests

WebSocket

Server-Sent Events

Chaos Simulation

Request Recording

JWT, CORS & Upload

Health Probes

Quick Start

Binary

Docker

From source

Usage

API Reference

Architecture

Tech Stack

Building

Cross-compile

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages