tim-worker

README

Tim Worker

The Tim Worker is a Faktory-based job processing service that handles background tasks for the Tim AI assistant platform.

Features

• Faktory Integration: Connects to Faktory server for distributed job processing
• Health Checks: HTTP endpoints for health and readiness checks
• Graceful Shutdown: Proper cleanup on termination signals
• Configurable Concurrency: Control worker concurrency via environment variables
• Structured Logging: JSON and console logging with configurable levels

Job Types

The worker currently registers placeholder handlers for:

• llm_relay: Handles LLM relay operations (placeholder implementation)
• tool_runner: Handles tool execution operations (placeholder implementation)

Configuration

Configuration is handled entirely through environment variables. See local.env.example for all available options.

Key Environment Variables

• FAKTORY_URL: Faktory server URL (default: tcp://localhost:7419)
• TIM_WORKER_MAXIMUM_CONCURRENCY: Maximum concurrent jobs (default: 20)
• LOG_LEVEL: Logging level - trace, debug, info, error (default: debug)
• LOG_FORMAT: Log format - json or console (default: json)

Building

go build -o bin/tim-worker .

Running

# With default configuration
./bin/tim-worker

# With custom environment
FAKTORY_URL=tcp://faktory:7419 LOG_LEVEL=info ./bin/tim-worker

HTTP Endpoints

• GET /health: Health check endpoint
• GET /ready: Readiness check endpoint

The HTTP server runs on port 8080 by default.

Development

The worker uses the Faktory Go client library and follows standard Faktory worker patterns:

1. Connect to Faktory server
2. Register job handlers
3. Process jobs from configured queues
4. Handle graceful shutdown

For more details on Faktory, see: https://github.com/contribsys/faktory