Cache Rules

速盾网络 Team

Cache rules define how Sudun caches and serves content from edge servers. Properly configured cache rules improve performance, reduce origin load, and enhance user experience.

How Caching Works

code

Request → Edge Server → Cache Check
                            │
                    ┌───────┴───────┐
                    │               │
               Cache HIT       Cache MISS
                    │               │
              Return cached    Fetch from origin
               content         Cache response
                               Return to user

Default Caching Behavior

By default, Sudun caches content based on:

Content Type	Default TTL	Cacheable
Images (jpg, png, gif, webp)	1 day	Yes
CSS, JavaScript	1 day	Yes
Fonts (woff, woff2, ttf)	1 day	Yes
HTML	Not cached	No
API responses	Not cached	No

Creating Cache Rules

Go to Domains → Select your domain
Navigate to Caching → Cache Rules
Click Create Rule

Rule Components

Component	Description	Example
Match Criteria	Conditions to match requests	URL path, file extension
Cache Action	How to handle matched requests	Cache, Bypass, Override
TTL	Time to live in cache	3600 (1 hour)

Match Criteria

URL Path Matching

code

# Exact match
/images/logo.png

# Prefix match
/static/*

# Wildcard match
/api/*/public

# Regex match (advanced)
^/blog/[0-9]{4}/.*$

File Extension Matching

Cache by file type:

json

{
  "match": {
    "file_extension": ["jpg", "jpeg", "png", "gif", "webp", "css", "js"]
  },
  "action": "cache",
  "ttl": 86400
}

Query String Matching

json

{
  "match": {
    "path": "/search",
    "query_string": {
      "contains": "category"
    }
  }
}

Header Matching

json

{
  "match": {
    "headers": {
      "Accept": "application/json"
    }
  },
  "action": "bypass"
}

Cache Actions

Cache

Store content at edge servers:

json

{
  "match": { "path": "/static/*" },
  "action": "cache",
  "ttl": 604800,
  "settings": {
    "browser_ttl": 86400,
    "serve_stale": true
  }
}

Bypass Cache

Always fetch from origin:

json

{
  "match": { "path": "/api/*" },
  "action": "bypass"
}

Override Origin Headers

Ignore origin cache headers:

json

{
  "match": { "path": "/assets/*" },
  "action": "override",
  "ttl": 2592000,
  "ignore_origin_headers": true
}

TTL Configuration

Edge TTL

How long content stays cached at edge servers:

Value	Duration	Use Case
60	1 minute	Frequently updated content
3600	1 hour	Semi-dynamic content
86400	1 day	Static assets
604800	1 week	Rarely changing content
2592000	30 days	Versioned assets

Browser TTL

How long browsers cache content locally:

json

{
  "edge_ttl": 86400,
  "browser_ttl": 3600
}

Tip: Set browser TTL shorter than edge TTL to maintain control over cache invalidation.

Cache Key Configuration

The cache key determines what makes a cached object unique.

Default Cache Key

code

https://example.com/page?sort=date&page=1
         │            │        │
      Scheme       Path    Query String

Query String Handling

Option	Behavior
Include All	Cache varies by all query params
Exclude All	Ignore query string for caching
Include Specific	Only specified params affect cache
Exclude Specific	Ignore specified params

Example: Include specific parameters

json

{
  "cache_key": {
    "query_string": {
      "include": ["category", "page"]
    }
  }
}

Header-Based Cache Key

Vary cache by request headers:

json

{
  "cache_key": {
    "headers": ["Accept-Language", "Accept-Encoding"]
  }
}

Vary cache by cookies (use sparingly):

json

{
  "cache_key": {
    "cookies": ["session_type", "user_tier"]
  }
}

Stale Content Handling

Serve Stale While Revalidate

Serve cached content while fetching fresh content:

json

{
  "serve_stale": {
    "while_revalidate": true,
    "on_error": true,
    "max_stale_age": 86400
  }
}

Stale-If-Error

Serve stale content when origin fails:

code

Origin Error (5xx) → Serve stale content → Log error

Respecting Origin Headers

By default, Sudun respects these origin headers:

Header	Behavior
Cache-Control: max-age=X	Cache for X seconds
Cache-Control: no-cache	Revalidate before serving
Cache-Control: no-store	Do not cache
Cache-Control: private	Do not cache at edge
Expires	Cache until specified date
ETag	Enable conditional requests

Override Origin Headers

Force caching regardless of origin headers:

json

{
  "match": { "path": "/static/*" },
  "action": "cache",
  "ttl": 86400,
  "respect_origin_headers": false
}

Rule Priority

Rules are evaluated in order. First matching rule wins:

code

Rule 1: /api/* → Bypass (Priority: 1)
Rule 2: /api/public/* → Cache (Priority: 2)
Rule 3: /* → Cache (Priority: 3)

Request: /api/users → Matches Rule 1 → Bypass
Request: /api/public/data → Matches Rule 1 → Bypass (not Rule 2!)

Important: Place more specific rules before general rules.

Common Cache Rule Patterns

Static Assets

json

{
  "name": "Static Assets",
  "match": {
    "file_extension": ["css", "js", "jpg", "png", "gif", "ico", "woff2"]
  },
  "action": "cache",
  "ttl": 2592000,
  "browser_ttl": 86400
}

API Responses

json

{
  "name": "API Bypass",
  "match": { "path": "/api/*" },
  "action": "bypass"
}

HTML Pages with Short TTL

json

{
  "name": "HTML Pages",
  "match": {
    "file_extension": ["html"],
    "path": "/*"
  },
  "action": "cache",
  "ttl": 300,
  "serve_stale": true
}

Versioned Assets (Long TTL)

json

{
  "name": "Versioned Assets",
  "match": {
    "path": "/assets/v*/*"
  },
  "action": "cache",
  "ttl": 31536000,
  "immutable": true
}

Debugging Cache Rules

Cache Status Header

Check the X-Cache-Status response header:

Status	Meaning
HIT	Served from cache
MISS	Fetched from origin
BYPASS	Cache was bypassed
EXPIRED	Cache expired, revalidating
STALE	Served stale content

Test Cache Rules

bash

# Check cache status
curl -I https://example.com/static/style.css

# Response headers
X-Cache-Status: HIT
Cache-Control: max-age=86400
Age: 3600

API Reference

Manage cache rules via API:

bash

# List cache rules
curl -X GET https://api.Sudun.com/v1/domains/example.com/cache-rules \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create cache rule
curl -X POST https://api.yeSudunom/v1/domains/example.com/cache-rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Static Assets",
    "match": {"file_extension": ["css", "js", "png"]},
    "action": "cache",
    "ttl": 86400
  }'

Need help with cache rules? Contact support@Sudun.com

Cache Rules

How Caching Works

Default Caching Behavior

Creating Cache Rules

Rule Components

Match Criteria

URL Path Matching

File Extension Matching

Query String Matching

Header Matching

Cache Actions

Cache

Bypass Cache

Override Origin Headers

TTL Configuration

Edge TTL

Browser TTL

Cache Key Configuration

Default Cache Key

Query String Handling

Header-Based Cache Key

Cookie-Based Cache Key

Stale Content Handling

Serve Stale While Revalidate

Stale-If-Error

Respecting Origin Headers

Override Origin Headers

Rule Priority

Common Cache Rule Patterns

Static Assets

API Responses

HTML Pages with Short TTL

Versioned Assets (Long TTL)

Debugging Cache Rules

Cache Status Header

Test Cache Rules

API Reference

Tags

How Caching Works

Default Caching Behavior

Creating Cache Rules

Rule Components

Match Criteria

URL Path Matching

File Extension Matching

Query String Matching

Header Matching

Cache Actions

Cache

Bypass Cache

Override Origin Headers

TTL Configuration

Edge TTL

Browser TTL

Cache Key Configuration

Default Cache Key

Query String Handling

Header-Based Cache Key

Cookie-Based Cache Key

Stale Content Handling

Serve Stale While Revalidate

Stale-If-Error

Respecting Origin Headers

Override Origin Headers

Rule Priority

Common Cache Rule Patterns

Static Assets

API Responses

HTML Pages with Short TTL

Versioned Assets (Long TTL)

Debugging Cache Rules

Cache Status Header

Test Cache Rules

API Reference