• Stars
    star
    786
  • Rank 56,770 (Top 2 %)
  • Language
    Lua
  • Created about 11 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

New FFI-based API for lua-nginx-module

Name

lua-resty-core - New FFI-based Lua API for ngx_http_lua_module and/or ngx_stream_lua_module

Table of Contents

Status

This library is production ready.

Synopsis

This library is automatically loaded by default since OpenResty 1.15.8.1. This behavior can be disabled via the lua_load_resty_core directive, but note that the use of this library is vividly recommended, as its FFI implementation is both faster, safer, and more complete than the Lua C API of the ngx_lua module.

If you are using an older version of OpenResty, you must load this library like so:

    # nginx.conf

    http {
        # you do NOT need to configure the following line when you
        # are using the OpenResty bundle 1.4.3.9+.
        lua_package_path "/path/to/lua-resty-core/lib/?.lua;;";

        init_by_lua_block {
            require "resty.core"
            collectgarbage("collect")  -- just to collect any garbage
        }

        ...
    }

Description

This pure Lua library reimplements part of the ngx_lua module's Nginx API for Lua with LuaJIT FFI and installs the new FFI-based Lua API into the ngx.* and ndk.* namespaces used by the ngx_lua module.

In addition, this Lua library implements any significant new Lua APIs of the ngx_lua module as proper Lua modules, like ngx.semaphore and ngx.balancer.

The FFI-based Lua API can work with LuaJIT's JIT compiler. ngx_lua's default API is based on the standard Lua C API, which will never be JIT compiled and the user Lua code is always interpreted (slowly).

Support for the new ngx_stream_lua_module has also begun.

This library is shipped with the OpenResty bundle by default. So you do not really need to worry about the dependencies and requirements.

Back to TOC

Prerequisites

WARNING This library is included with every OpenResty release. You should use the bundled version of this library in the particular OpenResty release you are using. Otherwise you may run into serious compatibility issues.

Back to TOC

Installation

By default, LuaJIT will search Lua files in /usr/local/share/lua/5.1/. But make install will install this module to /usr/local/lib/lua. So you may find the error like this:

nginx: [alert] failed to load the 'resty.core' module

You can install this module with the following command to resolve the above problem.

cd lua-resty-core
sudo make install LUA_LIB_DIR=/usr/local/share/lua/5.1

You can also change the installation directory to any other directory you like with the LUA_LIB_DIR argument.

cd lua-resty-core
sudo make install LUA_LIB_DIR=/opt/nginx/lualib

After that, you need to add the above directory to the LuaJIT search direcotries with lua_package_path nginx directive in the http context and stream context.

lua_package_path "/opt/nginx/lualib/?.lua;;";

Back to TOC

API Implemented

Back to TOC

resty.core.hash

Back to TOC

resty.core.base64

Back to TOC

resty.core.uri

Back to TOC

resty.core.regex

Back to TOC

resty.core.exit

Back to TOC

resty.core.shdict

Back to TOC

resty.core.var

Back to TOC

resty.core.ctx

Back to TOC

get_ctx_table

syntax: ctx = resty.core.ctx.get_ctx_table(ctx?)

Similar to ngx.ctx but it accepts an optional ctx argument. It will use the ctx from caller instead of creating a new table when the ctx table does not exist.

Notice: the ctx table will be used in the current request's whole life cycle. Please be very careful when you try to reuse the ctx table. You need to make sure there is no Lua code using or going to use the ctx table in the current request before you reusing the ctx table in some other place.

Back to TOC

resty.core.request

Back to TOC

resty.core.response

Back to TOC

resty.core.misc

Back to TOC

resty.core.time

Back to TOC

resty.core.worker

Back to TOC

resty.core.phase

Back to TOC

resty.core.ndk

Back to TOC

resty.core.socket

Back to TOC

resty.core.param

Back to TOC

ngx.semaphore

This Lua module implements a semaphore API for efficient "light thread" synchronization, which can work across different requests (but not across nginx worker processes).

See the documentation for this Lua module for more details.

Back to TOC

ngx.balancer

This Lua module implements for defining dynamic upstream balancers in Lua.

See the documentation for this Lua module for more details.

Back to TOC

ngx.ssl

This Lua module provides a Lua API for controlling SSL certificates, private keys, SSL protocol versions, and etc in NGINX downstream SSL handshakes.

See the documentation for this Lua module for more details.

Back to TOC

ngx.ssl.clienthello

This Lua module provides a Lua API for post-processing SSL client hello message for NGINX downstream SSL connections.

See the documentation for this Lua module for more details.

Back to TOC

ngx.ssl.session

This Lua module provides a Lua API for manipulating SSL session data and IDs for NGINX downstream SSL connections.

See the documentation for this Lua module for more details.

Back to TOC

ngx.re

This Lua module provides a Lua API which implements convenience utilities for the ngx.re API.

See the documentation for this Lua module for more details.

Back to TOC

ngx.resp

This Lua module provides Lua API which could be used to handle HTTP response.

See the documentation for this Lua module for more details.

Back to TOC

ngx.pipe

This module provides a Lua API to spawn processes and communicate with them in a non-blocking fashion.

See the documentation for this Lua module for more details.

This module was first introduced in lua-resty-core v0.1.16.

Back to TOC

ngx.process

This Lua module is used to manage the nginx process in Lua.

See the documentation for this Lua module for more details.

This module was first introduced in lua-resty-core v0.1.12.

Back to TOC

ngx.errlog

This Lua module provides Lua API to capture and manage nginx error log messages.

See the documentation for this Lua module for more details.

This module was first introduced in lua-resty-core v0.1.12.

Back to TOC

ngx.base64

This Lua module provides Lua API to urlsafe base64 encode/decode.

See the documentation for this Lua module for more details.

This module was first introduced in lua-resty-core v0.1.14.

Back to TOC

Caveat

If the user Lua code is not JIT compiled, then use of this library may lead to performance drop in interpreted mode. You will only observe speedup when you get a good part of your user Lua code JIT compiled.

Back to TOC

TODO

  • Re-implement ngx_lua's cosocket API with FFI.
  • Re-implement ngx_lua's ngx.eof and ngx.flush API functions with FFI.

Back to TOC

Author

Yichun "agentzh" Zhang (章亦春) [email protected], OpenResty Inc.

Back to TOC

Copyright and License

This module is licensed under the BSD license.

Copyright (C) 2013-2019, by Yichun "agentzh" Zhang, OpenResty Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • 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.

THIS 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.

Back to TOC

See Also

Back to TOC

More Repositories

1

openresty

High Performance Web Platform Based on Nginx and LuaJIT
C
12,238
star
2

lua-nginx-module

Embed the Power of Lua into NGINX HTTP servers
C
11,133
star
3

nginx-tutorials

Nginx Tutorials
Perl
2,855
star
4

lua-resty-redis

Lua redis client driver for the ngx_lua based on the cosocket API
Lua
1,876
star
5

openresty-systemtap-toolkit

Real-time analysis and diagnostics tools for OpenResty (including NGINX, LuaJIT, ngx_lua, and more) based on SystemTap
Perl
1,651
star
6

headers-more-nginx-module

Set, add, and clear arbitrary output headers in NGINX http servers
C
1,609
star
7

openresty.org

Code and data for the openresty.org site
HTML
1,259
star
8

luajit2

OpenResty's Branch of LuaJIT 2
C
1,196
star
9

echo-nginx-module

An Nginx module for bringing the power of "echo", "sleep", "time" and more to Nginx's config file
C
1,150
star
10

docker-openresty

Docker tooling for OpenResty
Dockerfile
922
star
11

redis2-nginx-module

Nginx upstream module for the Redis 2.0 protocol
C
901
star
12

lua-resty-limit-traffic

Lua library for limiting and controlling traffic in OpenResty/ngx_lua
Lua
808
star
13

stream-lua-nginx-module

Embed the power of Lua into NGINX TCP/UDP servers
C
714
star
14

lua-resty-mysql

Nonblocking Lua MySQL driver library for ngx_lua or OpenResty
Lua
699
star
15

stapxx

Simple macro language extentions to systemtap
Perl
689
star
16

sregex

A non-backtracking NFA/DFA-based Perl-compatible regex engine matching on large data streams
C
615
star
17

lua-resty-upstream-healthcheck

Health Checker for Nginx Upstream Servers in Pure Lua
Lua
510
star
18

lua-resty-websocket

WebSocket support for the ngx_lua module (and OpenResty)
Lua
498
star
19

lua-upstream-nginx-module

Nginx C module to expose Lua API to ngx_lua for Nginx upstreams
C
496
star
20

srcache-nginx-module

Transparent subrequest-based caching layout for arbitrary nginx locations.
C
469
star
21

opm

OpenResty Package Manager
Lua
458
star
22

lua-resty-lrucache

Lua-land LRU Cache based on LuaJIT FFI
Lua
434
star
23

test-nginx

Data-driven test scaffold for Nginx C module and OpenResty Lua library development
Perl
434
star
24

lua-resty-string

String utilities and common hash functions for ngx_lua and LuaJIT
Lua
423
star
25

lua-resty-upload

Streaming reader and parser for http file uploading based on ngx_lua cosocket
Lua
396
star
26

set-misc-nginx-module

Various set_xxx directives added to nginx's rewrite module (md5/sha1, sql/json quoting, and many more)
C
384
star
27

drizzle-nginx-module

an nginx upstream module that talks to mysql and drizzle by libdrizzle
C
336
star
28

openresty-gdb-utils

GDB Utilities for OpenResty (including Nginx, ngx_lua, LuaJIT, and more)
Python
331
star
29

lua-resty-dns

DNS resolver for the nginx lua module
Lua
320
star
30

lua-resty-balancer

A generic consistent hash implementation for OpenResty/Lua
Lua
320
star
31

programming-openresty

Programming OpenResty Book
Perl
316
star
32

lua-resty-lock

Simple nonblocking lock API for ngx_lua based on shared memory dictionaries
Lua
303
star
33

openresty-devel-utils

Utilities for nginx module development
Perl
265
star
34

resty-cli

Fancy command-line utilities for OpenResty
Perl
261
star
35

replace-filter-nginx-module

Streaming regular expression replacement in response bodies
C
257
star
36

memc-nginx-module

An extended version of the standard memcached module that supports set, add, delete, and many more memcached commands.
C
212
star
37

lua-resty-memcached

Lua memcached client driver for the ngx_lua based on the cosocket API
Lua
210
star
38

encrypted-session-nginx-module

encrypt and decrypt nginx variable values
C
197
star
39

openresty-packaging

Official OpenResty packaging source and scripts for various Linux distributions and other systems
Makefile
174
star
40

rds-json-nginx-module

An nginx output filter that formats Resty DBD Streams generated by ngx_drizzle and others to JSON
C
154
star
41

xss-nginx-module

Native support for cross-site scripting (XSS) in an nginx
C
147
star
42

mockeagain

Mocking ideally slow network that only allows reading and/or writing one byte at a time
C
128
star
43

lua-resty-shell

Lua module for nonblocking system shell command executions
Perl
122
star
44

lua-tablepool

Lua table recycling pools for LuaJIT
Perl
112
star
45

lua-redis-parser

Lua module for parsing raw redis responses
C
93
star
46

openresty-survey

OpenResty Web App for OpenResty User Survey
HTML
90
star
47

lua-ssl-nginx-module

NGINX C module that extends ngx_http_lua_module for enhanced SSL/TLS capabilities
Lua
86
star
48

opsboy

A rule-based sysadmin tool that helps setting up complex environment for blank machines
Perl
83
star
49

no-pool-nginx

replace nginx's pool mechanism with plain malloc & free to help tools like valgrind
Shell
77
star
50

stream-echo-nginx-module

TCP/stream echo module for NGINX (a port of ngx_http_echo_module)
C
70
star
51

meta-lua-nginx-module

Meta Lua Nginx Module supporting both Http Lua Module and Stream Lua Module
C
66
star
52

array-var-nginx-module

Add support for array-typed variables to nginx config files
C
66
star
53

lemplate

OpenResty/Lua template framework implementing Perl's TT2 templating language
Perl
53
star
54

openresty-con

JavaScript
47
star
55

nginx-dtrace

An nginx fork that adds dtrace USDT probes
C
44
star
56

orbpf-ko

The orbpf (eBPF+) Linux kernel module from OpenResty Inc.
C
37
star
57

lua-resty-memcached-shdict

Powerful memcached client with a shdict caching layer and many other features
Lua
33
star
58

lua-resty-shdict-simple

Simple applicaton-oriented interface to the OpenResty shared dictionary API
Perl
32
star
59

lua-resty-signal

Lua library for killing or sending signals to UNIX processes
Perl
31
star
60

luajit2-test-suite

OpenResty's LuaJIT test suite based on Mike Pall's LuaJIT tests
Lua
29
star
61

ngx_postgres

OpenResty's fork of FRiCKLE/ngx_postgres
C
26
star
62

rds-csv-nginx-module

Nginx output filter module to convert Resty-DBD-Streams (RDS) to Comma-Separated Values (CSV)
C
22
star
63

showman-samples

Sample screenplay files for generating our public video tutorials using OpenResty Showman
20
star
64

lua-rds-parser

Resty DBD Stream (RDS) parser for Lua written in C
C
19
star
65

redis-nginx-module

8
star
66

AB-test-http

test http requests between two systems.
Perl
5
star
67

transparency

2
star