redirhub/rapid

Redirector Service

A high-performance Go-based URL redirector service with Redis-backed storage, supporting wildcard matching, security filtering, and multiple redirect types.

Architecture

The application follows a clean architecture pattern with dependency injection:

cmd/server/          # Application entry point
internal/
├── app/            # Application assembly and startup
├── config/         # Configuration management
├── interfaces/     # Interface definitions
├── handlers/       # HTTP request handlers
├── services/       # Business logic services
├── storage/        # Data storage implementations
├── cache/          # Caching implementations
├── template/       # Template rendering
├── models/         # Data models
├── errors/         # Error types
└── tests/          # Unit and integration tests

Key Components

• Storage Layer: Redis-backed storage with interface abstraction
• Security Service: Robot detection, blacklist filtering, WeChat/QQ blocking
• URL Processor: Variable replacement, UTM parameter handling, multi-destination routing
• Template Engine: File-based template system with caching
• Record Matcher: Host/path matching with wildcard support
• Response Service: Multiple response types (redirect, frame, text, JS)

Building and Running

Development

bash
# Run directly
go run ./cmd/server [port]

# Build binary
go build -o server ./cmd/server
./server [port]

Docker

bash
# Build image
docker build -t redirector .

# Run with docker-compose (includes Redis)
docker-compose up

Testing

bash
# Unit tests
go test ./internal/...

# Integration tests
go test -v ./internal/tests/...

# Benchmark tests
go test -bench=. ./tests/...

Configuration

Environment Variables

• REDIS_HOST - Redis host (default: "redis")
• REDIS_PORT - Redis port (default: "6379")
• REDIS_DB - Redis database (default: "0")
• POWERBY - Service branding

Config File

Create config.json based on config.json.example:

json
{
  "name": "node-name",
  "cache": true,
  "ip": "server-ip",
  "country": "server-country"
}

Record Format

Records stored in Redis follow this structure:

json
{
  "_id": "domain.com/path",
  "value": "https://target.com",
  "type": "301",
  "handler": "redirect",
  "blacklist": false,
  "filters": ["nobot", "nowechat"],
  "destinations": ["url1", "url2"],
  "routing": "random",
  "utm": {"source": "redirect"},
  "params": {"ref": "redirector"}
}

Features

URL Matching

• Exact match: domain.com/path
• Wildcard match: domain.com/*
• Domain wildcard: *.domain.com/*

Security Features

• Bot detection and blocking
• Domain blacklisting
• WeChat/QQ app filtering
• JS challenge protection

Response Types

• 301/302/307/308 - HTTP redirects
• frame - Iframe embedding
• redirect_js - JavaScript redirect
• txt - Plain text response
• html - HTML content

Variable Replacement

• {host} - Full hostname
• {host.domain} - Top-level domain
• {host.sub} - Subdomain part
• {path}, {uri} - URL path
• {qs} - Query string
• {random_string} - Random 6-char string

Development

The refactored codebase provides:

1. Separation of Concerns: Each package has a single responsibility
2. Dependency Injection: All dependencies are injected via interfaces
3. Testability: Interfaces allow easy mocking and testing
4. Maintainability: Clear structure and consistent patterns
5. Extensibility: Easy to add new features via interfaces

Adding New Features

1. Define interface in internal/interfaces/
2. Implement service in internal/services/
3. Wire up in internal/app/app.go
4. Add tests in internal/tests/