{"id":13776152,"url":"https://github.com/openresty/stream-lua-nginx-module","last_synced_at":"2025-05-11T10:30:51.529Z","repository":{"id":3546441,"uuid":"49554190","full_name":"openresty/stream-lua-nginx-module","owner":"openresty","description":"Embed the power of Lua into NGINX TCP/UDP servers","archived":false,"fork":false,"pushed_at":"2024-03-27T04:01:06.000Z","size":1307,"stargazers_count":709,"open_issues_count":37,"forks_count":191,"subscribers_count":86,"default_branch":"master","last_synced_at":"2024-03-28T04:42:15.724Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openresty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-13T06:23:38.000Z","updated_at":"2024-07-06T07:35:40.939Z","dependencies_parsed_at":"2023-02-10T22:00:29.032Z","dependency_job_id":"ad637b07-0cd6-49ae-947a-fc6472f76470","html_url":"https://github.com/openresty/stream-lua-nginx-module","commit_stats":{"total_commits":407,"total_committers":32,"mean_commits":12.71875,"dds":0.5184275184275184,"last_synced_commit":"e45c6624b9894911532ad0a3713d65c755dd2ea3"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fstream-lua-nginx-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fstream-lua-nginx-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fstream-lua-nginx-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fstream-lua-nginx-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/stream-lua-nginx-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253551475,"owners_count":21926301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T18:00:17.563Z","updated_at":"2025-05-11T10:30:50.253Z","avatar_url":"https://github.com/openresty.png","language":"C","funding_links":[],"categories":["Modules","C"],"sub_categories":[],"readme":"\nName\n====\n\nngx_stream_lua_module - Embed the power of Lua into Nginx stream/TCP Servers.\n\nThis module is a core component of OpenResty. If you are using this module,\nthen you are essentially using OpenResty.\n\n*This module is not distributed with the Nginx source.* See [the installation\ninstructions](#installation).\n\nTable of Contents\n=================\n\n* [Name](#name)\n* [Status](#status)\n* [Version](#version)\n* [Synopsis](#synopsis)\n* [Description](#description)\n    * [Directives](#directives)\n    * [Nginx API for Lua](#nginx-api-for-lua)\n* [TODO](#todo)\n* [Nginx Compatibility](#nginx-compatibility)\n* [Installation](#installation)\n* [Community](#community)\n    * [English Mailing List](#english-mailing-list)\n    * [Chinese Mailing List](#chinese-mailing-list)\n* [Code Repository](#code-repository)\n* [Bugs and Patches](#bugs-and-patches)\n* [Acknowledgments](#acknowledgments)\n* [Copyright and License](#copyright-and-license)\n* [See Also](#see-also)\n\nStatus\n======\n\nProduction ready.\n\nVersion\n=======\n\nThis document describes ngx_stream_lua\n[v0.0.13](https://github.com/openresty/stream-lua-nginx-module/tags), which was released\non 21 May, 2023.\n\nSynopsis\n========\n\n```nginx\nevents {\n    worker_connections 1024;\n}\n\nstream {\n    # define a TCP server listening on the port 1234:\n    server {\n        listen 1234;\n\n        content_by_lua_block {\n            ngx.say(\"Hello, Lua!\")\n        }\n    }\n}\n```\n\nSet up as an SSL TCP server:\n\n```nginx\nstream {\n    server {\n        listen 4343 ssl;\n\n        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;\n        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;\n        ssl_certificate     /path/to/cert.pem;\n        ssl_certificate_key /path/to/cert.key;\n        ssl_session_cache   shared:SSL:10m;\n        ssl_session_timeout 10m;\n\n        content_by_lua_block {\n            local sock = assert(ngx.req.socket(true))\n            local data = sock:receive()  -- read a line from downstream\n            if data == \"thunder!\" then\n                ngx.say(\"flash!\")  -- output data\n            else\n                ngx.say(\"boom!\")\n            end\n            ngx.say(\"the end...\")\n        }\n    }\n}\n```\n\nListening on a UNIX domain socket is also supported:\n\n```nginx\nstream {\n    server {\n        listen unix:/tmp/nginx.sock;\n\n        content_by_lua_block {\n            ngx.say(\"What's up?\")\n            ngx.flush(true)  -- flush any pending output and wait\n            ngx.sleep(3)  -- sleeping for 3 sec\n            ngx.say(\"Bye bye...\")\n        }\n    }\n}\n```\n\n[Back to TOC](#table-of-contents)\n\nDescription\n===========\n\nThis is a port of the\n[ngx_http_lua_module](https://github.com/openresty/lua-nginx-module#readme) to\nthe Nginx \"stream\" subsystem so as to support generic stream/TCP clients.\n\nThe available Lua APIs and Nginx directives remain the same as those of the\nngx_http_lua module.\n\n[Back to TOC](#table-of-contents)\n\nDirectives\n----------\n\nThe following directives are ported directly from ngx_http_lua. Please check\nthe documentation of ngx_http_lua for more details about their usage and\nbehavior.\n\n* [lua_load_resty_core](https://github.com/openresty/lua-nginx-module#lua_load_resty_core)\n* [lua_code_cache](https://github.com/openresty/lua-nginx-module#lua_code_cache)\n* [lua_regex_cache_max_entries](https://github.com/openresty/lua-nginx-module#lua_regex_cache_max_entries)\n* [lua_package_path](https://github.com/openresty/lua-nginx-module#lua_package_path)\n* [lua_package_cpath](https://github.com/openresty/lua-nginx-module#lua_package_cpath)\n* [init_by_lua_block](https://github.com/openresty/lua-nginx-module#init_by_lua_block)\n* [init_by_lua_file](https://github.com/openresty/lua-nginx-module#init_by_lua_file)\n* [init_worker_by_lua_block](https://github.com/openresty/lua-nginx-module#init_worker_by_lua_block)\n* [init_worker_by_lua_file](https://github.com/openresty/lua-nginx-module#init_worker_by_lua_file)\n* [preread_by_lua_block](#preread_by_lua_block)\n* [preread_by_lua_file](#preread_by_lua_file)\n* [content_by_lua_block](https://github.com/openresty/lua-nginx-module#content_by_lua_block)\n* [content_by_lua_file](https://github.com/openresty/lua-nginx-module#content_by_lua_file)\n* [balancer_by_lua_block](https://github.com/openresty/lua-nginx-module#balancer_by_lua_block)\n* [balancer_by_lua_file](https://github.com/openresty/lua-nginx-module#balancer_by_lua_file)\n* [log_by_lua_block](#log_by_lua_block)\n* [log_by_lua_file](#log_by_lua_file)\n* [ssl_client_hello_by_lua_block](https://github.com/openresty/lua-nginx-module#ssl_client_hello_by_lua_block)\n* [ssl_client_hello_by_lua_file](https://github.com/openresty/lua-nginx-module#ssl_client_hello_by_lua_file)\n* [ssl_certificate_by_lua_block](https://github.com/openresty/lua-nginx-module#ssl_certificate_by_lua_block)\n* [ssl_certificate_by_lua_file](https://github.com/openresty/lua-nginx-module#ssl_certificate_by_lua_file)\n* [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict)\n* [lua_socket_connect_timeout](https://github.com/openresty/lua-nginx-module#lua_socket_connect_timeout)\n* [lua_socket_buffer_size](https://github.com/openresty/lua-nginx-module#lua_socket_buffer_size)\n* [lua_socket_pool_size](https://github.com/openresty/lua-nginx-module#lua_socket_pool_size)\n* [lua_socket_keepalive_timeout](https://github.com/openresty/lua-nginx-module#lua_socket_keepalive_timeout)\n* [lua_socket_log_errors](https://github.com/openresty/lua-nginx-module#lua_socket_log_errors)\n* [lua_ssl_ciphers](https://github.com/openresty/lua-nginx-module#lua_ssl_ciphers)\n* [lua_ssl_crl](https://github.com/openresty/lua-nginx-module#lua_ssl_crl)\n* [lua_ssl_protocols](https://github.com/openresty/lua-nginx-module#lua_ssl_protocols)\n* [lua_ssl_certificate](https://github.com/openresty/lua-nginx-module#lua_ssl_certificate)\n* [lua_ssl_certificate_key](https://github.com/openresty/lua-nginx-module#lua_ssl_certificate_key)\n* [lua_ssl_trusted_certificate](https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate)\n* [lua_ssl_verify_depth](https://github.com/openresty/lua-nginx-module#lua_ssl_verify_depth)\n* [lua_ssl_conf_command](https://github.com/openresty/lua-nginx-module#lua_ssl_conf_command)\n* [lua_check_client_abort](https://github.com/openresty/lua-nginx-module#lua_check_client_abort)\n* [lua_max_pending_timers](https://github.com/openresty/lua-nginx-module#lua_max_pending_timers)\n* [lua_max_running_timers](https://github.com/openresty/lua-nginx-module#lua_max_running_timers)\n* [lua_sa_restart](https://github.com/openresty/lua-nginx-module#lua_sa_restart)\n* [lua_add_variable](#lua_add_variable)\n* [lua_capture_error_log](https://github.com/openresty/lua-nginx-module#lua_capture_error_log)\n* [preread_by_lua_no_postpone](#preread_by_lua_no_postpone)\n\nThe [send_timeout](https://nginx.org/r/send_timeout) directive in the Nginx\n\"http\" subsystem is missing in the \"stream\" subsystem. As such,\nngx_stream_lua_module uses the `lua_socket_send_timeout` directive for this\npurpose instead.\n\n**Note:** the lingering close directive that used to exist in older version of\n`stream_lua_nginx_module` has been removed and can now be simulated with the\nnewly added [tcpsock:shutdown](#tcpsockshutdown) API if necessary.\n\n[Back to TOC](#table-of-contents)\n\npreread_by_lua_block\n--------------------\n\n**syntax:** *preread_by_lua_block { lua-script }*\n\n**context:** *stream, server*\n\n**phase:** *preread*\n\nActs as a `preread` phase handler and executes Lua code string specified in `lua-script` for every connection\n(or packet in datagram mode).\nThe Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox).\n\nIt is possible to acquire the raw request socket using [ngx.req.socket](https://github.com/openresty/lua-nginx-module#ngxreqsocket)\nand receive data from or send data to the client. However, keep in mind that calling the `receive()` method\nof the request socket will consume the data from the buffer and such consumed data will not be seen by handlers\nfurther down the chain.\n\nThe `preread_by_lua_block` code will always run at the end of the `preread` processing phase unless\n[preread\\_by\\_lua\\_no\\_postpone](#preread_by_lua_no_postpone) is turned on.\n\nThis directive was first introduced in the `v0.0.3` release.\n\n[Back to TOC](#directives)\n\npreread_by_lua_file\n-------------------\n\n**syntax:** *preread_by_lua_file \u0026lt;path-to-lua-script-file\u0026gt;*\n\n**context:** *stream, server*\n\n**phase:** *preread*\n\nEquivalent to [preread_by_lua_block](#preread_by_lua_block), except that the file specified by `\u003cpath-to-lua-script-file\u003e` contains the Lua code\nor LuaJIT bytecode to be executed.\n\nNginx variables can be used in the `\u003cpath-to-lua-script-file\u003e` string to provide flexibility. This however carries some risks and is not ordinarily recommended.\n\nWhen a relative path like `foo/bar.lua` is given, it will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option given when starting the Nginx server.\n\nWhen the Lua code cache is turned on (by default), the user code is loaded once at the first connection and cached. The Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid having to reload Nginx.\n\nThis directive was first introduced in the `v0.0.3` release.\n\n[Back to TOC](#directives)\n\nlog_by_lua_block\n----------------\n\n**syntax:** *log_by_lua_block { lua-script }*\n\n**context:** *stream, server*\n\n**phase:** *log*\n\nRuns the Lua source code specified as `\u003clua-script\u003e` during the `log` request processing phase. This does not replace the current access logs, but runs before.\n\nYielding APIs such as `ngx.req.socket`, `ngx.socket.*`, `ngx.sleep`, or `ngx.say` are **not** available in this phase.\n\nThis directive was first introduced in the `v0.0.3` release.\n\n[Back to TOC](#directives)\n\nlog_by_lua_file\n---------------\n\n**syntax:** *log_by_lua_file \u0026lt;path-to-lua-script-file\u0026gt;*\n\n**context:** *stream, server*\n\n**phase:** *log*\n\nEquivalent to [log_by_lua_block](#log_by_lua_block), except that the file specified by `\u003cpath-to-lua-script-file\u003e` contains the Lua code\nor LuaJIT bytecode to be executed.\n\nNginx variables can be used in the `\u003cpath-to-lua-script-file\u003e` string to provide flexibility. This however carries some risks and is not ordinarily recommended.\n\nWhen a relative path like `foo/bar.lua` is given, it will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option given when starting the Nginx server.\n\nWhen the Lua code cache is turned on (by default), the user code is loaded once at the first connection and cached. The Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid having to reload Nginx.\n\nThis directive was first introduced in the `v0.0.3` release.\n\n[Back to TOC](#directives)\n\nlua_add_variable\n----------------\n\n**syntax:** *lua_add_variable $var*\n\n**context:** *stream*\n\nAdd the variable `$var` to the \"stream\" subsystem and makes it changeable. If `$var` already exists,\nthis directive will do nothing.\n\nBy default, variables added using this directive are considered \"not found\" and reading them\nusing `ngx.var` will return `nil`. However, they could be re-assigned via the `ngx.var.VARIABLE` API at any time.\n\nThis directive was first introduced in the `v0.0.4` release.\n\n[Back to TOC](#directives)\n\npreread_by_lua_no_postpone\n--------------------------\n\n**syntax:** *preread_by_lua_no_postpone on|off*\n\n**context:** *stream*\n\nControls whether or not to disable postponing [preread\\_by\\_lua*](#preread_by_lua_block) directives\nto run at the end of the `preread` processing phase. By default, this directive is turned off\nand the Lua code is postponed to run at the end of the `preread` phase.\n\nThis directive was first introduced in the `v0.0.4` release.\n\n[Back to TOC](#directives)\n\nNginx API for Lua\n-----------------\n\nMany Lua API functions are ported from ngx_http_lua. Check out the official\nmanual of ngx_http_lua for more details on these Lua API functions.\n\n* [ngx.var.VARIABLE](https://github.com/openresty/lua-nginx-module#ngxvarvariable)\n\nThis module fully supports the new variable subsystem inside the Nginx stream core. You may access any\n[built-in variables](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#variables) provided by the stream core or\nother stream modules.\n* [Core constants](https://github.com/openresty/lua-nginx-module#core-constants)\n\n    `ngx.OK`, `ngx.ERROR`, and etc.\n* [Nginx log level constants](https://github.com/openresty/lua-nginx-module#nginx-log-level-constants)\n\n    `ngx.ERR`, `ngx.WARN`, and etc.\n* [print](https://github.com/openresty/lua-nginx-module#print)\n* [ngx.ctx](https://github.com/openresty/lua-nginx-module#ngxctx)\n* [ngx.balancer](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md)\n\n* [ngx.req.socket](https://github.com/openresty/lua-nginx-module#ngxreqsocket)\n\nOnly raw request sockets are supported, for obvious reasons. The `raw` argument value\nis ignored and the raw request socket is always returned. Unlike ngx_http_lua,\nyou can still call output API functions like `ngx.say`, `ngx.print`, and `ngx.flush`\nafter acquiring the raw request socket via this function.\n\nWhen the stream server is in UDP mode, reading from the downstream socket returned by the\n`ngx.req.socket` call will only return the content of a single packet. Therefore\nthe reading call will never block and will return `nil, \"no more data\"` when all the\ndata from the datagram has been consumed. However, you may choose to send multiple UDP\npackets back to the client using the downstream socket.\n\nThe raw TCP sockets returned by this module will contain the following extra method:\n\n[Back to TOC](#directives)\n\nreqsock:receiveany\n------------------\n\n**syntax:** *data, err = reqsock:receiveany(max)*\n\n**context:** *content_by_lua\u0026#42;, ngx.timer.\u0026#42;, ssl_certificate_by_lua\u0026#42;*\n\nThis method is similar to [tcpsock:receiveany](https://github.com/openresty/lua-nginx-module#tcpsockreceiveany) method\n\nThis method was introduced into `stream-lua-nginx-module` since `v0.0.8`.\n\n[Back to TOC](#directives)\n\ntcpsock:shutdown\n----------------\n\n**syntax:** *ok, err = tcpsock:shutdown(\"send\")*\n\n**context:** *content_by_lua\u0026#42;*\n\nShuts down the write part of the request socket, prevents all further writing to the client\nand sends TCP FIN, while keeping the reading half open.\n\nCurrently only the `\"send\"` direction is supported. Using any parameters other than \"send\" will return\nan error.\n\nIf you called any output functions (like [ngx.say](https://github.com/openresty/lua-nginx-module#ngxsay))\nbefore calling this method, consider use `ngx.flush(true)` to make sure all busy buffers are complely\nflushed before shutting down the socket. If any busy buffers were detected, this method will return `nil`\nwill error message `\"socket busy writing\"`.\n\nThis feature is particularly useful for protocols that generate a response before actually\nfinishing consuming all incoming data. Normally, the kernel will send RST to the client when\n[tcpsock:close](https://github.com/openresty/lua-nginx-module#tcpsockclose) is called without\nemptying the receiving buffer first. Calling this method will allow you to keep reading from\nthe receiving buffer and prevents RST from being sent.\n\nYou can also use this method to simulate lingering close similar to that\n[provided by the ngx_http_core_module](https://nginx.org/en/docs/http/ngx_http_core_module.html#lingering_close)\nfor protocols in need of such behavior. Here is an example:\n\n```lua\nlocal LINGERING_TIME = 30 -- 30 seconds\nlocal LINGERING_TIMEOUT = 5000 -- 5 seconds\n\nlocal ok, err = sock:shutdown(\"send\")\nif not ok then\n    ngx.log(ngx.ERR, \"failed to shutdown: \", err)\n    return\nend\n\nlocal deadline = ngx.time() + LINGERING_TIME\n\nsock:settimeouts(nil, nil, LINGERING_TIMEOUT)\n\nrepeat\n    local data, _, partial = sock:receive(1024)\nuntil (not data and not partial) or ngx.time() \u003e= deadline\n```\n\n[Back to TOC](#directives)\n\nreqsock:peek\n------------\n\n**syntax:** *ok, err = reqsock:peek(size)*\n\n**context:** *preread_by_lua\u0026#42;*\n\nPeeks into the [preread](https://nginx.org/en/docs/stream/stream_processing.html#preread_phase)\nbuffer that contains downstream data sent by the client without consuming them.\nThat is, data returned by this API will still be forwarded upstream in later phases.\n\nThis function takes a single required argument, `size`, which is the number of bytes to be peeked.\nRepeated calls to this function always returns data from the beginning of the preread buffer.\n\nNote that preread phase happens after the TLS handshake. If the stream server was configured with\nTLS enabled, the returned data will be in clear text.\n\nIf preread buffer does not have the requested amount of data, then the current Lua thread will\nbe yielded until more data is available, [`preread_buffer_size`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#preread_buffer_size)\nhas been exceeded, or [`preread_timeout`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#preread_timeout)\nhas elapsed. Successful calls always return the requested amounts of data, that is, no partial\ndata will be returned.\n\nWhen [`preread_buffer_size`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#preread_buffer_size)\nhas been exceeded, the current stream session will be terminated with the\n[session status code](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status) `400`\nimmediately by the stream core module, with error message `\"preread buffer full\"` that will be printed to the error log.\n\nWhen [`preread_timeout`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#preread_timeout) has been exceeded,\nthe current stream session will be terminated with the\n[session status code](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#var_status) `200` immediately by the stream core module.\n\nIn both cases, no further processing on the session is possible (except `log_by_lua*`). The connection will be closed by the\nstream core module automatically.\n\nNote that this API cannot be used if consumption of client data has occurred. For example, after calling\n`reqsock:receive`. If such an attempt was made, the Lua error `\"attempt to peek on a consumed socket\"` will\nbe thrown. Consuming client data after calling this API is allowed and safe.\n\nHere is an example of using this API:\n\n```lua\nlocal sock = assert(ngx.req.socket())\n\nlocal data = assert(sock:peek(1)) -- peek the first 1 byte that contains the length\ndata = string.byte(data)\n\ndata = assert(sock:peek(data + 1)) -- peek the length + the size byte\n\nlocal payload = data:sub(2) -- trim the length byte to get actual payload\n\nngx.log(ngx.INFO, \"payload is: \", payload)\n```\n\nThis API was first introduced in the `v0.0.6` release.\n\n[Back to TOC](#directives)\n\n* [ngx.print](https://github.com/openresty/lua-nginx-module#ngxprint)\n* [ngx.say](https://github.com/openresty/lua-nginx-module#ngxsay)\n* [ngx.log](https://github.com/openresty/lua-nginx-module#ngxlog)\n* [ngx.flush](https://github.com/openresty/lua-nginx-module#ngxflush)\n\n    This call currently ignores the `wait` argument and always wait for all the pending\noutput to be completely flushed out (to the system socket send buffers).\n* [ngx.exit](https://github.com/openresty/lua-nginx-module#ngxexit)\n* [ngx.eof](https://github.com/openresty/lua-nginx-module#ngxeof)\n* [ngx.sleep](https://github.com/openresty/lua-nginx-module#ngxsleep)\n* [ngx.escape_uri](https://github.com/openresty/lua-nginx-module#ngxescape_uri)\n* [ngx.unescape_uri](https://github.com/openresty/lua-nginx-module#ngxunescape_uri)\n* [ngx.encode_args](https://github.com/openresty/lua-nginx-module#ngxencode_args)\n* [ngx.decode_args](https://github.com/openresty/lua-nginx-module#ngxdecode_args)\n* [ngx.encode_base64](https://github.com/openresty/lua-nginx-module#ngxencode_base64)\n* [ngx.decode_base64](https://github.com/openresty/lua-nginx-module#ngxdecode_base64)\n* [ngx.crc32_short](https://github.com/openresty/lua-nginx-module#ngxcrc32_short)\n* [ngx.crc32_long](https://github.com/openresty/lua-nginx-module#ngxcrc32_long)\n* [ngx.hmac_sha1](https://github.com/openresty/lua-nginx-module#ngxhmac_sha1)\n* [ngx.md5](https://github.com/openresty/lua-nginx-module#ngxmd5)\n* [ngx.md5_bin](https://github.com/openresty/lua-nginx-module#ngxmd5_bin)\n* [ngx.sha1_bin](https://github.com/openresty/lua-nginx-module#ngxsha1_bin)\n* [ngx.quote_sql_str](https://github.com/openresty/lua-nginx-module#ngxquote_sql_str)\n* [ngx.today](https://github.com/openresty/lua-nginx-module#ngxtoday)\n* [ngx.time](https://github.com/openresty/lua-nginx-module#ngxtime)\n* [ngx.now](https://github.com/openresty/lua-nginx-module#ngxnow)\n* [ngx.update_time](https://github.com/openresty/lua-nginx-module#ngxupdate_time)\n* [ngx.localtime](https://github.com/openresty/lua-nginx-module#ngxlocaltime)\n* [ngx.utctime](https://github.com/openresty/lua-nginx-module#ngxutctime)\n* [ngx.re.match](https://github.com/openresty/lua-nginx-module#ngxrematch)\n* [ngx.re.find](https://github.com/openresty/lua-nginx-module#ngxrefind)\n* [ngx.re.gmatch](https://github.com/openresty/lua-nginx-module#ngxregmatch)\n* [ngx.re.sub](https://github.com/openresty/lua-nginx-module#ngxresub)\n* [ngx.re.gsub](https://github.com/openresty/lua-nginx-module#ngxregsub)\n* [ngx.shared.DICT](https://github.com/openresty/lua-nginx-module#ngxshareddict)\n* [ngx.socket.tcp](https://github.com/openresty/lua-nginx-module#ngxsockettcp)\n* [ngx.socket.udp](https://github.com/openresty/lua-nginx-module#ngxsocketudp)\n* [ngx.socket.connect](https://github.com/openresty/lua-nginx-module#ngxsocketconnect)\n* [ngx.get_phase](https://github.com/openresty/lua-nginx-module#ngxget_phase)\n* [ngx.thread.spawn](https://github.com/openresty/lua-nginx-module#ngxthreadspawn)\n* [ngx.thread.wait](https://github.com/openresty/lua-nginx-module#ngxthreadwait)\n* [ngx.thread.kill](https://github.com/openresty/lua-nginx-module#ngxthreadkill)\n* [ngx.on_abort](https://github.com/openresty/lua-nginx-module#ngxon_abort)\n* [ngx.timer.at](https://github.com/openresty/lua-nginx-module#ngxtimerat)\n* [ngx.timer.running_count](https://github.com/openresty/lua-nginx-module#ngxtimerrunning_count)\n* [ngx.timer.pending_count](https://github.com/openresty/lua-nginx-module#ngxtimerpending_count)\n* [ngx.config.debug](https://github.com/openresty/lua-nginx-module#ngxconfigdebug)\n* [ngx.config.subsystem](https://github.com/openresty/lua-nginx-module#ngxconfigsubsystem)\n\n    Always takes the Lua string value `\"stream\"` in this module.\n* [ngx.config.prefix](https://github.com/openresty/lua-nginx-module#ngxconfigprefix)\n* [ngx.config.nginx_version](https://github.com/openresty/lua-nginx-module#ngxconfignginx_version)\n* [ngx.config.nginx_configure](https://github.com/openresty/lua-nginx-module#ngxconfignginx_configure)\n* [ngx.config.ngx_lua_version](https://github.com/openresty/lua-nginx-module#ngxconfigngx_lua_version)\n* [ngx.worker.exiting](https://github.com/openresty/lua-nginx-module#ngxworkerexiting)\n* [ngx.worker.pid](https://github.com/openresty/lua-nginx-module#ngxworkerpid)\n* [ngx.worker.pids](https://github.com/openresty/lua-nginx-module#ngxworkerpids)\n* [ngx.worker.count](https://github.com/openresty/lua-nginx-module#ngxworkercount)\n* [ngx.worker.id](https://github.com/openresty/lua-nginx-module#ngxworkerid)\n* [coroutine.create](https://github.com/openresty/lua-nginx-module#coroutinecreate)\n* [coroutine.resume](https://github.com/openresty/lua-nginx-module#coroutineresume)\n* [coroutine.yield](https://github.com/openresty/lua-nginx-module#coroutineyield)\n* [coroutine.wrap](https://github.com/openresty/lua-nginx-module#coroutinewrap)\n* [coroutine.running](https://github.com/openresty/lua-nginx-module#coroutinerunning)\n* [coroutine.status](https://github.com/openresty/lua-nginx-module#coroutinestatus)\n\n[Back to TOC](#table-of-contents)\n\nTODO\n====\n\n* Add new directives `access_by_lua_block` and `access_by_lua_file`.\n* Add `lua_postpone_output` to emulate the [postpone_output](https://nginx.org/r/postpone_output) directive.\n\n[Back to TOC](#table-of-contents)\n\nNginx Compatibility\n===================\n\nThe latest version of this module is compatible with the following versions of Nginx:\n\n* 1.25.x (last tested: 1.25.1)\n* 1.21.x (last tested: 1.21.4)\n* 1.19.x (last tested: 1.19.3)\n* 1.17.x (last tested: 1.17.8)\n* 1.15.x (last tested: 1.15.8)\n* 1.13.x (last tested: 1.13.6)\n\nNginx cores older than 1.13.6 (exclusive) are *not* tested and may or may not\nwork. Use at your own risk!\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nIt is *highly* recommended to use [OpenResty releases](https://openresty.org)\nwhich bundle Nginx, ngx_http_lua, ngx_stream_lua, (this module), LuaJIT, as\nwell as other powerful companion Nginx modules and Lua libraries.\n\nIt is discouraged to build this module with Nginx yourself since it is tricky\nto set up exactly right.\n\nNote that Nginx, LuaJIT, and OpenSSL official releases have various limitations\nand long standing bugs that can cause some of this module's features to be\ndisabled, not work properly, or run slower. Official OpenResty releases are\nrecommended because they bundle [OpenResty's optimized LuaJIT 2.1 fork](https://github.com/openresty/luajit2) and\n[Nginx/OpenSSL\npatches](https://github.com/openresty/openresty/tree/master/patches).\n\nAlternatively, ngx_stream_lua can be manually compiled into Nginx:\n\n1. LuaJIT can be downloaded from the [latest release of OpenResty's LuaJIT fork](https://github.com/openresty/luajit2/releases). The official LuaJIT 2.x releases are also supported, although performance will be significantly lower for reasons elaborated above\n1. Download the latest version of ngx_stream_lua [HERE](https://github.com/openresty/stream-lua-nginx-module/tags)\n1. Download the latest supported version of Nginx [HERE](https://nginx.org/) (See [Nginx Compatibility](#nginx-compatibility))\n\nBuild the source with this module:\n\n```bash\nwget 'https://nginx.org/download/nginx-1.13.6.tar.gz'\ntar -xzvf nginx-1.13.6.tar.gz\ncd nginx-1.13.6/\n\n# tell nginx's build system where to find LuaJIT 2.1:\nexport LUAJIT_LIB=/path/to/luajit/lib\nexport LUAJIT_INC=/path/to/luajit/include/luajit-2.1\n\n# Here we assume Nginx is to be installed under /opt/nginx/.\n./configure --prefix=/opt/nginx \\\n        --with-ld-opt=\"-Wl,-rpath,/path/to/luajit-or-lua/lib\" \\\n        --with-stream \\\n        --with-stream_ssl_module \\\n        --add-module=/path/to/stream-lua-nginx-module\n\n# Build and install\nmake -j4\nmake install\n```\n\nYou may use `--without-http` if you do not wish to use this module with the\n\"http\" subsystem. ngx_stream_lua will work perfectly fine without the \"http\"\nsubsystem.\n\n[Back to TOC](#table-of-contents)\n\nCommunity\n=========\n\n[Back to TOC](#table-of-contents)\n\nEnglish Mailing List\n--------------------\n\nThe [openresty-en](https://groups.google.com/group/openresty-en) mailing list is for English speakers.\n\n[Back to TOC](#table-of-contents)\n\nChinese Mailing List\n--------------------\n\nThe [openresty](https://groups.google.com/group/openresty) mailing list is for Chinese speakers.\n\n[Back to TOC](#table-of-contents)\n\nCode Repository\n===============\n\nThe code repository of this project is hosted on GitHub at\n[openresty/stream-lua-nginx-module](https://github.com/openresty/stream-lua-nginx-module).\n\n[Back to TOC](#table-of-contents)\n\nBugs and Patches\n================\n\nPlease submit bug reports, wishlists, or patches by\n\n1. creating a ticket on the [GitHub Issue Tracker](https://github.com/openresty/stream-lua-nginx-module/issues),\n1. or posting to the [OpenResty community](#community).\n\n[Back to TOC](#table-of-contents)\n\nAcknowledgments\n===============\n\nWe appreciate [Kong Inc.](https://konghq.com/) for kindly sponsoring [OpenResty Inc.](https://openresty.com/) on the following\nwork:\n* Compatibility with Nginx core 1.13.3.\n* Development of [meta-lua-nginx-module](https://github.com/openresty/meta-lua-nginx-module)\nto make code sharing between this module and [lua-nginx-module](https://github.com/openresty/lua-nginx-module) possible.\n* `balancer_by_lua_*`, `preread_by_lua_*`, `log_by_lua_*` and `ssl_certby_lua*` phases support.\n* [`reqsock:peek`](#reqsockpeek) API support.\n\n[Back to TOC](#table-of-contents)\n\nCopyright and License\n=====================\n\nThis module is licensed under the BSD license.\n\nCopyright (C) 2009-2019, by Yichun \"agentzh\" Zhang (章亦春) \u003cagentzh@gmail.com\u003e, OpenResty Inc.\n\nCopyright (C) 2009-2016, by Xiaozhe Wang (chaoslawful) \u003cchaoslawful@gmail.com\u003e.\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[Back to TOC](#table-of-contents)\n\nSee Also\n========\n\n* [ngx_http_lua_module](https://github.com/openresty/lua-nginx-module)\n* [ngx_stream_echo_module](https://github.com/openresty/stream-echo-nginx-module)\n* [OpenResty](https://openresty.org/)\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fstream-lua-nginx-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Fstream-lua-nginx-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fstream-lua-nginx-module/lists"}