{"id":40315900,"url":"https://github.com/soulteary/warden","last_synced_at":"2026-02-01T20:13:34.721Z","repository":{"id":333505114,"uuid":"1127767122","full_name":"soulteary/warden","owner":"soulteary","description":"An allowlist identity directory that manages login-eligible users and their contact profiles. / 白名单身份目录服务，管理可登录用户及其邮箱和手机号等联系方式。","archived":false,"fork":false,"pushed_at":"2026-01-27T15:23:16.000Z","size":1546,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-27T21:35:01.705Z","etag":null,"topics":["acl","allowlist","authz","directory","enjoy-with-stargate","identity","user-management"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soulteary.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":"CONTRIBUTING.en.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-04T14:59:11.000Z","updated_at":"2026-01-27T15:23:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/soulteary/warden","commit_stats":null,"previous_names":["soulteary/warden"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/soulteary/warden","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fwarden","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fwarden/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fwarden/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fwarden/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soulteary","download_url":"https://codeload.github.com/soulteary/warden/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fwarden/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28988635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T18:17:03.387Z","status":"ssl_error","status_checked_at":"2026-02-01T18:16:57.287Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acl","allowlist","authz","directory","enjoy-with-stargate","identity","user-management"],"created_at":"2026-01-20T07:00:22.355Z","updated_at":"2026-02-01T20:13:34.703Z","avatar_url":"https://github.com/soulteary.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Warden\n\n\u003e 🌐 **Language / 语言**: [English](README.en.md) | [中文](README.md) | [Français](README.frFR.md) | [Italiano](README.itIT.md) | [日本語](README.jaJP.md) | [Deutsch](README.deDE.md) | [한국어](README.koKR.md)\n\nA high-performance AllowList user data service that supports data synchronization and merging from local and remote configuration sources.\n\n![Warden](.github/assets/banner.jpg)\n\n\u003e **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.\n\n## 📋 Project Overview\n\nWarden 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.\n\n## ✨ Core Features\n\n- 🚀 **High Performance**: Supports 5000+ requests per second with an average latency of 21ms\n- 🔄 **Multiple Data Sources**: Supports both local configuration files and remote APIs\n- 🎯 **Flexible Strategies**: Provides 6 data merging modes (remote-first, local-first, remote-only, local-only, etc.)\n- ⏰ **Scheduled Updates**: Scheduled tasks based on Redis distributed locks for automatic data synchronization\n- 📦 **Containerized Deployment**: Complete Docker support, ready to use out of the box\n- 📊 **Structured Logging**: Uses zerolog to provide detailed access logs and error logs\n- 🔒 **Distributed Locks**: Uses Redis to ensure scheduled tasks don't execute repeatedly in distributed environments\n\n## 🏗️ Architecture Design\n\nWarden uses a layered architecture design, including HTTP layer, business layer, and infrastructure layer. The system supports multiple data sources, multi-level caching, and distributed locking mechanisms.\n\nFor detailed architecture documentation, please refer to: [Architecture Design Documentation](docs/enUS/ARCHITECTURE.md)\n\n## 📦 Installation and Running\n\n\u003e 💡 **Quick Start**: Want to quickly experience Warden? Check out our [Quick Start Examples](example/README.en.md):\n\u003e - [Simple Example](example/basic/README.en.md) - Basic usage, local data file only\n\u003e - [Advanced Example](example/advanced/README.en.md) - Full features, including remote API and Mock service\n\n### Prerequisites\n\n- Go 1.25+ (refer to [go.mod](go.mod))\n- Redis (for distributed locks and caching)\n- Docker (optional, for containerized deployment)\n\n### Quick Start\n\n1. **Clone the project**\n```bash\ngit clone \u003crepository-url\u003e\ncd warden\n```\n\n2. **Install dependencies**\n```bash\ngo mod download\n```\n\n3. **Configure local data file**\nCreate a `data.json` file (refer to `data.example.json`):\n```json\n[\n    {\n        \"phone\": \"13800138000\",\n        \"mail\": \"admin@example.com\"\n    }\n]\n```\n\n4. **Run the service**\n```bash\ngo run main.go\n```\n\nFor detailed configuration and deployment instructions, please refer to:\n- [Configuration Documentation](docs/enUS/CONFIGURATION.md) - Learn about all configuration options\n- [Deployment Documentation](docs/enUS/DEPLOYMENT.md) - Learn about deployment methods\n\n## ⚙️ Configuration\n\nWarden supports multiple configuration methods: command line arguments, environment variables, and configuration files. The system provides 6 data merging modes with flexible configuration strategies.\n\nFor detailed configuration documentation, please refer to: [Configuration Documentation](docs/enUS/CONFIGURATION.md)\n\n## 📡 API Documentation\n\nWarden provides a complete RESTful API with support for user list queries, pagination, health checks, and more. The project also provides OpenAPI 3.0 specification documentation.\n\nFor detailed API documentation, please refer to: [API Documentation](docs/enUS/API.md)\n\nOpenAPI specification file: [openapi.yaml](openapi.yaml)\n\n## 🐳 Docker Deployment\n\nWarden supports complete Docker and Docker Compose deployment, ready to use out of the box.\n\n### Quick Start with Pre-built Image (Recommended)\n\nUse the pre-built image from GitHub Container Registry (GHCR) to get started quickly without local build:\n\n```bash\n# Pull the latest version image\ndocker pull ghcr.io/soulteary/warden:latest\n\n# Run container (basic example)\ndocker run -d \\\n  -p 8081:8081 \\\n  -v $(pwd)/data.json:/app/data.json:ro \\\n  -e PORT=8081 \\\n  -e REDIS=localhost:6379 \\\n  -e API_KEY=your-api-key-here \\\n  ghcr.io/soulteary/warden:latest\n```\n\n\u003e 💡 **Tip**: Using pre-built images allows you to get started quickly without a local build environment. Images are automatically updated to ensure you're using the latest version.\n\n### Using Docker Compose\n\n\u003e 🚀 **Quick Deployment**: Check the [Examples Directory](example/README.en.md) for complete Docker Compose configuration examples\n\nFor detailed deployment documentation, please refer to: [Deployment Documentation](docs/enUS/DEPLOYMENT.md)\n\n## 📊 Performance Metrics\n\nBased on wrk stress test results (30-second test, 16 threads, 100 connections):\n\n```\nRequests/sec:   5038.81\nTransfer/sec:   38.96MB\nAverage Latency: 21.30ms\nMax Latency:     226.09ms\n```\n\n## 📁 Project Structure\n\n```\nwarden/\n├── main.go                 # Program entry point\n├── data.example.json      # Local data file example\n├── config.example.yaml    # Configuration file example\n├── openapi.yaml           # OpenAPI specification file\n├── go.mod                 # Go module definition\n├── docker-compose.yml     # Docker Compose configuration\n├── LICENSE                # License file\n├── README.*.md            # Multi-language project documents (Chinese/English/French/Italian/Japanese/German/Korean)\n├── CONTRIBUTING.*.md      # Multi-language contribution guides\n├── docker/\n│   └── Dockerfile         # Docker image build file\n├── docs/                  # Documentation directory (multi-language)\n│   ├── enUS/              # English documentation\n│   └── zhCN/              # Chinese documentation\n├── example/               # Quick start examples\n│   ├── basic/             # Simple example (local file only)\n│   └── advanced/          # Advanced example (full features, includes Mock API)\n├── internal/\n│   ├── cache/             # Redis cache and lock implementation\n│   ├── cmd/               # Command line argument parsing\n│   ├── config/            # Configuration management\n│   ├── define/            # Constant definitions and data structures\n│   ├── di/                # Dependency injection\n│   ├── errors/            # Error handling\n│   ├── logger/            # Logging initialization\n│   ├── metrics/           # Metrics collection\n│   ├── middleware/        # HTTP middleware\n│   ├── parser/            # Data parser (local/remote)\n│   ├── router/            # HTTP route handling\n│   ├── validator/         # Validator\n│   └── version/           # Version information\n├── pkg/\n│   ├── gocron/            # Scheduled task scheduler\n│   └── warden/            # Warden SDK\n├── scripts/               # Scripts directory\n└── .github/               # GitHub configuration (CI/CD, Issue/PR templates, etc.)\n```\n\n## 🔒 Security Features\n\nWarden implements multiple security features, including API authentication, SSRF protection, rate limiting, TLS verification, and more.\n\nFor detailed security documentation, please refer to: [Security Documentation](docs/enUS/SECURITY.md)\n\n## 🔧 Development Guide\n\n\u003e 📚 **Reference Examples**: Check the [Examples Directory](example/README.en.md) for complete example code and configurations for different usage scenarios.\n\nFor detailed development documentation, please refer to: [Development Documentation](docs/enUS/DEVELOPMENT.md)\n\n### Code Standards\n\nThe project follows Go official code standards and best practices. For detailed standards, please refer to:\n\n- [CODE_STYLE.md](docs/enUS/CODE_STYLE.md) - Code style guide\n- [CONTRIBUTING.en.md](CONTRIBUTING.en.md) - Contribution guide\n\n## 📄 License\n\nSee the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nWelcome to submit Issues and Pull Requests!\n\n## 📞 Contact\n\nFor questions or suggestions, please contact via Issues.\n\n---\n\n**Version**: The program displays version, build time, and code version on startup (via `warden --version` or startup logs)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulteary%2Fwarden","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoulteary%2Fwarden","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulteary%2Fwarden/lists"}