warden

README

Warden

🌐 Language / 语言: English | 中文 | Français | Italiano | 日本語 | Deutsch | 한국어

A high-performance AllowList user data service that supports data synchronization and merging from local and remote configuration sources.

Warden continues to use Go's net/http server. Its shared kit dependencies use their Fiber v3-compatible v2 module lines, so Fiber v2 is no longer present in the module graph. Building from source requires Go 1.27 or later.

Warden (The Gatekeeper) — The guardian of the Stargate who decides who may pass and who will be denied. Just as the Warden of Stargate guards the Stargate, Warden guards your allowlist, ensuring only authorized users can pass through.

📋 Overview

Warden is a lightweight HTTP API service developed in Go, primarily used for providing and managing allowlist user data (phone numbers and email addresses). The service supports fetching data from local configuration files and remote APIs, and provides multiple data merging strategies to ensure data real-time performance and reliability.

Warden can be used standalone or integrated with other services (such as Stargate and Herald) as part of a larger authentication architecture. For detailed architecture information, see Architecture Documentation.

✨ Core Features

• 🚀 High Performance: 5000+ requests per second with 21ms average latency
• 🔄 Multiple Data Sources: Local configuration files and remote APIs
• 🎯 Flexible Strategies: 7 data merging modes (remote-first, local-first, remote-only, local-only, etc.)
• ⏰ Scheduled Updates: Automatic data synchronization with Redis distributed locks
• 📦 Containerized Deployment: Complete Docker support, ready to use out of the box
• 🌐 Multi-language Support: 7 languages with automatic language detection

🚀 Quick Start

Option 1: Docker (Recommended)

The fastest way to get started is using the pre-built Docker image:

# Pull the latest image
docker pull ghcr.io/soulteary/warden:latest

# Create a data file
cat > data.json <<EOF
[
    {
        "phone": "13800138000",
        "mail": "admin@example.com"
    }
]
EOF

# Run the container
docker run -d \
  -p 8081:8081 \
  -v $(pwd)/data.json:/app/data.json:ro \
  -e API_KEY=your-api-key-here \
  ghcr.io/soulteary/warden:latest

💡 Tip: For complete examples with Docker Compose, see the Examples Directory.

The root docker-compose.yml uses the same image by default. Set WARDEN_IMAGE to a version tag (for example ghcr.io/soulteary/warden:1.2.0) or digest for reproducible production deployments; latest is updated only by stable release tags.

Option 2: From Source

1. Clone and build

git clone <repository-url>
cd warden
go mod download

1. Create data file Create a data.json file (refer to data.example.json):

[
    {
        "phone": "13800138000",
        "mail": "admin@example.com"
    }
]

1. Run the service

# Run directly
go run . --api-key your-api-key-here

# Or build then run
go build -o warden .
./warden --api-key your-api-key-here

⚙️ Essential Configuration

Warden supports configuration via command line arguments, environment variables, and configuration files. The following are the most essential settings:

Setting	Environment Variable	Description	Required
Port	PORT	HTTP server port (default: 8081)	No
API Key	API_KEY	API authentication key (recommended for production)	Recommended
Redis	REDIS	Redis address for caching and distributed locks (e.g., localhost:6379)	Optional
Data File	DATA_FILE	Local data file path (default: ./data.json)	Yes*
Remote Config	CONFIG	Remote API URL for data fetching	Optional

* Required if not using remote API

For complete configuration options, see Configuration Documentation.

📡 API Usage

Warden provides a RESTful API for querying user lists, pagination, and health checks. The service supports multi-language responses via query parameter ?lang=xx or Accept-Language header.

Example:

# Query users
curl -H "X-API-Key: your-key" "http://localhost:8081/"

# Health check
curl "http://localhost:8081/health"

Health returns degraded with HTTP 200 while a non-critical fallback remains serviceable, and HTTP 503 when a critical check fails. In strict remote modes, set SNAPSHOT_MAX_AGE to bound how long the last successful snapshot may be served; see the configuration reference.

For complete API documentation, see API Documentation or OpenAPI Specification.

📊 Performance

Based on wrk stress test (30s, 16 threads, 100 connections):

• Requests/sec: 5038.81
• Average Latency: 21.30ms
• Max Latency: 226.09ms

📚 Documentation

Core Documentation

• Architecture - Technical architecture and design decisions
• API Reference - Complete API endpoint documentation
• Configuration - Configuration reference and examples
• Deployment - Deployment guide (Docker, Kubernetes, etc.)

Additional Resources

• Development Guide - Development environment setup and contribution guide
• Security - Security features and best practices
• SDK - Go SDK usage documentation
• Migration Guides - Configuration, HMAC v2, and remote encryption v2
• Examples - Quick start examples (basic and advanced)

📄 License

See the LICENSE file for details.

🤝 Contributing

Welcome to submit Issues and Pull Requests! See CONTRIBUTING.md for guidelines.

Documentation

Overview

Package main is the entry point of the application. Provides HTTP server, cache management, scheduled task scheduling and other functionality.

Package main - route registration and health check setup.