请求处理相关

项目

描述

语法

add_req_header(name, value [, append])。

说明

添加请求头，即回源请求头。

参数

• name：待添加的请求头name，字符类型。

• value：待添加的请求头value，字符类型。

• append：若请求头已添加，append决定是否追加value，默认覆盖（即默认不追加），布尔类型。

返回值

默认返回true，无效请求头返回false。

示例

add_req_header('USER-DEFINED-REQ-1', '1')
add_req_header('USER-DEFINED-REQ-1', 'x', true)

说明：添加2个请求头，分别为
USER-DEFINED-REQ-1: 1
USER-DEFINED-REQ-1: x

项目

描述

语法

del_req_header(name)。

说明

删除请求头，即回源请求头。

参数

name：待删除的请求头name，字符类型。

返回值

默认返回true，无效请求头返回false。

示例

add_req_header('USER-DEFINED-REQ-2', '2')
del_req_header('USER-DEFINED-REQ-2')

USER-DEFINED-REQ-2先添加、后删除，故回源请求头中无USER-DEFINED-REQ-2

项目

描述

语法

add_rsp_header(name, value [, append])。

说明

添加响应头。

参数

• name：待添加的响应头name，字符类型。

• value：待添加的响应头value，字符类型。

  value可包含如下标记，用于在响应阶段执行动态替换：

  • ${x} ：将替换为ngx.var.x的值。

  • @{y}：将替换为响应头y的值。

• append：若响应头已添加，append决定是否追加value，默认覆盖，布尔类型。

。

返回值

默认返回true，无效响应头返回false。

示例

add_rsp_header('USER-DEFINED-RSP-1', '1')
add_rsp_header('USER-DEFINED-RSP-1', 'x', true)

说明：添加2个响应头，分别为
USER-DEFINED-RSP-1：1
USER-DEFINED-RSP-1：x

项目

描述

语法

del_rsp_header(name)。

说明

删除响应头。

参数

name：待删除的响应头name，字符类型。

返回值

默认返回true，无效响应头返回false。

示例

add_rsp_header('USER-DEFINED-RSP-2', '2')
del_rsp_header('USER-DEFINED-RSP-2')

USER-DEFINED-RSP-2先添加、后删除，故响应头中无USER-DEFINED-RSP-2

项目

描述

语法

encode_args(d)。

说明

将字典d中的k/v，转换为URI编码的k1=v1&k2=v2格式的字符串。

参数

d：字典类型。

返回值

返回URI编码格式的字符串。

示例

my_args = []
set(my_args, 'key1', 'value1')
set(my_args, 'key2', 'value2')
my_args_str = encode_args(my_args)
say(concat('encode_args result: ', my_args_str))

输出：

encode_args result: key1=value1&key2=value2

项目

描述

语法

decode_args(s)。

说明

将URI编码的k1=v1&k2=v2格式的字符串，转换为字典类型。

参数

s：目标字符串。

返回值

返回转换后的字典对象。

示例

my_args = decode_args('key1=value1&key2=value2')
def echo_each(k, v, u) {
    say(concat(k, '=', v))
}
foreach(my_args, echo_each, [])

输出：

key1=value1
key2=value2

项目

描述

语法

rewrite(url, flag, code)。

说明

改写操作或重定向操作。

参数

• url：目标URL，字符类型。

  • 当flag=redirect或flag=break时，仅改写URI，则参数URL表示改写后的目标URI。

  • 当flag=enhance_redirect或flag=enhance_break时，修改整个URI和参数，参数URL表示改写后的目标URI和参数。

• flag：重写模式，字符类型。

  • redirect ：仅修改URI，不修改参数；默认执行302跳转至URL；如果指定参数code，则响应码可自定义为：301、302（默认）、303、307或308。

  • break ：仅修改URI，不修改参数，将URI修改为URL。

  • enhance_redirect：与redirect类似，但是修改整个URI和参数。

  • enhance_break：与break类似，但是修改整个URI和参数。

• code：为响应码，数字类型 。

  当flag=redirect或flag=enhance_redirect时，可自定义响应码。

返回值

• 对于改写操作，默认返回true。

• 对于重定向操作，默认不返回。

示例

if and($arg_mode, eq($arg_mode, 'rewrite:enhance_break')) {
  rewrite('/a/example/examplefile.txt?k=v', 'enhance_break')
}
说明：回源和缓存的uri+参数，修改为/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)
}
说明：302或301跳转至/a/example/examplefile.txt?k=v

if and($arg_mode, eq($arg_mode, 'rewrite:break')) {
  rewrite('/a/example/examplefile.txt', 'break')
}
说明：回源和缓存的uri，修改为/a/example/examplefile.txt，保持原参数不变

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)
}
说明：302或301跳转至/a/example/examplefile.txt，保持原参数不变

项目

描述

语法

say(arg)。

说明

输出响应体，并在行尾追加换行符。

参数

arg：任意类型。

返回值

无。

示例

say('hello')
say('hello')

输出：
hello
hello

项目

描述

语法

print(arg)。

说明

输出响应体与say()相同，但不会在行尾追加换行符。

参数

arg：任意类型。

返回值

无。

示例

print('byebye')
print('byebye')

输出：
byebyebyebye

项目

描述

语法

exit(code [, body])。

说明

以状态码code结束当前请求。若有body，则为响应体。

参数

• code：响应状态码。

• body：响应体。

返回值

无。

示例

• 示例1

  if not($arg_key) {
      exit(403)
  }
  说明：如果请求未携带参数key时，403拒绝请求。
  
  if not($cookie_user) {
      exit(403, 'not cookie user')
  }
  说明：当请求未携带cookie user时，403拒绝请求，响应body为'not cookie user'
  
  if not(0) {
      exit(403)
  }
  说明：not(0)的结果为false
  
  if not(false) {
      exit(403)
  }
  说明：not(false)的结果为true

• 示例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(str)。

说明

获取响应头。

参数

str：string类型。

返回值

返回string、number、字典和boolean类型。

• 头存在：返回对应的值，可以为字典和字符串类型。

• 头不存在：返回false。

示例

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(k, v [,properties])。

说明

设置响应cookie，每次调用均会生成一个新的Set-Cookie响应头。

参数

• k：cookie名称。

• v：cookie值。

• properties（可选参数）：cookie属性。详细信息，请参见Set-Cookie。

返回值

成功返回true，失败返回false。

示例

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'
])

响应：

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