Mock backend
1.3K
A lightweight, configurable canary/test API server written in Go. Perfect for testing backend integrations, simulating slow or large responses, and validating infrastructure configurations.
docker run -d -p 8080:8080 jerryibrahim/go-canary
services:
api:
image: jerryibrahim/go-canary
ports:
- "8080:8080"
environment:
- PORT=8080
- COLOR=blue
- LOG_LEVEL=INFO
docker run -d \
-p 8080:8080 \
-p 8443:8443 \
-v /path/to/certs:/secrets:ro \
-e TLS_CERT_FILE=/secrets/tls-cert \
-e TLS_KEY_FILE=/secrets/tls-key \
jerryibrahim/go-canary
| Variable | Default | Description |
|---|---|---|
PORT | 8080 | HTTP listen port |
PORT_TLS | 8443 | HTTPS listen port (if TLS enabled) |
LOG_LEVEL | INFO | Logging level: VERBOSE, TRACE, DEBUG, INFO, WARN, ERROR |
LOG_COLOR | false | Enable colorized log headers |
LOG_TIMESTAMP_NANO | false | Add nanoseconds to timestamp |
VERSION | 0.0.0 | Override app version (reads from /assets/version.txt by default) |
COLOR | blue | Color label for blue/green deployments |
GCR_ENV | false | Enable Google Cloud Run metadata fetching |
PROJECT_ID | local_svc | Google Project ID |
TLS_CERT_FILE | /secrets/tls-cert | Path to TLS certificate file |
TLS_KEY_FILE | /secrets/tls-key | Path to TLS private key file |
TLS_MIN_VERSION | 1.2 | Minimum TLS version (1.2 or 1.3) |
API_KEY | (empty) | API key for api-key header authorization. If empty, no API key required |
ADMIN_KEY | (empty) | Admin key for admin-key header authorization on /admin/* endpoints. If empty, no auth required |
CORS | false | Enable CORS headers |
CORS_DOMAINS | (empty) | Comma-separated allowed origin domains for CORS. Empty = all domains |
DOMAINS_FILTER | (empty) | Comma-separated allowed outbound domains for HTTP client requests (egress filter). Empty = all domains |
| Endpoint | Method | Description |
|---|---|---|
/status | GET | Standard health check endpoint |
/stats | GET | Returns server statistics (memory, threads, cache, queue) |
Example: /stats response
{
"timestamp": "2024-01-15T10:30:00Z",
"proc_mem": 12.345,
"proc_threads": 8,
"domains_cache": 5,
"dlq": 0,
"queue": 0,
"cache": 3
}
| Endpoint | Method | Description |
|---|---|---|
/ | GET | Returns color as plain text |
/version | GET | Returns version as JSON |
/color | GET | Returns version and color as JSON |
Example: /version response
{
"version": "1.0.0"
}
Example: /color response
{
"version": "1.0.0",
"color": "blue"
}
/timeSimulates a slow response by waiting a specified number of seconds.
| Parameter | Type | Default | Description |
|---|---|---|---|
k | int | 1 | Number of seconds to wait before responding |
Examples:
# Wait 1 second (default)
curl http://localhost:8080/time
# Wait 5 seconds
curl http://localhost:8080/time?k=5
Response:
{
"version": "1.0.0",
"time": "5"
}
/sizeReturns a configurable payload size for testing bandwidth and response handling.
| Parameter | Type | Default | Description |
|---|---|---|---|
k | int | 1 | Response size in KB |
Examples:
# Return ~1KB response (default)
curl http://localhost:8080/size
# Return ~15KB response
curl http://localhost:8080/size?k=15
/cacheTest in-memory caching functionality. First request sets the cache, subsequent requests return cached value.
| Parameter | Type | Default | Description |
|---|---|---|---|
k | string | 1 | Cache key identifier |
Examples:
# Get/set cache with default key
curl http://localhost:8080/cache
# Get/set cache with custom key
curl http://localhost:8080/cache?k=mykey
Response:
{
"type": "CACHE",
"version": "1.0.0",
"key": "mykey",
"timestamp": "2024-01-15T10:30:00Z"
}
/queueAdd requests to an internal queue for async processing demonstration.
| Parameter | Type | Default | Description |
|---|---|---|---|
k | string | 1 | Queue item key identifier |
Examples:
# Add to queue with default key
curl http://localhost:8080/queue
# Add to queue with custom key
curl http://localhost:8080/queue?k=order123
Response:
{
"type": "QUEUE",
"version": "1.0.0",
"key": "order123",
"timestamp": "2024-01-15T10:30:00Z"
}
/postEcho back POST form data and headers (POST method only).
Example:
curl -X POST -d "param1=value1¶m2=value2" http://localhost:8080/post
/admin/setenvDynamically update environment variables and control application state (POST method only).
Protected by MiddlewareAdminKey — if ADMIN_KEY env var is set, requests must include the admin-key header.
Update Log Level:
curl -X POST -d "LOG_LEVEL=DEBUG" http://localhost:8080/admin/setenv
Update Version:
curl -X POST -d "VERSION=1.1.1" http://localhost:8080/admin/setenv
Application Control:
# Reset application (clears cache, queues, memory)
curl -X POST -d "app=reset" http://localhost:8080/admin/setenv
# Pause queue consumers
curl -X POST -d "app=pause" http://localhost:8080/admin/setenv
# Resume queue consumers
curl -X POST -d "app=resume" http://localhost:8080/admin/setenv
With ADMIN_KEY authentication:
curl -X POST -H "admin-key: <key>" -d "LOG_LEVEL=DEBUG" http://localhost:8080/admin/setenv
Simulate various HTTP error responses for testing error handling.
| Endpoint | Response |
|---|---|
/400 | 400 Bad Request |
/401 | 401 Unauthorized |
/403 | 403 Forbidden |
/404 | 404 Not Found |
/405 | 405 Method Not Allowed |
/500 | 500 Internal Server Error |
Example:
curl -i http://localhost:8080/500
# HTTP/1.1 500 Internal Server Error
When API_KEY environment variable is set, all requests must include the api-key header:
# Set API key on container
docker run -d -p 8080:8080 -e API_KEY=mysecretkey jerryibrahim/go-canary
# Make authenticated request
curl -H "api-key: mysecretkey" http://localhost:8080/status
Enable CORS support for browser-based applications:
# Enable CORS for all domains
docker run -d -p 8080:8080 -e CORS=true jerryibrahim/go-canary
# Enable CORS for specific domains only
docker run -d -p 8080:8080 \
-e CORS=true \
-e CORS_DOMAINS=example.com,myapp.com \
jerryibrahim/go-canary
The container automatically enables HTTPS when TLS certificates are provided:
docker run -d \
-p 8080:8080 \
-p 8443:8443 \
-v /path/to/certs:/secrets:ro \
-e TLS_CERT_FILE=/secrets/tls.crt \
-e TLS_KEY_FILE=/secrets/tls.key \
jerryibrahim/go-canary
The server will:
COLOR environment variable to identify deployment versions/size and /time endpoints to simulate various response characteristics/status endpoint for container orchestration health probesCopyright © 2019-2026 @jerryibrahim
Content type
Image
Digest
sha256:c421713b6…
Size
7.3 MB
Last updated
9 days ago
docker pull jerryibrahim/go-canary:2.3.3