Echo Server

This is an HTTP echo server based on OpenResty, designed to display detailed information about HTTP requests.

Project Background

When developing and debugging network applications, understanding the details of HTTP requests is crucial. Echo Server provides a simple way to view request headers, request body, environment variables, and other information, helping developers diagnose problems and understand request flows.

Main Features

• Display detailed request information, including:
  • Request method (GET, POST, etc.)
  • Request path
  • Query parameters
  • Request headers
  • Request body
  • Client IP address
• Display server environment information, including:
  • Hostname
  • Pod information (if running in a Kubernetes environment)
  • Nginx and Lua versions
• Provide a silent response-timeout test endpoint (/hang)

Installation and Deployment

Using Docker

Method 1: Using Pre-built Image (Recommended)

docker run -p 8080:80 ghcr.io/echo-server/echo-server:main

The pre-built image supports both ARM and x86 CPU architectures, no need to build it yourself.

Method 2: Local Build

1. Clone the repository

git clone https://github.com/echo-server/echo-server.git
cd echo-server

2. Build the Docker image

docker build -t echo-server .

3. Run the container

docker run -p 8080:80 echo-server

Now, Echo Server will be running at http://localhost:8080.

Usage

Basic Usage

Access the server's root path to view request information:

curl http://localhost:8080

Or use a browser to visit http://localhost:8080

Sending Different Types of Requests

POST Request Example

curl -X POST -d "Hello World" http://localhost:8080

Request with Custom Headers

curl -H "X-Custom-Header: CustomValue" http://localhost:8080

Response Timeout Test

curl --verbose --max-time 10 http://localhost:8080/hang

This endpoint accepts the request and intentionally sends no response headers or body. The connection remains open until the client closes it, making it useful for verifying that HTTP clients configure a read timeout or an overall request deadline. Without a client-side timeout, the request waits indefinitely by design.

For example, Python Requests will connect successfully and then raise requests.exceptions.ReadTimeout after approximately 5 seconds:

import requests

requests.get("http://localhost:8080/hang", timeout=(3.05, 5))

When the client closes the connection, OpenResty detects the disconnect and cleans up the request handler. While the connection is open, the handler yields to the Nginx event loop rather than blocking a worker thread, though the connection still occupies a socket and request context. Half-open TCP connections where the peer disappears without sending FIN or RST depend on the operating system's TCP keepalive settings for detection.

If /hang is exposed through a reverse proxy or load balancer, configure its upstream response timeout accordingly. Otherwise, the intermediary may terminate or retry the request and eventually return a gateway timeout even though Echo Server itself keeps the connection open.

Using in Kubernetes

Echo Server can be deployed in a Kubernetes cluster, and it will automatically display Pod-related information (if environment variables are available).

Using pre-built image:

ghcr.io/echo-server/echo-server:main

Deployment example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo-server
  template:
    metadata:
      labels:
        app: echo-server
    spec:
      containers:
      - name: echo-server
        image: ghcr.io/echo-server/echo-server:main
        ports:
        - containerPort: 80
        env:
        - name: HOSTNAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: POD_IP
          valueFrom:
            fieldRef:
              fieldPath: status.podIP
---
apiVersion: v1
kind: Service
metadata:
  name: echo-server
spec:
  selector:
    app: echo-server
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

These environment variables will be displayed by the echo server, helping to debug and understand the Pod's runtime environment.

Technology Stack

• OpenResty: A high-performance web platform based on Nginx and Lua
• lua-resty-template: Lua template engine

Contribution

Issues and pull requests are welcome!

License

Please see the LICENSE file in the project.