3e4d8fb95c
Rename directory from email-server-worker to email-worker for clarity and brevity. Update all references in CLAUDE.md documentation.
116 lines
3.2 KiB
Markdown
116 lines
3.2 KiB
Markdown
# Email Server Worker
|
|
|
|
Background worker service with HTTP health monitoring and metrics collection.
|
|
|
|
## Overview
|
|
|
|
This is a TypeScript-based background worker service that combines periodic task execution with HTTP health monitoring and metrics collection. It implements a self-scheduling worker pattern with graceful shutdown support.
|
|
|
|
## Features
|
|
|
|
- **Periodic Task Execution**: Self-scheduling worker loop with configurable interval
|
|
- **Graceful Shutdown**: Ensures in-flight work completes before shutdown (Docker-compatible)
|
|
- **Health Monitoring**: HTTP health check endpoint to verify worker status
|
|
- **Metrics Collection**: Prometheus metrics with PRTG adapter
|
|
- **Error Isolation**: Worker errors don't crash the process
|
|
|
|
## Getting Started
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run start # Start with nodemon (auto-reload)
|
|
```
|
|
|
|
### Build & Run
|
|
|
|
```bash
|
|
npm run build # Compile TypeScript
|
|
npm run run-server # Run compiled version
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
npm run test # Run Jest in watch mode
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### Required
|
|
|
|
- `PULL_INTERVAL` - Milliseconds between work cycles (default: `"10000"`)
|
|
|
|
### Optional
|
|
|
|
- `PORT` - HTTP server port (default: `"3000"`)
|
|
- `PROMETHEUS_APP_LABEL` - App label for Prometheus metrics (default: `"email-worker"`)
|
|
- `PROMETHEUS_HISTOGRAM_BUCKETS` - Histogram bucket sizes (default: `"0.1, 0.5, 1, 5, 10"`)
|
|
- `DEBUG` - Debug namespaces for console logging (e.g., `"server:server"`)
|
|
- `ENV` - Environment mode: `"dev"`, `"jest"` (affects logging)
|
|
|
|
## HTTP Endpoints
|
|
|
|
- `GET /healthcheck` - Health check endpoint (verifies worker is running)
|
|
- `GET /metrics` - Prometheus metrics
|
|
- `GET /prtg` - PRTG-compatible metrics (XML format)
|
|
- `GET /ping` - Simple ping/pong endpoint
|
|
|
|
## Creating a Worker
|
|
|
|
See `src/exampleWorker.ts` for the worker template. The worker must export a `doWork` function:
|
|
|
|
```typescript
|
|
|
|
export const doWork = async () => {
|
|
// Your periodic task logic here
|
|
logger.info("Task Completed", "Work done successfully");
|
|
|
|
// Throw errors to mark as failed:
|
|
// throw new Error("Something went wrong");
|
|
};
|
|
```
|
|
|
|
Update `src/workRunner.ts` line 6 to import your worker:
|
|
|
|
```typescript
|
|
import { doWork } from "./yourWorker";
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **entry.ts** - HTTP server setup, signal handling, worker lifecycle
|
|
- **workRunner.ts** - Self-scheduling loop, metrics, graceful shutdown
|
|
- **app.ts** - Express app configuration, routes
|
|
- **src/lib/** - Shared utilities (logger, metrics, etc.)
|
|
- **src/routes/** - HTTP route handlers
|
|
|
|
## Deployment
|
|
|
|
The service uses the `stoppable` library for graceful shutdown with a 10-second timeout before force-closing connections. Docker containers will receive SIGTERM signals and shut down gracefully.
|
|
|
|
## Logging
|
|
|
|
The service supports two logging mechanisms:
|
|
|
|
1. **Console Logging**: Uses the `debug` package, controlled by `DEBUG` env variable
|
|
|
|
## Metrics
|
|
|
|
Prometheus metrics are automatically collected:
|
|
|
|
- `request_operations_total` - Total work cycles executed
|
|
- `request_operations_ok` - Successful work cycles
|
|
- `request_operations_failed` - Failed work cycles
|
|
- `request_duration_seconds` - Duration histogram of work cycles
|
|
|
|
## Documentation
|
|
|
|
See `CLAUDE.md` in the repository root for complete architecture documentation and guidance.
|