1 files changed, 61 insertions, 4 deletions
diff --git a/meta/3rd/OpenResty/library/resty.shell.lua b/meta/3rd/OpenResty/library/resty.shell.lua
index 19f68464..be2d41ea 100644
--- a/meta/3rd/OpenResty/library/resty.shell.lua
+++ b/meta/3rd/OpenResty/library/resty.shell.lua
@@ -1,5 +1,62 @@
 ---@meta
-resty_shell={}
-function resty_shell.run(cmd, stdin, timeout, max_size) end
-resty_shell.version=0.01
-return resty_shell
-\ No newline at end of file
+
+local shell = {
+    version = 0.03,
+}
+
+
+--- Runs a shell command, `cmd`, with an optional stdin.
+---
+--- The `cmd` argument can either be a single string value (e.g. `"echo 'hello,
+--- world'"`) or an array-like Lua table (e.g. `{"echo", "hello, world"}`). The
+--- former is equivalent to `{"/bin/sh", "-c", "echo 'hello, world'"}`, but simpler
+--- and slightly faster.
+---
+--- When the `stdin` argument is `nil` or `""`, the stdin device will immediately
+--- be closed.
+---
+--- The `timeout` argument specifies the timeout threshold (in ms) for
+--- stderr/stdout reading timeout, stdin writing timeout, and process waiting
+--- timeout. The default is 10 seconds as per https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/pipe.md#set_timeouts
+---
+--- The `max_size` argument specifies the maximum size allowed for each output
+--- data stream of stdout and stderr. When exceeding the limit, the `run()`
+--- function will immediately stop reading any more data from the stream and return
+--- an error string in the `reason` return value: `"failed to read stdout: too much
+--- data"`.
+---
+--- Upon terminating successfully (with a zero exit status), `ok` will be `true`,
+--- `reason` will be `"exit"`, and `status` will hold the sub-process exit status.
+---
+--- Upon terminating abnormally (non-zero exit status), `ok` will be `false`,
+--- `reason` will be `"exit"`, and `status` will hold the sub-process exit status.
+---
+--- Upon exceeding a timeout threshold or any other unexpected error, `ok` will be
+--- `nil`, and `reason` will be a string describing the error.
+---
+--- When a timeout threshold is exceeded, the sub-process will be terminated as
+--- such:
+---
+--- 1. first, by receiving a `SIGTERM` signal from this library,
+--- 2. then, after 1ms, by receiving a `SIGKILL` signal from this library.
+---
+--- Note that child processes of the sub-process (if any) will not be terminated.
+--- You may need to terminate these processes yourself.
+---
+--- When the sub-process is terminated by a UNIX signal, the `reason` return value
+--- will be `"signal"` and the `status` return value will hold the signal number.
+---
+---@param cmd string|string[]
+---@param stdin? string
+---@param timeout? number
+---@param max_size? number
+---
+---@return boolean ok
+---@return string? stdout
+---@return string? stderr
+---@return string|'"exit"'|'"signal"' reason
+---@return number? status
+function shell.run(cmd, stdin, timeout, max_size) end
+
+
+return shell
+\ No newline at end of file