jerryibrahim/go-canary

go-canary

A lightweight, configurable canary/test API server written in Go. Perfect for testing backend integrations, simulating slow or large responses, and validating infrastructure configurations.

Quick Start

Docker Run

bash
docker run -d -p 8080:8080 jerryibrahim/go-canary

Docker Compose

yaml
services:
  api:
    image: jerryibrahim/go-canary
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - COLOR=blue
      - LOG_LEVEL=INFO

With TLS

bash
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

---

Environment Variables

---

API Endpoints

Health & Status

Example: /stats response

json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "proc_mem": 12.345,
  "proc_threads": 8,
  "domains_cache": 5,
  "dlq": 0,
  "queue": 0,
  "cache": 3
}

---

Version & Color (Blue/Green)

Example: /version response

json
{
  "version": "1.0.0"
}

Example: /color response

json
{
  "version": "1.0.0",
  "color": "blue"
}

---

Testing Endpoints

Simulated Delay: /time

Simulates a slow response by waiting a specified number of seconds.

Examples:

bash
# Wait 1 second (default)
curl http://localhost:8080/time

# Wait 5 seconds
curl http://localhost:8080/time?k=5

Response:

json
{
  "version": "1.0.0",
  "time": "5"
}

---

Large Response: /size

Returns a configurable payload size for testing bandwidth and response handling.

Examples:

bash
# Return ~1KB response (default)
curl http://localhost:8080/size

# Return ~15KB response
curl http://localhost:8080/size?k=15

---

Memory Cache: /cache

Test in-memory caching functionality. First request sets the cache, subsequent requests return cached value.

Examples:

bash
# 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:

json
{
  "type": "CACHE",
  "version": "1.0.0",
  "key": "mykey",
  "timestamp": "2024-01-15T10:30:00Z"
}

---

Request Queue: /queue

Add requests to an internal queue for async processing demonstration.

Examples:

bash
# 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:

json
{
  "type": "QUEUE",
  "version": "1.0.0",
  "key": "order123",
  "timestamp": "2024-01-15T10:30:00Z"
}

---

POST Data Echo: /post

Echo back POST form data and headers (POST method only).

Example:

bash
curl -X POST -d "param1=value1&param2=value2" http://localhost:8080/post

---

Runtime Configuration: /admin/setenv

Dynamically 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:

bash
curl -X POST -d "LOG_LEVEL=DEBUG" http://localhost:8080/admin/setenv

Update Version:

bash
curl -X POST -d "VERSION=1.1.1" http://localhost:8080/admin/setenv

Application Control:

bash
# 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:

bash
curl -X POST -H "admin-key: <key>" -d "LOG_LEVEL=DEBUG" http://localhost:8080/admin/setenv

---

HTTP Error Simulation

Simulate various HTTP error responses for testing error handling.

Example:

bash
curl -i http://localhost:8080/500
# HTTP/1.1 500 Internal Server Error

---

API Key Authentication

When API_KEY environment variable is set, all requests must include the api-key header:

bash
# 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

---

CORS Configuration

Enable CORS support for browser-based applications:

bash
# 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

---

TLS/HTTPS Support

The container automatically enables HTTPS when TLS certificates are provided:

bash
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:

• Listen on HTTP port (default: 8080)
• Listen on HTTPS port (default: 8443) if valid certificates are found
• Automatically reload certificates when they change

---

Use Cases

• Blue/Green Deployments: Use the COLOR environment variable to identify deployment versions
• Load Testing: Use /size and /time endpoints to simulate various response characteristics
• Infrastructure Testing: Validate load ***s, proxies, and API gateways
• Error Handling: Test application behavior with various HTTP error codes
• CORS Testing: Validate cross-origin configurations
• Health Checks: Use /status endpoint for container orchestration health probes

---

License

Copyright © 2019-2026 @jerryibrahim