evidencija-rezija/email-server-worker

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

npm install

Development

npm run start  # Start with nodemon (auto-reload)

Build & Run

npm run build      # Compile TypeScript
npm run run-server # Run compiled version

Testing

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-server-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:

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:

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.