This topic describes the syntax, description, parameters, return values, and examples of request processing functions.

add_req_header

This function is described as follows:
  • Syntax: add_req_header(name, value [, append])
  • Description

    You can call this function to add an origin request header.

  • Parameters
    • name: the name of the request header to be added. Data type: string.
    • value: the value of the request header to be added. Data type: string.
    • append: specifies whether to append a request header with the specified value if a request header with the same name already exists. Valid values: true and false. Default value: false. If you specify false for this parameter, the specified value parameter will overwrite the value of the existing request header.
  • Return values

    This function returns true by default and returns false if you have specified an invalid request header.

  • Examples
    add_req_header('USER-DEFINED-REQ-1', '1')
    add_req_header('USER-DEFINED-REQ-1', 'x', true)
    add_req_header('USER-DEFINED-REQ-2', '2')
    del_req_header('USER-DEFINED-REQ-2')
    
    Note: Add the following request headers.
    USER-DEFINED-REQ-1: 1
    USER-DEFINED-REQ-1: x
    
    The USER-DEFINED-REQ-2 header is added first and then deleted, so the USER-DEFINED-REQ-2 request header is not included in the origin request.

del_req_header

This function is described as follows:
  • Syntax: del_req_header(name)
  • Description

    You can call this function to delete an origin request header.

  • Parameters

    name: the name of the request header to be deleted. Data type: string.

  • Return values

    This function returns true by default and returns false if you have specified an invalid request header.

  • Examples
    add_req_header('USER-DEFINED-REQ-1', '1')
    add_req_header('USER-DEFINED-REQ-1', 'x', true)
    add_req_header('USER-DEFINED-REQ-2', '2')
    del_req_header('USER-DEFINED-REQ-2')
    
    Note: Add the following request headers.
    USER-DEFINED-REQ-1: 1
    USER-DEFINED-REQ-1: x
    
    The USER-DEFINED-REQ-2 header is added first and then deleted, so the USER-DEFINED-REQ-2 request header is not included in the origin request.

add_rsp_header

This function is described as follows:
  • Syntax: add_rsp_header(name, value [, append])
  • Description

    You can call this function to add a response header.

  • Parameters
    • name: the name of the response header to be added. Data type: string.
    • value: the value of the response header to be added. Data type: string.
      You can specify one of the following expressions for the value parameter, so that the value can be replaced dynamically at the response phase.
      • ${x}: replaced with the value of ngx.var.x.
      • @{y}: replaced with the value of response header y.
    • append: specifies whether to append a response header with the specified value if a response header with the same name already exists. Valid values: true and false. Default value: false. If you specify false for this parameter, the specified value parameter will overwrite the value of the existing response header.
  • Return values

    This function returns true by default and returns false if you have specified an invalid response header.

  • Examples
    add_rsp_header('USER-DEFINED-RSP-1', '1')
    add_rsp_header('USER-DEFINED-RSP-1', 'x', true)
    add_rsp_header('USER-DEFINED-RSP-2', '2')
    del_rsp_header('USER-DEFINED-RSP-2')
    
    Note: Add the following response headers.
    USER-DEFINED-RSP-1: 1
    USER-DEFINED-RSP-1: x
    
    The USER-DEFINED-RSP-2 header is added first and then deleted, so the USER-DEFINED-RSP-2 header is not included in the response.

del_rsp_header

This function is described as follows:
  • Syntax: del_rsp_header(name)
  • Description

    You can call this function to delete a response header.

  • Parameters

    name: the name of the response header to be deleted. Data type: string.

  • Return values

    This function returns true by default and returns false if you have specified an invalid response header.

  • Examples
    add_rsp_header('USER-DEFINED-RSP-1', '1')
    add_rsp_header('USER-DEFINED-RSP-1', 'x', true)
    add_rsp_header('USER-DEFINED-RSP-2', '2')
    del_rsp_header('USER-DEFINED-RSP-2')
    
    Note: Add the following response headers.
    USER-DEFINED-RSP-1: 1
    USER-DEFINED-RSP-1: x
    
    The USER-DEFINED-RSP-2 header is added first and then deleted, so the USER-DEFINED-RSP-2 header is not included in the response.

encode_args

This function is described as follows:
  • Syntax: encode_args(d)
  • Description

    You can call this function to convert the k/v pairs in the dictionary specified by d to URI-encoded string in the format of k1=v1&k2=v2.

  • Parameters

    d: the dictionary to be converted.

  • Return values

    This function returns a URI-encoded string.

  • Examples
    my_args = []
    set(my_args, 'signature', 'da9dc4b7-87ae-4330-aaaf-e5454e2c2af1')
    set(my_args, 'algo', 'private sign1')
    my_args_str = encode_args(my_args)
    add_rsp_header('X-DSL-ENCODE-ARGS', my_args_str)
    
    to_args = decode_args(my_args_str)
    if get(to_args, 'algo') {
        add_rsp_header('X-DSL-DECODE-ARGS-ALGO', get(to_args, 'algo'))
    }
    if get(to_args, 'signature') {
        add_rsp_header('X-DSL-DECODE-ARGS-SIGN', get(to_args, 'signature'))
    }
    
    Output: Add the following response headers.
    X-DSL-ENCODE-ARGS: signature=da9dc4b7-87ae-4330-aaaf-e5454e2c2af1&algo=private%20sign1
    X-DSL-DECODE-ARGS-ALGO: private sign1
    X-DSL-DECODE-ARGS-SIGN: da9dc4b7-87ae-4330-aaaf-e5454e2c2af1

decode_args

This function is described as follows:
  • Syntax: decode_args(s)
  • Description

    You can call this function to convert the URI-encoded string in the format of k1=v1&k2=v2 to a string of the dictionary type.

  • Parameters

    s: the source string to be converted.

  • Return values

    This function returns the converted dictionary object.

  • Examples
    my_args = []
    set(my_args, 'signature', 'da9dc4b7-87ae-4330-aaaf-e5454e2c2af1')
    set(my_args, 'algo', 'private sign1')
    my_args_str = encode_args(my_args)
    add_rsp_header('X-DSL-ENCODE-ARGS', my_args_str)
    
    to_args = decode_args(my_args_str)
    if get(to_args, 'algo') {
        add_rsp_header('X-DSL-DECODE-ARGS-ALGO', get(to_args, 'algo'))
    }
    if get(to_args, 'signature') {
        add_rsp_header('X-DSL-DECODE-ARGS-SIGN', get(to_args, 'signature'))
    }
    
    Output: Add the following response headers.
    X-DSL-ENCODE-ARGS: signature=da9dc4b7-87ae-4330-aaaf-e5454e2c2af1&algo=private%20sign1
    X-DSL-DECODE-ARGS-ALGO: private sign1
    X-DSL-DECODE-ARGS-SIGN: da9dc4b7-87ae-4330-aaaf-e5454e2c2af1

rewrite

This function is described as follows:
  • Syntax: rewrite(url, flag, code)
  • Description

    You can call this function to perform a rewrite or redirect operation.

  • Parameters
    • url: the target URI in the rewrite rule. Data type: string.
      • If you set the flag parameter to redirect or break, only the URI is rewritten. This parameter specifies the target URI after the rewrite operation.
      • If you set the flag parameter to enhance_redirect or enhance_break, the URI and parameters are rewritten. This parameter specifies the target URI and parameters after the rewrite operation.
    • flag: the rewrite mode. Data type: string.
      • redirect: only rewrites the URI. Parameters are not rewritten. By default, a 302 redirect is performed. If you specify this mode, the code parameter is configurable. Valid values for the code parameter are 301, 302 (default), 303, 307, and 308.
      • break: only rewrites the URI as a URL. Parameters are not rewritten.
      • enhance_redirect: similar with redirect. However, parameters are also rewritten in this mode.
      • enhance_break: similar with break. However, parameters are also rewritten in this mode.
    • code: the response code. Data type: numeric type.

      This parameter is available for customization only when you set the flag parameter to redirect or enhance_redirect.

  • Return values
    • This function returns true by default for a rewrite operation.
    • This function does not return a value by default for a rewrite operation.
  • Examples
    if and($arg_mode, eq($arg_mode, 'rewrite:enhance_break')) {
        rewrite('/a/b/c.txt? k=v', 'enhance_break')
    }
    Note: Rewrite the URI and parameters of the origin request as /a/b/c.txt? k=v
    
    if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect')) {
        rewrite('/a/b/c.txt? k=v', 'enhance_redirect')
    }
    if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect_301')) {
        rewrite('/a/b/c.txt? k=v', 'enhance_redirect', 301)
    }
    Note: Perform a 302 or 301 redirect to /a/b/c.txt? k=v
    
    if and($arg_mode, eq($arg_mode, 'rewrite:break')) {
        rewrite('/a/b/c.txt', 'break')
    }
    Note: Rewrite the URI of the origin request as /a/b/c.txt and keep the original parameters in the request unchanged.
    
    if and($arg_mode, eq($arg_mode, 'rewrite:redirect')) {
        rewrite('/a/b/c.txt', 'redirect')
    }
    if and($arg_mode, eq($arg_mode, 'rewrite:redirect_301')) {
        rewrite('/a/b/c.txt', 'redirect', 301)
    }
    Note: Perform a 302 or 301 redirect to /a/b/c.txt and keep the original parameters unchanged.

say

This function is described as follows:
  • Syntax: say(arg)
  • Description

    You can call this function to output a response body and append a newline at the end of the output.

  • Parameters

    arg: the content of the response body. Data type: any type.

  • Return values

    None

  • Examples
    say('hello')
    print('byebye')
    print('byebye')
    
    Output:
    hello
    byebyebyebye

print

This function is described as follows:
  • Syntax: print(arg)
  • Description

    You can call this function to output a response body. Unlike the say () function, this function does not append a newline at the end of the output.

  • Parameters

    arg: the content of the response body. Data type: any type.

  • Return values

    None

  • Examples
    say('hello')
    print('byebye')
    print('byebye')
    
    Output:
    hello
    byebyebyebye

exit

This function is described as follows:
  • Syntax: exit(code [, body])
  • Description

    You can call this function to end the current request with the specified code. If you also specify the body parameter, a response that includes the specified response body is returned.

  • Parameters
    • code: the status code to return.
    • body: the response body to return.
  • Return values

    None

  • Examples
    • Example 1
      if not($arg_key) {
          exit(403)
      }
      Note: If the request does not include the key parameter, the request is rejected and status code 403 is returned.
      
      if not($cookie_user) {
          exit(403, 'not cookie user')
      }
      Note: If the request does not include a cookie user, the request is rejected. A response that contains "not cookie user" is returned with status code 403.
      
      if not(0) {
          exit(403)
      }
      Note: The not (0) function returns false.
      
      if not(false) {
          exit(403)
      }
      Note: The not (false) function returns true.
    • Example 2
      pcs = capture_re($request_uri,'^/([^/]+)/([^/]+)([^?] +)\?(.*)')
      sec1 = get(pcs, 1)
      sec2 = get(pcs, 2)
      sec3 = get(pcs, 3)
      if or(not(sec1), not(sec2), not(sec3)) {
         add_rsp_header('X-TENGINE-ERROR', 'auth failed - missing necessary uri set')
         exit(403)
      }
      digest = md5(concat(sec1, sec3))
      if ne(digest, sec2) {
          add_rsp_header('X-TENGINE-ERROR', 'auth failed - invalid digest')
          exit(403)
      }