ttws

README

ttws

Tiny test web server

This project provides building blocks for creating tiny web servers suitable for running inside containers. It also includes a few sample web servers.

Packages

Package	Description
webserver	The core webserver. Listens on a port, stops on SIGINT or SIGTERM, sets up handlers defined by the other packages.
cpuload	Adds a handler that calculates the square root of 0.0001, one million times, and emits the result.
ipaddresses	Adds a handler that emits the host name and ip addresses of the web host.
echo	Returns information about the client-server interaction as a formatted JSON payload.
envvars	Adds a handler that emits all environment variables of the host process.
filesystem	Adds a handler that emits directory and file names from the host filesystem. Path and depth can be specified.
probes	Allows adding probes , which are handlers that can be configured to fail after a specified number of calls, and recover after another specified number.
static	Allows adding handlers that serve directories on the web host statically.
delay	Adds a handler which waits for a specified duration before returning success. Path is /delay/PARAM, where PARAM is an integer (seconds) or an integer followed by 'm' (milliseconds).

Web Servers

Server	Description
ics	A web server which includes the ipaddresses, envvars and filesystem packages. Ipaddresses is default.
ldgen	A web server which includes only the cpuload package, which is default.
probestest	A web server which includes only the probes package, which is default. Two probes are available on the endpoints '/probes/liveness' and '/probes/readiness'.
ttws	A web server which includes all packages, including delay. The static package is the default. It serves a directory 'www' under the working directory on the endpoint '/'. Two probes are available on the endpoints '/probes/liveness' and '/probes/readiness'.

Options

All servers can have the following options specified either on the command line, or via an environment variable:

Option	Description	Env Variable
-p <port>	The port on which the server listens.	PORT
-tls	Enable TLS using existing certificates (requires -tlscert and -tlskey).	TLS
-tlsselfsigned	Enable TLS with automatically generated and persisted self-signed certificates. Path defaults to ./certs/.	TLS_SELF_SIGNED
-tlscert <path>	Path to the certificate file. (Default: ./certs/cert.pem)	TLS_CERT
-tlskey <path>	Path to the private key file. (Default: ./certs/key.pem)	TLS_KEY

The probestest and ttws servers allow the following command-line options:

Option	Description	Env Variable
-livenessfailafter <calls>	The number of calls after which the liveness probe fails.	LIVENESS_FAIL_AFTER
-livenessrecoverafter <calls>	The number of calls post failure after which the liveness probe recovers.	LIVENESS_RECOVER_AFTER
-livenessinitialfailed <true/false>	Set the initial state of the liveness probe to failed.	LIVENESS_INITIAL_FAILED
-livenessfailurecode <code>	The HTTP status code to return on liveness probe failure.	LIVENESS_FAILURE_CODE
-readinessfailafter <calls>	The number of calls after which the readiness probe fails.	READINESS_FAIL_AFTER
-readinessrecoverafter <calls>	The number of calls post failure after which the readiness probe recovers.	READINESS_RECOVER_AFTER
-readinessinitialfailed <true/false>	Set the initial state of the readiness probe to failed.	READINESS_INITIAL_FAILED
-readinessfailurecode <code>	The HTTP status code to return on readiness probe failure.	READINESS_FAILURE_CODE

Running in Containers

The servers in this project are designed to follow container best practices, especially for restricted environments like Kubernetes or OpenShift.

Security Model

The provided multistage.Dockerfile files (now the project standard):

• Run as a non-root user (USER 1001) by default.
• Use the Random UID + GID 0 model. The /certs and /www directories are owned by GID 0 and are group-writable. This allows the server to generate self-signed certificates at runtime even when running as a random non-root UID.

Volume Mounting

When running in a container, you can mount volumes to customize content or provide certificates:

Path	Purpose	Notes
/www	Static content	Used by ttws. Can be mounted read-only.
/certs	TLS certificates	Use for -tls or -tlsselfsigned. Must be group-writable (GID 0) if using -tlsselfsigned.

Example: Running with local certificates

docker run -p 8443:8080 -v $(pwd)/mycerts:/certs rajchaudhuri/ttws -tls -tlscert /certs/fullchain.pem -tlskey /certs/privkey.pem

The project now exclusively uses multi-stage builds to ensure minimal image size and maximum security.