Redbean web server debugging with ZeroBrane Studio

Redbean is a single file web server that runs on Linux, Windows, macOS and several other platforms and embeds Lua, SQLite, and a host of other useful components that are all available from Lua code. ZeroBrane Studio relies on Mobdebug for its debugging capabilities, which in turn requires luasocket, but redbean compiles all its components statically and doesn't yet support dynamic linking, so using luasocket wasn't an option. Fortunately, the author of redbean implemented a powerful UNIX module, which includes raw socket support, among other things. This was enough to implement a tiny Lua library that provides just enough methods to trick Mobdebug into thinking that it has luasocket available.

Redbean debugging

The redbean plugin that implements this integration is available in the plugin repository. Let's see how you can debug a Redbean script using this plugin.

ZeroBrane Studio configuration.

1. Get ZeroBrane Studio (1.60+). These instructions are for Windows, but the debugging should (and have been confirmed to) work on Linux and macOS as well.

2. Get redbean plugin and save it to HOME/.zbstudio/packages/ or ZBS/packages/ folder (where ZBS is the path to ZeroBrane Studio location and HOME is the path specified by the HOME environment variable); the first option may also be preferable for Mac OS X users as the packages/ folder may be overwritten during an application upgrade.

3. If you have redbean.com executable in your project folder or in one of the folders listed in the PATH environment variable, you can skip this step; if not, you can open ZeroBrane Studio config file (Edit | Preferences | Settings: User) and set path.redbean value pointing to the location of redbean.com executable. You'll need to restart the IDE for the configuration changes to have effect.

4. Start ZeroBrane Studio (zbstudio.exe or zbstudio.sh).

Script debugging.

Let's debug a simple Redbean script:

if MDB then MDB.on() end -- only needed when debugging .init.lua code
print("Hello from ZeroBrane Studio")
local a = 1
print("Hello from Redbean", a)
-- OnHttpRequest is executed on each request
function OnHttpRequest()
  local url = GetUrl()
  Write("inside request: " .. url)
end

Save it as .init.lua, set the project directory to the folder where you saved the script (Project | Project Directory | Set From Current File) and select Redbean as the current interpreter by going to Project | Lua Interpreter | Redbean (this option is only available when you have Redbean plugin already installed).

The last step is to add .init.lua file to your redbean.com file. If you are on Linux or macOS, you can use redbean.com -A .init.lua command. If you're on Windows, use zip.com archiver to add .init.lua to redbean.com.

Now if you Run the script, you should see the following output:

Hello from ZeroBrane Studio
Hello from Redbean	1
I2022-08-10T21:01:21.214333:tool/net/redbean.c:7067:redbean:10816] (srvr) listen http://192.168.1.8:8080
I2022-08-10T21:01:21+000000:tool/net/redbean.c:7067:redbean:10816] (srvr) listen http://127.0.0.1:8080

The first two lines came from the two print calls in .init.lua and the last two are the log messages from redbean.

There are a couple of things worth mentioning: the first line with a check for MDB enables debugging of .init.lua code itself; the MDB value is only set when debugging is requested from the IDE, so it can be left in, as the script will be executed correctly outside of the IDE as well.

If you set a breakpoint on line 4 and select Debug, you should see the debugging started and suspended at line 4:

Redbean debugging

You should now be able to step through the script, look at the stack trace, and use all other debugging functionality available in ZeroBrane Studio. For example, you can use the Remote console tab to get the value of local variable and change them (as shown in the screenshot). If you continue the execution of the script (using Run) or step through the next line (using Step), you should see "Hello from Redbean 11" printed:

More Redbean debugging

You can also set breakpoints inside the OnHttpRequest function, so if you set a breakpoint on line 8, execute Run and point your browser to http://localhost:8080/, you should see the execution stopped on that breakpoint (and the Output updated with a new log message from the request). You can now inspect the value of any script variable and run any other Redbean commands (like GetHeader, SetHeader and others). Every command executed in the Remote console tab is executed in the context of the actual redbean process, so if you modify the value the url variable (as shown in the next screenshot) and continue execution, you should see the result in the browser with the modified value:

More Redbean debugging with modified output

When you're done with debugging, you can either stop the process using Project | Stop menu (which will stop redbean instance if it's running on the same computer) or detach the redbean process using Project | Detach (which will continue running the current process, but without debugging).

You should get a copy of my slick ZeroBrane Studio IDE.

2 Comments

Hi, Redbean seems to use Lua V5.4 and when I tried recently for general debugging of Lua code run via Pandoc, mobdebug and ZBS didn't support V5.4, I couldn't see a new update?

Hi Ian, both mobdebug and ZeroBrane Studio support Lua 5.4, but the Lua interpreter itself is not bundled with the IDE, as it's still work in progress. You can check this ticket and the branch referenced there for the Windows binaries: https://github.com/pkulchenko/ZeroBraneStudio/issues/1075#issuecomment-1014834591

Leave a comment

what will you say?
(required)
(required)
Close