@hotmeshio/hotmesh 0.21.1 → 0.22.1
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/README.md +12 -129
- package/build/modules/utils.d.ts +2 -0
- package/build/modules/utils.js +9 -1
- package/build/package.json +8 -2
- package/build/services/activities/hook.d.ts +178 -58
- package/build/services/activities/hook.js +244 -58
- package/build/services/activities/trigger.js +5 -1
- package/build/services/durable/client.d.ts +273 -67
- package/build/services/durable/client.js +351 -126
- package/build/services/durable/index.d.ts +7 -3
- package/build/services/durable/index.js +6 -0
- package/build/services/durable/schemas/factory.js +40 -0
- package/build/services/durable/worker.js +5 -28
- package/build/services/durable/workflow/condition.d.ts +69 -37
- package/build/services/durable/workflow/condition.js +70 -39
- package/build/services/hotmesh/index.d.ts +31 -4
- package/build/services/hotmesh/index.js +31 -4
- package/build/services/store/index.d.ts +1 -1
- package/build/services/store/providers/postgres/kvsql.d.ts +1 -1
- package/build/services/store/providers/postgres/kvtables.js +83 -122
- package/build/services/store/providers/postgres/kvtypes/hash/basic.d.ts +1 -1
- package/build/services/store/providers/postgres/kvtypes/hash/basic.js +8 -8
- package/build/services/store/providers/postgres/kvtypes/hash/index.d.ts +1 -1
- package/build/services/store/providers/postgres/postgres.d.ts +51 -188
- package/build/services/store/providers/postgres/postgres.js +542 -285
- package/build/types/activity.d.ts +2 -0
- package/build/types/hmsh_escalations.d.ts +240 -0
- package/build/types/index.d.ts +1 -1
- package/build/types/provider.d.ts +2 -0
- package/package.json +9 -2
- package/build/types/signal.d.ts +0 -147
- /package/build/types/{signal.js → hmsh_escalations.js} +0 -0
|
@@ -285,162 +285,347 @@ class ClientService {
|
|
|
285
285
|
},
|
|
286
286
|
};
|
|
287
287
|
/**
|
|
288
|
-
*
|
|
289
|
-
*
|
|
290
|
-
*
|
|
288
|
+
* Escalation queue operations over `public.hmsh_escalations` — a global
|
|
289
|
+
* table that surfaces workflow signal pauses as role-based, claimable,
|
|
290
|
+
* searchable queue items.
|
|
291
291
|
*
|
|
292
|
-
*
|
|
293
|
-
*
|
|
292
|
+
* When a YAML `hook` activity suspends with an `escalation:` block, or
|
|
293
|
+
* `Durable.workflow.condition(signalId, config)` fires, **one row is
|
|
294
|
+
* written atomically** with the workflow checkpoint — no enrichment step,
|
|
295
|
+
* no secondary round-trip. Every connected app shares the same table;
|
|
296
|
+
* rows are namespaced by `namespace` + `app_id`.
|
|
294
297
|
*
|
|
295
|
-
*
|
|
298
|
+
* **Status lifecycle:**
|
|
299
|
+
* ```
|
|
300
|
+
* pending → claimed → resolved
|
|
301
|
+
* ↘ cancelled (any non-terminal state)
|
|
302
|
+
* ↗ pending (via release or releaseExpired)
|
|
303
|
+
* ```
|
|
304
|
+
*
|
|
305
|
+
* **Typical human-in-the-loop flow:**
|
|
296
306
|
* ```typescript
|
|
297
|
-
* //
|
|
298
|
-
* const
|
|
299
|
-
*
|
|
300
|
-
*
|
|
301
|
-
*
|
|
307
|
+
* // 1. Workflow pauses and writes the escalation row automatically
|
|
308
|
+
* const decision = await Durable.workflow.condition('manager-approval', {
|
|
309
|
+
* role: 'manager',
|
|
310
|
+
* type: 'order-approval',
|
|
311
|
+
* priority: 2,
|
|
312
|
+
* metadata: { orderId },
|
|
302
313
|
* });
|
|
303
314
|
*
|
|
304
|
-
*
|
|
305
|
-
*
|
|
306
|
-
*
|
|
307
|
-
*
|
|
308
|
-
*
|
|
309
|
-
*
|
|
310
|
-
*
|
|
315
|
+
* // 2. Dashboard lists pending approvals for this role
|
|
316
|
+
* const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
|
|
317
|
+
*
|
|
318
|
+
* // 3. Reviewer claims it (sets assigned_to + expiry)
|
|
319
|
+
* await client.escalations.claim({ id: item.id, assignee: 'alice@company.com' });
|
|
320
|
+
*
|
|
321
|
+
* // 4. Resolve atomically marks it resolved AND delivers the signal
|
|
322
|
+
* await client.escalations.resolve({
|
|
323
|
+
* id: item.id,
|
|
324
|
+
* resolverPayload: { approved: true },
|
|
325
|
+
* });
|
|
326
|
+
* // workflow resumes with { approved: true }
|
|
311
327
|
* ```
|
|
312
328
|
*/
|
|
313
|
-
this.
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
});
|
|
329
|
+
this.escalations = {
|
|
330
|
+
/**
|
|
331
|
+
* Returns all escalation rows matching the given filters.
|
|
332
|
+
*
|
|
333
|
+
* @example
|
|
334
|
+
* ```typescript
|
|
335
|
+
* // All pending approvals for the manager role
|
|
336
|
+
* const items = await client.escalations.list({ role: 'manager', status: 'pending' });
|
|
337
|
+
*
|
|
338
|
+
* // By workflow ID
|
|
339
|
+
* const items = await client.escalations.list({ workflowId: 'order-123' });
|
|
340
|
+
* ```
|
|
341
|
+
*/
|
|
342
|
+
list: async (params) => {
|
|
343
|
+
const hotMeshClient = await this.getHotMeshClient(null, params?.namespace);
|
|
344
|
+
return hotMeshClient.engine.store.listEscalations(params ?? {});
|
|
329
345
|
},
|
|
346
|
+
/**
|
|
347
|
+
* Returns a single escalation row by its UUID primary key.
|
|
348
|
+
* Returns `null` if not found.
|
|
349
|
+
*/
|
|
330
350
|
get: async (id, namespace) => {
|
|
331
|
-
const
|
|
332
|
-
|
|
333
|
-
if (typeof store.getSignal !== 'function')
|
|
334
|
-
return null;
|
|
335
|
-
const ns = namespace ?? factory_1.APP_ID;
|
|
336
|
-
return store.getSignal({ namespace: ns, appId: store.appId, id });
|
|
351
|
+
const hotMeshClient = await this.getHotMeshClient(null, namespace);
|
|
352
|
+
return hotMeshClient.engine.store.getEscalation(id, namespace);
|
|
337
353
|
},
|
|
354
|
+
/**
|
|
355
|
+
* Looks up an escalation row by its `signal_key` — the value that was
|
|
356
|
+
* passed to `condition()` or stored in the hook activity's collation rule.
|
|
357
|
+
* This is the same key used to deliver the signal via `hotMesh.signal()`.
|
|
358
|
+
*
|
|
359
|
+
* @example
|
|
360
|
+
* ```typescript
|
|
361
|
+
* const item = await client.escalations.getBySignalKey('manager-approval');
|
|
362
|
+
* ```
|
|
363
|
+
*/
|
|
338
364
|
getBySignalKey: async (signalKey, namespace) => {
|
|
339
|
-
const
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
365
|
+
const hotMeshClient = await this.getHotMeshClient(null, namespace);
|
|
366
|
+
return hotMeshClient.engine.store.getEscalationBySignalKey(signalKey, namespace);
|
|
367
|
+
},
|
|
368
|
+
/**
|
|
369
|
+
* Creates a standalone escalation row that is **not** backed by a signal.
|
|
370
|
+
* `signal_key` is `null`. Useful for external task tracking that doesn't
|
|
371
|
+
* need to resume a workflow (e.g., audit tasks, out-of-band approvals).
|
|
372
|
+
*
|
|
373
|
+
* @example
|
|
374
|
+
* ```typescript
|
|
375
|
+
* const entry = await client.escalations.create({
|
|
376
|
+
* role: 'support',
|
|
377
|
+
* type: 'data-correction',
|
|
378
|
+
* description: 'Fix the customer address',
|
|
379
|
+
* metadata: { customerId: 'cust-42' },
|
|
380
|
+
* });
|
|
381
|
+
* ```
|
|
382
|
+
*/
|
|
383
|
+
create: async (params) => {
|
|
384
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
385
|
+
return hotMeshClient.engine.store.createEscalation(params);
|
|
386
|
+
},
|
|
387
|
+
/**
|
|
388
|
+
* Patches an existing escalation row. All fields are optional — only
|
|
389
|
+
* provided fields are written. `metadata` is **merged**, not replaced.
|
|
390
|
+
*
|
|
391
|
+
* Signal routing fields (`signalKey`, `topic`, `workflowId`, …) can be
|
|
392
|
+
* enriched after the row is created — useful when the row is created
|
|
393
|
+
* before the workflow starts and routing context is not yet known.
|
|
394
|
+
*
|
|
395
|
+
* @example
|
|
396
|
+
* ```typescript
|
|
397
|
+
* await client.escalations.update({
|
|
398
|
+
* id: item.id,
|
|
399
|
+
* description: 'Updated description',
|
|
400
|
+
* metadata: { extraKey: 'value' }, // merged into existing metadata
|
|
401
|
+
* });
|
|
402
|
+
* ```
|
|
403
|
+
*/
|
|
404
|
+
update: async (params) => {
|
|
405
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
406
|
+
return hotMeshClient.engine.store.updateEscalation(params);
|
|
407
|
+
},
|
|
408
|
+
/**
|
|
409
|
+
* Appends one or more milestone entries to the escalation's
|
|
410
|
+
* `milestones` audit trail array. Milestones are append-only; they
|
|
411
|
+
* record events like state transitions, reviewer notes, or external
|
|
412
|
+
* system callbacks.
|
|
413
|
+
*
|
|
414
|
+
* @example
|
|
415
|
+
* ```typescript
|
|
416
|
+
* await client.escalations.appendMilestones({
|
|
417
|
+
* id: item.id,
|
|
418
|
+
* milestones: [{ at: new Date().toISOString(), by: 'alice', note: 'Reviewed' }],
|
|
419
|
+
* });
|
|
420
|
+
* ```
|
|
421
|
+
*/
|
|
422
|
+
appendMilestones: async (params) => {
|
|
423
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
424
|
+
return hotMeshClient.engine.store.appendEscalationMilestones(params);
|
|
345
425
|
},
|
|
426
|
+
/**
|
|
427
|
+
* Atomically claims an escalation row by UUID. Sets `assigned_to`,
|
|
428
|
+
* `claimed_at`, and `claim_expires_at`. Returns `conflict` if another
|
|
429
|
+
* actor already holds the claim.
|
|
430
|
+
*
|
|
431
|
+
* @example
|
|
432
|
+
* ```typescript
|
|
433
|
+
* const result = await client.escalations.claim({
|
|
434
|
+
* id: item.id,
|
|
435
|
+
* assignee: 'alice@company.com',
|
|
436
|
+
* durationMinutes: 30,
|
|
437
|
+
* });
|
|
438
|
+
* if (!result.ok) console.warn('Already claimed by someone else');
|
|
439
|
+
* ```
|
|
440
|
+
*/
|
|
346
441
|
claim: async (params) => {
|
|
347
|
-
const
|
|
348
|
-
|
|
349
|
-
if (typeof store.claimSignal !== 'function') {
|
|
350
|
-
return { ok: false, reason: 'not-found' };
|
|
351
|
-
}
|
|
352
|
-
const ns = params.namespace ?? factory_1.APP_ID;
|
|
353
|
-
return store.claimSignal({
|
|
354
|
-
namespace: ns,
|
|
355
|
-
appId: store.appId,
|
|
356
|
-
id: params.id,
|
|
357
|
-
assignee: params.assignee,
|
|
358
|
-
durationMinutes: params.durationMinutes,
|
|
359
|
-
});
|
|
442
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
443
|
+
return hotMeshClient.engine.store.claimEscalation(params);
|
|
360
444
|
},
|
|
445
|
+
/**
|
|
446
|
+
* Atomically claims the highest-priority pending escalation whose
|
|
447
|
+
* `metadata` contains the given key/value pair. Uses
|
|
448
|
+
* `FOR UPDATE SKIP LOCKED` so concurrent callers never double-claim.
|
|
449
|
+
*
|
|
450
|
+
* Returns `candidatesExist` to distinguish two cases:
|
|
451
|
+
* - `not-found, candidatesExist: 0` — no rows matched the metadata filter
|
|
452
|
+
* - `conflict, candidatesExist: N` — matching rows exist but all are claimed
|
|
453
|
+
*
|
|
454
|
+
* @example
|
|
455
|
+
* ```typescript
|
|
456
|
+
* const result = await client.escalations.claimByMetadata({
|
|
457
|
+
* key: 'region',
|
|
458
|
+
* value: 'west',
|
|
459
|
+
* assignee: 'bob@company.com',
|
|
460
|
+
* roles: ['manager'],
|
|
461
|
+
* });
|
|
462
|
+
* if (result.ok) console.log('Claimed:', result.entry.id);
|
|
463
|
+
* ```
|
|
464
|
+
*/
|
|
361
465
|
claimByMetadata: async (params) => {
|
|
362
|
-
const
|
|
363
|
-
|
|
364
|
-
if (typeof store.claimSignalByMetadata !== 'function') {
|
|
365
|
-
return { ok: false, reason: 'not-found' };
|
|
366
|
-
}
|
|
367
|
-
const ns = params.namespace ?? factory_1.APP_ID;
|
|
368
|
-
return store.claimSignalByMetadata({
|
|
369
|
-
namespace: ns,
|
|
370
|
-
appId: store.appId,
|
|
371
|
-
key: params.key,
|
|
372
|
-
value: params.value,
|
|
373
|
-
assignee: params.assignee,
|
|
374
|
-
durationMinutes: params.durationMinutes,
|
|
375
|
-
});
|
|
466
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
467
|
+
return hotMeshClient.engine.store.claimEscalationByMetadata(params);
|
|
376
468
|
},
|
|
469
|
+
/**
|
|
470
|
+
* Releases a claimed escalation, returning it to `pending` status and
|
|
471
|
+
* clearing `assigned_to` and `claim_expires_at`. The row is immediately
|
|
472
|
+
* available for other actors to claim.
|
|
473
|
+
*
|
|
474
|
+
* @example
|
|
475
|
+
* ```typescript
|
|
476
|
+
* await client.escalations.release({ id: item.id });
|
|
477
|
+
* ```
|
|
478
|
+
*/
|
|
377
479
|
release: async (params) => {
|
|
378
|
-
const
|
|
379
|
-
|
|
380
|
-
if (typeof store.releaseSignal !== 'function') {
|
|
381
|
-
return { ok: false, reason: 'not-found' };
|
|
382
|
-
}
|
|
383
|
-
const ns = params.namespace ?? factory_1.APP_ID;
|
|
384
|
-
return store.releaseSignal({
|
|
385
|
-
namespace: ns,
|
|
386
|
-
appId: store.appId,
|
|
387
|
-
id: params.id,
|
|
388
|
-
});
|
|
480
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
481
|
+
return hotMeshClient.engine.store.releaseEscalation(params);
|
|
389
482
|
},
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
483
|
+
/**
|
|
484
|
+
* Reassigns the escalation to a different role, clearing any current
|
|
485
|
+
* claim and returning status to `pending`. Use when an escalation must
|
|
486
|
+
* be handled by a different team or tier.
|
|
487
|
+
*
|
|
488
|
+
* @example
|
|
489
|
+
* ```typescript
|
|
490
|
+
* await client.escalations.escalateToRole({ id: item.id, role: 'senior-manager' });
|
|
491
|
+
* ```
|
|
492
|
+
*/
|
|
493
|
+
escalateToRole: async (params) => {
|
|
494
|
+
const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
|
|
495
|
+
return hotMeshClient.engine.store.escalateEscalationToRole(params);
|
|
496
|
+
},
|
|
497
|
+
/**
|
|
498
|
+
* Terminates the escalation without delivering a signal. Rows in
|
|
499
|
+
* `pending` or `claimed` state move to `cancelled`. Terminal rows
|
|
500
|
+
* (`resolved`, `cancelled`) return `already-terminal`.
|
|
501
|
+
*
|
|
502
|
+
* @example
|
|
503
|
+
* ```typescript
|
|
504
|
+
* await client.escalations.cancel(item.id);
|
|
505
|
+
* ```
|
|
506
|
+
*/
|
|
507
|
+
cancel: async (id, namespace) => {
|
|
508
|
+
const hotMeshClient = await this.getHotMeshClient(null, namespace);
|
|
509
|
+
return hotMeshClient.engine.store.cancelEscalation(id, namespace);
|
|
510
|
+
},
|
|
511
|
+
/**
|
|
512
|
+
* Atomically marks the escalation `resolved` **and** delivers the
|
|
513
|
+
* signal to the waiting workflow — one round-trip, no separate
|
|
514
|
+
* `signal()` call required. If `signal_key` is null (standalone
|
|
515
|
+
* escalation), only the row is updated.
|
|
516
|
+
*
|
|
517
|
+
* @example
|
|
518
|
+
* ```typescript
|
|
519
|
+
* const result = await client.escalations.resolve({
|
|
520
|
+
* id: item.id,
|
|
521
|
+
* resolverPayload: { approved: true, note: 'LGTM' },
|
|
522
|
+
* });
|
|
523
|
+
* if (!result.ok) console.error(result.reason); // 'not-found' | 'already-resolved' | 'signal-failed'
|
|
524
|
+
* // workflow resumes with { approved: true, note: 'LGTM' }
|
|
525
|
+
* ```
|
|
526
|
+
*/
|
|
527
|
+
resolve: async (params, namespace) => {
|
|
528
|
+
const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
|
|
529
|
+
const hotMeshClient = await this.getHotMeshClient(null, ns);
|
|
530
|
+
const store = hotMeshClient.engine.store;
|
|
531
|
+
// store.resolveEscalation() uses FOR UPDATE inside its CTE, serializing concurrent
|
|
532
|
+
// callers at the DB level. The second caller blocks on the row lock, reads
|
|
533
|
+
// 'already-resolved' after the first commits, and returns — no signal is queued.
|
|
534
|
+
// This eliminates the double-signal race that the previous KVTransaction approach
|
|
535
|
+
// had: two concurrent callers could both pass the unlocked getEscalation() read,
|
|
536
|
+
// both queue signal INSERTs, and both commit them — even though only one UPDATE won.
|
|
537
|
+
const dbResult = await store.resolveEscalation({
|
|
400
538
|
id: params.id,
|
|
401
539
|
resolverPayload: params.resolverPayload,
|
|
540
|
+
// namespace intentionally omitted — UUID lookup; passing ns would miss rows
|
|
541
|
+
// stored under namespace 'hmsh' (the engine default) when ns = APP_ID = 'durable'.
|
|
402
542
|
});
|
|
403
|
-
if (!
|
|
404
|
-
return
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
return { ok: false, reason: 'signal-failed', signalKey: storeResult.signalKey };
|
|
543
|
+
if (!dbResult.ok)
|
|
544
|
+
return dbResult;
|
|
545
|
+
if (dbResult.signalKey) {
|
|
546
|
+
const signalPayload = { id: dbResult.signalKey, data: params.resolverPayload ?? {} };
|
|
547
|
+
const delivered = await this._deliverEscalationSignal(ns, dbResult.topic, signalPayload);
|
|
548
|
+
if (!delivered)
|
|
549
|
+
return { ok: false, reason: 'signal-failed' };
|
|
411
550
|
}
|
|
551
|
+
return { ok: true };
|
|
412
552
|
},
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
553
|
+
/**
|
|
554
|
+
* Resolves the highest-priority matching escalation by metadata filter,
|
|
555
|
+
* then delivers its signal. Identical semantics to `resolve()` but
|
|
556
|
+
* selects the target row by metadata key/value instead of UUID.
|
|
557
|
+
*
|
|
558
|
+
* @example
|
|
559
|
+
* ```typescript
|
|
560
|
+
* await client.escalations.resolveByMetadata({
|
|
561
|
+
* key: 'orderId',
|
|
562
|
+
* value: 'order-123',
|
|
563
|
+
* resolverPayload: { approved: true },
|
|
564
|
+
* });
|
|
565
|
+
* ```
|
|
566
|
+
*/
|
|
567
|
+
resolveByMetadata: async (params, namespace) => {
|
|
568
|
+
const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
|
|
569
|
+
const hotMeshClient = await this.getHotMeshClient(null, ns);
|
|
570
|
+
const store = hotMeshClient.engine.store;
|
|
571
|
+
// Same FOR UPDATE CTE serialization as resolve(). Metadata filter selects
|
|
572
|
+
// the highest-priority matching row; the lock prevents concurrent callers
|
|
573
|
+
// from both resolving it.
|
|
574
|
+
const dbResult = await store.resolveEscalationByMetadata({
|
|
423
575
|
key: params.key,
|
|
424
576
|
value: params.value,
|
|
425
577
|
resolverPayload: params.resolverPayload,
|
|
578
|
+
roles: params.roles,
|
|
426
579
|
});
|
|
427
|
-
if (!
|
|
428
|
-
return
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
return { ok: false, reason: 'signal-failed', signalKey: storeResult.signalKey };
|
|
580
|
+
if (!dbResult.ok)
|
|
581
|
+
return dbResult;
|
|
582
|
+
if (dbResult.signalKey) {
|
|
583
|
+
const signalPayload = { id: dbResult.signalKey, data: params.resolverPayload ?? {} };
|
|
584
|
+
const delivered = await this._deliverEscalationSignal(ns, dbResult.topic, signalPayload);
|
|
585
|
+
if (!delivered)
|
|
586
|
+
return { ok: false, reason: 'signal-failed' };
|
|
435
587
|
}
|
|
588
|
+
return { ok: true };
|
|
436
589
|
},
|
|
590
|
+
/**
|
|
591
|
+
* Full-fidelity migration: inserts an escalation row preserving the original
|
|
592
|
+
* UUID and all lifecycle state. Returns the inserted row, or `null` if the
|
|
593
|
+
* UUID already exists (idempotent — safe to call multiple times with the same
|
|
594
|
+
* `params.id`). Use this to migrate rows from a legacy escalation table to
|
|
595
|
+
* `hmsh_escalations` without losing original IDs or state.
|
|
596
|
+
*
|
|
597
|
+
* @example
|
|
598
|
+
* ```typescript
|
|
599
|
+
* const entry = await client.escalations.migrate({
|
|
600
|
+
* id: 'original-uuid',
|
|
601
|
+
* status: 'resolved',
|
|
602
|
+
* resolvedAt: new Date('2025-01-01'),
|
|
603
|
+
* type: 'order-approval',
|
|
604
|
+
* role: 'approver',
|
|
605
|
+
* });
|
|
606
|
+
* // null on subsequent calls with the same id — idempotent
|
|
607
|
+
* ```
|
|
608
|
+
*/
|
|
609
|
+
migrate: async (params, namespace) => {
|
|
610
|
+
const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
|
|
611
|
+
const hotMeshClient = await this.getHotMeshClient(null, ns);
|
|
612
|
+
return hotMeshClient.engine.store.createEscalationForMigration(params);
|
|
613
|
+
},
|
|
614
|
+
/**
|
|
615
|
+
* Releases all claimed escalations whose `claim_expires_at` has lapsed,
|
|
616
|
+
* returning them to `pending` so they can be claimed again. Returns the
|
|
617
|
+
* number of rows released. Call periodically from a maintenance job or
|
|
618
|
+
* cron to prevent stale claims from blocking the queue.
|
|
619
|
+
*
|
|
620
|
+
* @example
|
|
621
|
+
* ```typescript
|
|
622
|
+
* const released = await client.escalations.releaseExpired();
|
|
623
|
+
* console.log(`Released ${released} expired claims`);
|
|
624
|
+
* ```
|
|
625
|
+
*/
|
|
437
626
|
releaseExpired: async (namespace) => {
|
|
438
|
-
const
|
|
439
|
-
|
|
440
|
-
if (typeof store.releaseExpiredSignals !== 'function')
|
|
441
|
-
return 0;
|
|
442
|
-
const ns = namespace ?? factory_1.APP_ID;
|
|
443
|
-
return store.releaseExpiredSignals({ namespace: ns, appId: store.appId });
|
|
627
|
+
const hotMeshClient = await this.getHotMeshClient(null, namespace);
|
|
628
|
+
return hotMeshClient.engine.store.releaseExpiredEscalations(namespace);
|
|
444
629
|
},
|
|
445
630
|
};
|
|
446
631
|
this.connection = config.connection;
|
|
@@ -518,6 +703,46 @@ class ClientService {
|
|
|
518
703
|
}
|
|
519
704
|
}
|
|
520
705
|
}
|
|
706
|
+
/**
|
|
707
|
+
* Delivers a signal to the registered escalation topic.
|
|
708
|
+
*
|
|
709
|
+
* When the topic is known (stored at condition() time), we deliver only to that
|
|
710
|
+
* topic. This avoids writing a stale pending entry to the alternate stream, which
|
|
711
|
+
* would interfere with concurrent consumers in other workflows or tests.
|
|
712
|
+
*
|
|
713
|
+
* When topic is null (legacy/standalone rows with no registered topic), we try
|
|
714
|
+
* both wfs.signal and wfs.wait unconditionally — engine.signal() on the wrong
|
|
715
|
+
* topic stores pending without throwing, so a sequential fallback would skip
|
|
716
|
+
* the second topic and leave single-condition workflows permanently suspended.
|
|
717
|
+
*
|
|
718
|
+
* @private
|
|
719
|
+
*/
|
|
720
|
+
async _deliverEscalationSignal(ns, topic, signalPayload) {
|
|
721
|
+
if (topic) {
|
|
722
|
+
// Registered topic known — deliver precisely, no stream pollution.
|
|
723
|
+
try {
|
|
724
|
+
const tc = await this.getHotMeshClient(topic, ns);
|
|
725
|
+
await tc.engine.signal(topic, signalPayload, types_1.StreamStatus.SUCCESS, 200);
|
|
726
|
+
return true;
|
|
727
|
+
}
|
|
728
|
+
catch { /* topic not currently registered — fall through */ }
|
|
729
|
+
}
|
|
730
|
+
// Topic unknown or primary delivery failed — try both topics unconditionally.
|
|
731
|
+
let delivered = false;
|
|
732
|
+
try {
|
|
733
|
+
const sc = await this.getHotMeshClient(`${ns}.wfs.signal`, ns);
|
|
734
|
+
await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
|
|
735
|
+
delivered = true;
|
|
736
|
+
}
|
|
737
|
+
catch { /* no collator hook rule for this workflow */ }
|
|
738
|
+
try {
|
|
739
|
+
const wc = await this.getHotMeshClient(`${ns}.wfs.wait`, ns);
|
|
740
|
+
await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
|
|
741
|
+
delivered = true;
|
|
742
|
+
}
|
|
743
|
+
catch { /* no waiter hook rule for this workflow */ }
|
|
744
|
+
return delivered;
|
|
745
|
+
}
|
|
521
746
|
/**
|
|
522
747
|
* @private
|
|
523
748
|
*/
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { HotMesh } from '../hotmesh';
|
|
2
2
|
import { ContextType, WorkflowInboundCallsInterceptor, WorkflowOutboundCallsInterceptor, ActivityInboundCallsInterceptor } from '../../types/durable';
|
|
3
|
-
import { guid } from '../../modules/utils';
|
|
3
|
+
import { guid, uuid } from '../../modules/utils';
|
|
4
4
|
import { ClientService } from './client';
|
|
5
5
|
import { ConnectionService } from './connection';
|
|
6
6
|
import { Search } from './search';
|
|
@@ -277,6 +277,12 @@ declare class DurableClass {
|
|
|
277
277
|
* Generate a unique identifier for workflow IDs
|
|
278
278
|
*/
|
|
279
279
|
static guid: typeof guid;
|
|
280
|
+
/**
|
|
281
|
+
* Generate a standard RFC 4122 v4 UUID — use for DB primary keys and
|
|
282
|
+
* any context that requires a hyphenated UUID format rather than the
|
|
283
|
+
* compact HotMesh guid format.
|
|
284
|
+
*/
|
|
285
|
+
static uuid: typeof uuid;
|
|
280
286
|
/**
|
|
281
287
|
* Provision a scoped Postgres role for a worker. The role can only
|
|
282
288
|
* dequeue, ack, and respond on its assigned stream names via stored
|
|
@@ -318,5 +324,3 @@ declare class DurableClass {
|
|
|
318
324
|
}
|
|
319
325
|
export { DurableClass as Durable };
|
|
320
326
|
export type { ContextType };
|
|
321
|
-
export type { ConditionQueueConfig } from './workflow/condition';
|
|
322
|
-
export type { ClaimSignalResult, ReleaseSignalResult, ResolveSignalResult, SignalQueueEntry, } from '../../types/signal';
|
|
@@ -310,6 +310,12 @@ DurableClass.interceptorService = new interceptor_1.InterceptorService();
|
|
|
310
310
|
* Generate a unique identifier for workflow IDs
|
|
311
311
|
*/
|
|
312
312
|
DurableClass.guid = utils_1.guid;
|
|
313
|
+
/**
|
|
314
|
+
* Generate a standard RFC 4122 v4 UUID — use for DB primary keys and
|
|
315
|
+
* any context that requires a hyphenated UUID format rather than the
|
|
316
|
+
* compact HotMesh guid format.
|
|
317
|
+
*/
|
|
318
|
+
DurableClass.uuid = utils_1.uuid;
|
|
313
319
|
/**
|
|
314
320
|
* Provision a scoped Postgres role for a worker. The role can only
|
|
315
321
|
* dequeue, ack, and respond on its assigned stream names via stored
|
|
@@ -336,6 +336,9 @@ const getWorkflowYAML = (app, version) => {
|
|
|
336
336
|
type: string
|
|
337
337
|
originJobId:
|
|
338
338
|
type: string
|
|
339
|
+
queueConfig:
|
|
340
|
+
type: object
|
|
341
|
+
description: optional escalation queue config passed to condition()
|
|
339
342
|
job:
|
|
340
343
|
maps:
|
|
341
344
|
response: '{$self.output.data.response}'
|
|
@@ -370,6 +373,23 @@ const getWorkflowYAML = (app, version) => {
|
|
|
370
373
|
waiter:
|
|
371
374
|
title: Waits for a matching signal or optional timeout (single condition)
|
|
372
375
|
type: hook
|
|
376
|
+
escalation:
|
|
377
|
+
type: '{worker.output.data.queueConfig.type}'
|
|
378
|
+
subtype: '{worker.output.data.queueConfig.subtype}'
|
|
379
|
+
entity: '{worker.output.data.queueConfig.entity}'
|
|
380
|
+
description: '{worker.output.data.queueConfig.description}'
|
|
381
|
+
role: '{worker.output.data.queueConfig.role}'
|
|
382
|
+
priority: '{worker.output.data.queueConfig.priority}'
|
|
383
|
+
metadata: '{worker.output.data.queueConfig.metadata}'
|
|
384
|
+
envelope: '{worker.output.data.queueConfig.envelope}'
|
|
385
|
+
originId: '{worker.output.data.queueConfig.originId}'
|
|
386
|
+
parentId: '{worker.output.data.queueConfig.parentId}'
|
|
387
|
+
initiatedBy: '{worker.output.data.queueConfig.initiatedBy}'
|
|
388
|
+
traceId: '{worker.output.data.queueConfig.traceId}'
|
|
389
|
+
spanId: '{worker.output.data.queueConfig.spanId}'
|
|
390
|
+
expiresAt: '{worker.output.data.queueConfig.expiresAt}'
|
|
391
|
+
taskQueue: '{trigger.output.data.taskQueue}'
|
|
392
|
+
workflowType: '{trigger.output.data.workflowName}'
|
|
373
393
|
sleep: '{worker.output.data.duration}'
|
|
374
394
|
hook:
|
|
375
395
|
type: object
|
|
@@ -1137,6 +1157,9 @@ const getWorkflowYAML = (app, version) => {
|
|
|
1137
1157
|
type: string
|
|
1138
1158
|
originJobId:
|
|
1139
1159
|
type: string
|
|
1160
|
+
queueConfig:
|
|
1161
|
+
type: object
|
|
1162
|
+
description: optional escalation queue config passed to condition()
|
|
1140
1163
|
|
|
1141
1164
|
signaler_sleeper:
|
|
1142
1165
|
title: Pauses a single thread within the worker for a set amount of seconds while the main flow thread and all other subthreads remain active
|
|
@@ -1165,6 +1188,23 @@ const getWorkflowYAML = (app, version) => {
|
|
|
1165
1188
|
signaler_waiter:
|
|
1166
1189
|
title: Waits for a matching signal or optional timeout (single condition in signal-in path)
|
|
1167
1190
|
type: hook
|
|
1191
|
+
escalation:
|
|
1192
|
+
type: '{signaler_worker.output.data.queueConfig.type}'
|
|
1193
|
+
subtype: '{signaler_worker.output.data.queueConfig.subtype}'
|
|
1194
|
+
entity: '{signaler_worker.output.data.queueConfig.entity}'
|
|
1195
|
+
description: '{signaler_worker.output.data.queueConfig.description}'
|
|
1196
|
+
role: '{signaler_worker.output.data.queueConfig.role}'
|
|
1197
|
+
priority: '{signaler_worker.output.data.queueConfig.priority}'
|
|
1198
|
+
metadata: '{signaler_worker.output.data.queueConfig.metadata}'
|
|
1199
|
+
envelope: '{signaler_worker.output.data.queueConfig.envelope}'
|
|
1200
|
+
originId: '{signaler_worker.output.data.queueConfig.originId}'
|
|
1201
|
+
parentId: '{signaler_worker.output.data.queueConfig.parentId}'
|
|
1202
|
+
initiatedBy: '{signaler_worker.output.data.queueConfig.initiatedBy}'
|
|
1203
|
+
traceId: '{signaler_worker.output.data.queueConfig.traceId}'
|
|
1204
|
+
spanId: '{signaler_worker.output.data.queueConfig.spanId}'
|
|
1205
|
+
expiresAt: '{signaler_worker.output.data.queueConfig.expiresAt}'
|
|
1206
|
+
taskQueue: '{trigger.output.data.taskQueue}'
|
|
1207
|
+
workflowType: '{trigger.output.data.workflowName}'
|
|
1168
1208
|
sleep: '{signaler_worker.output.data.duration}'
|
|
1169
1209
|
hook:
|
|
1170
1210
|
type: object
|