feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern (MAPCO-9803) by almog8k · Pull Request #17 · MapColonies/cleaner

almog8k · 2026-02-09T14:54:33Z

Question	Answer
New feature	✔
Documentation	✔
Tests added	✔

Further information:
Implements the foundational skeleton for the cleaner worker service, including error handling, validation infrastructure, and the strategy pattern for task execution.

Changes

Add error handling framework (RecoverableError/UnrecoverableError/ErrorHandler)
Add Zod-based validation infrastructure with TaskValidator
Add strategy pattern (ITaskStrategy, StrategyFactory, TilesDeletionStrategy stub)
Configure queue polling settings across all deployment levels
Update testing documentation with hybrid architecture
Remove boilerplate demo code (logistics)
Add comprehensive unit tests.
What's NOT Included (Future Work)
TaskPoller implementation (orchestration layer)
Actual tiles deletion logic (stub only)
Full DI container wiring for cleaner services

- Add configuration sync across all deployment levels (default.json, env vars, Helm) - Create complete custom-environment-variables.json with all config mappings - Add helm/local.yaml for local development overrides - Update Helm chart values and ConfigMap template - Add config/local.json example for local development (gitignored) - Document configuration sync requirement in common-patterns.md - Update gitignore to exclude local.json

- Add implementation-plan.md to gitignore for local use only - File can be regenerated as needed and doesn't need version control

- Add QUEUE_CLIENT, TASK_POLLER, STRATEGY_FACTORY, TASK_VALIDATOR, ERROR_HANDLER tokens - Add migration note for jobnik-sdk tokens - Document that strategies use task type strings instead of Symbol tokens - Update common-patterns.md with correct Symbol syntax

- Move polling.dequeueIntervalMs to queue.dequeueIntervalMs - Move polling.pairs to queue.pairs - Update env var name: POLLING_DEQUEUE_INTERVAL_MS → QUEUE_DEQUEUE_INTERVAL_MS - Simplifies config structure - all queue-related settings in one place - Update all config levels: default.json, env vars, Helm values/templates

- Add RecoverableError for retryable failures (network, timeouts) - Add UnrecoverableError for permanent failures (validation, config) - Add ValidationError for schema validation failures - Add StrategyNotFoundError for missing task strategies - Add core type definitions: PollingPairConfig, QueueConfig, HttpRetryConfig, ErrorContext, ErrorDecision, TaskResponse

- Add createMockLogger() test helper for reusable logger mocking - Add TaskValidator class for type-safe parameter validation - Add taskSchemas map for registering task-specific schemas - Add placeholder tilesDeletionParamsSchema (TODO implementation) - Validation failures throw ValidationError (unrecoverable) - Add basic test coverage for validation infrastructure

- Add zod@^3.25.76 to match version from mc-utils - Required for validation schema definitions - Ensures single version across dependencies

- Add ErrorHandler class to decide retry vs reject for task errors - Handle RecoverableError: retry if attempts < maxAttempts - Handle UnrecoverableError: never retry (validation, config errors) - Handle unknown errors: treat as recoverable with retry fallback - Log errors with full context (job, task, attempts, error details) - Add comprehensive test coverage (100% for ErrorHandler)

- Replace generic examples with actual project patterns - Add hybrid philosophy (unit *.spec.ts + integration *.integration.spec.ts) - Document testing decision guide (when to use unit vs integration) - Add real examples from codebase (ErrorHandler, createMockLogger) - Include faker usage examples for test data generation - Add troubleshooting section for common issues - Document selective test running commands - Remove outdated boilerplate references - Keep guide concise and practical (~220 lines)

…n stub - Add ITaskStrategy<T> interface with generic params for type-safe execution - Strategy receives only validated params, no context duplication - Add StrategyFactory using DI container to resolve strategies by task type - Add TilesDeletionStrategy stub implementing ITaskStrategy<TilesDeletionParams> - Factory resolves strategies from DI container via string tokens - Factory throws StrategyNotFoundError for unregistered task types - Add comprehensive unit tests for StrategyFactory (5 test cases) - TilesDeletionStrategy implementation deferred (TODO with placeholder) - Strategies focus on business logic, orchestration layer handles context

- Remove src/logistics/ directory (demo manager and types) - Remove src/seeder.ts (demo job/task seeder) - Remove tests/logistics.spec.ts (demo integration tests) - Update containerConfig.ts to remove logistics types - Update index.ts to remove seedData demo call - Replace worker.ts with stub pending TaskPoller implementation - Reduces test count from 16 to 14 (removed 2 demo tests)

github-actions · 2026-02-09T14:56:43Z

🎫 Related Jira Issue: MAPCO-9803

CL-SHLOMIKONCHA

After our conversation, implement an abstract class of TaskStrategy that includes validate method, avoid "validation" dir by move schemas directly into the cleaner

config/custom-environment-variables.json

config/default.json

helm/templates/configmap.yaml

helm/local.yaml

helm/values.yaml

helm/templates/configmap.yaml

src/cleaner/errors/errors.ts

CL-SHLOMIKONCHA

After our conversation, implement an abstract class of TaskStrategy that includes validate method, avoid "validation" dir by move schemas directly into the cleaner

CL-SHLOMIKONCHA

After our conversation, implement an abstract class of TaskStrategy that includes validate method, avoid "validation" dir by move schemas directly into the cleaner

config/custom-environment-variables.json

CL-SHLOMIKONCHA

After our conversation, implement an abstract class of TaskStrategy that includes validate method, avoid "validation" dir by move schemas directly into the cleaner

…aner

Implement capability declaration pattern with explicit job/task pairs instead of cartesian product. Worker declares specific job/task combinations it handles, validated against global job definitions with ConfigurationError for misconfigurations.

Move task validation from centralized TaskValidator into individual strategies. Simplify StrategyFactory to single resolveWithContext() method for automatic logger enrichment with complete job context. - Add validate() method to ITaskStrategy interface - Create validateSchema() helper using DI container for logger - Implement validate() in TilesDeletionStrategy - Simplify StrategyFactory: remove resolve(), keep only resolveWithContext() - Add TaskContext with jobId, taskId, jobType, taskType for full tracing - Remove TaskValidator class and taskSchemas registry - Add comprehensive tests for validation and context enrichment - Fix mock logger to include child() method

…gging

…Handle with async disposal

… asyncDispose method

helm/local.yaml

helm/values.yaml

CL-SHLOMIKONCHA · 2026-02-17T09:43:45Z

src/cleaner/errors/errors.ts

+ * Configuration error - invalid or missing configuration.
+ * This is always unrecoverable and indicates a deployment/configuration issue.
+ */
+export class ConfigurationError extends UnrecoverableError {


as we discussed, extends from Error & configuration schema will be implemented within mapcolonies schemas repo to reuse the validation of infra config

I will create the relevant Schema for the cleaner config. Will added to mapcolonies/schemas and will added to cleaner in different pr

src/cleaner/strategies/strategyFactory.ts

src/cleaner/utils/validationHelper.ts

CL-SHLOMIKONCHA · 2026-02-17T12:06:34Z

tests/helpers/mocks.ts

no need for logger mock, we can just define Logger as {enabled: false} as we usually do,
exmaple:
`

errorHandler = new ErrorHandler(jsLogger({ enabled: false }));

furthermore i think its irrelevant to test the logger its self with toHaveBeenCalledTimes() or toHaveBeenCalledWith()

We are using logger abilities like child logger per container so we need to make sure that the logger behave as expected- for this we must mock the logger instead of using:
jsLogger({ enabled: false })

I can relate to that, but as best practice we should test the act itself (that logger as been called) but not the exactly log message as it breaks frequently

… interface

refactor(validation): update logging messages in validateSchema function refactor(tests): simplify ErrorHandler tests by removing mock logger assertions

src/cleaner/utils/validationHelper.ts

CL-SHLOMIKONCHA · 2026-02-22T13:13:19Z

tests/helpers/mocks.ts

I can relate to that, but as best practice we should test the act itself (that logger as been called) but not the exactly log message as it breaks frequently

CL-SHLOMIKONCHA

Good job, remember to delete local.yaml file after you ignore it from git

almog8k added 12 commits February 8, 2026 11:49

docs(workflow): add incremental commit and PR workflow instructions

6a1fd2a

chore(docs): remove implementation-plan.md from git tracking

b419a00

- Add implementation-plan.md to gitignore for local use only - File can be regenerated as needed and doesn't need version control

chore(deps): add zod as direct dependency

d5dd374

- Add zod@^3.25.76 to match version from mc-utils - Required for validation schema definitions - Ensures single version across dependencies

mapcolonies-devops assigned almog8k Feb 9, 2026

almog8k changed the title ~~feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern(Mapco 9803)~~ feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern(Mapco-9803) Feb 9, 2026

almog8k changed the title ~~feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern(Mapco-9803)~~ feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern (Mapco-9803) Feb 9, 2026

almog8k changed the title ~~feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern (Mapco-9803)~~ feat: implement cleaner worker skeleton with error handling, validation, and strategy pattern (MAPCO-9803) Feb 9, 2026

CL-SHLOMIKONCHA requested changes Feb 9, 2026

View reviewed changes

config/custom-environment-variables.json Outdated Show resolved Hide resolved

CL-SHLOMIKONCHA reviewed Feb 9, 2026

View reviewed changes

almog8k added 9 commits February 10, 2026 10:00

chore: add helm/local.yaml to .gitignore

44fd6a9

feat: update project references from jobnik-worker-boilerplate to cle…

8289f6c

…aner

refactor(validation): simplify validation method and improve error lo…

e9facc2

…gging

fix: ensure stack trace is captured for custom errors

708a445

fix(tests): use faker for dynamic job and task IDs in strategy tests

fafe8dd

refactor(strategy): update resolveWithContext to return ITaskStrategy…

21a0bc9

…Handle with async disposal

refactor(tests): update strategyFactory tests to use handle and check…

5ffcda2

… asyncDispose method

CL-SHLOMIKONCHA requested changes Feb 17, 2026

View reviewed changes

almog8k added 2 commits February 18, 2026 10:39

refactor(strategy): simplify StrategyFactory and update ITaskStrategy…

92e2a9d

… interface

refactor(values): clean up jobDefinitions structure in values.yaml

9d687f8

refactor(validation): update logging messages in validateSchema function refactor(tests): simplify ErrorHandler tests by removing mock logger assertions

CL-SHLOMIKONCHA requested changes Feb 22, 2026

View reviewed changes

refactor(tests): remove redundant logging assertions in tests

45a68f5

CL-SHLOMIKONCHA approved these changes Feb 22, 2026

View reviewed changes

refactor(helm): remove local.yaml

1ed8e3f

almog8k merged commit bf43c75 into master Feb 22, 2026
6 checks passed

almog8k deleted the MAPCO-9803/implement-cleaner-worker-skeleton branch February 22, 2026 13:33

Conversation

almog8k commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 9, 2026 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CL-SHLOMIKONCHA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CL-SHLOMIKONCHA left a comment

Choose a reason for hiding this comment

Uh oh!

CL-SHLOMIKONCHA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CL-SHLOMIKONCHA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CL-SHLOMIKONCHA Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

almog8k Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CL-SHLOMIKONCHA Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

CL-SHLOMIKONCHA Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

almog8k Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

CL-SHLOMIKONCHA Feb 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CL-SHLOMIKONCHA Feb 22, 2026

Choose a reason for hiding this comment

Uh oh!

CL-SHLOMIKONCHA left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

almog8k commented Feb 9, 2026 •

edited

Loading

github-actions bot commented Feb 9, 2026 •

edited by atlassian bot

Loading

CL-SHLOMIKONCHA left a comment •

edited

Loading