Track HiveGrid Cloud planning reference

2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
@@ -0,0 +1,58 @@
+# @toolctrl/queue
+
+BullMQ-oriented queue contracts and producer helpers for web/API enqueue paths and the opt-in worker runtime.
+
+This package defines stable queue names, typed payloads, job descriptors, producer helpers and small BullMQ factory helpers. Processors live in `apps/worker`; queues only run when the worker is enabled and the related runtime flags/services are configured.
+
+## Queues
+
+| Queue                         | Purpose                                                         |
+| ----------------------------- | --------------------------------------------------------------- |
+| `toolctrl.email`              | Transactional email and webhook delivery jobs.                  |
+| `toolctrl.notifications`      | User notification delivery jobs.                                |
+| `toolctrl.maintenance`        | Background cleanup and retention jobs.                          |
+| `toolctrl.ai-chatbot`         | Contract for admin-managed AI chat completion jobs.             |
+| `toolctrl.browser-automation` | Contract for browser session run, cleanup and usage flush jobs. |
+| `toolctrl.file-scan`          | Storage file scan jobs.                                         |
+| `toolctrl.exports`            | Export job execution.                                           |
+| `toolctrl.imports`            | Import job execution.                                           |
+| `toolctrl.plugin-invoke`      | Isolated third-party plugin invocation jobs.                    |
+
+## AI/Browser Jobs
+
+Stable job names:
+
+- `chat-completion`
+- `browser-session-run`
+- `browser-session-cleanup`
+- `usage-flush`
+- `scan-file`
+- `run-export`
+- `run-import`
+
+These are typed contracts and descriptors. Concrete processing is owned by `apps/worker` handlers and may still be disabled until the matching service flag or provider configuration is present.
+
+## Redis
+
+Queue workers resolve Redis from `BULLMQ_REDIS_URL` first. `REDIS_URL` is fallback only when `BULLMQ_REDIS_URL` is absent, so new deployments should prefer the BullMQ-specific variable and keep generic platform Redis bindings optional.
+
+Supported URL schemes:
+
+- `redis://localhost:6379/0`
+- `rediss://user:password@example.redis:6379/0`
+
+## Usage
+
+```ts
+import { createQueue, queueNames, resolveRedisConnectionOptions } from "@toolctrl/queue";
+
+const emailQueue = createQueue(queueNames.email, {
+  connection: resolveRedisConnectionOptions({ required: true }),
+});
+
+await emailQueue.add("send-email", {
+  kind: "mail.transactional",
+  recipientEmail: "user@example.com",
+  templateId: "welcome",
+});
+```