开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Introduction

This a tiny library, intended to be used with OpenResty applications, when you need to execute a subprocess (or shell command). It works similarly to os.execute and io.popen, except that it is completely non-blocking, and therefore is safe to use even for commands that take long time to complete.

The library depends on a daemon component that you would need to run on your webserver - sockproc. The basic idea is that the shell library connects to the unix domain socket of sockproc daemon, sends the command along with any input data that the child program is expecting, and then reads back the exit code, output stream data, and error stream data of the child process. Because we use co-socket API, provided by lua-nginx-module, the nginx worker is never blocked.

More info on sockproc server, including complete source code here: https://github.com/juce/sockproc

Example usage

Make sure to have sockproc running and listenning on a UNIX domain socket:

$ ./sockproc /tmp/shell.sock

In your OpenResty config:

location /test {
    content_by_lua '
        local shell = require("resty.shell")

        -- define a table to hold arguments with the following elements:
        --
        -- timeout: timeout for the socket connection
        --
        -- data: STDIN to send to sockproc
        --
        -- socket: either a table containg the elements 'host' and 'port' for tcp connections,
        -- or a string defining a unix socket
        local args = {
            socket = "unix:/tmp/shell.sock",
        }

        local status, out, err = shell.execute("uname -a", args)

        ngx.header.content_type = "text/plain"
        ngx.say("Hello from:\n" .. out)
    ';
}

License

The MIT License (MIT)