Cosmoparrot

A simple HTTP based echo server.

Building Cosmoparrot • Configuration • Running Cosmoparrot

Overview

Cosmosparrot simple HTTP based echo server designed to provide a response that mirrors the contents included in the initial request.
It was initially created for Pub/Sub end-to-end test scenarios where it is important to simulate an event message consumer that responds to HTTP (callback) requests.

Building Cosmoparrot

Go build

Assuming you have already installed go, simply run the follwoing to build the executable:

go build

Alternatively, you can also follow the Docker build in the following section if you want to build a Docker image without the need to have Golang installed locally.

Docker build

This repository provides a multi-stage Dockerfile that will also take care about compiling the software, as well as dockerizing Cosmoparrot. Simply run:

docker build -t cosmoparrot:latest  . 

Configuration

Cosmoparrot supports configuration via environment variables and/or a configuration file (config.yml). The configuration file has to be located in the same directory as the executable.

Path	Variable	Type	Default	Description
port	COSMOPARROT_PORT	int	8080	Sets the port to listen on.
responseCode	COSMOPARROT_RESPONSECODE	int	200	Enforces a specific HTTP response code. Can be used to test different consumer behavior.
methodResponseCodeMapping	COSMOPARROT_METHODRESPONSECODEMAPPING	string	""	Control the HTTP response code per HTTP method, for example: "POST:401"
otelEnabled	COSMOPARROT_OTELENABLED	bool	false	Enables OpenTelemetry tracing for incoming HTTP requests.
otelServiceName	COSMOPARROT_OTELSERVICENAME	string	cosmoparrot	Service name reported in traces.
requestLogging	COSMOPARROT_REQUESTLOGGING	bool	true	Logs every incoming request (request line and headers). Set to false to disable per-request logging, e.g. for high-throughput scenarios. Request bodies are never logged.

When tracing is enabled, exporter behavior can be configured via standard OpenTelemetry environment variables like OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, and OTEL_EXPORTER_OTLP_PROTOCOL.

Memory (GOMEMLIMIT): On startup Cosmoparrot detects the container's cgroup memory limit and sets a Go soft memory limit (GOMEMLIMIT) at 90% of it. This makes the garbage collector run more aggressively as memory fills up, which prevents the pod from being OOM-killed under bursty load. Set the GOMEMLIMIT environment variable explicitly to override the auto-detected value.

Endpoints

Echo (catch-all)

Any request that does not match a specific route is handled by the echo handler. It mirrors the request back as a JSON response including path, method, headers, and body.

• Supports ?mirrorBody=false to suppress echoing the request body back in the response body (defaults to true). When disabled, the request body is not read at all — it is neither echoed nor stored, and is not validated (no 400 on malformed JSON). This keeps large payloads off-heap.

Request store

The echo handler can record incoming requests in an in-memory cache so they can be retrieved later via /api/v1/requests and /api/v1/requests/:key (useful for asserting, in tests, what a component sent). A request is stored only when it carries one of the headers listed in storeKeyRequestHeaders, keyed by that header's value; entries expire after 1 hour.

The store is disabled when storeKeyRequestHeaders is empty (the Helm default) — no separate toggle is needed. Avoid configuring a header that is unique per request (e.g. a trace id such as X-B3-Traceid): every request then creates its own entry and the cache grows unbounded until it OOMs. Use a coarse key (or leave it empty) for high-throughput/load scenarios.

/api/v1/devnull

A high-performance sink endpoint that accepts any HTTP method. It reads and discards the request payload without parsing, logging, or storing anything — making it safe for sustained high-throughput scenarios with no risk of OOM.

• Returns the configured response code (default 200).
• Supports ?responseCode=<code> query parameter to override the status code per request.

/api/v1/requests

Returns all stored requests as JSON (requires store key headers to be configured).

/api/v1/requests/:key

Returns stored requests for a specific key.

/api/v1/slowloris

Simulates a slowloris response by streaming data slowly. Supports ?duration=<seconds> and ?interval=<seconds> query parameters.

Running Cosmoparrot

Locally

Simply run the built cosmoparrot executable to start the server:

./cosmoparrot

Alternatively you can run the server in a container:

docker run -p 8080:8080 cosmoparrot

Deployment

For the deployment of Cosmoparrot you can use Kubernetes deployment manifest/deployment.yaml and adjust it to your needs, or you can use and customize the Heln chart located in manifest/helm.

Helm example:

helm install cosmoparrot ./manifest/helm/cosmoparrot \
  --namespace custom-namespace --create-namespace \
  --set cosmoparrot.storeKeyRequestHeaders="{X-Request-ID,X-Correlation-ID}" \
  --set image.repository=myregistry.com/cosmoparrot \
  --set image.tag=latest \
  --set ingress.enabled=true \
  --set ingress.host=cosmoparrot.mycompany.com \
  --set imagePullSecrets[0].name=my-pull-secret

Contributing

We're committed to open source, so we welcome and encourage everyone to join its developer community and contribute, whether it's through code or feedback.
By participating in this project, you agree to abide by its Code of Conduct at all times.

Code of Conduct

This project has adopted the Contributor Covenant in version 2.1 as our code of conduct. Please see the details in our Code of Conduct. All contributors must abide by the code of conduct. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

This project follows the REUSE standard for software licensing. You can find a guide for developers at https://telekom.github.io/reuse-template/.
Each file contains copyright and license information, and license texts can be found in the ./LICENSES folder. For more information visit https://reuse.software/.