Request Routing Limitations

last updated: 2025-07-07

Overview

This document explains how our request routing system works and the limitations that may affect your deployments. Understanding these constraints helps you design your applications effectively.

How Request Routing Works

Our routing system uses an S3-based configuration management approach where ingress rules are stored as JSON files and automatically indexed for fast lookups. This provides reliable routing but introduces specific timing and configuration considerations.

Routing Limitations

Configuration Propagation

Timeline: Ingress configuration changes typically propagate within 30-60 seconds, but may take up to 2 minutes in rare cases.

Impact on Deployments:

  • Plan for this delay when making critical routing changes
  • Deploy your service before updating ingress rules
  • Allow sufficient time for configuration to take effect before testing

URI Path Constraints

Character Sanitization: URI paths are automatically sanitized for S3 compatibility:

  • Alphanumeric characters, hyphens, underscores, and dots are preserved
  • Special characters are converted to underscores
  • Maximum path length: 1024 characters

Examples:

  • /api/v1/users → _api_v1_users
  • /api/v1/users?filter=active → _api_v1_users_filter_active
  • /api/v1/users@domain → _api_v1_users_domain

Recommendation: Design your API paths to be S3-friendly from the start to avoid unexpected routing issues.

Service Discovery

Index-Based Lookup: Our system uses index files to map URIs to services, which provides:

  • Fast routing decisions (< 10ms)
  • Version tracking for rollbacks
  • Automatic cleanup of invalid configurations

Implications:

  • Service endpoints must be registered before they can receive traffic
  • Deleted services are automatically removed from routing within the propagation window
  • Configuration conflicts are resolved based on the most recent update

Deployment Considerations

1. Service Deployment Order

When deploying new services:

  1. Deploy your service first and verify it’s healthy
  2. Update ingress configuration after service deployment
  3. Wait for configuration propagation (30-60 seconds)
  4. Test the new routing

2. URI Design Best Practices

  • Use RESTful, predictable URI patterns
  • Avoid special characters in paths
  • Keep paths reasonably short (< 200 characters)
  • Use consistent naming conventions

3. Monitoring and Testing

  • Monitor your service health endpoints
  • Test routing changes in staging environments
  • Allow sufficient time for configuration propagation
  • Have a rollback plan ready

Troubleshooting Routing Issues

Service Not Receiving Traffic

  1. Check Service Health: Ensure your service is running and responding
  2. Verify Ingress Configuration: Confirm the ingress rule is properly configured
  3. Check URI Path: Ensure the path matches exactly (case-sensitive)
  4. Wait for Propagation: Allow up to 2 minutes for configuration changes

Configuration Update Failures

  1. Validate JSON Format: Verify your configuration is valid JSON
  2. Check Character Limits: Ensure paths don’t exceed 1024 characters
  3. Review Domain Limits: Confirm you haven’t exceeded 100 rules per domain

Performance Characteristics

  • Routing Decision: < 10ms
  • Configuration Update: 30-60 seconds
  • Failover: Automatic failover to healthy service instances