Scripting Architecture

Scripting & Container Architecture

JustHostMC's scripting environment uses a locked-down gopher-lua interpreter to safely run third-party server providers and automation scripts.

Sandboxing & Security

Every script runs in a highly restricted sandbox:

• Safe standard libraries only: Access is granted to base, table, string, and math.
• No dangerous libraries: The os, io, package/require, debug, and coroutine libraries are completely omitted.
• Escape hatches removed: Potentially dangerous functions in the base library like dofile, load, loadfile, and require are deleted.
• Strict Filesystem Confinement: All filesystem access (via the jhmc.fs.* host API) is strictly confined to the server's working directory. The engine prevents path traversal (e.g., ../) and provides zip-slip protection.

Execution Model

The execution model guarantees isolation:

• Providers: Each provider invocation (e.g., calling versions() or install()) receives a fresh interpreter state. State cannot leak between calls.
• Automation: Automation scripts are allocated a long-lived, dedicated LState. Because gopher-lua is not safe for concurrent use, all automation event hooks are strictly serialized onto a single goroutine by the engine.

Persistent Storage

The scripting engine maintains several data stores on disk:

• GrantStore (*-grants.json): Persists the permission consent decisions for third-party scripts. Different script types use their own files (e.g., grants.json for providers, script-grants.json for automation, parser-grants.json for parsers, shop-grants.json for shops).
• KV Store (script-data/*.json): Each automation script is allocated an isolated, persistent Key-Value store mapped to jhmc.store.* to save cursors, counts, and other runtime data across engine restarts.

Isolation & Containers

When a Provider script finishes downloading and configuring a server, it returns a launch specification containing the required Java version (java_major) and startup arguments (args).

The engine passes this specification to its Isolation Layer, which manages the server process:

• Backends: The isolation layer uses Windows Job Objects (on native Windows setups) or the Docker Backend (if Docker is present and enabled).
• Resource Limits: The isolation layer enforces hard memory caps (MemoryMB) and tracks live telemetry independently of the Lua script.
• Metrics (Stats): The backend samples metrics such as CPUPercent, MemoryBytes, and NetRxBytesPerSec, forwarding them to the JustHostMC UI.

Navigation

• Back to the Scripting Hub