Redirection Engine & Cache Mechanism
Relevant source files
The following files were used as context for generating this wiki page:
The Redirection Engine is the core component of GoGovSG responsible for resolving short URLs to their corresponding long URLs or file targets. It manages the user journey from the initial request to the final destination, incorporating security validations, anti-phishing measures, and analytics logging.
The system utilizes a multi-layered storage approach, employing a PostgreSQL database for persistent link mappings and Redis for transient storage of frequently used shortlinks, sessions, and real-time click statistics. This architecture ensures high availability and low latency for redirect operations.
Sources: README.md:12-16, src/server/index.ts:245-253
Architecture and Request Flow
The redirection process starts when the Express server receives a GET request on the /:shortUrl endpoint. The request passes through a route guard before being handled by the RedirectController.
Redirection Sequence
The following diagram illustrates the interaction between the controller, the service layer, and external security services during a redirect request.
Key Components
| Component | Responsibility |
|---|---|
RedirectController | Handles HTTP request parameters, session updates, and renders the final response (302 or EJS template). |
RedirectService | Contains business logic for URL lookup, crawler detection, and threat scanning. |
shortUrlRouteGuard | Validates the structure of the short URL before processing to prevent invalid lookups. |
AnalyticsLoggerService | Generates analytics cookies and logs redirection events to Google Analytics. |
dogstatsd | Increments the SHORTLINK_CLICKS metric for real-time monitoring. |
Sources: src/server/modules/redirect/RedirectController.ts:18-35, src/server/index.ts:246-250
Security and Threat Validation
The engine incorporates several security checks to protect users from malicious content and phishing attempts.
Safe Browsing Integration
Before redirection, the RedirectService verifies if the target longUrl is malicious.
- Expiration Check: If the
safeBrowsingExpiryfor a link has passed, the system performs a new threat scan. - Malicious Link Deactivation: If a threat is confirmed, the system deactivates the short URL and returns a
NotFoundErrorto the user. - Fail-Open Policy: If the threat scan itself fails (e.g., API outage), the system allows the redirect to proceed but does not update the safety expiry date.
Sources: src/server/modules/redirect/services/tests/RedirectService.test.ts:167-235
Anti-Phishing Transition Page
To prevent users from being misled, the engine determines whether to show a transition page based on the referrer header and the user's history.
Direct Redirect*: Occurs if the user has visited the shortlink before (stored in the visits cookie) or if the referrer exactly matches the configured ogUrl.
- Transition Page: Rendered if the request comes from an external or unknown domain. This page displays the destination root domain and requires user interaction to proceed.
Sources: src/server/modules/redirect/services/tests/RedirectService.test.ts:98-165, src/server/modules/redirect/RedirectController.ts:92-106
Cache and Performance Optimization
The system leverages Redis to minimize database load and improve response times for high-traffic links.
Redis Usage Tiers
The infrastructure configuration defines specific Redis databases for different redirection concerns:
- REDIS_REDIRECT_URI: Stores frequently accessed shortlink mappings to bypass PostgreSQL lookups.
- REDIS_STAT_URI: Used for transient storage of click statistics before they are flushed or aggregated.
- REDIS_SESSION_URI: Manages server-side sessions for authenticated users and redirect visit history.
- FF_USE_REPLICA_FOR_REDIRECTS: A feature flag allowing the engine to query a read-only database replica for redirections, further reducing load on the primary database.
Sources: README.md:120-135, README.md:166-167
Click Tracking Mechanism
Redirection clicks are tracked asynchronously to avoid blocking the user experience.
- The
RedirectControllercallsdogstatsd.incrementupon every successful resolution. - The
AnalyticsLoggerServicecreates a page view hit based on request headers. - End-to-end tests verify that click counts are updated and visible in the directory via the
waitForRecordedClicksutility.
Sources: src/server/modules/redirect/RedirectController.ts:89-91, test/end-to-end/util/LinkCreationProcedure.ts:38-42
Validation Rules
During link creation and redirection, the engine enforces strict validation to prevent misuse.
| Validation Type | Description |
|---|---|
| Circular Redirects | Prevents a short URL from pointing back to the GoGovSG domain. |
| Blacklisted Domains | Blocks creation of links pointing to known malicious or restricted domains. |
| Single Path Segment | The :shortUrl parameter must be a single string; arrays or multi-segment paths trigger a 404. |
| Malicious Files | File uploads are scanned for viruses; if malicious, the link creation is aborted. |
Sources: test/end-to-end/UrlCreation.spec.ts:59-75, src/server/modules/redirect/RedirectController.ts:74-82, test/end-to-end/UrlCreation.spec.ts:246-255
Summary
The Redirection Engine & Cache Mechanism provides a secure, high-performance gateway for official government links. By combining Redis caching, Google Safe Browsing integration, and anti-phishing transition pages, it ensures that citizens can trust shortened URLs while maintaining the scalability required for national-level service.