🦜 Parrot

A modern, production-ready HTTP echo server that parrots back comprehensive request information. Perfect for debugging webhooks, testing HTTP clients, monitoring network requests, and understanding API interactions.

✨ Features

• ⚡ Lightning Fast - Built on Bun runtime and Elysia framework for maximum performance
• 🔒 Secure by Default - Distroless container, non-root user, sensitive data redaction
• 📊 Comprehensive Echo - Captures method, headers, query params, body, and server metadata
• 🚀 Production Ready - Kubernetes health probes, Helm charts, horizontal pod autoscaling
• 📚 Auto-Generated Docs - Interactive OpenAPI/Swagger documentation
• 🧪 Fully Tested - Comprehensive unit, integration, and e2e test suite

🚀 Quick Start

Docker

docker run -p 9999:9999 ghcr.io/kayaman/parrot:latest

Kubernetes (Helm)

helm repo add parrot https://kayaman.github.io/parrot
helm install my-parrot parrot/parrot

Test It

curl -X POST http://localhost:9999/api/test \
  -H "Content-Type: application/json" \
  -d '{"hello": "world"}'

📖 Documentation

• API Documentation - Complete API reference
• Helm Guide - Kubernetes deployment guide
• Interactive Docs - Swagger UI (when running)

🎯 Use Cases

• Webhook Debugging - Test and debug webhook integrations
• API Client Testing - Validate HTTP client implementations
• Network Monitoring - Inspect request details in real-time
• Load Testing - Lightweight echo server for performance testing
• Learning & Education - Understand HTTP requests and responses

🔧 Development

Prerequisites

• Bun v1.0.0 or higher
• Docker (for container builds)
• Kubernetes + Helm (for deployment testing)

Local Development

# Clone the repository
git clone https://github.com/kayaman/parrot.git
cd parrot

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run linter
bun run check

# Build for production
bun run build

Project Structure

parrot/
├── src/
│   ├── index.ts              # Application entry point
│   ├── app.ts                # Elysia app configuration
│   ├── routes/
│   │   ├── health.ts         # Health check endpoints
│   │   └── parrot.ts         # Echo handler
│   ├── services/
│   │   ├── metadata.ts       # Request metadata extraction
│   │   └── response.ts       # Response builder
│   ├── types/
│   │   └── index.ts          # TypeScript interfaces
│   └── config/
│       └── server.ts         # Server configuration
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── e2e/                  # End-to-end tests
├── charts/parrot/            # Helm chart
└── docs/                     # GitHub Pages site

📦 API Reference

Health Endpoints

GET /health/live

Liveness probe for Kubernetes. Returns 200 if the application is running.

GET /health/ready

Readiness probe for Kubernetes. Returns 200 when ready to accept traffic.

Echo Endpoint

ANY /*

Accepts any HTTP method and path. Returns comprehensive request information.

Example Response:

{
  "message": "Request echoed successfully",
  "timestamp": "2025-12-19T10:30:00.000Z",
  "request": {
    "method": "POST",
    "path": "/api/test",
    "query": { "foo": "bar" },
    "headers": { "content-type": "application/json" },
    "body": { "hello": "world" },
    "clientIp": "192.168.1.1",
    "userAgent": "curl/8.0.1"
  },
  "server": {
    "hostname": "parrot-pod-abc123",
    "platform": "linux",
    "uptime": 3600,
    "memory": { "heapUsed": 25165824 }
  }
}

Security Features

Sensitive headers are automatically redacted:

• authorization
• cookie
• x-api-key
• x-auth-token

🐳 Container

The container image is built using a multi-stage distroless approach:

• Base: gcr.io/distroless/base-debian12:nonroot
• Size: ~60MB
• User: Non-root (UID 65532)
• Health Check: Built-in container health check
• Architectures: linux/amd64, linux/arm64

# Pull the latest image
docker pull ghcr.io/kayaman/parrot:latest

# Run with custom port
docker run -p 8080:9999 -e PORT=9999 ghcr.io/kayaman/parrot:latest

⎈ Kubernetes Deployment

Basic Installation

helm repo add parrot https://kayaman.github.io/parrot
helm install my-parrot parrot/parrot

Production Configuration

helm install parrot-prod parrot/parrot \
  --set replicaCount=3 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set autoscaling.enabled=true \
  --set autoscaling.minReplicas=3 \
  --set autoscaling.maxReplicas=20

With Ingress

helm install my-parrot parrot/parrot \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.hosts[0].host=parrot.example.com \
  --set ingress.hosts[0].paths[0].path=/

🧪 Testing

# Run all tests
bun test

# Run specific test suites
bun run test:unit
bun run test:integration
bun run test:e2e

# Run with coverage
bun run test:coverage

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

• Elysia - Fast and ergonomic TypeScript framework
• Bun - Fast all-in-one JavaScript runtime
• Biome - Fast linter and formatter

📬 Contact

• GitHub: @kayaman
• Issues: GitHub Issues
• Documentation: https://kayaman.github.io/parrot

---

Made with ❤️ by kayaman