Bulk Redirect Phase¶

The bulk redirect phase enables efficient management of large-scale URL redirects through organized redirect lists. This phase processes after security checks but before origin requests, allowing for comprehensive redirect management without impacting performance.

Phase Overview¶

Phase Name: bulk_redirect
Processing Order: After firewall and rate limiting phases
Purpose: Manage large numbers of redirects through organized lists
Action Type: redirect

How Bulk Redirects Work¶

Request Processing Flow¶

Request Evaluation: Incoming requests are matched against redirect rules
List Reference: Rules reference redirect lists by name using from_list parameter
Entry Matching: System searches through enabled entries in the specified list
Redirect Execution: Matching entries trigger HTTP redirects with configured status codes
Query Preservation: Query strings can be optionally preserved in redirects

Redirect Lists¶

Redirect lists provide logical organization for related redirects:

{
  "name": "product_migrations",
  "description": "Legacy product page redirects",
  "entries_count": 150,
  "uuid": "12345678-1234-5678-9abc-123456789012"
}

Redirect Entries¶

Each entry defines a specific redirect mapping:

{
  "source_path": "/old-product",
  "target_url": "https://newsite.com/products/updated-product",
  "status_code": "301",
  "enabled": true,
  "source_scheme": "https",
  "source_domain": "legacy.example.com",
  "preserve_query_string": true
}

Rule Configuration¶

Basic Bulk Redirect Rule¶

# The expression is optional. If omitted, the action applies to all requests.
# http.request.uri.path in $migrated_products
#
# The action uses 'from_list' to specify the redirect list to use.
redirect:
  from_list: "product_migrations"

Advanced Conditional Redirects¶

Name: Legacy Domain Redirects
Expression: http.host eq "old.example.com" and 
           starts_with(http.request.uri.path, "/products/")
Action: redirect
Parameters: {
  "from_list": "legacy_products"
}

Domain-Specific Redirects¶

Name: Mobile App Deep Links
Expression: http.host eq "m.example.com" and
           http.user_agent contains "Mobile"
Action: redirect
Parameters: {
  "from_list": "mobile_redirects"
}

Redirect Entry Configuration¶

Path Matching¶

Exact Path Matching:

Source paths must match exactly (case-sensitive)
No wildcard or regex support in paths
Query strings not allowed in source paths

Example:

{
  "source_path": "/product/12345",
  "target_url": "https://newsite.com/items/12345"
}

Status Codes¶

Available Redirect Types:

301 (Permanent): "301" - SEO-friendly permanent redirects
302 (Found): "302" - Temporary redirects, preserve original URL ranking
307 (Temporary): "307" - Temporary, maintains HTTP method
308 (Permanent): "308" - Permanent, maintains HTTP method

SEO Best Practices:

{
  "status_code": "301",  // For permanent content moves
  "status_code": "302",  // For temporary campaigns or A/B tests
  "status_code": "307",  // For API endpoints requiring method preservation
  "status_code": "308"   // For permanent API endpoint changes
}

Advanced Configuration Options¶

Source Filtering:

{
  "source_path": "/checkout",
  "source_scheme": "http",        // Only redirect HTTP requests
  "source_domain": "old.site.com", // Only from specific domain
  "target_url": "https://secure.site.com/checkout",
  "preserve_query_string": true    // Keep ?param=value
}

Query String Handling:

{
  "source_path": "/search",
  "target_url": "https://newsite.com/find",
  "preserve_query_string": true,
  "status_code": "301"
}
// /search?q=test → https://newsite.com/find?q=test

Management Operations¶

Creating Redirect Lists¶

API Endpoint: POST /api/v1/domains/{domain}/services/rp/rules/bulk_redirects

curl -X POST "https://api.peakhour.io/domains/example.com/services/rp/rules/bulk_redirects" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "seo_redirects",
    "description": "SEO migration redirects for Q4 2024"
  }'

Adding Redirect Entries¶

Single Entry: POST /api/v1/domains/{domain}/services/rp/rules/bulk_redirects/{list_id}/entries

curl -X POST "https://api.peakhour.io/domains/example.com/services/rp/rules/bulk_redirects/12345/entries" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/old-page",
    "target_url": "https://newsite.com/new-page",
    "status_code": "301",
    "preserve_query_string": true
  }'

Bulk Entry Creation: PUT /api/v1/domains/{domain}/services/rp/rules/bulk_redirects/{list_id}/entries

curl -X PUT "https://api.peakhour.io/domains/example.com/services/rp/rules/bulk_redirects/12345/entries" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "source_path": "/product/1", 
        "target_url": "https://newsite.com/products/1",
        "status_code": "301"
      },
      {
        "source_path": "/product/2",
        "target_url": "https://newsite.com/products/2", 
        "status_code": "301"
      }
    ]
  }'

Managing Entries¶

Update Entry: PATCH /api/v1/domains/{domain}/services/rp/rules/bulk_redirects/{list_id}/entries/{entry_id}

curl -X PATCH "https://api.peakhour.io/domains/example.com/services/rp/rules/bulk_redirects/12345/entries/67890" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "target_url": "https://updated.com/new-target"
  }'

Delete Entry: DELETE /api/v1/domains/{domain}/services/rp/rules/bulk_redirects/{list_id}/entries/{entry_id}

Performance Optimization¶

Database Efficiency¶

Lazy Loading: Entries are loaded on-demand to minimize memory usage Computed Counts: Entry counts calculated via SQL for dashboard efficiency Bulk Operations: Multiple entries created in single database transaction

Configuration Generation¶

Enabled Filtering: Only enabled entries included in edge configuration List Organization: Logical grouping reduces configuration complexity Caching: Redirect lists cached at edge for fast lookup

Best Practices¶

List Organization:

seo_migrations/        # SEO-related redirects
├── product_pages/     # Product page moves  
├── category_updates/  # Category restructuring
└── legacy_urls/       # Old URL patterns

campaign_redirects/    # Marketing campaigns
├── summer_2024/       # Seasonal campaigns
├── partner_links/     # Partner redirections
└── social_media/      # Social media campaigns

Entry Limits:

Recommended: < 1,000 entries per list for optimal performance
Maximum: 10,000 entries per list (contact support for larger needs)
Total: No limit on number of lists per domain

Integration Examples¶

E-commerce Migration¶

Scenario: Migrating from old e-commerce platform to new system

// Rule: Product Page Redirects
Name: E-commerce Product Migration  
Expression: http.host eq "oldstore.com" and 
           starts_with(http.request.uri.path, "/products/")
Action: redirect
Parameters: {"from_list": "product_migration"}

// Rule: Category Redirects
Name: Category Structure Update
Expression: http.request.uri.path starts_with "/category/" and
           http.request.uri.path in $old_categories  
Action: redirect
Parameters: {"from_list": "category_restructure"}

Redirect List Entries:

[
  {
    "source_path": "/products/widget-1",
    "target_url": "https://newstore.com/shop/widget-1-pro",
    "status_code": "301",
    "preserve_query_string": true
  },
  {
    "source_path": "/category/electronics", 
    "target_url": "https://newstore.com/categories/tech",
    "status_code": "301"
  }
]

Marketing Campaigns¶

Scenario: Short-term campaign redirects with analytics

Name: Holiday Campaign Redirects
Expression: http.request.uri.path starts_with "/holiday2024/" or
           http.request.uri.path starts_with "/black-friday/"
Action: redirect  
Parameters: {"from_list": "holiday_campaigns"}

API Versioning¶

Scenario: API endpoint migration with method preservation

Name: API v1 to v2 Migration
Expression: starts_with(http.request.uri.path, "/api/v1/") and
           http.host eq "api.example.com"
Action: redirect
Parameters: {"from_list": "api_migration"}

API Redirect Entries:

[
  {
    "source_path": "/api/v1/users",
    "target_url": "https://api.example.com/api/v2/users",
    "status_code": "308",  // Preserves HTTP method
    "preserve_query_string": true
  }
]

Monitoring and Analytics¶

Redirect Tracking¶

Monitor redirect effectiveness through:

Analytics Dashboard: Track redirect hit rates and patterns
Log Analysis: Monitor 301/302 response codes in access logs
Performance Metrics: Measure redirect response times

Common Issues¶

High Redirect Chains:

Problem: /old → /temp → /new (multiple redirects)
Solution: Direct redirect /old → /new

Query String Loss:

Problem: /search?q=test → /find (loses parameter)
Solution: Enable preserve_query_string: true

Redirect Loops:

Problem: /page-a → /page-b → /page-a  
Solution: Validate redirect targets don't create cycles

Validation and Testing¶

Entry Validation¶

Automatic Validation:

Source paths must be valid URL paths
Target URLs must be complete URLs with scheme
Status codes must be valid redirect codes (301, 302, 307, 308)
No query strings allowed in source paths

Testing Redirects:

# Test redirect behavior
curl -I "https://example.com/old-page"
HTTP/1.1 301 Moved Permanently
Location: https://newsite.com/new-page

# Test with query preservation  
curl -I "https://example.com/search?q=test"
HTTP/1.1 301 Moved Permanently
Location: https://newsite.com/find?q=test

The bulk redirect phase provides enterprise-grade redirect management with efficient list organization, comprehensive configuration options, and robust performance optimization for large-scale URL migration and redirect scenarios.