DocsICP FilingConsole
官方文档
首页

Request processing functions

更新时间：
复制 MD 格式
产品详情
我的收藏

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

add_req_header

The following table describes the details about this function.
ItemDescription
Syntaxadd_req_header(name, value [, append])
DescriptionAdds a request header to requests before they are redirected to the origin server.
Parameter
  • name: the name of the request header that you want to add. Data type: string.
  • value: the value of the request header that you want to add. 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. Data type: Boolean. If you set this parameter to false, the specified value will overwrite the value of the existing request header.
Return valueReturns true by default and returns false if the specified request header is invalid.
Example
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: The following request headers are added:
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

The USER-DEFINED-REQ-2 header is added and then deleted. Therefore, the USER-DEFINED-REQ-2 request header is not included in requests that are redirected to the origin server.

del_req_header

The following table describes the details about this function.
ItemDescription
Syntaxdel_req_header(name)
DescriptionDeletes a request header from requests before they are redirected to the origin server.
Parametername: the name of the request header that you want to delete. Data type: string.
Return valueReturns true by default and returns false if the specified request header is invalid.
Example
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: The following request headers are added:
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

The USER-DEFINED-REQ-2 header is added and then deleted. Therefore, the USER-DEFINED-REQ-2 request header is not included in requests that are redirected to the origin server.

add_rsp_header

The following table describes the details about this function.
ItemDescription
Syntaxadd_rsp_header(name, value [, append])
DescriptionAdds a response header.
Parameter
  • name: the name of the response header that you want to add. Data type: string.
  • value: the value of the response header that you want to add. Data type: string.
    You can specify one of the following expressions for the value parameter to enable the value to be dynamically replaced in 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. Data type: Boolean. If you set this parameter to false, the specified value will overwrite the value of the existing response header.
Return valueReturns true by default and returns false if the specified response header is invalid.
Example
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: The following response headers are added:
USER-DEFINED-RSP-1: 1
USER-DEFINED-RSP-1: x

The USER-DEFINED-RSP-2 header is added and then deleted. Therefore, the USER-DEFINED-RSP-2 header is not included in the responses.

del_rsp_header

The following table describes the details about this function.
ItemDescription
Syntaxdel_rsp_header(name)
DescriptionDeletes a response header.
Parametername: the name of the response header that you want to delete. Data type: string.
Return valueReturns true by default and returns false if the specified response header is invalid.
Example
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')

The following response headers are added:
USER-DEFINED-RSP-1: 1
USER-DEFINED-RSP-1: x

The USER-DEFINED-RSP-2 header is added and then deleted. Therefore, the USER-DEFINED-RSP-2 header is not included in the responses.

encode_args

The following table describes the details about this function.
ItemDescription
Syntaxencode_args(d)
DescriptionConverts the k/v pairs in the dictionary specified by d to a URI-encoded string in the format of k1=v1&k2=v2.
Parameterd: the dictionary that you want to convert.
Return valueReturns a URI-encoded string.
Example
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: The following response headers are added:
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

The following table describes the details about this function.
ItemDescription
Syntaxdecode_args(s)
DescriptionConverts a URI-encoded string in the format of k1=v1&k2=v2 to a string of dictionary type.
Parameters: the string that you want to convert.
Return valueReturns a dictionary object converted from the specified string.
Example
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: The following response headers are added:
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

ItemDescription
syntaxrewrite(url, flag, code)
descriptionPerforms a URI rewrite or a redirect.
parameter
  • url (string): The target URL for the operation.
    • When flag is redirect or break, only the URI path is rewritten. The url parameter specifies the new target URI.
    • When flag is enhance_redirect or enhance_break, the entire URI (path and query parameters) is replaced. The url parameter specifies the new target URI and its parameters.
  • (string): The rewrite mode.
    • code: Rewrites only the URI path and performs a redirect, preserving the original query parameters. By default, it uses a 302 HTTP status code. You can specify a different code (301, 303, 307, or 308) with the parameter.
    • : Rewrites the URI path to the specified url, preserving the original query parameters.
    • redirect: Similar to redirect, but modifies the entire URI, including the path and query parameters.
    • break: Similar to break, but modifies the entire URI, including the path and query parameters.
  • code (number, optional): The HTTP status code to use for the redirect. This parameter applies only when flag is redirect or enhance_redirect.

return value
  • trueFor a rewrite operation (, ), the function returns .
  • For a redirect operation (redirect, enhance_redirect), the function terminates the current request processing and does not return a value.
Example
if and($arg_mode, eq($arg_mode, 'rewrite:enhance_break')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_break')
}
// Rewrites the URI and query parameters for the origin request and cache key to /a/example/examplefile.txt?k=v.

if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:enhance_redirect_301')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_redirect', 301)
}
// Redirects the client to /a/example/examplefile.txt?k=v with a 302 or 301 HTTP status code.

if and($arg_mode, eq($arg_mode, 'rewrite:break')) {
  rewrite('/a/example/examplefile.txt', 'break')
}
// Rewrites the URI path for the origin request and cache key to /a/example/examplefile.txt, preserving the original query parameters.

if and($arg_mode, eq($arg_mode, 'rewrite:redirect')) {
  rewrite('/a/example/examplefile.txt', 'redirect')
}
if and($arg_mode, eq($arg_mode, 'rewrite:redirect_301')) {
  rewrite('/a/example/examplefile.txt', 'redirect', 301)
}
// Redirects the client to /a/example/examplefile.txt with a 302 or 301 HTTP status code, preserving the original query parameters.

say

The following table describes the details about this function.
ItemDescription
Syntaxsay(arg)
DescriptionPrints a response body and appends a newline character at the end of the output.
Parameterarg: the content of the response body. Data type: any type.
Return valueNone.
Example
say('hello')
print('byebye')
print('byebye')

Output:
hello
byebyebyebye

print

The following table describes the details about this function.
ItemDescription
Syntaxprint(arg)
DescriptionPrints a response body. This function is different from the say() function. This function does not append a newline at the end of the output.
Parameterarg: the content of the response body. Data type: any type.
Return valueNone.
Example
say('hello')
print('byebye')
print('byebye')

Output:
hello
byebyebyebye

exit

The following table describes the details about this function.
ItemDescription
Syntaxexit(code [, body])
DescriptionEnds the current request with the specified code. If you also set the body parameter, a response that includes the specified response body is returned.
Parameter
  • code: the HTTP status code to return.
  • body: the response body.
Return valueNone.
Example
  • Example 1 
    if not($arg_key) {
    exit(403)
}
Note: If a request does not include the key parameter, the request is denied and the HTTP 403 status code is returned. 

if not($cookie_user) {
    exit(403, 'not cookie user')
}
Note: If a request does not include cookie_user, the request is denied and a response that contains the body "not cookie user" is returned with the HTTP 403 status code.

if not(0) {
    exit(403)
}
Note: The not(0) function returns a value of false.

if not(false) {
    exit(403)
}
Note: The not(false) function returns a value of 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)
}

get_rsp_header

The following table describes the details about this function.
ItemDescription
Syntaxget_rsp_header(str)
DescriptionObtains a response header.
Parameterstr: the response header that you want to obtain. Data type: string.
Return valueReturns the specified response header of string, number, dictionary, or Boolean data type.
  • If the specified response header exists, the response header is returned. The data type of the response header is dictionary or string.
  • If the specified response header does not exist, a value of false is returned.
Example
ct = get_rsp_header('content-type')
if ct {
    add_rsp_header('origin-content-type', 'is')
} else {
      add_rsp_header('origin-content-type', 'no')
}

add_rsp_cookie

The following table describes the details about this function.
ItemDescription
Syntaxadd_rsp_cookie(k, v [,properties])
DescriptionSets the response cookie. Each time the function is called, a new Set-Cookie response header is generated.
Parameter
  • k: the name of the cookie.
  • v: the value of the cookie.
  • properties: the properties of the cookie. This parameter is optional. For more information, see Set-Cookie.
Return valueA value of true is returned if the specified cookie is set and a value of false is returned if the specified cookie failed to be set.
Example
add_rsp_cookie('user', 'edgescript')

add_rsp_cookie('login_time', tostring(now()), [
    'path' = '/'
])

expires = cookie_time(time())
add_rsp_cookie('psid', 'SDF93745HFSDF2934JKHG', [
    'path' = '/play',
    'domain' = 'foo.com',
    'secure' = true,
    'httponly' = true,
    'expires' = expires,
    'max_age' = 100,
    'samesite' = 'Strict',
    'extension' = 'xxt3s'
])
Response:
Set-Cookie: user=edgescript
Set-Cookie: login_time=1582538968.912; Path=/
Set-Cookie: psid=SDF93745HFSDF2934JKHG; Expires=Mon, 24-Feb-20 10:09:28 GMT; Max-Age=100; Domain=foo.com; Path=/play; Secure; HttpOnly; SameSite=Strict; xxt3s
Previous：Dictionary functionsNext：Throttling functions