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)
}