# Rules Execution & Ordering

Understanding how smoxy evaluates and executes rules is crucial for building effective traffic management and security policies. This page explains the execution flow, ordering system, and behavior patterns across all rule types.

### Execution Flow Between Rule Types

Requests are processed in a specific sequence:

1. **Access Rules**: Security layer, evaluated first, handle security decisions (block, challenge, skip, continue).
2. **Rewrite Rules**: URL rewriting, modifies the request URL before other rules are applied.
3. **Conditional Rules**: Condition-based settings, applied last.

**Importance of Order:**

* **Access Rules first**: Prioritize security actions.
* **Rewrite Rules second**: Transform URLs for consistent processing.
* **Conditional Rules last**: Implement complex logic conditions.

**Example:** A request to `/old-page` may be rewritten to `/new-page` via a Rewrite Rule. Then, Conditional Rules for `/new-page` are applied.

### Position Within Each Rule Type

#### How Position Works

Within each rule type, rules are evaluated based on their **position** (also called order):

* Position starts at **1** (not 0)
* Rules are evaluated in **ascending order** (1 → 2 → 3 → ...)
* When you create a new rule, it's automatically assigned the next available position
* Position is independent for each rule type (e.g., Access Rule #1 and Conditional Rule #1 are separate)

**Example:**

```
Access Rules: Position 1, 2, 3, 4, 5...
Rewrite Rules: Position 1, 2, 3...
Conditional Rules: Position 1, 2, 3, 4...
```

#### Position Determines Evaluation Order

The position number determines which rule is evaluated first within its type:

```
Position 1: Evaluated FIRST
Position 2: Evaluated SECOND
Position 3: Evaluated THIRD
...
Position N: Evaluated LAST
```

This is especially important for:

* **Access Rules**: Whitelist rules (skip, or continue actions) should have lower positions than block rules
* **Rewrite Rules**: More specific URL patterns should come before general patterns
* **Conditional Rules**: Rules you want to apply first should have lower positions

### Reordering Rules

You can change the execution order of your rules at any time using the drag-and-drop interface in the smoxy dashboard.

#### How Reordering Works

When you move a rule to a new position:

1. **Moving UP** (to a smaller position number):
   * All rules between the new and old position shift down (+1)
2. **Moving DOWN** (to a larger position number):
   * All rules between the old and new position shift up (-1)
3. **Moving to Bottom**:
   * Set a very high position number (e.g., 100)
   * The system automatically places it at the end

**Example:**

```
Before: [Rule-1, Rule-2, Rule-3, Rule-4, Rule-5]
Move Rule-5 to position 2
After:  [Rule-1, Rule-5, Rule-2, Rule-3, Rule-4]
```

#### Position Validation

The system ensures:

* No duplicate positions
* No gaps in position numbers
* Sequential ordering is maintained
* If conflicts are detected, all positions are automatically recalculated

### First Match vs All Matching

Different rule types have different execution patterns:

| Rule Type             | Execution Pattern  | Stops After Match? | Notes                                   |
| --------------------- | ------------------ | ------------------ | --------------------------------------- |
| **Access Rules**      | All matching apply | ⚠️ Optional        | `skip` action can skip subsequent rules |
| **Rewrite Rules**     | First match wins   | ✅ **Yes**          | Stops after first URL match             |
| **Conditional Rules** | All matching apply | ⚠️ Optional        | Continues unless `stop=true`            |

#### Access Rules - Position-Based with Skip

Access Rules evaluate in position order, but the `skip` action affects subsequent execution:

* **Block/Challenge actions**: Continue to next Access Rule
* **Skip action with flags**:
  * `access_rules=true`: Skip remaining Access Rules
  * `waf=true`: Bypass Web Application Firewall

**Best Practice:** Place skip rules (whitelist) at lower positions (1, 2, 3...) and block/challenge rules at higher positions.

**Exception:** If a rule has `stop=true`, no further Access Rules are evaluated.

#### Rewrite Rules - First Match Wins

Rewrite Rules stop after the **first matching URL pattern**:

```
Position 1: Match /old-path → Rewrite to /new-path → STOP
Position 2: Match /legacy/* → NOT EVALUATED
Position 3: Match /* → NOT EVALUATED
```

**Important:** Order matters! More specific patterns should come before general patterns.

#### Conditional Rules - All Matching Apply

Conditional Rules evaluate **all enabled rules** that match the conditions:

```
Position 1: Match (IP from office) → Settings Applied → Continue
Position 2: Match (Country = US) → Settings Applied → Continue
Position 3: Match (URI = /api/*) → Settings Applied → Continue
All three rules can apply to the same request!
```

**Exception:** If a rule has `stop=true`, no further Conditional Rules are evaluated.

### Stop Behavior (Conditional & Access Rules)

The **Stop** option is only available for Conditional & Access Rules.

#### How Stop Works

When enabled (`stop=true`):

* The rule's settings are applied
* **All subsequent Rules are skipped**
* Other rule types (Rewrite, Conditional) are not affected

When disabled (`stop=false`, default):

* The rule's settings are applied
* Evaluation continues to the next Rule

**Use Case Example:**

```
Position 1: IF (maintenance mode) THEN (show maintenance page) STOP
Position 2: IF (office IP) THEN (disable basic auth) [never evaluated during maintenance]
Position 3: IF (mobile) THEN (optimize images) [never evaluated during maintenance]
```

### Cache Hit vs Cache Miss Execution

Rules execute at different stages depending on whether content is served from cache or fetched from your origin:

#### Typical Execution Context

* **Access Rules**: Execute on **both cache hit and miss** (security always applies)
* **Rewrite Rules**: Execute **before cache lookup** (URL transformation happens first)
* **Conditional Rules**: Execute based on request conditions (independent of cache status)

#### Debug Headers

Enable **Debug Headers** in your site's configuration to see:

* Which rules were applied
* Cache hit/miss status
* Rule evaluation details

This helps you understand exactly how your rules are being executed for each request.

### Best Practices for Rule Ordering

#### 1. Access Rules - Whitelist First

```
Position 1-3: Skip rules (trusted IPs, internal tools)
Position 4+: Block/Challenge rules (suspicious traffic)
```

#### 2. Rewrite Rules - Specific Before General

```
Position 1: /exact-old-url → /new-url (most specific)
Position 2-3: Regex patterns
Position 4-5: Catch-all patterns (max 5 rules total)
```

#### 4. Conditional Rules - Critical First

```
Position 1: Maintenance mode (with stop=true)
Position 2-5: Business logic rules
Position 6+: Optimization rules
```

### Testing Your Rule Order

1. **Enable Debug Headers** in your site configuration
2. **Make test requests** to your site
3. **Check response headers** to see which rules were applied
4. **Adjust positions** based on the results
5. **Repeat** until you achieve the desired behavior