Template Worker Service
Developer documentation for the template-worker service - the template execution engine that runs user-defined Lua/Luau scripts in a sandboxed environment.
Template Worker Service
The template-worker is a Rust-based microservice responsible for executing user-defined Lua/Luau templates in a secure, sandboxed environment. It provides the runtime infrastructure for AntiRaid's templating system, enabling users to customize bot behavior through Lua scripts.
Overview
The template-worker service:
- Executes Lua/Luau templates in isolated, per-guild virtual machines (VMs)
- Manages VM lifecycle including creation, persistence, and cleanup
- Handles template dispatching and runs expiry tasks as needed
- Enforces resource limits (memory, execution time, stack size)
- Provides sandboxing to prevent malicious code execution
- Exposes HTTP API for template execution and management
Repository
The template-worker service is maintained in a separate repository:
GitHub: https://github.com/Anti-Raid/template-worker
HTTP Documentation Notes
All types used by the HTTP API must either be in src/api/types.rs or src/events. They must also be annotated with #[derive(utoipa::ToSchema)] to ensure they are documented in the OpenAPI spec.
Key Features
Template Execution
- Per-guild Lua(u) VM instances
- Persistent VM state across template executions
- Asynchronous event dispatching
- Resource limit enforcement
HTTP API
The service exposes an HTTP API for:
- Template execution requests
- VM management operations
- Health checks and monitoring
- Expiry task management
Expiry Tasks
The service runs expiry tasks as needed, handling:
- Key-value store expiration events
- Scheduled template executions
- Cleanup operations
Architecture
The template-worker uses:
- Rust for the core service implementation
- Luau (Roblox Lua) for template execution
- Khronos runtime for Lua VM management
- Tokio for async runtime
- Utoipa for OpenAPI documentation
Service Communication
The template-worker communicates with other services via:
- HTTP/RPC protocols for receiving template execution requests
- Internal message queues for event dispatching
- Port 60000 (default) for HTTP API
Documentation
Architecture
VM distribution strategies, lifecycle management, and runtime details
Internals
Deep dive into implementation details, code patterns, and internal architecture
HTTP API
API endpoints, types, and OpenAPI documentation
Deployment
Docker and native deployment guides
Development
Building, testing, and code structure
Related Documentation
- Templating Introduction - User-facing templating docs
- Templating Architecture - VM distribution and architecture details
- Templating API Reference - Available Lua APIs and plugins
- Services Overview- Overview of all AntiRaid services
Services Developer Docs
Documentation for core service implementations in AntiRaid, including architecture and extension points.
- Hosting Guides - Deployment and hosting information
For more information on the templating system from a user perspective, see the Templating Documentation.
Last updated on