@open-mercato/queue 0.4.7-develop-c89cca0193 → 0.4.7-develop-bdeaa0fc10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agentic/standalone-guide.md +53 -0
- package/package.json +1 -1
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Queue Package — Standalone Developer Guide
|
|
2
|
+
|
|
3
|
+
`@open-mercato/queue` provides background job processing. MUST NOT implement custom job queues or polling loops.
|
|
4
|
+
|
|
5
|
+
## Strategy Selection
|
|
6
|
+
|
|
7
|
+
| Strategy | When | Config |
|
|
8
|
+
|----------|------|--------|
|
|
9
|
+
| Local | Development — processes from `.mercato/queue/` | `QUEUE_STRATEGY=local` |
|
|
10
|
+
| BullMQ | Production — Redis-backed with retries | `QUEUE_STRATEGY=async` |
|
|
11
|
+
|
|
12
|
+
## Adding a Worker
|
|
13
|
+
|
|
14
|
+
Create `src/modules/<module>/workers/<name>.ts`:
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
export const metadata = {
|
|
18
|
+
queue: 'my-queue',
|
|
19
|
+
id: 'my-worker',
|
|
20
|
+
concurrency: 5,
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export default async function handler(job) {
|
|
24
|
+
// MUST be idempotent — jobs may be retried on failure
|
|
25
|
+
// Check state before mutating
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Run `yarn generate` after adding.
|
|
30
|
+
|
|
31
|
+
## Concurrency Guidelines
|
|
32
|
+
|
|
33
|
+
| Worker type | Concurrency | Rationale |
|
|
34
|
+
|-------------|-------------|-----------|
|
|
35
|
+
| I/O-bound (API calls, email) | 5–10 | Network latency allows parallelism |
|
|
36
|
+
| CPU-bound (calculations) | 1–2 | Avoid blocking event loop |
|
|
37
|
+
| Database-heavy (bulk writes) | 3–5 | Balance with connection pool |
|
|
38
|
+
|
|
39
|
+
Max concurrency: 20.
|
|
40
|
+
|
|
41
|
+
## MUST Rules
|
|
42
|
+
|
|
43
|
+
1. **MUST make workers idempotent** — duplicate execution MUST NOT corrupt data
|
|
44
|
+
2. **MUST export `metadata`** with `{ queue, id?, concurrency? }`
|
|
45
|
+
3. **MUST test with both strategies** (`local` and `async`)
|
|
46
|
+
|
|
47
|
+
## Running Workers (Production)
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
yarn mercato <module> worker <queue-name> --concurrency=5
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Development: local strategy auto-processes from `.mercato/queue/`.
|
package/package.json
CHANGED