You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
functionngx_balancer.set_current_peer(addr, port) end
4
-
functionngx_balancer.set_timeouts(connect_timeout, send_timeout, read_timeout) end
5
-
functionngx_balancer.get_last_failure() end
6
-
functionngx_balancer.set_more_tries(count) end
7
-
ngx_balancer.version="0.1.17"
8
-
returnngx_balancer
2
+
localbalancer= {
3
+
version=require("resty.core.base").version,
4
+
}
5
+
6
+
--- Sets the peer address (host and port) for the current backend query (which
7
+
--- may be a retry).
8
+
---
9
+
--- Domain names in host do not make sense. You need to use OpenResty libraries
10
+
--- like lua-resty-dns to obtain IP address(es) from all the domain names before
11
+
--- entering the `balancer_by_lua*` handler (for example, you can perform DNS
12
+
--- lookups in an earlier phase like `access_by_lua*` and pass the results to the
13
+
--- `balancer_by_lua*` handler via `ngx.ctx`.
14
+
---
15
+
---@paramaddrstring
16
+
---@paramportinteger
17
+
---@returnboolean ok
18
+
---@returnstring?error
19
+
functionbalancer.set_current_peer(addr, port) end
20
+
21
+
22
+
--- Sets the upstream timeout (connect, send and read) in seconds for the
23
+
--- current and any subsequent backend requests (which might be a retry).
24
+
---
25
+
--- If you want to inherit the timeout value of the global nginx.conf
26
+
--- configuration (like `proxy_connect_timeout`), then just specify the nil value
27
+
--- for the corresponding argument (like the `connect_timeout` argument).
28
+
---
29
+
--- Zero and negative timeout values are not allowed.
30
+
---
31
+
--- You can specify millisecond precision in the timeout values by using floating
32
+
--- point numbers like 0.001 (which means 1ms).
33
+
---
34
+
--- Note: `send_timeout` and `read_timeout` are controlled by the same config
35
+
--- `proxy_timeout` for `ngx_stream_proxy_module`. To keep API compatibility, this
36
+
--- function will use `max(send_timeout, read_timeout)` as the value for setting
37
+
--- proxy_timeout.
38
+
---
39
+
--- Returns `true` when the operation is successful; returns `nil` and a string
40
+
--- describing the error otherwise.
41
+
---
42
+
--- This only affects the current downstream request. It is not a global change.
43
+
---
44
+
--- For the best performance, you should use the OpenResty bundle.
45
+
---
46
+
--- This function was first added in the 0.1.7 version of this library.
47
+
---
48
+
---@paramconnect_timeout?number
49
+
---@paramsend_timeout?number
50
+
---@paramread_timeout?number
51
+
---@returnboolean ok
52
+
---@returnstring?error
53
+
functionbalancer.set_timeouts(connect_timeout, send_timeout, read_timeout) end
54
+
55
+
---@aliasngx.balancer.failure
56
+
---| '"next"' # Failures due to bad status codes sent from the backend server. The origin's response is same though, which means the backend connection can still be reused for future requests.
57
+
---| '"failed"' Fatal errors while communicating to the backend server (like connection timeouts, connection resets, and etc). In this case, the backend connection must be aborted and cannot get reused.
58
+
59
+
--- Retrieves the failure details about the previous failed attempt (if any) when
60
+
--- the next_upstream retrying mechanism is in action. When there was indeed a
61
+
--- failed previous attempt, it returned a string describing that attempt's state
62
+
--- name, as well as an integer describing the status code of that attempt.
63
+
---
64
+
--- Possible status codes are those HTTP error status codes like 502 and 504.
65
+
---
66
+
--- For stream module, `status_code` will always be 0 (`ngx.OK`) and is provided
67
+
--- for compatibility reasons.
68
+
---
69
+
--- When the current attempt is the first attempt for the current downstream
70
+
--- request (which means there is no previous attempts at all), this method
71
+
--- always returns a single `nil` value.
72
+
---
73
+
---@returnngx.balancer.failure?state_name
74
+
---@returninteger?status_code
75
+
functionbalancer.get_last_failure() end
76
+
77
+
--- Sets the tries performed when the current attempt (which may be a retry)
78
+
--- fails (as determined by directives like proxy_next_upstream, depending on
79
+
--- what particular nginx uptream module you are currently using).
80
+
--
81
+
--- Note that the current attempt is excluded in the count number set here.
82
+
---
83
+
--- Please note that, the total number of tries in a single downstream request
84
+
--- cannot exceed the hard limit configured by directives like
85
+
--- `proxy_next_upstream_tries`, depending on what concrete NGINX upstream
86
+
--- module you are using. When exceeding this limit, the count value will get
87
+
--- reduced to meet the limit and the second return value will be the string
88
+
--- "reduced tries due to limit", which is a warning, while the first return
89
+
--- value is still a `true` value.
90
+
---
91
+
---@paramcountinteger
92
+
---@returnboolean ok
93
+
---@returnstring?error
94
+
functionbalancer.set_more_tries(count) end
95
+
96
+
--- Recreates the request buffer for sending to the upstream server.
97
+
---
98
+
--- This is useful, for example if you want to change a request header field
99
+
--- to the new upstream server on balancer retries.
100
+
---
101
+
--- Normally this does not work because the request buffer is created once
102
+
--- during upstream module initialization and won't be regenerated for subsequent
103
+
--- retries. However you can use `proxy_set_header My-Header $my_header` and
104
+
--- set the `ngx.var.my_header` variable inside the balancer phase. Calling
105
+
--- `recreate_request()` after updating a header field will cause the request
106
+
--- buffer to be re-generated and the `My-Header` header will thus contain the
107
+
--- new value.
108
+
---
109
+
--- Warning: because the request buffer has to be recreated and such allocation
110
+
--- occurs on the request memory pool, the old buffer has to be thrown away and
111
+
--- will only be freed after the request finishes. Do not call this function too
112
+
--- often or memory leaks may be noticeable. Even so, a call to this function
113
+
--- should be made only if you know the request buffer must be regenerated,
114
+
--- instead of unconditionally in each balancer retries.
115
+
---
116
+
--- This function was first added in the 0.1.20 version of this library.
--- Return the nginx core's error log filter level (defined via the `error_log` configuration directive in nginx.conf) as an integer value.
7
+
---@returnngx.log.level
8
+
functionerrlog.get_sys_filter_level() end
9
+
10
+
11
+
--- Specifies the filter log level, only to capture and buffer the error logs with a log level no lower than the specified level.
12
+
---
13
+
--- If we don't call this API, all of the error logs will be captured by default.
14
+
---
15
+
--- In case of error, `nil` will be returned as well as a string describing the error.
16
+
---
17
+
--- This API should always work with directive `lua_capture_error_log`.
18
+
---
19
+
--- See Nginx log level constants for all nginx log levels.
20
+
---
21
+
---@paramlevelngx.log.level
22
+
---@returnboolean ok
23
+
---@returnstring?err
24
+
functionerrlog.set_filter_level(level) end
25
+
26
+
27
+
--- Fetches the captured nginx error log messages if any in the global data buffer specified by ngx_lua's `lua_capture_error_log` directive. Upon return, this Lua function also removes those messages from that global capturing buffer to make room for future new error log data.
28
+
---
29
+
--- In case of error, nil will be returned as well as a string describing the error.
30
+
---
31
+
--- The optional max argument is a number that when specified, will prevent `get_logs()` from adding more than max messages to the res array.
32
+
---
33
+
---```lua
34
+
--- for i = 1, 20 do
35
+
--- ngx.log(ngx.ERR, "test")
36
+
--- end
37
+
---
38
+
--- local errlog = require "ngx.errlog"
39
+
--- local res = errlog.get_logs(10)
40
+
--- -- the number of messages in the `res` table is 10 and the `res` table
41
+
--- -- has 30 elements.
42
+
---```
43
+
---
44
+
--- The resulting table has the following structure:
--- The timeX values are UNIX timestamps in seconds with millisecond precision. The sub-second part is presented as the decimal part. The time format is exactly the same as the value returned by ngx.now. It is also subject to NGINX core's time caching.
55
+
---
56
+
--- The msgX values are the error log message texts.
57
+
---
58
+
--- So to traverse this array, the user can use a loop like this:
59
+
---
60
+
---```lua
61
+
---
62
+
--- for i = 1, #res, 3 do
63
+
--- local level = res[i]
64
+
--- if not level then
65
+
--- break
66
+
--- end
67
+
---
68
+
--- local time = res[i + 1]
69
+
--- local msg = res[i + 2]
70
+
---
71
+
--- -- handle the current message with log level in `level`,
72
+
--- -- log time in `time`, and log message body in `msg`.
73
+
--- end
74
+
---```
75
+
---
76
+
--- Specifying max <= 0 disables this behavior, meaning that the number of results won't be limited.
77
+
---
78
+
--- The optional 2th argument res can be a user-supplied Lua table to hold the result instead of creating a brand new table. This can avoid unnecessary table dynamic allocations on hot Lua code paths. It is used like this:
79
+
---
80
+
---```lua
81
+
--- local errlog = require "ngx.errlog"
82
+
--- local new_tab = require "table.new"
83
+
---
84
+
--- local buffer = new_tab(100 * 3, 0) -- for 100 messages
85
+
---
86
+
--- local errlog = require "ngx.errlog"
87
+
--- local res, err = errlog.get_logs(0, buffer)
88
+
--- if res then
89
+
--- -- res is the same table as `buffer`
90
+
--- for i = 1, #res, 3 do
91
+
--- local level = res[i]
92
+
--- if not level then
93
+
--- break
94
+
--- end
95
+
--- local time = res[i + 1]
96
+
--- local msg = res[i + 2]
97
+
--- ...
98
+
--- end
99
+
--- end
100
+
---```
101
+
---
102
+
--- When provided with a res table, `get_logs()` won't clear the table for performance reasons, but will rather insert a trailing nil value after the last table element.
103
+
---
104
+
--- When the trailing nil is not enough for your purpose, you should clear the table yourself before feeding it into the `get_logs()` function.
105
+
---
106
+
---@parammaxnumber
107
+
---@paramres?table
108
+
---@returntable?res
109
+
---@returnstring?err
110
+
functionerrlog.get_logs(max, res) end
111
+
112
+
--- Log msg to the error logs with the given logging level.
113
+
---
114
+
--- Just like the ngx.log API, the log_level argument can take constants like ngx.ERR and ngx.WARN. Check out Nginx log level constants for details.
115
+
---
116
+
--- However, unlike the ngx.log API which accepts variadic arguments, this function only accepts a single string as its second argument msg.
117
+
---
118
+
--- This function differs from ngx.log in the way that it will not prefix the written logs with any sort of debug information (such as the caller's file and line number).
0 commit comments