Template Worker HTTP API

The template-worker service exposes an HTTP API for template execution, VM management, and monitoring. The API is documented using OpenAPI (via Utoipa) and is accessible on port 60000 by default.

API Documentation Requirements

All types used by the HTTP API must:

1. Be defined in either:

   • src/api/types.rs - API-specific types
   • src/events - Event type definitions

2. Be annotated with #[derive(utoipa::ToSchema)] to ensure they are documented in the OpenAPI spec

OpenAPI Specification

The service generates an OpenAPI specification that can be accessed at:

GET /openapi

This endpoint returns the complete OpenAPI 3.0 specification for all available endpoints.

Endpoints

Health & Monitoring

The service provides health check endpoints for monitoring and orchestration:

• Health Check - Basic health status
• Metrics - Prometheus metrics (if configured)

Template Execution

Endpoints for executing templates and managing template execution:

• Template execution requests
• Execution status queries
• Result retrieval

VM Management

Endpoints for managing Lua VMs:

• VM lifecycle operations
• VM state queries
• VM cleanup operations

Expiry Tasks

Endpoints for managing expiry tasks:

• Task scheduling
• Task status queries
• Task cancellation

Type Definitions

API Types (src/api/types.rs)

Types specific to the HTTP API, including:

• Request/response types
• Error types
• Status types
• Configuration types

Event Types (src/events)

Event type definitions used for:

• Template event dispatching
• Internal event handling
• Event serialization

All event types must implement utoipa::ToSchema for OpenAPI documentation.

Example: Adding a New Endpoint

To add a new HTTP endpoint:

1. Define the request/response types in src/api/types.rs:

#[derive(Serialize, Deserialize, utoipa::ToSchema)]
pub struct MyRequest {
    pub field: String,
}

#[derive(Serialize, Deserialize, utoipa::ToSchema)]
pub struct MyResponse {
    pub result: String,
}

2. Create the handler in the appropriate API module

3. Register the endpoint with the OpenAPI documentation

4. Test the endpoint and verify it appears in the OpenAPI spec

API Client Integration

The HTTP API can be consumed by:

• Bot Service - For template execution requests
• API Service - For template management operations
• Jobserver - For scheduled template executions
• Monitoring Tools - For health checks and metrics

Related Documentation

• Template Worker Overview

  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.

  - Service overview
• Architecture

  Template Worker Architecture

  Architecture details for the template-worker service including VM distribution, lifecycle, and runtime management.

  - Service architecture
• Development

  Template Worker Development

  Development guide for the template-worker service including building, testing, and code structure.

  - Building and testing

References

• Template Worker Repository
• Utoipa Documentation - OpenAPI documentation framework