Conditional Rules

Conditional Rules let you customize smoxy's behavior based on rich conditions like IP addresses, geographic location, headers, cookies, and more. Unlike Page Rules which stop at first match, Conditional Rules allow multiple rules to apply to the same request, making them perfect for complex, layered configurations.

What are Conditional Rules?

Conditional Rules allow you to override any smoxy configuration setting based on powerful conditional logic. They're ideal for scenarios where you need multiple configuration changes to stack together or when URL patterns alone aren't sufficient.

Key characteristics:

  • Execute fourth (last) in the rule sequence (after Access, Rewrite, and Page Rules)

  • Rich condition matching - IP, country, headers, cookies, user agents, and more

  • Evaluated in position order (1, 2, 3...)

  • All matching rules apply - multiple rules can modify the same request

  • Optional Stop - set stop=true to halt further evaluation

  • Can override any smoxy setting from your site configuration

How Conditional Rules Work

Conditional Rules are evaluated in ascending position order (1 → 2 → 3...) for every incoming request. When a rule's conditions match, its settings are applied, and evaluation continues to the next rule (unless stop=true).

Position-Based Evaluation

Request from Germany, mobile device
    ↓
Conditional Rule (Position 1) → Match (Country = DE)? → Apply Settings → CONTINUE
    ↓
Conditional Rule (Position 2) → Match (Mobile)? → Apply Settings → CONTINUE
    ↓
Conditional Rule (Position 3) → Match (URI = /api)? → No match → Skip
    ↓
Response (with settings from Rule 1 AND Rule 2)

Important: Unlike Page and Access Rules, Conditional Rules do not automatically stop after the first match. All matching rules apply their settings unless a rule has stop=true.

Conditions & Expressions

Conditional Rules use a rich condition builder that lets you match requests based on various characteristics including:

  • URI: Request path

  • Host: Domain name

  • IP: Client IP address or IP ranges

  • Country: ISO 3166-2 country code

  • City: Client's city

  • Subdivisions: State/region

  • Is European: Boolean - true if request is from EU

  • Method: HTTP method (GET, POST, PUT, DELETE, etc.)

  • User Agent: Browser or client identifier

  • Referer: Referring page URL

  • Accept Language: Client's preferred language

  • Cookie: Specific cookie value

  • Arg: Query parameter value

  • HTTP: Any HTTP header value

  • Cache-Control: Cache-Control header directives

Operators

  • Equal: Value matches exactly

  • Not Equal: Value doesn't match

  • In: Value is in a list

  • Not In: Value is not in a list

  • Matches: Matches regex pattern

  • Contains: Contains substring

  • Not Contains: Doesn't contain substring

  • Exists: Field exists (regardless of value)

  • Not Exists: Field doesn't exist

AND/OR Logic

Combine multiple conditions with AND/OR operators to create sophisticated rules:

Stop Behavior

The Stop option is unique to Conditional Rules and controls whether evaluation continues after a rule matches.

How Stop Works

When stop=false (default):

  • Rule's settings are applied

  • Evaluation continues to the next Conditional Rule

  • Multiple rules can modify the same request

When stop=true:

  • Rule's settings are applied

  • All subsequent Conditional Rules are skipped

  • Other rule types (Access, Rewrite, Page) are not affected

When to Use Stop

Use stop=true when:

  • A rule should be final and no further modifications are needed

  • You want to prevent conflicting settings from other rules

  • You're implementing maintenance mode or similar override scenarios

Example:

When to Use Conditional Rules

Use Conditional Rules When:

  • ✅ You need complex conditions (IPs, countries, headers, cookies, etc.)

  • ✅ You want multiple rules to apply to the same request

  • ✅ You need advanced AND/OR logic with multiple conditions

  • ✅ URL patterns alone aren't sufficient

  • ✅ Different conditions require different configurations that should stack

Use Page Rules Instead When:

  • ❌ You only need simple URL-based matching

  • ❌ You want first match wins behavior

  • ❌ The logic can be expressed with URL patterns only

Settings: Override Any Configuration

Conditional Rules can override any setting from your site's configuration, just like Page Rules. This includes:

  • Routing: Choose different origins or load balancers

  • Caching: Control cache TTL, cache keys, cache tags, bypass cache

  • Image Optimization: AVIF, WebP, JPEG, PNG quality levels

  • Security: Enable/disable WAF, basic auth, custom error pages

  • Headers: Add, modify, or remove request/response headers

  • Optimization: HTML/JS/CSS minification

  • Advanced: Maintenance mode, debug headers, proxy timeouts

Simply select the settings you want to override when creating or editing a Conditional Rule. The available settings are grouped by category in the smoxy dashboard.

Use Cases & Examples

Example 1: Geographic Content Optimization

Scenario: Serve higher quality images to users in wealthy markets, standard quality elsewhere.

Why not Page Rules? Page Rules can't match on country - you need Conditional Rules for geographic targeting.

Example 2: Disable Basic Auth for Office IPs

Scenario: Your site uses basic authentication, but your team shouldn't need to login from the office.

Why not Access Rules? Access Rules are for blocking/challenging/whitelisting, not for toggling features like basic auth.

Example 3: Mobile-Optimized Images

Scenario: Mobile users should get more aggressive image optimization to save bandwidth.

Why multiple rules? Both rules can apply - Rule 1 sets baseline mobile optimization, Rule 2 adds extra optimization for specific markets.

Conditional Rules vs Page Rules

The key differences:

Feature
Page Rules
Conditional Rules

Matching

URL patterns only

Rich conditions (IP, country, headers, etc.)

Execution

First match wins, stops

All matching rules apply

Stop option

No

Yes (optional)

Position

3rd in sequence

4th (last) in sequence

Settings

Override any setting

Override any setting

Can you use both? Absolutely! They complement each other:

Execution order: Page Rule executes first (stops on match), then Conditional Rules evaluate (all matching apply).

Rule Order Best Practices

1. Critical Rules First

Place rules that should always take precedence at lower positions:

2. Use Stop Strategically

3. Layer Complementary Rules

Since all matching rules apply, you can build layered configurations:

4. Avoid Conflicting Settings

If multiple rules set the same configuration key, the last matching rule wins:

Using IP Lists

Instead of hardcoding IPs in each rule, create reusable IP Lists in your account settings:

  1. Create an IP List named "office_ips" with your office IP ranges

  2. Reference it in your Conditional Rule conditions

Benefit: Update the IP list once, and all rules using it are automatically updated across all your sites.

Uniqueness

Each site can only have one Conditional Rule per unique expression. If you try to create a duplicate, you'll see: "The rule for this expression already exists."

This prevents duplicate rules and keeps your configuration clean.

Common Mistakes

❌ Forgetting rules stack

✅ Be aware of interactions

❌ Using Stop too early

✅ Stop only when necessary

❌ Using Conditional Rules for simple URLs

✅ Use Page Rules for URL-only logic

❌ Conflicting settings from multiple rules

✅ Plan for overlapping conditions

Testing Conditional Rules

  1. Enable Debug Headers in your site configuration

  2. Make test requests with different conditions (IPs, user agents, etc.)

  3. Check response headers to see which Conditional Rules matched

  4. Verify settings are being applied in the expected order

  5. Test overlapping conditions to ensure the last-match-wins behavior is acceptable

Last updated

Was this helpful?