Check redirect chains free: how to inspect 301/302 redirects before launch

   warnings.push(`Cross-domain redirect blocked: ${currentHost} -> ${nextHost}`);
        break;
      }
    }
    
    currentUrl = nextUrl;
    continue;
  }

  // Final response reached
  break;
} catch (err) {
  errors.push(`Request failed for ${currentUrl}: ${(err as Error).message}`);
  break;
}

}

// Validation logic if (hops.length > opts.maxHops) { errors.push(Chain exceeded max hops limit (${opts.maxHops})); }

if (finalStatus !== 200 && finalStatus !== 304) { errors.push(Final status is ${finalStatus}, expected 200 or 304); }

// Check for 302 usage on permanent paths hops.forEach((hop, idx) => { if (hop.status === 302) { warnings.push(Hop ${idx + 1} uses 302 Found. Ensure this is temporary.); } if (hop.status === 301 && idx < hops.length - 1) { // 301 in the middle of a chain is often a misconfiguration warnings.push(Hop ${idx + 1} uses 301 Moved Permanently mid-chain. Consider consolidating.); } });

return { startUrl: targetUrl, hops, finalUrl: currentUrl, finalStatus, chainLength: hops.length, isValid: errors.length === 0, errors, warnings, }; }

#### Rationale

*   **`HEAD` Method:** Using `HEAD` reduces payload transfer during audits, focusing solely on headers and status codes. This speeds up bulk checks.
*   **Undici/Fetch:** Modern fetch implementations provide better control over redirects and timeouts compared to legacy `http` modules.
*   **Relative URL Resolution:** The `new URL(hop.location, currentUrl)` pattern ensures relative `Location` headers are handled correctly, a common source of audit failures.
*   **Warning System:** The code distinguishes between errors (broken chains, loops, non-200 finals) and warnings (302 usage, mid-chain 301s). This allows teams to prioritize fixes based on severity.
*   **Cross-Domain Control:** The `followCrossDomain` flag enables auditing of external redirects, which is crucial for tracking links and affiliate routing.

### Pitfall Guide

Production environments often harbor subtle redirect misconfigurations. The following pitfalls are frequently encountered during audits and migrations.

| Pitfall Name | Explanation | Fix Strategy |
| :--- | :--- | :--- |
| **Protocol-Host-Slug Fragmentation** | Rules are split across layers: one rule handles `http`→`https`, another handles `www`→`non-www`, and a third handles path changes. This creates a 3-hop chain. | Consolidate rules into a single canonicalization step. Ensure the first redirect resolves protocol, host, and path simultaneously where possible. |
| **302 Masquerading as 301** | Developers use `302 Found` for permanent moves due to browser caching behavior or CMS defaults. This prevents search engines from transferring link equity and causes repeated re-crawling. | Audit all redirects. Use `301 Moved Permanently` for permanent URL changes. Reserve `302` strictly for temporary campaigns or A/B tests. |
| **Infinite Loop Traps** | Misconfigured rules cause a URL to redirect to itself or a cycle (e.g., `A`→`B`→`A`). This results in browser errors and crawl failures. | Implement max-hop limits in resolvers. Review rule logic for circular dependencies. Use the cycle detection logic in the audit script. |
| **Proxy Injection Hops** | Reverse proxies (Nginx, Apache) or CDN edge rules inject redirects that are invisible to the application code. For example, a CDN might force HTTPS before the origin server processes the request. | Map the full infrastructure stack. Audit URLs against the edge endpoint, not just the origin. Check `X-Redirect-By` headers to identify the source of hops. |
| **Analytics Referral Bleed** | Redirects that cross domains or involve multiple hops can break the `Referer` header chain. Traffic may appear as "Direct" in analytics, obscuring campaign performance. | Keep redirects within the same domain where possible. Use `301` for permanent moves to preserve referrer data. Test analytics attribution alongside redirect audits. |
| **Parameter Pollution** | URLs with tracking parameters (UTM, click IDs) trigger redirects that strip parameters or route to different destinations, causing inconsistent behavior. | Normalize URLs by stripping tracking parameters before routing logic, or ensure the final destination handles parameters gracefully without additional hops. |
| **Staging vs. Production Divergence** | Redirect rules differ between staging and production environments. A chain that works in staging may break in prod due to different DNS or CDN configurations. | Mirror production redirect configurations in staging. Run the same audit scripts against both environments. Use infrastructure-as-code to ensure parity. |

### Production Bundle

#### Action Checklist

Use this checklist to validate redirect hygiene before deployment and during routine maintenance.

- [ ] **Define Canonical Policy:** Document the canonical domain, protocol, and trailing slash rules. Ensure all variants redirect to this canonical form.
- [ ] **Map Legacy URLs:** Create a comprehensive mapping of old URLs to new destinations. Verify that no legacy URL results in a chain longer than one hop.
- [ ] **Implement Max-Hop Guard:** Configure your web server or CDN to reject or flag requests that exceed a reasonable hop count (e.g., 5 hops).
- [ ] **Audit Status Codes:** Run the audit script to verify that permanent moves use `301` and temporary moves use `302`. Flag any `302` usage on permanent paths.
- [ ] **Check Cross-Domain Redirects:** Identify all cross-domain redirects. Ensure they are intentional and that analytics tracking is preserved.
- [ ] **Validate Final Status:** Confirm that the final URL in every chain returns `200 OK` or `304 Not Modified`. Flag any `404` or `500` responses.
- [ ] **Post-Deployment Smoke Test:** After deploying redirect changes, re-run the audit against a sample of critical URLs to verify the new rules are active and correct.

#### Decision Matrix

Select the appropriate redirect strategy based on the use case and constraints.

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Site Migration** | Bulk `301` Redirects | Transfers SEO equity permanently. Signals to crawlers that content has moved. | Low (Config change). High value for SEO retention. |
| **A/B Testing** | `302` Redirects or Cookie-based Routing | Temporary nature prevents caching of variant URLs. Preserves original URL indexing. | Medium (Requires testing infrastructure). |
| **Legacy Cleanup** | Consolidate Rules into Single Hop | Reduces latency and crawl waste. Simplifies maintenance. | Medium (Refactoring effort). Long-term performance gain. |
| **Tracking Links** | Edge Rewrite or Final Page Handling | Avoids redirect hops for marketing links. Preserves referrer data. | Low (Edge config). Improves analytics accuracy. |
| **HTTPS Enforcement** | HSTS + Edge Redirect | Forces secure connections efficiently. Reduces protocol hops. | Low. Improves security and performance. |

#### Configuration Template

Below are configuration examples for common platforms. These templates demonstrate consolidated redirect rules that minimize hops.

**Nginx Configuration:**
```nginx
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://www.example.com$request_uri;
}

server {
    listen 443 ssl;
    server_name example.com;
    # Consolidate protocol and host canonicalization
    return 301 https://www.example.com$request_uri;
}

server {
    listen 443 ssl;
    server_name www.example.com;

    # Consolidate path migration
    location /old-slug {
        return 301 /new-slug;
    }

    # Catch-all for legacy paths
    location ~ ^/legacy/(.*) {
        return 301 /modern/$1;
    }

    location / {
        proxy_pass http://backend;
    }
}

Vercel / Netlify (vercel.json / netlify.toml style):

{
  "redirects": [
    {
      "source": "/old-blog/:path*",
      "destination": "/articles/:path*",
      "status": 301,
      "force": true
    },
    {
      "source": "/campaign-temp",
      "destination": "/landing-v2",
      "status": 302,
      "conditions": {
        "cookie": "experiment=true"
      }
    },
    {
      "source": "/(.*)",
      "has": [
        {
          "type": "host",
          "value": "example.com"
        }
      ],
      "destination": "https://www.example.com/$1",
      "status": 301
    }
  ]
}

Quick Start Guide

Get your redirect audit pipeline running in under five minutes.

1. Initialize Project: Create a new TypeScript project and install dependencies.

   mkdir redirect-audit && cd redirect-audit
   npm init -y
   npm install undici typescript @types/node
   npx tsc --init
   

2. Add Auditor Code: Copy the auditRedirectChain function from the Core Solution into src/auditor.ts.
3. Create URL List: Create a urls.txt file with critical URLs to test.

   https://example.com
   https://example.com/old-page
   http://example.com/legacy
   

4. Run Audit Script: Create src/run.ts to read URLs and output results.

   import { readFileSync } from 'fs';
   import { auditRedirectChain } from './auditor';
   
   const urls = readFileSync('urls.txt', 'utf-8').split('\n').filter(Boolean);
   
   async function main() {
     for (const url of urls) {
       console.log(`\nAuditing: ${url}`);
       const report = await auditRedirectChain(url);
       console.log(`Chain Length: ${report.chainLength}`);
       console.log(`Final Status: ${report.finalStatus}`);
       console.log(`Valid: ${report.isValid}`);
       if (report.errors.length) console.error('Errors:', report.errors);
       if (report.warnings.length) console.warn('Warnings:', report.warnings);
     }
   }
   
   main();
   

5. Execute: Run the script and review the output.

   npx ts-node src/run.ts
   

   Analyze the report for chain lengths, status codes, and warnings. Fix any identified issues in your configuration and re-run to verify.