Getting Started with Custom EdgeRules

EdgeRules provide users a great amount of flexibility to customize the behavior of the StackPath CDN. EdgeRules perform the specified action upon requests that match user-defined triggers. 

StackPath's custom rules engine provides additional control to alter StackPath's systems' behavior to

• Apply custom caching policies for assets
• Add response headers to influence browser behavior
• Hide response headers to improve security
• Add request headers to the origin for improved insights
• Apply custom redirects to change the target of specific content
• Add URL Signing to specific types of requests

Table of Contents

• Components of an EdgeRule
• If Statements
  • URL
  • Header
  • HTTP Method
  • Status Code
  • Cookie
• Matching Conditions
• Then Statements
  • Header Actions
  • Caching Actions
  • Redirect Actions
  • URL Signing
• Variables
  • General Expansion Variables
  • Request Receipt Expansion Variables

Components of an EdgeRule

EdgeRules have three main parts, the Filter, Matching condition, and Action. 

1. "If" statement filters that are used to determine what requests will trigger rules.
2. Matching conditions specify how the CDN will match the provided filter.
3. "Then" statements specify the desired action or change to behavior.

Custom fields are provided for each part of the rule to include dynamic variables or specific patterns.
This article covers some examples of potential patterns and how to use them to influence caching behavior.

IF Statement Filters

A filter specifies the required match for an EdgeRule to trigger. These will often scan against incoming requests to modify the response behavior. 

Available Filters:

URL

Using URL will cause a rule to be triggered when the request URL matches the applied filters. You can use wildcards, regex, or a simple direct match when checking for URL Conditions.

Target: All Requests / Condition: Matches / Pattern: * / Example Match: https://www.example.com/blog/01

Target: Only HTTP Requests / Condition: Matches / Pattern: HTTP://* / Example Match: http://www.example.com/index.html

Target: Only HTTPS Requests / Condition: Matches / Pattern: HTTPS://* / Example Match: https://www.example.com/index.html

Target: Exact URL Detection / Condition: Matches / Pattern: https://example.com/wp-admin/ / Example Match: https://example.com/wp-admin/

Target: http://example.com/pages/* (where * can be anything) / Condition: Regex Matches / Pattern: /(^http://example.com(/.*/)+.$)/ / Example Match: http://example.com/pages/blog/

Target: https://example.com/pages/*/article (where * can be anything) / Condition: Regex Matches / Pattern: /https://example.com/pages/[^\/]+/article/ / Example Match: https://example.com/pages/vacations/article/

Header

The rule will be triggered when the request headers from the end-user match the rule condition. wildcards, regex or a simple match are available when creating the Header condition.

HTTP Method

The rule will be triggered when the selected HTTP method will be used in the request. It is possible to select multiple methods for a given rule (for example, POST or DELETE). If more than one HTTP method is selected it is treated as an "Or", meaning any of the included methods will trigger the rule.

Target: Any User-Agent / Condition: Matches / Pattern: User-Agent: * / Example Match: All User Agents

Target: Specific User-Agents (example: mobile) / Condition: Regex Matches / Pattern: /User-Agent: *(iPhone|Android).*/ / Example Match: iPhone and Android User Agents

Status Code

Create a rule based on the website origin response status code. Multiple values can be included within a single rule, and wildcards can be used to specify a broader selection.

Target: Status Code 404 / Conditions: Matches / Pattern: 404 / Example Match: Only requests that return a 404

Target: Status Code 301 and 302 / Condition: Matches / Pattern: 301,302 / Example Match: Requests that are 301 or 302

Target: Any Status Code in the 500 range / Condition: Matches / Pattern: 5* / Example Match: Any request that returns a 5xx

Cookie

Create a rule based on the cookie(s) included with the request, the cookie value is optional. Regex and simple match is available.

Target: Match if any cookie exists / Condition: Matches / Pattern: * / Example Match: cookie: foo=bar

Target: Match any cookies with a name starting with "wp" / Condition: Matches / Pattern: wp* / Example Match: Cookie: wp-value=1; id=123

Target: Match when there is no cookie with a name starting with "wp" / Condition: Matches / Pattern: !wp* / Example Match: Cookie: fake-wp-value=1; id=123 , or no cookie at all

Target: Match if the cookie name is wp and value is 1 / Condition: Matches / Pattern: wp=1 / Example Match: Cookie: wp=1

Target: Match any cookies with a name starting with "wp" and with a value of 1 / Condition: Matches / Pattern: wp*=1 / Example Match: Cookie: wp-value=1; id=123

More examples for cookie matching can be found here: https://support.stackpath.com/hc/en-us/articles/360035190332-EdgeRules-Bypass-Cache-Using-a-Cookie-

 

Matching Conditions

• Matches - This is the equivalent to Equals; the rule triggers on the exact pattern provided. Wildcards can provide a broader spectrum of matching patterns, and commas can be included to match multiple patterns.
• Matches Regular Expression - The rule's trigger is based on a pattern defined using regular expression. Regex provides much more versatility in that patterns can be more specific and intricate, using text strings that describe patterns to define text or positions within a body of text. 
  StackPath uses ? this tool can help: https://regex-golang.appspot.com/assets/html/index.html
  
  

THEN Statement Actions

Actions define the behavioral adjustment applied to matched requests. These will change depending on the Scope/Filter selected, and can modify aspects of a request/response or even the caching behavior of the CDN.

Available Actions:

Header Actions

• Add Response Header
  • The header will be added to the response (CDN to End User)
  • Key-Value, for example:
    Key: X-XSS-Protection: Value: 1; mode:block
• Add Header to CDN
  • This will add a header as a request to the CDN (User to CDN)
  • Possible input value: Key-Value, for example:
    Key: X-Mobile Value: Ture
• Add Header to Origin
  • Add Header from CDN to your origin server
  • Possible input value: Key-Value, for example:
    Key: X-Mobile: Value: True
• Modify Header
  • Modify the value of an existing header
  • Possible input value: Regex, for example:
    regex:(?i)x-amz*.*
• Remove Header
  • Remove an existing response header
  • Possible input value: Name = value, for example:
    User-Agent: new agent

Caching Actions

• Cache
• Configure the Caching TTL for a selected Filter
• Do Not Cache
• Bypass cache for the configured filter
• Never Expire
• The resource (matched condition) will be cached indefinitely

Redirect Actions

Force a 301 redirect when the conditions are met.
Possible input value: Full HTTP address (e.g. https://www.example.com)

URL Signing

URL Signing allows you to protect your CDN assets by ensuring only authorized end users are able to access them and to set an expiration time on a given URL.

Variables

Variables allow for dynamic rules to be made without needing new rules for every possible permutation of a request or response. Use Variables for advanced fine-tuning of the delivery of your content over the StackPath CDN Network.

Available Variables:

General Expansion Variables:

%server.ip% | The Server IP  

%server.fqdn% | The Server Host Name

 %server.name% | The Server Name

%server.pop% | The Server Pop

%server.region% | The Server Region

%server.platform% | The Server Platform Name

%server.epoch% | The Server Time

%client.ip% | The Client IP

%client.request.protocol% | The protocol of the request (http/https)

%client.request.host% | hostname in the Host header of the request

%client.request.fullurl% | Full URL of request (including protocol and host name)

%client.request.fullfilepath% | Full File Path from request (without qs param)

%client.request.params% | Query Parameters from request (with leading ?)

%client.request.pathonly% | Only Path (without filename) from request

%client.request.filename% | Only filename from request

%client.geoip.areaCode% | The telephone area code

%client.geoip.city% | The city or town name

%client.geoip.continentCode% | The two-character code for the continent

%client.geoip.countryCode% | The two-character ISO-3166-1 country code

%client.geoip.countryCode3% | The three-character country code

%client.geoip.countryName% | The country name

%client.geoip.dmaCode% | Designated Market Area code

%client.geoip.latitude% | The latitude

%client.geoip.longitude% | The longitude

%client.geoip.postalCode% | The postal code

%client.geoip.regionCode% | A two character ISO-3166-2 or FIPS 1-=4 code for state/region

%client.geoip.regionName% | The region name

%client.geoip.timeZone% | The time zone is generated from IANA time zone database (e.g., America/New_York)

%query.separator% | The query separator character

%function.random(min, max)% | Random Number Generator