warden

command module
v1.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 44 Imported by: 0

README ΒΆ

Warden

License Go Version Published report coverage Go Report Card

Badges show published report snapshots; current Linux CI enforces at least 95% coverage. See report provenance.

Current release: v1.8.0 β€” upgrade and rollback notes.

🌐 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.4 or later.

Warden

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.

Architecture

Warden architecture

✨ 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

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",
        "status": "active"
    }
]
EOF

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

Redis is enabled by default and expected at localhost:6379. REDIS_ENABLED=false runs this single instance without it. If the variable is left out and no Redis is reachable, Warden still serves the data, but /health reports degraded and the log repeats Redis connection errors. To use Redis, set REDIS to its address instead.

A record is allowed only when its status is "active". A record without status is loaded as "inactive" and is denied.

The command above runs in the default development environment, which is meant for trying Warden out. For a real deployment set ENVIRONMENT=production and use a generated key; the documentation placeholders are rejected there:

docker run -d \
  -p 8081:8081 \
  -v $(pwd)/data.json:/app/data.json:ro \
  -e ENVIRONMENT=production \
  -e MERGE_MODE=ONLY_LOCAL \
  -e API_KEY="$(openssl rand -hex 32)" \
  ghcr.io/soulteary/warden:latest

See Environment for what development relaxes.

πŸ’‘ 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.5.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",
        "status": "active"
    }
]
  1. Run the service
# Run directly; pass the API key through the environment
REDIS_ENABLED=false API_KEY=your-api-key-here go run .

# Or build then run
go build -o warden .
REDIS_ENABLED=false API_KEY=your-api-key-here ./warden

REDIS_ENABLED=false is for running without Redis, as in Option 1; leave it out when a Redis server listens on localhost:6379, or set REDIS to its address.

Pass secrets through environment variables (API_KEY, KEY, REDIS_PASSWORD) or a password file (REDIS_PASSWORD_FILE). The --api-key, --key and --redis-password flags still work, but a flag value is visible to other local users in the process list (ps).

βš™οΈ 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
Environment ENVIRONMENT development (default), test or production. production turns on the security checks described below Set to production for real deployments
API Key API_KEY API authentication key. Without a credential every data route answers 401 Yes, unless HMAC or mTLS is configured
Redis REDIS Redis address for caching and distributed locks (default: localhost:6379). Enabled by default; set REDIS_ENABLED=false to run without it 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

Environment

ENVIRONMENT selects the security policy and is independent of the data merge mode (MERGE_MODE). The default is development, in which Warden:

  • serves /metrics without authentication;
  • includes per-check details in /health responses and the original message in error responses;
  • starts without any credential (the data routes then answer 401) and accepts the placeholder keys from the documentation and HMAC secrets shorter than 32 bytes;
  • accepts a remote source over plain HTTP, without encryption, and with HTTP_INSECURE_TLS=true;
  • accepts IP_WHITELIST without TRUSTED_PROXY_IPS;
  • serves data regardless of how old the last successful source load is (SNAPSHOT_READ_POLICY defaults to observe).

With ENVIRONMENT=production each of these is refused at startup or switched to the strict behaviour: a credential is required, /metrics requires authentication, error and health responses carry no details, a remote source must use HTTPS with the v2 encrypted envelope, and SNAPSHOT_READ_POLICY defaults to enforce. The root docker-compose.yml sets ENVIRONMENT=production by default. See the Security guide.

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
Additional Resources

πŸ“„ 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.

Directories ΒΆ

Path Synopsis
internal
auditlog
Package auditlog provides audit logging functionality for Warden service.
Package auditlog provides audit logging functionality for Warden service.
cache
Package cache provides user data caching functionality.
Package cache provides user data caching functionality.
cmd
Package cmd provides command-line argument parsing and configuration management functionality.
Package cmd provides command-line argument parsing and configuration management functionality.
config
Package config provides configuration file loading and management functionality.
Package config provides configuration file loading and management functionality.
define
Package define defines constants and data structures in the application.
Package define defines constants and data structures in the application.
errors
Package errors provides unified error handling functionality.
Package errors provides unified error handling functionality.
i18n
Package i18n provides internationalization support.
Package i18n provides internationalization support.
identity
Package identity provides centralized validation and indexing of allow-list users before they enter the shared cache.
Package identity provides centralized validation and indexing of allow-list users before they enter the shared cache.
loader
Package loader provides rules loading via parser-kit (multi-source fallback/merge).
Package loader provides rules loading via parser-kit (multi-source fallback/merge).
logger
Package logger provides logging functionality.
Package logger provides logging functionality.
middleware
Package middleware provides HTTP middleware functionality.
Package middleware provides HTTP middleware functionality.
prommetrics
Package prommetrics provides Prometheus metrics collection functionality.
Package prommetrics provides Prometheus metrics collection functionality.
remote
Package remote provides remote config fetch with optional authenticated decryption.
Package remote provides remote config fetch with optional authenticated decryption.
router
Package router provides HTTP routing functionality.
Package router provides HTTP routing functionality.
serviceauth
Package serviceauth defines optional service credential permissions.
Package serviceauth defines optional service credential permissions.
tracing
Package tracing provides OpenTelemetry tracing functionality for HTTP requests.
Package tracing provides OpenTelemetry tracing functionality for HTTP requests.
validator
Package validator provides configuration validation functionality.
Package validator provides configuration validation functionality.
Package locales provides embedded translation files.
Package locales provides embedded translation files.
pkg
gocron
Package gocron : A Golang Job Scheduling Package.
Package gocron : A Golang Job Scheduling Package.
warden
Package warden provides a client SDK for interacting with Warden API.
Package warden provides a client SDK for interacting with Warden API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL