Redirect Validation Tool

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/validate-redirects/main.go
• scripts/README-redirects.md
• CONTRIBUTING.md
• ARCHITECTURE.md
• README.md

The Redirect Validation Tool is a specialized utility designed to ensure the integrity and accuracy of URI redirects within the CircleCI documentation platform. Its primary purpose is to verify that legacy URLs correctly map to their new destinations with the appropriate HTTP status codes, preventing broken links and maintaining SEO value during content migrations.

The tool is integrated into the project's maintenance and deployment workflows, specifically supporting the validation of AWS S3 website redirects. It allows developers to batch-process redirect mappings and verify that the destination pages are reachable and return successful status codes after the redirect occurs.
Sources: cmd/validate-redirects/main.go:1-25, scripts/README-redirects.md:1-15, README.md:1-15

Core Architecture and Logic

The tool is implemented as a Go command-line application that utilizes concurrent workers to process redirect entries efficiently. It leverages a validator structure to manage HTTP clients, concurrency control via semaphores, and error tracking.

Workflow Execution

The execution flow involves loading redirect mappings from a configuration file, initializing a concurrent validator, and executing head/get requests against a base URL to verify the redirect chain.

The diagram above illustrates the high-level execution flow of the validation process, from loading configuration to final reporting.
Sources: cmd/validate-redirects/main.go:40-100

Validation Logic

For each redirect entry, the tool performs the following checks:

1. Redirect Status: Ensures the old URL returns a 3xx status code.
2. Location Header: Verifies that the Location header matches the expected new path.
3. Destination Reachability: Performs a follow-up request to the new URL to ensure it returns a successful (non-3xx/non-error) status code.

This sequence shows the interaction between the validation tool and the hosting server (e.g., S3) to verify a single redirect mapping.
Sources: cmd/validate-redirects/main.go:136-180

Configuration and Implementation Details

The tool uses several internal data structures and flags to control its behavior during a validation run.

CLI Options and Configuration

Option	Type	Default	Description
start	Integer	0	Starting index in the redirect list (inclusive).
end	Integer	-1	Ending index in the redirect list (exclusive).
BaseURL	String	(Required)	The root URL where documentation is hosted (Arg 0).
concurrency	Constant	20	Number of simultaneous validation requests.

Sources: cmd/validate-redirects/main.go:27-45

Key Data Structures

The validator utilizes a thread-safe structure to track failures across concurrent goroutines.

type validator struct {
	client  *retryablehttp.Client
	baseURL string
	sem     *semaphore.Weighted

	mu       sync.Mutex
	failures []string
}

Sources: cmd/validate-redirects/main.go:102-111

Error Handling and Retries

The tool is built using retryablehttp, which provides resilience against transient network issues. It is configured with a maximum of 10 retries per request to ensure that validation failures are genuine and not due to temporary flapping.
Sources: cmd/validate-redirects/main.go:114-125

Integration with Documentation Infrastructure

The Redirect Validation Tool is part of a larger documentation ecosystem that includes Antora for site generation and AWS S3 for hosting.

• S3 Integration: The tool specifically validates redirects created using the x-amz-website-redirect-location metadata on S3 objects.
• Deployment Pipeline: Validation is intended to run as part of or after the deploy-production job to ensure that site updates haven't broken existing redirect logic.
• Redirect Mappings: Uses mapping files like redirects_v2.yml as the source of truth for URI changes.

Sources: scripts/README-redirects.md:5-25, ARCHITECTURE.md:15-35, CONTRIBUTING.md:120-135

Conclusion

The Redirect Validation Tool provides a robust mechanism for maintaining link integrity in the CircleCI documentation project. By automating the verification of HTTP status codes and location headers through a concurrent Go-based architecture, it ensures that content migrations do not negatively impact the user experience or search engine indexing. Its integration with the broader S3-based hosting strategy allows for confident deployments and consistent link behavior across documentation versions.
Sources: cmd/validate-redirects/main.go:195-210, scripts/README-redirects.md:40-50