|
|
|
|
@@ -8,7 +8,7 @@ This is a multi-project repository containing:
|
|
|
|
|
- **web-app/**: Next.js 14 utility bills tracking application
|
|
|
|
|
- **docker-stack/**: Docker Compose configurations and deployment scripts
|
|
|
|
|
- **housekeeping/**: Database backup and maintenance scripts
|
|
|
|
|
- **email-server-worker/**: Background worker service with HTTP health monitoring
|
|
|
|
|
- **email-worker/**: Background worker service with HTTP health monitoring
|
|
|
|
|
|
|
|
|
|
Each project is self-contained with its own dependencies.
|
|
|
|
|
|
|
|
|
|
@@ -30,7 +30,7 @@ All commands should be run from within the respective project directory.
|
|
|
|
|
- `./db-dump--standalone.sh` - Run standalone database dump
|
|
|
|
|
- See housekeeping/README.md for more details
|
|
|
|
|
|
|
|
|
|
**Email Server Worker** (`cd email-server-worker`):
|
|
|
|
|
**Email Server Worker** (`cd email-worker`):
|
|
|
|
|
- `npm install` - Install dependencies
|
|
|
|
|
- `npm run start` - Start development server with nodemon
|
|
|
|
|
- `npm run build` - Build TypeScript to JavaScript
|
|
|
|
|
@@ -103,7 +103,7 @@ export const actionName = withUser(async (user: AuthenticatedUser, ...args) => {
|
|
|
|
|
|
|
|
|
|
## Email Server Worker Architecture
|
|
|
|
|
|
|
|
|
|
The email-server-worker is a TypeScript-based background worker service that combines periodic task execution with HTTP health monitoring and metrics collection.
|
|
|
|
|
The email-worker is a TypeScript-based background worker service that combines periodic task execution with HTTP health monitoring and metrics collection.
|
|
|
|
|
|
|
|
|
|
### Tech Stack
|
|
|
|
|
- **Runtime**: Node.js with TypeScript
|
|
|
|
|
@@ -115,16 +115,16 @@ The email-server-worker is a TypeScript-based background worker service that com
|
|
|
|
|
|
|
|
|
|
The service implements a **self-contained worker pattern** that runs periodic background tasks while exposing HTTP endpoints for monitoring.
|
|
|
|
|
|
|
|
|
|
**Entry Point** (`email-server-worker/src/entry.ts:1`):
|
|
|
|
|
**Entry Point** (`email-worker/src/entry.ts:1`):
|
|
|
|
|
- Creates Express HTTP server with graceful shutdown support (stoppable)
|
|
|
|
|
- Starts the worker via `startSyncWorker()` from `email-server-worker/src/workRunner.ts:134`
|
|
|
|
|
- Starts the worker via `startSyncWorker()` from `email-worker/src/workRunner.ts:134`
|
|
|
|
|
- Handles SIGTERM/SIGINT for graceful shutdown (Docker-compatible)
|
|
|
|
|
- Calls `disposeSyncWorker()` on shutdown to allow pending work to complete
|
|
|
|
|
|
|
|
|
|
**Work Runner** (`email-server-worker/src/workRunner.ts:1`):
|
|
|
|
|
**Work Runner** (`email-worker/src/workRunner.ts:1`):
|
|
|
|
|
The work runner implements a self-scheduling loop with the following characteristics:
|
|
|
|
|
|
|
|
|
|
- **Self-Scheduling Loop**: After completing work, schedules next execution via `setTimeout(workRunner, PULL_INTERVAL)` at `email-server-worker/src/workRunner.ts:113`
|
|
|
|
|
- **Self-Scheduling Loop**: After completing work, schedules next execution via `setTimeout(workRunner, PULL_INTERVAL)` at `email-worker/src/workRunner.ts:113`
|
|
|
|
|
- **Graceful Shutdown**: Tracks pending work via Promise, allows in-flight operations to complete before shutdown
|
|
|
|
|
- **Status Tracking**: Exports `workerRunnerInfo` with `status` and `lastWorkTime` for health monitoring
|
|
|
|
|
- **Error Isolation**: Worker errors don't crash the process - caught, logged, and execution continues
|
|
|
|
|
@@ -148,17 +148,17 @@ export const doWork = async () => {
|
|
|
|
|
};
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The work runner imports and calls this function at `email-server-worker/src/workRunner.ts:88`.
|
|
|
|
|
The work runner imports and calls this function at `email-worker/src/workRunner.ts:88`.
|
|
|
|
|
|
|
|
|
|
### Key Files & Responsibilities
|
|
|
|
|
|
|
|
|
|
**Core Worker Files**:
|
|
|
|
|
- `email-server-worker/src/entry.ts` - HTTP server setup, signal handling, worker lifecycle management
|
|
|
|
|
- `email-server-worker/src/workRunner.ts` - Self-scheduling loop, graceful shutdown, metrics integration
|
|
|
|
|
- `email-server-worker/src/app.ts` - Express app configuration, route registration
|
|
|
|
|
- `email-server-worker/src/lib/logger.ts` - Debug logger factory (uses 'debug' package)
|
|
|
|
|
- `email-worker/src/entry.ts` - HTTP server setup, signal handling, worker lifecycle management
|
|
|
|
|
- `email-worker/src/workRunner.ts` - Self-scheduling loop, graceful shutdown, metrics integration
|
|
|
|
|
- `email-worker/src/app.ts` - Express app configuration, route registration
|
|
|
|
|
- `email-worker/src/lib/logger.ts` - Debug logger factory (uses 'debug' package)
|
|
|
|
|
|
|
|
|
|
**HTTP Routes** (`email-server-worker/src/routes/`):
|
|
|
|
|
**HTTP Routes** (`email-worker/src/routes/`):
|
|
|
|
|
- `healthcheckRouter.ts` - Health check endpoint (checks worker status via `workerRunnerInfo`)
|
|
|
|
|
- `metricsRouter.ts` - Prometheus metrics endpoint
|
|
|
|
|
- `prtgMetricsRouter.ts` - PRTG-compatible metrics adapter
|
|
|
|
|
@@ -167,10 +167,10 @@ The work runner imports and calls this function at `email-server-worker/src/work
|
|
|
|
|
- `finalErrorRouter.ts` - Catch-all error handler for unexpected errors
|
|
|
|
|
|
|
|
|
|
**Infrastructure**:
|
|
|
|
|
- `email-server-worker/src/lib/metricsCounters.ts` - Prometheus counter/histogram definitions
|
|
|
|
|
- `email-server-worker/src/lib/initTools.ts` - Utility functions (coalesce, etc.)
|
|
|
|
|
- `email-server-worker/src/lib/serializeError.ts` - Error serialization for logging
|
|
|
|
|
- `email-server-worker/src/lib/Prometheus2Prtg.ts` - Converts Prometheus metrics to PRTG XML format
|
|
|
|
|
- `email-worker/src/lib/metricsCounters.ts` - Prometheus counter/histogram definitions
|
|
|
|
|
- `email-worker/src/lib/initTools.ts` - Utility functions (coalesce, etc.)
|
|
|
|
|
- `email-worker/src/lib/serializeError.ts` - Error serialization for logging
|
|
|
|
|
- `email-worker/src/lib/Prometheus2Prtg.ts` - Converts Prometheus metrics to PRTG XML format
|
|
|
|
|
|
|
|
|
|
### Environment Variables
|
|
|
|
|
|
|
|
|
|
@@ -188,7 +188,7 @@ The work runner imports and calls this function at `email-server-worker/src/work
|
|
|
|
|
|
|
|
|
|
To implement a new worker task:
|
|
|
|
|
|
|
|
|
|
1. **Create worker file** (e.g., `email-server-worker/src/myWorker.ts`):
|
|
|
|
|
1. **Create worker file** (e.g., `email-worker/src/myWorker.ts`):
|
|
|
|
|
```typescript
|
|
|
|
|
export const doWork = async () => {
|
|
|
|
|
// Implement your periodic task here
|
|
|
|
|
@@ -204,7 +204,7 @@ export const doWork = async () => {
|
|
|
|
|
import { doWork } from "./myWorker";
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. **Add environment variables** to `email-server-worker/src/types/environment.d.ts` as needed
|
|
|
|
|
3. **Add environment variables** to `email-worker/src/types/environment.d.ts` as needed
|
|
|
|
|
|
|
|
|
|
4. **Update `package.json` metadata** if the service purpose changes (name, description)
|
|
|
|
|
|
|
|
|
|
@@ -219,7 +219,7 @@ import { doWork } from "./myWorker";
|
|
|
|
|
### Testing
|
|
|
|
|
|
|
|
|
|
- **Framework**: Jest with esbuild-jest for TypeScript
|
|
|
|
|
- **Test Location**: `email-server-worker/tests/`
|
|
|
|
|
- **Mocks**: Common mocks in `email-server-worker/tests/__mocks__/` (prom-client)
|
|
|
|
|
- **Test Location**: `email-worker/tests/`
|
|
|
|
|
- **Mocks**: Common mocks in `email-worker/tests/__mocks__/` (prom-client)
|
|
|
|
|
- **Test Pattern**: Co-located with source in `tests/` mirroring `src/` structure
|
|
|
|
|
- **Run Tests**: `npm run test` (watch mode)
|