saks/lua-resty-repl

Interactive console (REPL) for Openresty and luajit code

Welcome to Resty Repl

Features

Resty Repl is a powerful alternative to the standard luajit shell ispired by pry. It is written from scratch to provide a number of advanced features, including:

• Full read/write access to locals, upvalues and global variables
• Pretty print for objects
• A Powerful and flexible command system
• Ability to view and replay history
• Ability to see a context and source of the place in code from where repl was started
• Runtime invocation (use Resty Repl as a developer console or debugger)
• Tab completion
• Simple and easy way to debug lua running in the nginx (openresty)

Runtime invocation

First install luarock

luarocks install lua-resty-repl

Then just drop this snippet anywhere in your code:

require('resty.repl').start()

or run as cli:

resty-repl

Openresty debugger

But what makes it really nice is that now you can debug your openresty code right from running nginx!

master_process off;
error_log stderr notice;
daemon off;

events {
  worker_connections 1024;
}

http {
  server {
    listen 8080;
    lua_code_cache off;

    location / {
      content_by_lua_block {
        require('resty.repl').start()
      }
    }
  }
}

and start debugging:

$ curl -H X-Header:buz 172.17.0.2:8080?foo=bar

nginx -c /tmp/ngx.conf
2016/09/20 16:26:33 [alert] 2257#0: lua_code_cache is off; this will hurt performance in /tmp/ngx.conf:12
nginx: [alert] lua_code_cache is off; this will hurt performance in /tmp/ngx.conf:12
2016/09/20 16:26:33 [notice] 2257#0: using the "epoll" event method
2016/09/20 16:26:33 [notice] 2257#0: openresty/1.11.2.1
2016/09/20 16:26:33 [notice] 2257#0: built by gcc 4.9.2 (Debian 4.9.2-10)
2016/09/20 16:26:33 [notice] 2257#0: OS: Linux 4.4.0-38-generic
2016/09/20 16:26:33 [notice] 2257#0: getrlimit(RLIMIT_NOFILE): 65536:65536

From: content_by_lua(ngx.conf:17) @ line 2

[1] ngx(content)> ngx.req.get_headers()
=> {
  accept = "*/*",
  host = "172.17.0.2:8080",
  ["user-agent"] = "curl/7.47.0",
  ["x-header"] = "buz",
  <metatable> = {
    __index = <function 1>
  }
}
[2] ngx(content)> ngx.req.get_uri_args()
=> {
  foo = "bar"
}
[3] ngx(content)> ngx.say 'it works!'
=> 1
[4] ngx(content)> ngx.exit(ngx.OK)
172.17.0.1 - - [20/Sep/2016:16:26:50 +0000] "GET /?foo=bar HTTP/1.1" 200 20 "-" "curl/7.47.0"

Compatibility

Right now it's only compatible with:

• luajit
• lua5.1 (no readline)

Os Support

• GNU/Linux
• Mac OS

Roadmap

• colorized output
• smarter completion
• full readline support for lua (no ffi environments)
• remote debugger
• command for showing function source
• test suite with resty-cli, luajit and different versions of lua
• better inspect library

Code Status

License

resty-repl is released under the MIT License.

lua-resty-repl's Issues

history is not persisted

use ~/.luahistory file for history

make sure history file is writable or write to /tmp

Integrate with OpenResty Package Manager

https://github.com/openresty/opm

print doesn't work when debugging code in nginx

from standalone console:

$ make repl 
[1] ngx(timer)> print(123)
123
=> true

but when debugging nginx:

# nginx -c /tmp/ngx.conf 
... log messages here ...
[1] ngx(content)> print(123)
2016/09/23 12:52:05 [notice] 155#0: *1 [lua] [C]:-1: 123, client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "172.17.0.2:8080"
=> nil
[2] ngx(content)> 

print output appears in logs.
Would be nice if print can always print as expected.

make completion result more informative

Currently when looking at completion result, it's hard to understand, what is the type value of particular key:

[3] ngx(content)> ngx.loca        
ngx.localtime  ngx.location

where

• ngx.localtime is a function
• ngx.location is a table

Make it more information so it will be easy to make a difference between:

• table
• function
• userdata
• cdata (?)
• the rest of lua types

GitHub deprecated usage of unencrypted `git://` protocol last week, so luarocks can no longer install the package

GitHub deprecated usage of git:// (unencrypted Git protocol) on March 15th, 2022, so LuaRocks will fail to install any package including a source.url starting with git://. According to the LuaRocks documentation, the correct syntax for referencing https:// URLs is git+https://.

The solution is to change git:// to git+https:// in the rockspec file. I would open a PR for this, but I'm not sure your versioning process or which files to change. So I just wanted to leave the note here.

For anyone who sees this issue and is looking for a fix that doesn't require waiting for every luarocks package to update their rockspec files, here is a workaround, courtesy of stackoverflow:

git config --global url.https://github.com/.insteadOf git://github.com/

how to print variable a

`2016/12/14 17:25:46 [notice] 31488#31488: signal 17 (SIGCHLD) received
2016/12/14 17:25:46 [notice] 31488#31488: cache loader process 31491 exited with code 0
2016/12/14 17:25:46 [notice] 31488#31488: signal 29 (SIGIO) received
[1] ngx(content)> ngx.req.get_uri_args()
=> {
aa = "55",
h = "78",
nn = "90"
}
[2] ngx(content)>
[3] ngx(content)>
[4] ngx(content)>
[5] ngx(content)>
[6] ngx(content)>
[7] ngx(content)>
[8] ngx(content)>
[9] ngx(content)>
[10] ngx(content)> a
=> nil

`

`
nginx.conf
content_by_lua_file /data/a.lua;

require('resty.repl').start()
local a = 78
ngx.say(a)

`

variables with `false` values are not accessible

$ cat /tmp/1.lua

local up = false

local f = function()
    local x = false
    local y = true
    require('resty.repl').start()
end

f()

$ lua /tmp/1.lua 
[1] lua(main)> x
=> nil
[2] lua(main)> y
=> true
[3] lua(main)> up
=> nil

repl cannot be used from lua coroutine

resty-repl
[1] lua(main)> c = coroutine.create(function() require('resty.repl').start() end)
=> nil
[2] lua(main)> coroutine.resume(c)
=> { false, "/usr/local/share/lua/5.1/resty/repl/binding.lua:87: attempt to perform arithmetic on a nil value" }

install error when reload nginx

/usr/local/openresty/lualib/resty/repl/formatter.lua:1: module 'inspect' not found:
no field package.preload['inspect']
no file '/data1/inspect.lua'

make it possible to type multi-line code

cache docker image on CI

one way of doing this

Missing results in completion

$ make repl 
[1] ngx(timer)> ngx.E <TAB>
ngx.EMERG  ngx.ERR    ngx.ERROR  
[1] ngx(timer)> ngx.ERR <TAB>
ngx.ERR
[1] ngx(timer)> ngx.ERR

During second completion ngx.ERR and press TAB, there is the only completion result: ngx.ERR.
There must also be ngx.ERROR.

cannot print table-error

/app # resty-repl 
[1] lua(main)> x=function() error { a = 1 } end
=> nil
[2] lua(main)> x()
/usr/local/bin/lua: /usr/local/share/lua/5.1/resty/repl/formatter.lua:9: attempt to concatenate a table value
stack traceback:
	/usr/local/share/lua/5.1/resty/repl/formatter.lua:9: in function 'print'
	/usr/local/share/lua/5.1/resty/repl.lua:36: in function 'handle_input'
	/usr/local/share/lua/5.1/resty/repl.lua:51: in function 'start'
	...lib/luarocks/rocks/lua-resty-repl/0.0.6-0/bin/resty-repl:107: in main chunk
	[C]: at 0x55a1b3307a0e

strange behavior of Ctrl-C

When debugging lua code, it does nothing, just prints ^C.
When debugging nginx, it prints ^C and then nginx handles SIGINT.

Most reasonable behavior would be to:

1. show next prompt line
2. move cursor to the next line

add completion for "object:method" definition

Assume we have code like this:

local m = {}
function m:meth1() end
local mt = {}
function mt:meth2() end

and then

[1] lua(main)> m:

hit TAB, but no completion

invalid command is not stored in the history

[1] lua(main)> x+x
ERROR: [string "stdin"]:1: attempt to perform arithmetic on global 'x' (a nil value)
[2] lua(main)> 

there is no x+x command in history afterwards