echo

README

echo - HTTP Server Environment Debugger

echo accepts any request and responds with with 200 OK. The response payload is a web page which displays information about the request and the server environment.

All requests to the server are logged as JSON.

Features

The echoserver provides:

• Request debugging by dumping the HTTP request as received by the server both to the UI, and as JSON-encoded log entries for debugging when the browser cannot reach the server.

• Server Environment debugging by dumping a user-configurable subset of the server environment.

Environment Debugging

By default, the server will not dump any of the environment. To enable this, the environment variable ECHO_VARS must be set to a space-separated list of the environment variables you wish to expose to HTTP requests. Alternatively, you can set ECHO_VARS=... (a literal "...") to instruct the server to dump all environment variables. You should probably never ever do that in production, but if you do, it's not my fault.

Here is a screen shot of what the server returns for a GET request after being started with docker run --rm -p 8080:8080 -e ECHO_VARS='...' cfunkhouser/echoserver:latest.

Running It

You can run the server directly from this repository. Following is a manual execution, displaying the startup log and a dump of a single request.

$ go run ./cmd/echoserver
go run ./cmd/echoserver
{"time":"2024-01-11T10:07:10.189852-07:00","level":"INFO","msg":"Server starting","address":":8080"}
{"time":"2024-01-11T10:07:15.552663-07:00","level":"INFO","msg":"incoming request","request":{"requestor":"127.0.0.1:50175","method":"GET","target":"/","protocol":"HTTP/1.1","headers":[{"name":"Accept","value":"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8","index":0,"repeat_count":1},{"name":"Accept-Encoding","value":"gzip, deflate, br","index":0,"repeat_count":1},{"name":"Accept-Language","value":"en-US,en;q=0.5","index":0,"repeat_count":1},{"name":"Connection","value":"keep-alive","index":0,"repeat_count":1},{"name":"Cookie","value":"__profilin=p%3Dt","index":0,"repeat_count":1},{"name":"Dnt","value":"1","index":0,"repeat_count":1},{"name":"Sec-Fetch-Dest","value":"document","index":0,"repeat_count":1},{"name":"Sec-Fetch-Mode","value":"navigate","index":0,"repeat_count":1},{"name":"Sec-Fetch-Site","value":"none","index":0,"repeat_count":1},{"name":"Sec-Fetch-User","value":"?1","index":0,"repeat_count":1},{"name":"Upgrade-Insecure-Requests","value":"1","index":0,"repeat_count":1},{"name":"User-Agent","value":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:121.0) Gecko/20100101 Firefox/121.0","index":0,"repeat_count":1}]}}
{"time":"2024-01-11T10:07:15.601182-07:00","level":"INFO","msg":"incoming request","request":{"requestor":"127.0.0.1:50175","method":"GET","target":"/favicon.ico","protocol":"HTTP/1.1","headers":[{"name":"Accept","value":"image/avif,image/webp,*/*","index":0,"repeat_count":1},{"name":"Accept-Encoding","value":"gzip, deflate, br","index":0,"repeat_count":1},{"name":"Accept-Language","value":"en-US,en;q=0.5","index":0,"repeat_count":1},{"name":"Connection","value":"keep-alive","index":0,"repeat_count":1},{"name":"Cookie","value":"__profilin=p%3Dt","index":0,"repeat_count":1},{"name":"Dnt","value":"1","index":0,"repeat_count":1},{"name":"Referer","value":"http://localhost:8080/","index":0,"repeat_count":1},{"name":"Sec-Fetch-Dest","value":"image","index":0,"repeat_count":1},{"name":"Sec-Fetch-Mode","value":"no-cors","index":0,"repeat_count":1},{"name":"Sec-Fetch-Site","value":"same-origin","index":0,"repeat_count":1},{"name":"User-Agent","value":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:121.0) Gecko/20100101 Firefox/121.0","index":0,"repeat_count":1}]}}

You can install it directly, and run it:

$ go install idontfixcomputers.com/echo/cmd/echoserver@latest
go: downloading idontfixcomputers.com/echo v0.1.1
$ which echo
/home/whatever/bin/echo
$ echo --help
Usage of echo:
  -address string
        Bind address in host:port format. (default ":8080")
$ echo --address 127.0.0.1:9000
{"time":"2024-01-11T10:07:10.189852-07:00","level":"INFO","msg":"Server starting","address":":8080"}

Docker

A Docker image is published to cfunkhouser/echoserver tagged with each release. It can be run with docker run --rm -p 8080:8080 cfunkhouser/echoserver:latest.

Documentation

Overview

Package echo contains utilities to inspect HTTP requests.

Index

• Constants
• Variables
• func Echo(w http.ResponseWriter, r *http.Request)
• func PolicyFromEnv() func(*EnvVar) bool
• func VeryDangerousAllowAll(_ *EnvVar) bool
• type Body
  • func DumpBody(req *http.Request) (ret Body)
• type Color
• type ColorPalette
• type EchoHandler
  • func New(logger *slog.Logger) *EchoHandler
  • func (h *EchoHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type EnvVar
• type EnvironmentDump
  • func DumpEnv(policy EnvironmentDumpPolicy) *EnvironmentDump
• type EnvironmentDumpPolicy
• type Header
  • func DumpHeader(req *http.Request) (ret []*Header)
• type RGBAColor
  • func (c *RGBAColor) CSS() template.CSS
• type RequestDump
  • func DumpRequest(req *http.Request) *RequestDump

Constants

const FullOpacity uint8 = 100

Variables

var (
	// DefaultColors for the rendering of the UI.
	DefaultColors = ColorPalette{
		&RGBAColor{9, 94, 147, FullOpacity},
		&RGBAColor{102, 157, 13, FullOpacity},
		&RGBAColor{243, 0, 8, FullOpacity},
		&RGBAColor{221, 162, 0, FullOpacity},
		&RGBAColor{71, 25, 134, FullOpacity},
	}
)

Functions

func Echo

func Echo(w http.ResponseWriter, r *http.Request)

Echo the request back to the client as plain text.

func PolicyFromEnv

func PolicyFromEnv() func(*EnvVar) bool

PolicyFromEnv is an EnvironmentDumpPolicy which reads the value of the ECHO_VARS environment variable, and allows dumping any env var names found. If the value is set to "..." then the entire environment is dumped (which is often a bad idea).

func VeryDangerousAllowAll

func VeryDangerousAllowAll(_ *EnvVar) bool

VeryDangerousAllowAll is an EnvironmentDumpPolicy which dumps the entire environment. Aim this away from your foot before using.

Types

type Body

type Body struct {
	// Content of the HTTP body, represented as bytes.
	Content []byte

	// AllegedType of the content, as reported by the client. No validation is
	// done on this value, so be sure you trust the client before relying on it.
	AllegedType string
}

Body of an HTTP payload.

func DumpBody

func DumpBody(req *http.Request) (ret Body)

DumpBody for rendering in an HTML payload.

type Color

type Color interface {
	CSS() template.CSS
}

Color abstracts the rendering of different color spaces as CSS for rendering the UI.

type ColorPalette

type ColorPalette []Color

ColorPalette for rendering the UI.

type EchoHandler

type EchoHandler struct {
	Log *slog.Logger
}

EchoHandler renders HTML payloads containing the in-bound request along with some details about the running environment of the server.

func New

func New(logger *slog.Logger) *EchoHandler

New echo handler for use in HTTP servers.

func (*EchoHandler) ServeHTTP

func (h *EchoHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type EnvVar

type EnvVar struct {
	Name, Value string
}

EnvVar is an environment variable value stored in memory as a name / value pair.

type EnvironmentDump

type EnvironmentDump struct {
	Variables []*EnvVar
}

EnvironmentDump represents the bits of the running environment to be dumped for return in a response payload.

func DumpEnv

func DumpEnv(policy EnvironmentDumpPolicy) *EnvironmentDump

DumpEnv for rendering in an HTML payload.

type EnvironmentDumpPolicy

type EnvironmentDumpPolicy func(*EnvVar) bool

EnvironmentDumpPolicy determines what should be dumped from the running process' environment.

type Header

type Header struct {
	Name  string `json:"name"`
	Value string `json:"value,omitempty"`
	Index int    `json:"index"`
	Count int    `json:"repeat_count"`
}

Header of an HTTP request.

func DumpHeader

func DumpHeader(req *http.Request) (ret []*Header)

DumpeHeader from an HTTP request.

type RGBAColor

type RGBAColor struct {
	// R, G, and B color values between 0 and 255.
	R, G, B uint8

	// Alpha value out of 100. Values higher than 100 will be rounded down.
	Alpha uint8
}

RGBAColor implements Color for the RGBA color space.

func (*RGBAColor) CSS

func (c *RGBAColor) CSS() template.CSS

CSS representation of the RGBA color.

type RequestDump

type RequestDump struct {
	Requestor string    `json:"requestor"`
	Method    string    `json:"method"`
	Target    string    `json:"target"`
	Proto     string    `json:"protocol"`
	Headers   []*Header `json:"headers"`
	Body      Body      `json:"-"`
}

RequestDump is a renderable dump of an inbound HTTP request.

func DumpRequest

func DumpRequest(req *http.Request) *RequestDump

DumpRequest for rendering in an HTML payload.