Hot-Reloadable Plugin Host

Project roadmap

1. 01

   Design the host and plugin contract

   ~2h

   Write DESIGN.md: a plugin is a file in plugins/ that returns a table with a name, a version, and the functions init(api), shutdown() and optionally save_state() and restore_state(state). List exactly what the api table offers (for example register_command, log, get_config and on_tick) and what plugins cannot access (os, io, require and the global table). Describe what happens on reload and on errors. Done when: DESIGN.md defines the contract, the API and every failure case.

2. 02

   Load plugins in a sandbox

   ~2.5h

   Load each plugin with loadfile using a fresh environment table that contains only safe functions (such as string, table and math, and a limited print) and nothing else. Call it and init with pcall, and check the returned table has the required fields. A plugin that fails to load is reported and skipped, never crashing the host. Done when: good plugins load, and plugins that try to use os or io fail with a clear error.

3. 03

   Build the host API and a command loop

   ~2h

   Implement the api table given to each plugin, tagging everything a plugin registers (commands and tick handlers) with its name, so they can be removed later. Build a simple host: a command prompt that runs registered commands, and a timer that calls tick handlers. Write two example plugins, such as a greeter and a counter. Done when: commands from both example plugins work.

4. 04

   Detect changes and reload

   ~2.5h

   Check the plugins folder regularly for changed files, using modification times from LuaFileSystem (lfs) or file contents hashes. On a change, load the new version in a new sandbox first. Only if it loads and passes init, call the old version's shutdown, remove its commands and handlers, and switch to the new one. If the new version fails, keep the old one running and report the error. Done when: editing a plugin while the host runs updates its behavior, and a broken edit leaves the old version working.

5. 05

   Keep state across reloads

   ~1.5h

   Before switching versions, call the old plugin's save_state, and pass the result to the new version's restore_state. Only plain data (strings, numbers, booleans and tables of them) can be passed, checked with a deep copy that rejects functions. Done when: the counter plugin keeps its count after being edited and reloaded.

6. 06

   Limit misbehaving plugins

   ~2h

   Stop runaway plugins with debug.sethook counting instructions, so a plugin stuck in an infinite loop is interrupted and disabled. Disable a plugin that errors too many times in a row. Add commands to list plugins with their status, disable, enable and reload one. Done when: a plugin with an infinite loop is stopped and disabled while the host keeps running.

7. 07

   Test it

   ~2h

   Write tests with busted: the sandbox blocks unsafe globals, a broken new version keeps the old one, state survives a reload, removed plugins lose their commands, and runaway plugins are stopped. Use temporary folders and files written by the tests. Package with a rockspec that depends on luafilesystem. Done when: busted passes.

Resources

• DocsLua 5.4 reference manual: load, pcall and environments
• DocsProgramming in Lua: environments (first edition)
• DocsLuaFileSystem documentation
• Articlelua-users wiki: sandboxes
• Docsbusted testing framework