Domain Rules 101 | SaaS Custom Domains Help Center

What are Domain Rules?

Domain rules are powerful configurations that allow you to customize how traffic is handled on your custom domains. Think of rules as "if-then" statements for your domain: "If a request matches certain conditions, then perform specific actions." Rules give you fine-grained control over request handling without modifying your upstream application.

How Rules Work

Each rule consists of two main components:

Matchers (the "if" part) - Conditions that determine when a rule should be applied
Handlers (the "then" part) - Actions that specify what happens when the conditions are met

Rules are evaluated in order based on their position, with lower-numbered positions being evaluated first. When a request comes in, SaaS Custom Domains checks each rule in sequence until it finds a match. Once a matching rule is found, its handlers are executed. We continue this process so multiple Rules can be matched and executed for the same request.

Note: Multiple matching rules will be executed in order unless one rule returns a direct response (like with the static_response handler).

Rule Components

Matchers

Matchers define the conditions that must be met for a rule to apply. You can create rules based on:

Path - Match requests based on the URL path (e.g., /blog/*)
Method - Match requests based on the HTTP method (e.g., GET, POST, PUT)
Header - Match requests based on HTTP headers (e.g. Content-Type: text/html)
Query - Match requests based on query parameters (e.g. utm_source=facebook)

Each matcher supports various comparison operators such as "is", "starts_with", "contains", etc. Multiple matchers in a rule are combined with AND logic, meaning all conditions must be satisfied for the rule to match.

Here's an example to illustrate how matchers with different operators work together:

For a rule that matches blog article pages for premium users you'd add two matchers:

Path matcher: starts_with /blog/
Header matcher: is Premium-User: true

This rule will only trigger when BOTH conditions are met: the URL path starts with "/blog/" AND the request has a header "Premium-User" with value "true".

Handlers

Handlers define the actions to take when a rule matches. Available handlers include:

Static Response - Return a custom response without forwarding to your upstream
Rewrite - Modify the request URL before forwarding to your upstream
Replace Response - Modify the content in the response body
Set Response Header - Add or modify headers in the HTTP response
Delete Response Header - Remove specific headers from the HTTP response

You can configure multiple handlers for a single rule, and they will be executed in the order they are defined.

Note: If a Static Response handler is used, it immediately returns a response to the client, and any handlers defined after it in the same rule will not be executed.

Creating Your First Rule

To create a rule:

Navigate to your custom domain dashboard
Click on the "Rules" tab
Click "Create Rule"

The new rule will be added to the bottom of your rules list by default.

4. Give your rule a descriptive name

5. Add matchers to define when the rule should apply

6. Add handlers to specify what actions to take

7. Save your rule

You can reorder rules by dragging them to change their evaluation priority. For example, if you want the Forwarding rule to execute before blocking requests with empty User-Agent header, you would click and drag it to the first place.

Common Use Cases

Domain rules can solve many common challenges:

Redirecting old URLs to new ones
Implementing custom error pages
Adding security headers to all responses
Serving static content for specific paths
Creating A/B tests without modifying your application
Implementing path-based routing to different applications

💡 This is just the beginning!

As we continue to expand our platform, we'll be adding more matcher types and handler options to enable even more sophisticated routing patterns, security configurations, and content transformations. Stay tuned for updates as we regularly enhance our rules engine with new capabilities to solve your domain management challenges.

Rule Evaluation Order

Remember that rule order matters, but different from what you might expect! All matching rules will be executed in order (lowest position number first) unless a rule contains a handler that returns a response directly (like the Static Response handler).

Consider this sequence:

A rule that matches all /api/* requests and adds authentication headers
A rule that matches all /api/public/* requests and removes authentication headers

In this order, a request to /api/public/status would first have authentication headers added by rule #1, but then rule #2 would also match and remove those headers. The final result would be a request without authentication headers.

To ensure proper authentication, you might want to use the Static Response handler in your rules to prevent further rule processing when needed, or carefully design your rules to account for the cumulative effect of multiple matching rules.

Rule Status

Each rule can be active or inactive. Inactive rules remain in your configuration but are not evaluated during request processing. This allows you to temporarily disable rules without deleting them.

Best Practices

Give rules descriptive names that indicate their purpose
Keep the number of rules manageable for easier troubleshooting
Consider cumulative effects since multiple matching rules will execute together
If you need to prevent further rule execution, use the Static Response handler
Test your rules thoroughly after implementation to ensure they work as expected
Remember that rule position determines execution order, which affects how rules interact with each other
Document your rule configurations for easier maintenance and troubleshooting

Next Steps

Now that you understand the basics of domain rules, you might want to explore:

Specific matcher types and their capabilities
Handler configurations for different scenarios
Advanced use cases and patterns

That's it! Now you know everything about Rules.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!