From 3e4d8fb95c88e2ec0727565af12a089bf0c11cf8 Mon Sep 17 00:00:00 2001 From: Knee Cola Date: Tue, 30 Dec 2025 10:33:59 +0100 Subject: [PATCH] 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. --- .claude/settings.local.json | 6 ++- CLAUDE.md | 42 +++++++++---------- .../.dockerignore | 0 {email-server-worker => email-worker}/.env | 0 .../.gitignore | 0 .../.vscode/launch.json | 0 .../.vscode/settings.json | 0 .../Dockerfile | 0 .../README.md | 2 +- .../build-image.sh | 0 .../jest.config.ts | 0 .../package.json | 2 +- .../run-image.sh | 0 .../sent-mail-tester.mjs | 0 .../src/app.ts | 0 .../src/entry.ts | 0 .../src/exampleWorker.ts | 0 .../src/healthcheck.ts | 0 .../src/lib/initTools.ts | 0 .../src/lib/logger.ts | 0 .../src/lib/metricsCounters.ts | 2 +- .../src/lib/serializeError.ts | 0 .../src/routes/errorRouter.ts | 0 .../src/routes/finalErrorRouter.ts | 0 .../src/routes/healthcheckRouter.ts | 0 .../src/routes/metricsRouter.ts | 0 .../src/routes/pingRouter.ts | 0 .../src/types/NgitLocals.ts | 0 .../src/types/enums/SupportedRoutes.ts | 0 .../src/types/environment.d.ts | 2 +- .../src/workRunner.ts | 0 .../tests/__mocks__/prom-client.ts | 0 .../tests/helpers/mockHttpContext.ts | 0 .../tests/routers/errorRouter.spec.ts | 0 .../tsconfig.json | 0 evidencija-rezija.code-workspace | 4 +- sprints/email-worker.md | 0 37 files changed, 32 insertions(+), 28 deletions(-) rename {email-server-worker => email-worker}/.dockerignore (100%) rename {email-server-worker => email-worker}/.env (100%) rename {email-server-worker => email-worker}/.gitignore (100%) rename {email-server-worker => email-worker}/.vscode/launch.json (100%) rename {email-server-worker => email-worker}/.vscode/settings.json (100%) rename {email-server-worker => email-worker}/Dockerfile (100%) rename {email-server-worker => email-worker}/README.md (99%) rename {email-server-worker => email-worker}/build-image.sh (100%) rename {email-server-worker => email-worker}/jest.config.ts (100%) rename {email-server-worker => email-worker}/package.json (97%) rename {email-server-worker => email-worker}/run-image.sh (100%) rename {email-server-worker => email-worker}/sent-mail-tester.mjs (100%) rename {email-server-worker => email-worker}/src/app.ts (100%) rename {email-server-worker => email-worker}/src/entry.ts (100%) rename {email-server-worker => email-worker}/src/exampleWorker.ts (100%) rename {email-server-worker => email-worker}/src/healthcheck.ts (100%) rename {email-server-worker => email-worker}/src/lib/initTools.ts (100%) rename {email-server-worker => email-worker}/src/lib/logger.ts (100%) rename {email-server-worker => email-worker}/src/lib/metricsCounters.ts (98%) rename {email-server-worker => email-worker}/src/lib/serializeError.ts (100%) rename {email-server-worker => email-worker}/src/routes/errorRouter.ts (100%) rename {email-server-worker => email-worker}/src/routes/finalErrorRouter.ts (100%) rename {email-server-worker => email-worker}/src/routes/healthcheckRouter.ts (100%) rename {email-server-worker => email-worker}/src/routes/metricsRouter.ts (100%) rename {email-server-worker => email-worker}/src/routes/pingRouter.ts (100%) rename {email-server-worker => email-worker}/src/types/NgitLocals.ts (100%) rename {email-server-worker => email-worker}/src/types/enums/SupportedRoutes.ts (100%) rename {email-server-worker => email-worker}/src/types/environment.d.ts (94%) rename {email-server-worker => email-worker}/src/workRunner.ts (100%) rename {email-server-worker => email-worker}/tests/__mocks__/prom-client.ts (100%) rename {email-server-worker => email-worker}/tests/helpers/mockHttpContext.ts (100%) rename {email-server-worker => email-worker}/tests/routers/errorRouter.spec.ts (100%) rename {email-server-worker => email-worker}/tsconfig.json (100%) create mode 100644 sprints/email-worker.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json index f10d589..86454ea 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -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, diff --git a/CLAUDE.md b/CLAUDE.md index e3978f4..f3bf15f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) \ No newline at end of file diff --git a/email-server-worker/.dockerignore b/email-worker/.dockerignore similarity index 100% rename from email-server-worker/.dockerignore rename to email-worker/.dockerignore diff --git a/email-server-worker/.env b/email-worker/.env similarity index 100% rename from email-server-worker/.env rename to email-worker/.env diff --git a/email-server-worker/.gitignore b/email-worker/.gitignore similarity index 100% rename from email-server-worker/.gitignore rename to email-worker/.gitignore diff --git a/email-server-worker/.vscode/launch.json b/email-worker/.vscode/launch.json similarity index 100% rename from email-server-worker/.vscode/launch.json rename to email-worker/.vscode/launch.json diff --git a/email-server-worker/.vscode/settings.json b/email-worker/.vscode/settings.json similarity index 100% rename from email-server-worker/.vscode/settings.json rename to email-worker/.vscode/settings.json diff --git a/email-server-worker/Dockerfile b/email-worker/Dockerfile similarity index 100% rename from email-server-worker/Dockerfile rename to email-worker/Dockerfile diff --git a/email-server-worker/README.md b/email-worker/README.md similarity index 99% rename from email-server-worker/README.md rename to email-worker/README.md index c3f92a6..9bed122 100644 --- a/email-server-worker/README.md +++ b/email-worker/README.md @@ -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) diff --git a/email-server-worker/build-image.sh b/email-worker/build-image.sh similarity index 100% rename from email-server-worker/build-image.sh rename to email-worker/build-image.sh diff --git a/email-server-worker/jest.config.ts b/email-worker/jest.config.ts similarity index 100% rename from email-server-worker/jest.config.ts rename to email-worker/jest.config.ts diff --git a/email-server-worker/package.json b/email-worker/package.json similarity index 97% rename from email-server-worker/package.json rename to email-worker/package.json index bf6843a..f827476 100644 --- a/email-server-worker/package.json +++ b/email-worker/package.json @@ -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", diff --git a/email-server-worker/run-image.sh b/email-worker/run-image.sh similarity index 100% rename from email-server-worker/run-image.sh rename to email-worker/run-image.sh diff --git a/email-server-worker/sent-mail-tester.mjs b/email-worker/sent-mail-tester.mjs similarity index 100% rename from email-server-worker/sent-mail-tester.mjs rename to email-worker/sent-mail-tester.mjs diff --git a/email-server-worker/src/app.ts b/email-worker/src/app.ts similarity index 100% rename from email-server-worker/src/app.ts rename to email-worker/src/app.ts diff --git a/email-server-worker/src/entry.ts b/email-worker/src/entry.ts similarity index 100% rename from email-server-worker/src/entry.ts rename to email-worker/src/entry.ts diff --git a/email-server-worker/src/exampleWorker.ts b/email-worker/src/exampleWorker.ts similarity index 100% rename from email-server-worker/src/exampleWorker.ts rename to email-worker/src/exampleWorker.ts diff --git a/email-server-worker/src/healthcheck.ts b/email-worker/src/healthcheck.ts similarity index 100% rename from email-server-worker/src/healthcheck.ts rename to email-worker/src/healthcheck.ts diff --git a/email-server-worker/src/lib/initTools.ts b/email-worker/src/lib/initTools.ts similarity index 100% rename from email-server-worker/src/lib/initTools.ts rename to email-worker/src/lib/initTools.ts diff --git a/email-server-worker/src/lib/logger.ts b/email-worker/src/lib/logger.ts similarity index 100% rename from email-server-worker/src/lib/logger.ts rename to email-worker/src/lib/logger.ts diff --git a/email-server-worker/src/lib/metricsCounters.ts b/email-worker/src/lib/metricsCounters.ts similarity index 98% rename from email-server-worker/src/lib/metricsCounters.ts rename to email-worker/src/lib/metricsCounters.ts index 736159f..94220eb 100644 --- a/email-server-worker/src/lib/metricsCounters.ts +++ b/email-worker/src/lib/metricsCounters.ts @@ -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 }); diff --git a/email-server-worker/src/lib/serializeError.ts b/email-worker/src/lib/serializeError.ts similarity index 100% rename from email-server-worker/src/lib/serializeError.ts rename to email-worker/src/lib/serializeError.ts diff --git a/email-server-worker/src/routes/errorRouter.ts b/email-worker/src/routes/errorRouter.ts similarity index 100% rename from email-server-worker/src/routes/errorRouter.ts rename to email-worker/src/routes/errorRouter.ts diff --git a/email-server-worker/src/routes/finalErrorRouter.ts b/email-worker/src/routes/finalErrorRouter.ts similarity index 100% rename from email-server-worker/src/routes/finalErrorRouter.ts rename to email-worker/src/routes/finalErrorRouter.ts diff --git a/email-server-worker/src/routes/healthcheckRouter.ts b/email-worker/src/routes/healthcheckRouter.ts similarity index 100% rename from email-server-worker/src/routes/healthcheckRouter.ts rename to email-worker/src/routes/healthcheckRouter.ts diff --git a/email-server-worker/src/routes/metricsRouter.ts b/email-worker/src/routes/metricsRouter.ts similarity index 100% rename from email-server-worker/src/routes/metricsRouter.ts rename to email-worker/src/routes/metricsRouter.ts diff --git a/email-server-worker/src/routes/pingRouter.ts b/email-worker/src/routes/pingRouter.ts similarity index 100% rename from email-server-worker/src/routes/pingRouter.ts rename to email-worker/src/routes/pingRouter.ts diff --git a/email-server-worker/src/types/NgitLocals.ts b/email-worker/src/types/NgitLocals.ts similarity index 100% rename from email-server-worker/src/types/NgitLocals.ts rename to email-worker/src/types/NgitLocals.ts diff --git a/email-server-worker/src/types/enums/SupportedRoutes.ts b/email-worker/src/types/enums/SupportedRoutes.ts similarity index 100% rename from email-server-worker/src/types/enums/SupportedRoutes.ts rename to email-worker/src/types/enums/SupportedRoutes.ts diff --git a/email-server-worker/src/types/environment.d.ts b/email-worker/src/types/environment.d.ts similarity index 94% rename from email-server-worker/src/types/environment.d.ts rename to email-worker/src/types/environment.d.ts index 08fa949..14d35f3 100644 --- a/email-server-worker/src/types/environment.d.ts +++ b/email-worker/src/types/environment.d.ts @@ -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 /** diff --git a/email-server-worker/src/workRunner.ts b/email-worker/src/workRunner.ts similarity index 100% rename from email-server-worker/src/workRunner.ts rename to email-worker/src/workRunner.ts diff --git a/email-server-worker/tests/__mocks__/prom-client.ts b/email-worker/tests/__mocks__/prom-client.ts similarity index 100% rename from email-server-worker/tests/__mocks__/prom-client.ts rename to email-worker/tests/__mocks__/prom-client.ts diff --git a/email-server-worker/tests/helpers/mockHttpContext.ts b/email-worker/tests/helpers/mockHttpContext.ts similarity index 100% rename from email-server-worker/tests/helpers/mockHttpContext.ts rename to email-worker/tests/helpers/mockHttpContext.ts diff --git a/email-server-worker/tests/routers/errorRouter.spec.ts b/email-worker/tests/routers/errorRouter.spec.ts similarity index 100% rename from email-server-worker/tests/routers/errorRouter.spec.ts rename to email-worker/tests/routers/errorRouter.spec.ts diff --git a/email-server-worker/tsconfig.json b/email-worker/tsconfig.json similarity index 100% rename from email-server-worker/tsconfig.json rename to email-worker/tsconfig.json diff --git a/evidencija-rezija.code-workspace b/evidencija-rezija.code-workspace index 4a8c1c2..fd7fed6 100644 --- a/evidencija-rezija.code-workspace +++ b/evidencija-rezija.code-workspace @@ -17,8 +17,8 @@ "path": "mailgun-webhook" }, { - "name": "⚙️ email-server-worker", - "path": "email-server-worker" + "name": "⚙️ email-worker", + "path": "email-worker" }, { "name": "📦 root", diff --git a/sprints/email-worker.md b/sprints/email-worker.md new file mode 100644 index 0000000..e69de29