# 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.