Page Rule Actions

# Limit Request Rate

# Parameter Description

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.