# Rules Overview

Rules are powerful tools that allow you to customize how smoxy handles traffic to your site. They let you change smoxy's behavior for specific URLs, conditions, or security scenarios without modifying your site's base configuration.

### What are Rules?

Think of rules as "if-then" statements for your CDN:

* **IF** a request matches certain criteria (a URL pattern, an IP address, a geographic location, etc.)
* **THEN** modify smoxy's behavior (change caching, route to different servers, block access, etc.)

Rules give you fine-grained control over how smoxy processes each request, allowing you to create sophisticated routing, caching, and security policies.

### The 4 Rule Types

smoxy offers three types of rules, each designed for specific use cases:

| Rule Type             | Best For                   | Matching Based On                            | Execution Behavior                     |
| --------------------- | -------------------------- | -------------------------------------------- | -------------------------------------- |
| **Access Rules**      | Security & access control  | Rich conditions (IP, country, headers, etc.) | Runs **first**, before everything else |
| **Rewrite Rules**     | URL rewriting & redirects  | URL patterns                                 | Runs **second**, nginx-style rewriting |
| **Conditional Rules** | Complex logic & conditions | Rich conditions (IP, country, headers, etc.) | **All matching rules apply**           |

#### Quick Comparison

**Access Rules** vs **Conditional Rules**:

* Both use rich condition matching (IP, country, headers, cookies, etc.)
* Access Rules are for **security** (block, challenge, whitelist) and run **first**
* Conditional Rules are for **configuration changes** (caching, routing, headers) and run **later**

**Rewrite Rules**:

* Specialized for URL rewriting (like nginx rewrite rules)
* Limited to 5 rules per site
* Runs **second** in the sequence (after Access Rules, before Conditional Rules)

### Execution Order

Rules are evaluated in a specific sequence for every request:

```
Incoming Request
    ↓
1. Access Rules (Security Layer)
   - Position 1, 2, 3... (in order)
   - Block, challenge, or whitelist traffic
   - All matching rules apply (unless "Stop" is enabled)
    ↓
2. Rewrite Rules (URL Rewriting)
   - Position 1, 2, 3... (in order)
   - Rewrites URL if matched
    ↓
3. Conditional Rules (Condition Matching)
   - Position 1, 2, 3... (in order)
   - All matching rules apply (unless "Stop" is enabled)
    ↓
Response
```

#### Within Each Rule Type

Rules within the same type are evaluated based on their **position** (also called priority or order):

* Position 1 is evaluated first
* Position 2 is evaluated second
* And so on...

You can reorder rules at any time using drag-and-drop in the smoxy hub.

### When to Use Which Rule Type

#### Use Access Rules When:

* ✅ You need to **block or challenge** suspicious traffic
* ✅ You want to **whitelist trusted IPs** (skip security checks)
* ✅ You need to **bypass WAF** for specific requests (e.g., internal tools)
* ✅ Security decisions need to happen **before any other processing**

**Example**: Block all requests from a specific country, except for your office IP.

#### Use Rewrite Rules When:

* ✅ You need to **rewrite URLs** (like nginx rewrite rules)
* ✅ You're doing **URL normalization or redirection**
* ✅ You need **legacy URL support** or **clean URL structures**
* ✅ URL transformations need to happen **before** other rules evaluate

**Example**: Rewrite `/old-path` to `/new-path`, or normalize URLs for better caching.

#### Use Conditional Rules When:

* ✅ You need **different settings for different URLs**
* ✅ You need **complex conditions** (IPs, countries, headers, cookies, etc.)
* ✅ You want **multiple rules to apply** to the same request
* ✅ You need **advanced logic** (AND/OR combinations)
* ✅ Different conditions require different configurations

**Example**: Serve higher quality images to users from Europe, enable basic auth for non-office IPs, and route mobile traffic differently.

**Example**: Disable caching for `/admin/*` URLs, or route `/api/*` to a different load balancer.

### Settings: Override Any smoxy Configuration

**Conditional Rules can override ANY setting from your site's configuration.**

This means any configuration you can set in your site (caching, image optimization, load balancing, security, headers, etc.) can be overridden by a rule for specific requests.

**Available settings include:**

* **Routing**: Choose different origins or load balancers
* **Caching**: Control cache TTL, cache keys, cache tags
* **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, SSI/ESI

### Best Practices

1. **Start with Access Rules for security**: Always define your whitelist (skip/continue) rules first, then add block/challenge rules
2. **Use Rewrite Rules early**: URL rewrites happen before Conditional Rules evaluate, so plan accordingly
3. **Use Conditional Rules for complex logic**: When you need multiple conditions or want multiple rules to apply
4. **Test with debug headers**: Enable debug headers to see which rules are being applied to your requests
5. **Order matters**: Review the position/order of your rules - especially important for Access and Conditional Rules