Page Rule Actions

Limit Request Rate

Parameter Description

Parameter NameData TypeRequiredDescription
limit_keystringYesKey for rate limiting, used to distinguish between different types of requests. See limit_key options for more information
key_argstringNoUsed in conjunction with limit_key, some limit_key require an additional parameter
rate_shapenumberYesRequest rate at which traffic shaping begins
rate_shape_unitstringYesUnit of traffic control, options: r/s (requests per second) and r/min (requests per minute)
rate_rejectnumberYesRequest rate at which reject_action is executed to handle excessive requests
rate_reject_unitstringYesUnit for handling excessive requests, options: r/s (requests per second) and r/min (requests per minute)
reject_actionstringYesAction executed when rate limit is exceeded, see reject_action options for more details
error_page_status_codestringNoWhen reject_action is error_page, this response status code must be set
edge_captcha_clearance_timestringYesWhen reject_action is enable_edge_captcha, this field must be set
hcaptcha_clearance_timestringYesWhen reject_action is enable_hcaptcha, this field must be set
redirect_validate_clearance_timestringYesWhen reject_action is redirect_validate, this field must be set

limit_key options:

  • client-addr: Client address
  • uri: Requested URI
  • uri-arg: Request parameters
  • req-cookie: Cookies in the request
  • req-header: Request header
  • first-x-forwarded-addr: The first address in the X-Forwarded-For header
  • last-x-forwarded-addr: The last address in the X-Forwarded-For header

uri-arg, req-cookie, and req-header should be used in conjunction with key_arg to specify specific parameters and cookie or request header names.

reject_action options:

  • enable_hcaptcha: Enable hCaptcha verification
  • enable_edge_captcha: Enable Edge Captcha verification
  • error_page: Return the error page corresponding to the specified error_page_status_code
  • close_connection: Close the TCP connection directly
  • redirect_validate: Perform redirect validation
  • js_challenge: Execute a JS challenge

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    limit-req-rate:
      limit_key: uri
      rate_shape: 10
      rate_shape_unit: r/s
      rate_reject: 20
      rate_reject_unit: r/s
      reject_action: error_page
      error_page_status_code: 429

The example demonstrates that request rate is limited based on the URI. When the request rate reaches 10 r/s, traffic shaping begins, meaning requests may be delayed; when the rate reaches 20 r/s, the excessive requests are rejected and an error page with the status code 429 is returned.

Circuit Breaker

Parameter Description

Parameter NameData TypeRequiredDescription
strategystringYesThe strategy adopted by the circuit breaker, options include slow-ratio, failure-ratio, and failure-count
window_timestringYesThe sliding window duration for calculating the percentage of errors or slow responses in seconds
open_timenumberYesThe duration the circuit breaker remains open after tripping, during which all requests perform open_action in seconds
hopen_timestringYesThe semi-open state duration, during which the circuit breaker attempts to recover by testing a limited number of requests in seconds
failure_timenumberNoThe time threshold considered for slow requests, in milliseconds
failure_statusstringNoThe list of status codes considered for failed requests, the optional status codes are: 401、403、404、414、502、503、503
failure_percentstringNoThe percentage threshold of failed or slow requests that trigger the tripping of the circuit breaker
failure_countstringNoThe count threshold of failed requests that triggers the tripping of the circuit breaker
min_reqs_in_windowstringYesThe minimum number of requests reached within the sliding window period, used to calculate and trigger tripping
open_actionstringYesThe action performed when the circuit breaker is open; currently supported actions include exit (return default response) and redirect (redirect to an alternate service), etc.
resp_statusstringNoWhen open_action is exit, the HTTP status code returned after the circuit breaker opens
resp_bodystringNoWhen open_action is exit, the content of the response body returned after the circuit breaker opens
redirect_urlstringNoWhen open_action is redirect, the URL the circuit breaker redirects to after opening

Circuit breaker strategy options:

  • slow-ratio: Slow request ratio, when the ratio of slow requests to normal requests reaches the threshold, the circuit breaker trips.
  • failure-ratio: Failure request ratio, when the ratio of failed requests to normal requests reaches the threshold, the circuit breaker trips.
  • failure-count: Failure request count, when the volume of failed requests reaches the threshold, the circuit breaker trips.

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    enable-circuit-breaker:
      strategy: failure-count
      window_time: 10
      open_time: 15
      hopen_time: 30
      open_action: exit
      failure_time: 3000
      failure_status:
      - 500
      - 502
      - 503
      failure_count: 3
      min_reqs_in_window: 5
      resp_status: 500

This example uses a “failure request count” strategy circuit breaker. The circuit breaker is enabled when the URI is /hello. If there are more than 5 requests in a 10-second window and 3 failures with status codes 500, 502, or 503, the circuit breaker will trip for 15 seconds. All requests will execute the exit action during the trip and return a 500 status code. After 15 seconds of being tripped, it enters a semi-open state for 30 seconds, during which, if the first request is successful, it will return to an open state; otherwise, it will re-enter the tripped state.

Block Request

Parameter Description

Parameter NameData TypeRequiredDescription
limit_keystringYesKey for rate limiting, used to distinguish between different types of requests. See limit_key options for more information
key_argstringNoUsed in conjunction with limit_key, some limit_key require an additional parameter
rate_shapenumberYesRequest rate at which traffic shaping begins
rate_shape_unitstringYesUnit of traffic control, options: r/s (requests per second) and r/min (requests per minute)
rate_rejectnumberYesRequest rate at which the requests are responded with a 503
rate_reject_unitstringYesUnit for handling excessive requests, options: r/s (requests per second) and r/min (requests per minute)
block_thresholdnumberYesThe threshold count of requests for blocking
observe_intervalnumberNoObservation period, in seconds
block_timenumberNoDuration of the block, in seconds

Within the observe_interval observation period, if the number of limited requests reaches the block_threshold, then requests identified by limit_key will be blocked for a continuous block_time seconds, directly responding with a 503. More block actions will be supported in the future.

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    block-req:
      limit_key: uri
      rate_shape: 10
      rate_shape_unit: r/s
      rate_reject: 20
      rate_reject_unit: r/s
      block_threshold: 10
      observe_interval: 60
      block_time: 3600

In this example, requests are categorized based on the URI. When the request rate reaches 10 r/s, traffic shaping begins; when the rate hits 20 r/s, the excessive requests are rejected. If the rejected requests exceed the block threshold of 10 within a 60-second observation period, subsequent requests of this type will be directly responded to with a 503 status code and blocked for 3600 seconds.

OAuth JWT Validation

Parameter Description

Parameter NameData TypeRequiredDescription
discoverystringNoDiscover configuration information through a URL, used as one of three options along with public_key and symmetric_key
public_keystringNoPublic key for asymmetric encryption, used as one of three options along with discovery and symmetric_key
symmetric_keynumberNoPrivate key for symmetric encryption, used as one of three options along with discovery and public_key
token_signing_algarrayYesThe types of algorithms used for token verification, supports HS256, HS512, RS256, ES256, ES512, RS512, none, etc., multiple choices allowed
accept_unsupported_algboolYesWhether to accept unsupported algorithms

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    oauth2-jwt-validate:
      discovery: https://accounts.openresty.com/.well-known/introspect-configuration
      token_signing_alg:
      - HS256
      - HS512
      - RS256
      - ES256
      - ES512
      - RS512
      - none
      accept_unsupported_alg: false

In this example, OAuth2 JWT validation is enabled when the request URI is /hello. The key is discovered through a URL, all supported token signing algorithms are selected, and unsupported algorithms are rejected.

Enable Basic Authentication

Parameter Description

Parameter NameData TypeRequiredDescription
group_namestringYesThe name of the group to which the Basic authentication user belongs

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    enable-basic-authentication:
      group_name: hello

In this example, Basic authentication is enabled when the request URI is /hello, and only members of the hello user group can access the corresponding resources.

Enable WebSocket

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    enable-websocket: {}

Set URI

Parameter Description

Parameter NameData TypeRequiredDescription
uristringYesThe new URI to be set

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    set-uri:
      uri: /world

In the example, when the request URI is /hello, the URI will be changed to /world.

Add URI Prefix

Parameter Description

Parameter NameData TypeRequiredDescription
valuestringYesThe URI prefix to be added

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /world

  actions:
    add-uri-prefix:
      value: /hello

In the example, when the request URI is /world, the URI will be modified to /hello/world.

Remove URI Prefix

Parameter Description

Parameter NameData TypeRequiredDescription
valuestringYesThe URI prefix to be removed

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    rm-uri-prefix:
      value: /hello

In the example, when the request URI is /hello/world, the /hello prefix will be removed from the URI, resulting in /world.

Set Request Header

Parameter Description

Parameter NameData TypeRequiredDescription
headerstringYesThe name of the request header to be set
valuestringYesThe value of the request header to be set

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-req-header:
      header: Host
      value: openresty.com

In the example, when the request URI is /hello/world, the Host request header will be modified to openresty.com. It will be added if the Host header does not exist.

Add Request Header

Parameter Description

Parameter NameData TypeRequiredDescription
headerstringYesThe name of the request header to be added
valuestringYesThe value of the request header to be added

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    add-req-header:
      header: Foo
      value: Bar

In the example, when the request URI is /hello/world, the Foo: Bar request header will be added regardless of whether it already exists.

Remove Request Header

Parameter Description

Parameter NameData TypeRequiredDescription
namestringYesThe name of the request header to remove

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    rm-req-header:
      name: Foo

In this example, when the request’s URI is /hello/world, the system will remove the Foo request header. If the request is proxied to the upstream server, the upstream server will not receive this header.

Set Proxy URI

Parameter Description

Parameter NameData TypeRequiredDescription
uristringYesThe proxy URI to set

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello

  actions:
    set-proxy-uri:
      uri: /hello/world

This example demonstrates that when the request’s URI is /hello, the URI will be changed to /hello/world in the proxy request, while the URI in the original request remains unchanged.

Set Proxy Header

Parameter Description

Parameter NameData TypeRequiredDescription
headerstringYesThe name of the proxy request header to set
valuestringNoThe value of the proxy request header to set, alternatively choose el_var
el_varstringNoUse an Edge variable as the request header value, alternatively choose value
el_var_argstringNoIf needed, use together with el_var

The request header’s value can be set directly as a fixed value with value, or dynamically with el_var and el_var_arg. The examples below will provide both scenarios.

el_var supports variables including:

  • client-addr: Client address
  • client-port: Client port
  • host: The hostname of the request
  • scheme: The protocol of the HTTP request, can be http or https
  • first-x-forwarded-addr: The first address in the X-Forwarded-For request header
  • last-x-forwarded-addr: The last address in the X-Forwarded-For request header
  • system-hostname: System hostname of the OpenResty Edge node
  • req-header: A specified request header, the name of which is indicated by el_var_arg
  • ssl-client-s-dn: Holder information of the SSL client certificate
  • ssl-client-i-dn: Issuing authority (CA) information of the SSL client certificate
  • ssl-client-serial: Serial number of the SSL client certificate
  • ssl-client-verify-result: Verification result of the SSL client certificate

Example

Example 1:

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-proxy-header:
      header: Host
      value: openresty.com

In this example, when the request’s URI is /hello/world, the Host request header for the proxy request will be set to openresty.com. If there is no Host request header, it will be added.

Example 2:

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-proxy-header:
      header: X-Forwarded-For
      el_var: client-addr

In this example, when the request’s URI is /hello/world, the proxy request’s X-Forwarded-For request header will be set to the actual client address.

Example 3:

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-proxy-header:
      header: Host
      el_var: req-header
      el_var_arg: Host

In this example, when the requested URI is /hello/world, the Host header from the original request headers will be set in the proxy request.

Set Response Header

Parameter Description

Parameter NameData TypeRequiredDescription
namestringYesThe name of the response header to set
valuestringNoThe value of the response header to set, alternatively choose el_var
el_varstringNoUse an Edge variable as the response header value, alternatively choose value
el_var_argstringNoIf needed, use together with el_var

The response header’s value can be set directly as a fixed value with value or dynamically with el_var and el_var_arg. The examples below provide both scenarios.

el_var supports variables including:

  • system-hostname: System hostname of the OpenResty Edge node
  • req-header: A specified request header, the name of which is indicated by el_var_arg

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    set-resp-header:
      name: Foo
      value: Bar

In this example, when the request’s URI is /hello/world, the response header Foo: Bar will be set. If there is no Foo response header, it will be added.

Add Response Header

Parameter Description

Parameter NameData TypeRequiredDescription
namestringYesThe name of the response header to add
valuestringNoThe value of the response header to add, alternatively choose el_var
el_varstringNoUse an Edge variable as the response header value, alternatively choose value
el_var_argstringNoIf needed, use together with el_var

The response header’s value can be set directly as a fixed value with value or dynamically with el_var and el_var_arg. The examples below provide both scenarios.

el_var supports variables including:

  • system-hostname: System hostname of the OpenResty Edge node
  • req-header: A specified request header, the name of which is indicated by el_var_arg

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    add-resp-header:
      name: Foo
      value: Bar

In this example, regardless of whether the Foo response header already exists, when the request’s URI is /hello/world, an additional Foo: Bar response header will be added.

Remove Response Header

Parameter Description

Parameter NameData TypeRequiredDescription
namestringYesThe name of the response header to remove

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    rm-resp-header:
      name: Access-Control-Allow-Origin

In this example, when the request’s URI is /hello/world, it will be removed if the response header contains Access-Control-Allow-Origin.

Output Response Body

Parameter Description

Parameter NameData TypeRequiredDescription
msgstringYesThe content of the response body to output

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /hello/world

  actions:
    print:
      msg: |
        Hello World!

In this example, when the request’s URI is /hello/world, Hello World! will be the output of the response body.

Exit Current Request

Parameter Description

Parameter NameData TypeRequiredDescription
codenumberYesHTTP response status code

Example

- enable_rule: true
  conditions:
  - var: uri
    op: eq
    val: /bad/request

  actions:
    exit:
      code: 403

In this example, when the request’s URI is /bad/request, the request will be responded to with a 403 status code.

Set Variable

Parameters

Parameter NameData TypeRequiredDescription
var_namestringYesVariable name
var_typestringYesVariable type, options are ‘app’ and ‘global’, representing application user variables and global user variables respectively
valuestringYesValue of the variable

Example

- enable_rule: true
  order: 11
  actions:
  - set-var:
      value: hello
      var_name: uuid
      var_type: app
  - set-var:
      value: world
      var_name: uuid
      var_type: global

In this example, the application user variable uuid is set to hello and the global user variable uuid is set to world.

Using Edgelang Language

Parameters

Parameter NameData TypeRequiredDescription
elnumberYesEdgelang source code

Example

- enable_rule: true
  order: 12
  actions:
  - user-code:
      el: |-
        true =>
            say($or_user_variable_test),
            say($or_global_user_variable_uuid);

In this example, the application user variable uuid and global user variable uuid are output as the response to the request.

Custom Error Page

Parameters

Parameter NameData TypeRequiredDescription
statusarrayYesList of HTTP status codes
content_typestringYesContent type
file_pathstringNoStatic file path
page_template_namestringNoName of the page template

Example

- enable_rule: true
  actions:
  - set-error-page:
      status:
      - 404
      content_type: text/html; charset=utf8
      file_path: dir1/setup.sh
  - set-error-page:
      status:
      - 403
      content_type: text/html; charset=utf8
      page_template_name: page403

This example includes two actions. One sets the error page for status code 404 to a static file with the path dir1/setup.sh. The other sets the error page for status code 403 to a page template named page403.

Custom Action

Parameters

Parameter NameData TypeRequiredDescription
global_action_namestringYesName of the global custom action

Example

- enable_rule: true
  actions:
  - global_action:
      global_action_name: global-action-1
  - global_action:
      global_action_name: global-action-2

This example includes two actions. One is a global custom action named global-action-1, and the other is a global custom action named global-action-2.

Mirror Request

Parameters

Parameter NameData TypeRequiredDescription
upstream_typestringYesUpstream type, options are ‘app’ and ‘global’, representing application upstream and global upstream respectively
upstream_namestringYesUpstream name
retriesnumberNoNumber of retries
retry_conditionarrayNoRetry conditions, available options are: error, timeout, invalid_header, http_500, http_502, http_504, http_503, http_404
typestringNoType of static request, ‘raw’: mirror original request, ‘custom’: request processed by custom Lua module
module_namestringNoWhen type is ‘custom’, specify the name of the Lua module
algorithmstringNoLoad balancing algorithm, supports chash, hash, roundrobin
send_timeoutnumberNoSend timeout
conn_timeoutnumberNoConnection timeout
read_timeoutnumberNoRead timeout

Example

- enable_rule: true
  actions:
  - mirror-request:
      retries: 1
      upstream_type: global
      conn_timeout: 60
      type: raw
      retry_condition:
      - error
      - timeout
      - invalid_header
      - http_500
      - http_502
      - http_504
      module_name: ''
      algorithm: hash
      send_timeout: 60
      read_timeout: 60
      upstream_name: global_upstream_name1

In this example, the original request is mirrored to the global upstream named global_upstream_name1.