refactor: rename email-server-worker to email-worker

Rename directory from email-server-worker to email-worker for clarity and brevity. Update all references in CLAUDE.md documentation.
This commit is contained in:
Knee Cola
2025-12-30 10:33:59 +01:00
parent 9d6ad17452
commit 3e4d8fb95c
37 changed files with 32 additions and 28 deletions

View File

@@ -24,7 +24,11 @@
"Bash(git mv:*)",
"Bash(rmdir:*)",
"Bash(mkdir:*)",
"Bash(git diff:*)"
"Bash(git diff:*)",
"Bash(grep:*)",
"Bash(for file in CommError HTTPResponseError JsonParsingError clientIpAddress)",
"Bash(do echo \"=== $file ===\")",
"Bash(done)"
]
},
"enableAllProjectMcpServers": true,

View File

@@ -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)

View File

@@ -50,7 +50,7 @@ npm run test # Run Jest in watch mode
### Optional
- `PORT` - HTTP server port (default: `"3000"`)
- `PROMETHEUS_APP_LABEL` - App label for Prometheus metrics (default: `"email-server-worker"`)
- `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)

View File

@@ -1,5 +1,5 @@
{
"name": "email-server-worker",
"name": "email-worker",
"version": "0.1.0",
"description": "Background worker service with HTTP health monitoring and metrics collection",
"main": "entry.ts",

View File

@@ -5,7 +5,7 @@ import { coalesce } from './initTools';
const PROMETHEUS_HISTOGRAM_BUCKETS = coalesce(process.env.PROMETHEUS_HISTOGRAM_BUCKETS, "0.1, 0.5, 1, 5, 10");
/** Labela kojom želimo da bude označena metrika prikupljena na ovom web servisu */
const PROMETHEUS_APP_LABEL = coalesce(process.env.PROMETHEUS_APP_LABEL, 'email-server-worker');
const PROMETHEUS_APP_LABEL = coalesce(process.env.PROMETHEUS_APP_LABEL, 'email-worker');
// na "app" labele ćemo razdvajanje rezultata u Grafani
register.setDefaultLabels({ app: PROMETHEUS_APP_LABEL });

View File

@@ -9,7 +9,7 @@ declare global {
ENV?:"dev"|"jest"
/**
* (optional) App label to be used in Prometheus (Grafana)
* @default "email-server-worker"
* @default "email-worker"
* */
PROMETHEUS_APP_LABEL?: string
/**

View File

@@ -17,8 +17,8 @@
"path": "mailgun-webhook"
},
{
"name": "⚙️ email-server-worker",
"path": "email-server-worker"
"name": "⚙️ email-worker",
"path": "email-worker"
},
{
"name": "📦 root",

0
sprints/email-worker.md Normal file
View File