# @toolctrl/worker

Opt-in BullMQ worker runtime for queue-backed jobs.

The worker is disabled by default and is not imported by the web runtime. Running it directly without `WORKER_ENABLED=true` exits immediately.

## Local execution

Check worker readiness and Redis configuration without starting processors:

```sh
pnpm --filter @toolctrl/worker health
```

Run the disabled-by-default worker locally:

```sh
pnpm --filter @toolctrl/worker dev
```

Start the enabled worker against a local Redis instance and database:

```sh
WORKER_ENABLED=true WORKER_QUEUE_GROUP=general BULLMQ_REDIS_URL=redis://localhost:6379/0 DATABASE_URL=postgresql://localhost/app pnpm --filter @toolctrl/worker dev
```

The worker stays disabled unless `WORKER_ENABLED=true`. When enabled, `DATABASE_URL` is required, and Redis is resolved from `BULLMQ_REDIS_URL` first; `REDIS_URL` is fallback only when `BULLMQ_REDIS_URL` is absent for deployments that already provide a generic Redis binding.

## Docker Compose

Build the worker image and start a disabled smoke container with local Redis:

```sh
docker compose up redis worker-general
```

The compose topology builds the Dockerfile `worker` target for five grouped services: `worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, and `worker-plugin`. Each service leaves processors disabled by default and wires Redis with `BULLMQ_REDIS_URL=redis://redis:6379/0` using the compose service name. Enable real processors only with a valid database URL and the group you want to exercise, for example with `WORKER_ENABLED=true DATABASE_URL=postgresql://... docker compose up worker-mail` or an override file.

Manual E2E note: real queued job processing requires a running Redis/container smoke test outside Auto-Mode; Auto-Mode verification for this task is limited to static configuration and documentation checks.

## Current processors

The worker has concrete handler paths for mail, webhooks, notifications, maintenance, storage scans, exports, imports, and guarded AI/browser job descriptors. Some queues remain disabled unless feature flags and provider services are configured.

- `toolctrl.email`
- `toolctrl.notifications`
- `toolctrl.maintenance`
- `toolctrl.ai-chatbot`
- `toolctrl.browser-automation`
- `toolctrl.file-scan`
- `toolctrl.exports`
- `toolctrl.imports`
- `toolctrl.plugin-invoke`