pi-wechat-session-hub 0.1.1 → 0.1.2
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/CHANGELOG.md +95 -0
- package/README.md +420 -365
- package/docs/handoff-next-session.md +4 -4
- package/docs/implementation-spec.md +150 -147
- package/extensions/daemon-entry.mjs +31 -0
- package/extensions/wechat-session-hub.ts +12 -12
- package/package.json +72 -68
- package/scripts/release-preflight.mjs +229 -0
- package/src/gateway/command-parser.ts +25 -9
- package/src/gateway/command-router.ts +1790 -1449
- package/src/gateway/durable-message-queue.ts +1154 -1043
- package/src/gateway/gateway-control-ipc.ts +705 -687
- package/src/gateway/turn-health.ts +305 -0
- package/src/gateway/ui-worker-extension-bridge.ts +1 -4
- package/src/gateway/wechat-ilink/api-client.ts +386 -390
- package/src/runtime/gateway-service-controller.ts +341 -339
- package/src/runtime/windows-logon-autostart-manager.ts +401 -0
- package/src/runtime/windows-logon-task-manager.ts +0 -212
|
@@ -1,1043 +1,1154 @@
|
|
|
1
|
-
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
-
import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
|
|
3
|
-
import { dirname, join } from "node:path";
|
|
4
|
-
import { GatewayLease } from "../registry/gateway-lease.ts";
|
|
5
|
-
import type { IlinkReplyContext } from "./channel-types.ts";
|
|
6
|
-
|
|
7
|
-
export type QueueItemState =
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
export
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
)
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
* @param
|
|
134
|
-
* @param
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
throw new DurableQueueError(
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
const
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
*
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
*
|
|
313
|
-
*
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
await this.
|
|
351
|
-
const
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
if (
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
*
|
|
445
|
-
*
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
if (
|
|
499
|
-
this.
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
);
|
|
540
|
-
this.
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
}
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
*
|
|
568
|
-
*
|
|
569
|
-
* @param
|
|
570
|
-
* @
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
}
|
|
582
|
-
|
|
583
|
-
/**
|
|
584
|
-
*
|
|
585
|
-
*
|
|
586
|
-
* @param
|
|
587
|
-
* @param
|
|
588
|
-
* @returns 无返回值。
|
|
589
|
-
*/
|
|
590
|
-
private
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
):
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
*
|
|
642
|
-
*
|
|
643
|
-
* @param
|
|
644
|
-
* @returns
|
|
645
|
-
*/
|
|
646
|
-
private
|
|
647
|
-
const
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
*
|
|
682
|
-
*
|
|
683
|
-
* @
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
const
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
}
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
*
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
state
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
*
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
}
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
}
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { GatewayLease } from "../registry/gateway-lease.ts";
|
|
5
|
+
import type { IlinkReplyContext } from "./channel-types.ts";
|
|
6
|
+
|
|
7
|
+
export type QueueItemState =
|
|
8
|
+
| "queued"
|
|
9
|
+
| "processing"
|
|
10
|
+
| "completed"
|
|
11
|
+
| "failed"
|
|
12
|
+
| "interrupted"
|
|
13
|
+
| "skipped";
|
|
14
|
+
|
|
15
|
+
export interface DurableQueueItem {
|
|
16
|
+
id: string;
|
|
17
|
+
messageId: string;
|
|
18
|
+
routeId: string;
|
|
19
|
+
text: string;
|
|
20
|
+
receivedAt: string;
|
|
21
|
+
updatedAt: string;
|
|
22
|
+
state: QueueItemState;
|
|
23
|
+
attempts: number;
|
|
24
|
+
errorCode?: string;
|
|
25
|
+
replyContext?: IlinkReplyContext;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export type QueueClaimResult =
|
|
29
|
+
| { kind: "claimed"; item: DurableQueueItem }
|
|
30
|
+
| { kind: "empty" }
|
|
31
|
+
| { kind: "skipped"; item: DurableQueueItem };
|
|
32
|
+
|
|
33
|
+
export interface QueueDispatchResult {
|
|
34
|
+
item: DurableQueueItem;
|
|
35
|
+
duplicate: boolean;
|
|
36
|
+
reply?: string;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export type QueueProcessor = (item: DurableQueueItem) => Promise<string>;
|
|
40
|
+
|
|
41
|
+
type QueueWaiter = {
|
|
42
|
+
duplicate: boolean;
|
|
43
|
+
promise: Promise<QueueDispatchResult>;
|
|
44
|
+
resolve: (result: QueueDispatchResult) => void;
|
|
45
|
+
reject: (error: Error) => void;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
type SkippedNotifier = (routeId: string, item: DurableQueueItem) => Promise<void>;
|
|
49
|
+
|
|
50
|
+
interface EnqueueEvent {
|
|
51
|
+
type: "enqueue";
|
|
52
|
+
id: string;
|
|
53
|
+
messageId: string;
|
|
54
|
+
text: string;
|
|
55
|
+
receivedAt: string;
|
|
56
|
+
replyContext?: IlinkReplyContext;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
interface StateEvent {
|
|
60
|
+
type: "state";
|
|
61
|
+
id: string;
|
|
62
|
+
state: QueueItemState;
|
|
63
|
+
updatedAt: string;
|
|
64
|
+
attempts: number;
|
|
65
|
+
errorCode?: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
interface DedupeIndex {
|
|
69
|
+
schemaVersion: 1;
|
|
70
|
+
entries: Array<{ messageHash: string; completedAt: string }>;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
type QueueEvent = EnqueueEvent | StateEvent;
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* 表示 durable queue 发生容量、幂等或状态冲突。
|
|
77
|
+
*/
|
|
78
|
+
export class DurableQueueError extends Error {
|
|
79
|
+
/**
|
|
80
|
+
* 创建 queue 错误。
|
|
81
|
+
*
|
|
82
|
+
* @param code 稳定错误代码。
|
|
83
|
+
* @param message 面向用户的中文错误信息。
|
|
84
|
+
*/
|
|
85
|
+
constructor(
|
|
86
|
+
readonly code:
|
|
87
|
+
| "queue_full"
|
|
88
|
+
| "queue_item_not_found"
|
|
89
|
+
| "invalid_queue_transition"
|
|
90
|
+
| "queue_blocked",
|
|
91
|
+
message: string,
|
|
92
|
+
) {
|
|
93
|
+
super(message);
|
|
94
|
+
this.name = "DurableQueueError";
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* 表示 queue JSONL 损坏, 需要 fail-closed 人工检查。
|
|
100
|
+
*/
|
|
101
|
+
export class QueueCorruptionError extends Error {
|
|
102
|
+
/**
|
|
103
|
+
* 创建 queue 文件损坏错误。
|
|
104
|
+
*
|
|
105
|
+
* @param message 不包含消息正文的中文说明。
|
|
106
|
+
*/
|
|
107
|
+
constructor(message: string) {
|
|
108
|
+
super(message);
|
|
109
|
+
this.name = "QueueCorruptionError";
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
const MAX_RECENT_DEDUPE_IDS = 1000;
|
|
114
|
+
|
|
115
|
+
const MAX_RETAINED_SKIPPED_ITEMS = 20;
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* 将路由消息保存为按 route 分片的 append-only JSONL 队列。
|
|
119
|
+
*/
|
|
120
|
+
export class DurableMessageQueue {
|
|
121
|
+
private writeQueue: Promise<void> = Promise.resolve();
|
|
122
|
+
private readonly drainingRoutes = new Set<string>();
|
|
123
|
+
private readonly drainRequested = new Set<string>();
|
|
124
|
+
private readonly idleWaiters = new Set<() => void>();
|
|
125
|
+
private readonly waiters = new Map<string, QueueWaiter>();
|
|
126
|
+
private readonly waiterRoutes = new Map<string, string>();
|
|
127
|
+
private readonly skippedNotices = new Map<string, DurableQueueItem[]>();
|
|
128
|
+
private skippedNotifier?: SkippedNotifier;
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* 创建 durable queue。
|
|
132
|
+
*
|
|
133
|
+
* @param directory manager 数据目录。
|
|
134
|
+
* @param lease Gateway owner 租约。
|
|
135
|
+
*/
|
|
136
|
+
constructor(
|
|
137
|
+
readonly directory: string,
|
|
138
|
+
private readonly lease: GatewayLease,
|
|
139
|
+
) {}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* 持久化入站消息并按 messageId 去重。
|
|
143
|
+
*
|
|
144
|
+
* @param routeId 个人微信对话稳定 ID。
|
|
145
|
+
* @param messageId iLink 提供的幂等消息 ID。
|
|
146
|
+
* @param text 消息正文, 仅写入私有 queue 文件。
|
|
147
|
+
* @param maxPending 最大未完成消息数。
|
|
148
|
+
* @returns 队列项及是否为重复消息。
|
|
149
|
+
* @throws {DurableQueueError} 容量不足或参数非法时抛出。
|
|
150
|
+
*/
|
|
151
|
+
async enqueue(
|
|
152
|
+
routeId: string,
|
|
153
|
+
messageId: string,
|
|
154
|
+
text: string,
|
|
155
|
+
maxPending: number,
|
|
156
|
+
replyContext?: IlinkReplyContext,
|
|
157
|
+
): Promise<{ item: DurableQueueItem; duplicate: boolean }> {
|
|
158
|
+
if (
|
|
159
|
+
!routeId.trim() ||
|
|
160
|
+
routeId.length > 256 ||
|
|
161
|
+
!messageId.trim() ||
|
|
162
|
+
messageId.length > 512 ||
|
|
163
|
+
!text.trim() ||
|
|
164
|
+
(replyContext !== undefined && (
|
|
165
|
+
!replyContext.recipientId.trim() ||
|
|
166
|
+
!replyContext.contextToken.trim() ||
|
|
167
|
+
replyContext.recipientId.length > 256 ||
|
|
168
|
+
replyContext.contextToken.length > 8192
|
|
169
|
+
))
|
|
170
|
+
) {
|
|
171
|
+
throw new DurableQueueError(
|
|
172
|
+
"invalid_queue_transition",
|
|
173
|
+
"routeId、messageId 不能为空且长度需在限制内, 消息正文也不能为空。",
|
|
174
|
+
);
|
|
175
|
+
}
|
|
176
|
+
if (text.length > 32000) {
|
|
177
|
+
throw new DurableQueueError(
|
|
178
|
+
"invalid_queue_transition",
|
|
179
|
+
"消息正文超过 durable queue 的单条消息上限。",
|
|
180
|
+
);
|
|
181
|
+
}
|
|
182
|
+
if (!Number.isInteger(maxPending) || maxPending <= 0) {
|
|
183
|
+
throw new DurableQueueError("invalid_queue_transition", "maxPending 必须是正整数。");
|
|
184
|
+
}
|
|
185
|
+
return this.withWriteQueue(async () => {
|
|
186
|
+
await this.lease.assertOwned();
|
|
187
|
+
const items = await this.loadRoute(routeId);
|
|
188
|
+
const duplicate = [...items.values()].find((item) => item.messageId === messageId);
|
|
189
|
+
if (duplicate) {
|
|
190
|
+
if (duplicate.state === "completed") {
|
|
191
|
+
await this.compactRouteUnlocked(routeId, items.values());
|
|
192
|
+
}
|
|
193
|
+
return { item: duplicate, duplicate: true };
|
|
194
|
+
}
|
|
195
|
+
if ([...items.values()].some((item) => item.state === "completed")) {
|
|
196
|
+
await this.compactRouteUnlocked(routeId, items.values());
|
|
197
|
+
}
|
|
198
|
+
const dedupeIndex = await this.readDedupeIndex(routeId);
|
|
199
|
+
const completedAt = dedupeIndex.entries.find((entry) => entry.messageHash === hashMessageId(messageId))?.completedAt;
|
|
200
|
+
if (completedAt) {
|
|
201
|
+
return {
|
|
202
|
+
item: {
|
|
203
|
+
id: `dedupe:${hashMessageId(messageId)}`,
|
|
204
|
+
messageId,
|
|
205
|
+
routeId,
|
|
206
|
+
text: "",
|
|
207
|
+
receivedAt: completedAt,
|
|
208
|
+
updatedAt: completedAt,
|
|
209
|
+
state: "completed",
|
|
210
|
+
attempts: 0,
|
|
211
|
+
},
|
|
212
|
+
duplicate: true,
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
const pendingCount = [...items.values()].filter((item) =>
|
|
216
|
+
item.state === "queued" || item.state === "processing" || item.state === "interrupted" || item.state === "failed",
|
|
217
|
+
).length;
|
|
218
|
+
if (pendingCount >= maxPending) {
|
|
219
|
+
throw new DurableQueueError(
|
|
220
|
+
"queue_full",
|
|
221
|
+
`当前 route 队列已达到上限 ${maxPending}, 新消息未入队。`,
|
|
222
|
+
);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
const now = new Date().toISOString();
|
|
226
|
+
const event: EnqueueEvent = {
|
|
227
|
+
type: "enqueue",
|
|
228
|
+
id: randomUUID(),
|
|
229
|
+
messageId,
|
|
230
|
+
text,
|
|
231
|
+
receivedAt: now,
|
|
232
|
+
...(replyContext ? { replyContext } : {}),
|
|
233
|
+
};
|
|
234
|
+
await this.appendEvent(routeId, event);
|
|
235
|
+
return {
|
|
236
|
+
item: {
|
|
237
|
+
...event,
|
|
238
|
+
routeId,
|
|
239
|
+
updatedAt: now,
|
|
240
|
+
state: "queued",
|
|
241
|
+
attempts: 0,
|
|
242
|
+
},
|
|
243
|
+
duplicate: false,
|
|
244
|
+
};
|
|
245
|
+
});
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* 入队并按 route FIFO 处理消息; handler 应先完成实际回复投递再返回。
|
|
250
|
+
*
|
|
251
|
+
* @param routeId route 稳定 ID。
|
|
252
|
+
* @param messageId channel 提供的幂等 ID。
|
|
253
|
+
* @param text 用户消息正文。
|
|
254
|
+
* @param maxPending 最大未完成消息数。
|
|
255
|
+
* @param processor 单条消息处理函数。
|
|
256
|
+
* @returns 处理结果; 重复且已结束的消息不再执行。
|
|
257
|
+
*/
|
|
258
|
+
async dispatch(
|
|
259
|
+
routeId: string,
|
|
260
|
+
messageId: string,
|
|
261
|
+
text: string,
|
|
262
|
+
maxPending: number,
|
|
263
|
+
processor: QueueProcessor,
|
|
264
|
+
replyContext?: IlinkReplyContext,
|
|
265
|
+
): Promise<QueueDispatchResult> {
|
|
266
|
+
const { item, duplicate } = await this.enqueue(routeId, messageId, text, maxPending, replyContext);
|
|
267
|
+
if (duplicate && item.state !== "queued") {
|
|
268
|
+
if (item.state === "processing" && !this.waiters.has(item.id)) {
|
|
269
|
+
this.kickDrain(routeId, processor);
|
|
270
|
+
}
|
|
271
|
+
return { item, duplicate: true };
|
|
272
|
+
}
|
|
273
|
+
const existingWaiter = this.waiters.get(item.id);
|
|
274
|
+
if (existingWaiter) {
|
|
275
|
+
return existingWaiter.promise;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
let resolveResult!: (result: QueueDispatchResult) => void;
|
|
279
|
+
let rejectResult!: (error: Error) => void;
|
|
280
|
+
const result = new Promise<QueueDispatchResult>((resolvePromise, rejectPromise) => {
|
|
281
|
+
resolveResult = resolvePromise;
|
|
282
|
+
rejectResult = rejectPromise;
|
|
283
|
+
});
|
|
284
|
+
this.waiters.set(item.id, {
|
|
285
|
+
duplicate,
|
|
286
|
+
promise: result,
|
|
287
|
+
resolve: resolveResult,
|
|
288
|
+
reject: rejectResult,
|
|
289
|
+
});
|
|
290
|
+
this.waiterRoutes.set(item.id, routeId);
|
|
291
|
+
this.kickDrain(routeId, processor);
|
|
292
|
+
return result;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* 等待当前已启动的所有 route FIFO drain 完成。
|
|
297
|
+
*
|
|
298
|
+
* Gateway 停止接收新消息后应等待此方法, 再关闭 worker 并释放单写者租约。
|
|
299
|
+
*
|
|
300
|
+
* @returns 所有 drain 完成时正常结束。
|
|
301
|
+
*/
|
|
302
|
+
async waitForIdle(): Promise<void> {
|
|
303
|
+
if (this.drainingRoutes.size === 0) {
|
|
304
|
+
return;
|
|
305
|
+
}
|
|
306
|
+
await new Promise<void>((resolveIdle) => {
|
|
307
|
+
this.idleWaiters.add(resolveIdle);
|
|
308
|
+
});
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* 注册失败项被自动跳过时的通知回调。
|
|
313
|
+
*
|
|
314
|
+
* 通知为 best-effort: 回调失败不会阻塞队列继续处理后续消息。
|
|
315
|
+
*
|
|
316
|
+
* @param notifier 跳过通知回调, 传 undefined 取消注册。
|
|
317
|
+
* @returns 无返回值。
|
|
318
|
+
*/
|
|
319
|
+
setSkippedNotifier(notifier: SkippedNotifier | undefined): void {
|
|
320
|
+
this.skippedNotifier = notifier;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* 恢复某 route 的 queued 消息处理; 失败或中断项会被自动跳过而不是阻塞 FIFO。
|
|
325
|
+
*
|
|
326
|
+
* @param routeId route 稳定 ID。
|
|
327
|
+
* @param processor 单条消息处理函数。
|
|
328
|
+
* @returns 无返回值。
|
|
329
|
+
*/
|
|
330
|
+
drainPending(routeId: string, processor: QueueProcessor): void {
|
|
331
|
+
this.kickDrain(routeId, processor);
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
/**
|
|
335
|
+
* 显式将上次 Gateway 遗留的 processing 项标为 interrupted。
|
|
336
|
+
*
|
|
337
|
+
* @param routeId route 稳定 ID。
|
|
338
|
+
* @returns 恢复后的 route 队列。
|
|
339
|
+
* @throws {DurableQueueError} 当前进程仍在处理该 route 或有多条 processing 项时抛出。
|
|
340
|
+
*/
|
|
341
|
+
async recoverInterrupted(routeId: string): Promise<DurableQueueItem[]> {
|
|
342
|
+
return this.withWriteQueue(async () => {
|
|
343
|
+
await this.lease.assertOwned();
|
|
344
|
+
if (this.drainingRoutes.has(routeId)) {
|
|
345
|
+
throw new DurableQueueError(
|
|
346
|
+
"queue_blocked",
|
|
347
|
+
"route 当前仍有 worker 在处理, 不会把 processing 项标记为中断。",
|
|
348
|
+
);
|
|
349
|
+
}
|
|
350
|
+
const items = await this.loadRoute(routeId);
|
|
351
|
+
const processingItems = [...items.values()].filter((item) => item.state === "processing");
|
|
352
|
+
if (processingItems.length > 1) {
|
|
353
|
+
throw new QueueCorruptionError("同一 route 同时存在多个 processing 项, 已停止恢复。");
|
|
354
|
+
}
|
|
355
|
+
if (processingItems.length === 1) {
|
|
356
|
+
const processing = processingItems[0];
|
|
357
|
+
await this.writeState(routeId, processing, "interrupted");
|
|
358
|
+
}
|
|
359
|
+
return [...(await this.loadRoute(routeId)).values()]
|
|
360
|
+
.filter((item) => item.state !== "completed");
|
|
361
|
+
});
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/**
|
|
365
|
+
* 声明 route 上最早的可执行消息为 processing。
|
|
366
|
+
*
|
|
367
|
+
* 上次进程遗留的 processing、failed 或 interrupted 项会被标记为 skipped 并返回,
|
|
368
|
+
* 由调用方通知用户后继续处理后续消息, 不再阻塞整个 route。
|
|
369
|
+
*
|
|
370
|
+
* @param routeId route 稳定 ID。
|
|
371
|
+
* @returns 已声明项、空队列或刚被跳过的项。
|
|
372
|
+
*/
|
|
373
|
+
async claimNext(routeId: string): Promise<QueueClaimResult> {
|
|
374
|
+
return this.withWriteQueue(async () => {
|
|
375
|
+
await this.lease.assertOwned();
|
|
376
|
+
const items = [...(await this.loadRoute(routeId)).values()];
|
|
377
|
+
const firstUnfinished = items.find((item) =>
|
|
378
|
+
item.state !== "completed" && item.state !== "skipped",
|
|
379
|
+
);
|
|
380
|
+
if (!firstUnfinished) {
|
|
381
|
+
await this.compactRouteUnlocked(routeId, items);
|
|
382
|
+
return { kind: "empty" };
|
|
383
|
+
}
|
|
384
|
+
if (
|
|
385
|
+
firstUnfinished.state === "processing" ||
|
|
386
|
+
firstUnfinished.state === "failed" ||
|
|
387
|
+
firstUnfinished.state === "interrupted"
|
|
388
|
+
) {
|
|
389
|
+
const skipped = await this.writeState(routeId, firstUnfinished, "skipped");
|
|
390
|
+
this.recordSkippedNotice(routeId, skipped);
|
|
391
|
+
await this.pruneSkippedUnlocked(routeId);
|
|
392
|
+
return { kind: "skipped", item: skipped };
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
const claimed = await this.writeState(routeId, firstUnfinished, "processing", {
|
|
396
|
+
attempts: firstUnfinished.attempts + 1,
|
|
397
|
+
});
|
|
398
|
+
return { kind: "claimed", item: claimed };
|
|
399
|
+
});
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* 标记 processing 消息已完成。
|
|
404
|
+
*
|
|
405
|
+
* @param routeId route 稳定 ID。
|
|
406
|
+
* @param itemId queue 项目 ID。
|
|
407
|
+
* @returns 更新后的队列项。
|
|
408
|
+
*/
|
|
409
|
+
async complete(routeId: string, itemId: string): Promise<DurableQueueItem> {
|
|
410
|
+
return this.withWriteQueue(async () => {
|
|
411
|
+
await this.lease.assertOwned();
|
|
412
|
+
const items = await this.loadRoute(routeId);
|
|
413
|
+
const item = items.get(itemId);
|
|
414
|
+
if (!item) {
|
|
415
|
+
throw new DurableQueueError("queue_item_not_found", "未找到 queue 项目。");
|
|
416
|
+
}
|
|
417
|
+
const completed = await this.writeState(routeId, item, "completed");
|
|
418
|
+
const updated = new Map(items);
|
|
419
|
+
updated.set(itemId, completed);
|
|
420
|
+
await this.compactRouteUnlocked(routeId, updated.values());
|
|
421
|
+
return completed;
|
|
422
|
+
});
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
/**
|
|
426
|
+
* 标记 processing 消息失败, 只记录稳定错误类型, 不记录异常正文。
|
|
427
|
+
*
|
|
428
|
+
* @param routeId route 稳定 ID。
|
|
429
|
+
* @param itemId queue 项目 ID。
|
|
430
|
+
* @param errorCode 稳定错误代码。
|
|
431
|
+
* @returns 更新后的队列项。
|
|
432
|
+
*/
|
|
433
|
+
async fail(routeId: string, itemId: string, errorCode: string): Promise<DurableQueueItem> {
|
|
434
|
+
const safeErrorCode = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(errorCode)
|
|
435
|
+
? errorCode
|
|
436
|
+
: "UnknownError";
|
|
437
|
+
return this.updateState(routeId, itemId, "failed", { errorCode: safeErrorCode });
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* 显式重试失败或中断项, 后续 FIFO 消息仍保持在其后。
|
|
442
|
+
*
|
|
443
|
+
* @param routeId route 稳定 ID。
|
|
444
|
+
* @param messageId 幂等消息 ID。
|
|
445
|
+
* @returns 更新后的队列项。
|
|
446
|
+
*/
|
|
447
|
+
async retry(routeId: string, messageId: string): Promise<DurableQueueItem> {
|
|
448
|
+
return this.withWriteQueue(async () => {
|
|
449
|
+
await this.lease.assertOwned();
|
|
450
|
+
const item = [...(await this.loadRoute(routeId)).values()]
|
|
451
|
+
.find((candidate) => candidate.messageId === messageId);
|
|
452
|
+
if (!item) {
|
|
453
|
+
throw new DurableQueueError("queue_item_not_found", "未找到要重试的 queue 消息。");
|
|
454
|
+
}
|
|
455
|
+
if (
|
|
456
|
+
item.state !== "failed" &&
|
|
457
|
+
item.state !== "interrupted" &&
|
|
458
|
+
item.state !== "skipped"
|
|
459
|
+
) {
|
|
460
|
+
throw new DurableQueueError(
|
|
461
|
+
"invalid_queue_transition",
|
|
462
|
+
`只有 failed、interrupted 或 skipped 消息可重试, 当前状态为 ${item.state}。`,
|
|
463
|
+
);
|
|
464
|
+
}
|
|
465
|
+
return this.writeState(routeId, item, "queued", { errorCode: undefined });
|
|
466
|
+
});
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
/**
|
|
470
|
+
* 列出指定 route 尚未处理完的队列项, 按入队顺序返回。
|
|
471
|
+
*
|
|
472
|
+
* 已完成与已自动跳过的项不在此列表内, 跳过项用 {@link listSkipped} 查询。
|
|
473
|
+
*
|
|
474
|
+
* @param routeId route 稳定 ID。
|
|
475
|
+
* @returns 待处理队列状态列表。
|
|
476
|
+
*/
|
|
477
|
+
async list(routeId: string): Promise<DurableQueueItem[]> {
|
|
478
|
+
return this.withWriteQueue(async () => {
|
|
479
|
+
await this.lease.assertOwned();
|
|
480
|
+
const items = await this.loadRoute(routeId);
|
|
481
|
+
if ([...items.values()].some((item) => item.state === "completed")) {
|
|
482
|
+
await this.compactRouteUnlocked(routeId, items.values());
|
|
483
|
+
}
|
|
484
|
+
return [...items.values()].filter((item) =>
|
|
485
|
+
item.state !== "completed" && item.state !== "skipped",
|
|
486
|
+
);
|
|
487
|
+
});
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
/**
|
|
491
|
+
* 启动 route 的单项处理器, 避免并行处理同一 route。
|
|
492
|
+
*
|
|
493
|
+
* @param routeId route 稳定 ID。
|
|
494
|
+
* @param processor 单条消息处理函数。
|
|
495
|
+
* @returns 无返回值。
|
|
496
|
+
*/
|
|
497
|
+
private kickDrain(routeId: string, processor: QueueProcessor): void {
|
|
498
|
+
if (this.drainingRoutes.has(routeId)) {
|
|
499
|
+
this.drainRequested.add(routeId);
|
|
500
|
+
return;
|
|
501
|
+
}
|
|
502
|
+
this.drainingRoutes.add(routeId);
|
|
503
|
+
setImmediate(() => {
|
|
504
|
+
void this.processNext(routeId, processor);
|
|
505
|
+
});
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* 声明并处理一条 route 队列消息, 完成后异步调度下一条。
|
|
510
|
+
*
|
|
511
|
+
* @param routeId route 稳定 ID。
|
|
512
|
+
* @param processor 单条消息处理函数。
|
|
513
|
+
* @returns 无返回值。
|
|
514
|
+
*/
|
|
515
|
+
private async processNext(routeId: string, processor: QueueProcessor): Promise<void> {
|
|
516
|
+
let claim: QueueClaimResult;
|
|
517
|
+
try {
|
|
518
|
+
claim = await this.claimNext(routeId);
|
|
519
|
+
} catch (error) {
|
|
520
|
+
this.rejectRouteWaiters(routeId, asError(error));
|
|
521
|
+
this.finishDrain(routeId, processor);
|
|
522
|
+
return;
|
|
523
|
+
}
|
|
524
|
+
if (claim.kind === "empty") {
|
|
525
|
+
this.finishDrain(routeId, processor);
|
|
526
|
+
return;
|
|
527
|
+
}
|
|
528
|
+
if (claim.kind === "skipped") {
|
|
529
|
+
await this.notifySkipped(routeId, claim.item);
|
|
530
|
+
setImmediate(() => {
|
|
531
|
+
void this.processNext(routeId, processor);
|
|
532
|
+
});
|
|
533
|
+
return;
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
const item = claim.item;
|
|
537
|
+
try {
|
|
538
|
+
const reply = await processor(item);
|
|
539
|
+
const completed = await this.complete(routeId, item.id);
|
|
540
|
+
this.resolveWaiter(item.id, {
|
|
541
|
+
item: completed,
|
|
542
|
+
duplicate: this.waiters.get(item.id)?.duplicate ?? false,
|
|
543
|
+
reply,
|
|
544
|
+
});
|
|
545
|
+
setImmediate(() => {
|
|
546
|
+
void this.processNext(routeId, processor);
|
|
547
|
+
});
|
|
548
|
+
} catch (error) {
|
|
549
|
+
const failureCode = describeFailureCode(error);
|
|
550
|
+
try {
|
|
551
|
+
await this.fail(routeId, item.id, failureCode);
|
|
552
|
+
} catch {
|
|
553
|
+
this.rejectWaiter(item.id, new DurableQueueError(
|
|
554
|
+
"queue_blocked",
|
|
555
|
+
"消息处理失败且 queue 状态无法持久化, 已停止该 route 的后续处理。",
|
|
556
|
+
));
|
|
557
|
+
}
|
|
558
|
+
this.rejectWaiter(item.id, asError(error));
|
|
559
|
+
setImmediate(() => {
|
|
560
|
+
void this.processNext(routeId, processor);
|
|
561
|
+
});
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
|
|
565
|
+
/**
|
|
566
|
+
* 对刚被自动跳过的失败项发送一次用户可见提示, 失败不影响后续处理。
|
|
567
|
+
*
|
|
568
|
+
* @param routeId route 稳定 ID。
|
|
569
|
+
* @param item 被跳过的 queue 项。
|
|
570
|
+
* @returns 无返回值。
|
|
571
|
+
*/
|
|
572
|
+
private async notifySkipped(routeId: string, item: DurableQueueItem): Promise<void> {
|
|
573
|
+
if (!this.skippedNotifier) {
|
|
574
|
+
return;
|
|
575
|
+
}
|
|
576
|
+
try {
|
|
577
|
+
await this.skippedNotifier(routeId, item);
|
|
578
|
+
} catch {
|
|
579
|
+
// 通知本身依赖 iLink 投递, 失败时只放弃提示, 不阻塞队列。
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/**
|
|
584
|
+
* 完成当前 route drain 并处理并发到达的下一次 drain 请求。
|
|
585
|
+
*
|
|
586
|
+
* @param routeId route 稳定 ID。
|
|
587
|
+
* @param processor 单条消息处理函数。
|
|
588
|
+
* @returns 无返回值。
|
|
589
|
+
*/
|
|
590
|
+
private finishDrain(routeId: string, processor: QueueProcessor): void {
|
|
591
|
+
this.drainingRoutes.delete(routeId);
|
|
592
|
+
const requested = this.drainRequested.delete(routeId);
|
|
593
|
+
if (requested) {
|
|
594
|
+
this.kickDrain(routeId, processor);
|
|
595
|
+
return;
|
|
596
|
+
}
|
|
597
|
+
if (this.drainingRoutes.size === 0) {
|
|
598
|
+
for (const resolveIdle of this.idleWaiters) {
|
|
599
|
+
resolveIdle();
|
|
600
|
+
}
|
|
601
|
+
this.idleWaiters.clear();
|
|
602
|
+
}
|
|
603
|
+
}
|
|
604
|
+
|
|
605
|
+
/**
|
|
606
|
+
* 完成并移除指定 queue item 的等待者。
|
|
607
|
+
*
|
|
608
|
+
* @param itemId queue 项目 ID。
|
|
609
|
+
* @param result 处理结果。
|
|
610
|
+
* @returns 无返回值。
|
|
611
|
+
*/
|
|
612
|
+
private resolveWaiter(itemId: string, result: QueueDispatchResult): void {
|
|
613
|
+
const waiter = this.waiters.get(itemId);
|
|
614
|
+
if (!waiter) {
|
|
615
|
+
return;
|
|
616
|
+
}
|
|
617
|
+
this.waiters.delete(itemId);
|
|
618
|
+
this.waiterRoutes.delete(itemId);
|
|
619
|
+
waiter.resolve(result);
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
/**
|
|
623
|
+
* 拒绝并移除指定 queue item 的等待者。
|
|
624
|
+
*
|
|
625
|
+
* @param itemId queue 项目 ID。
|
|
626
|
+
* @param error 处理错误。
|
|
627
|
+
* @returns 无返回值。
|
|
628
|
+
*/
|
|
629
|
+
private rejectWaiter(itemId: string, error: Error): void {
|
|
630
|
+
const waiter = this.waiters.get(itemId);
|
|
631
|
+
if (!waiter) {
|
|
632
|
+
return;
|
|
633
|
+
}
|
|
634
|
+
this.waiters.delete(itemId);
|
|
635
|
+
this.waiterRoutes.delete(itemId);
|
|
636
|
+
waiter.reject(error);
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
/**
|
|
640
|
+
* 拒绝 route 上所有等待中的消息, 不删除仍持久化的 queue 记录。
|
|
641
|
+
*
|
|
642
|
+
* @param routeId route 稳定 ID。
|
|
643
|
+
* @param error 处理错误。
|
|
644
|
+
* @returns 无返回值。
|
|
645
|
+
*/
|
|
646
|
+
private rejectRouteWaiters(routeId: string, error: Error): void {
|
|
647
|
+
for (const [itemId, waiterRouteId] of this.waiterRoutes) {
|
|
648
|
+
if (waiterRouteId === routeId) {
|
|
649
|
+
this.rejectWaiter(itemId, error);
|
|
650
|
+
}
|
|
651
|
+
}
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/**
|
|
655
|
+
* 更新一项 queue 状态并持久化状态事件。
|
|
656
|
+
*
|
|
657
|
+
* @param routeId route 稳定 ID。
|
|
658
|
+
* @param itemId queue 项目 ID。
|
|
659
|
+
* @param state 新状态。
|
|
660
|
+
* @param extra 可选的 attempts 或 errorCode 覆盖值。
|
|
661
|
+
* @returns 更新后的队列项。
|
|
662
|
+
*/
|
|
663
|
+
private async updateState(
|
|
664
|
+
routeId: string,
|
|
665
|
+
itemId: string,
|
|
666
|
+
state: QueueItemState,
|
|
667
|
+
extra: { attempts?: number; errorCode?: string } = {},
|
|
668
|
+
): Promise<DurableQueueItem> {
|
|
669
|
+
return this.withWriteQueue(async () => {
|
|
670
|
+
await this.lease.assertOwned();
|
|
671
|
+
const item = (await this.loadRoute(routeId)).get(itemId);
|
|
672
|
+
if (!item) {
|
|
673
|
+
throw new DurableQueueError("queue_item_not_found", "未找到 queue 项目。");
|
|
674
|
+
}
|
|
675
|
+
return this.writeState(routeId, item, state, extra);
|
|
676
|
+
});
|
|
677
|
+
}
|
|
678
|
+
|
|
679
|
+
/**
|
|
680
|
+
* 读取不含正文的有限期幂等索引。
|
|
681
|
+
*
|
|
682
|
+
* @param routeId route 稳定 ID。
|
|
683
|
+
* @returns 最近完成消息的哈希索引。
|
|
684
|
+
*/
|
|
685
|
+
private async readDedupeIndex(routeId: string): Promise<DedupeIndex> {
|
|
686
|
+
const filePath = this.routeDedupeFilePath(routeId);
|
|
687
|
+
try {
|
|
688
|
+
const value: unknown = JSON.parse(await readFile(filePath, "utf8"));
|
|
689
|
+
if (
|
|
690
|
+
typeof value !== "object" ||
|
|
691
|
+
value === null ||
|
|
692
|
+
!("schemaVersion" in value) ||
|
|
693
|
+
value.schemaVersion !== 1 ||
|
|
694
|
+
!("entries" in value) ||
|
|
695
|
+
!Array.isArray(value.entries)
|
|
696
|
+
) {
|
|
697
|
+
throw new QueueCorruptionError("route dedupe index 格式无效。");
|
|
698
|
+
}
|
|
699
|
+
const entries = value.entries as unknown[];
|
|
700
|
+
if (entries.some((entry) => {
|
|
701
|
+
return typeof entry !== "object" ||
|
|
702
|
+
entry === null ||
|
|
703
|
+
!("messageHash" in entry) ||
|
|
704
|
+
typeof entry.messageHash !== "string" ||
|
|
705
|
+
!("completedAt" in entry) ||
|
|
706
|
+
typeof entry.completedAt !== "string";
|
|
707
|
+
})) {
|
|
708
|
+
throw new QueueCorruptionError("route dedupe index 包含无效条目。");
|
|
709
|
+
}
|
|
710
|
+
return value as DedupeIndex;
|
|
711
|
+
} catch (error) {
|
|
712
|
+
if (isNodeError(error) && error.code === "ENOENT") {
|
|
713
|
+
return { schemaVersion: 1, entries: [] };
|
|
714
|
+
}
|
|
715
|
+
throw error;
|
|
716
|
+
}
|
|
717
|
+
}
|
|
718
|
+
|
|
719
|
+
/**
|
|
720
|
+
* 压缩 route queue, 移除已完成消息正文并保留有限期哈希去重信息。
|
|
721
|
+
*
|
|
722
|
+
* @param routeId route 稳定 ID。
|
|
723
|
+
* @param values 当前 queue 项。
|
|
724
|
+
* @returns 无返回值。
|
|
725
|
+
*/
|
|
726
|
+
private async compactRouteUnlocked(
|
|
727
|
+
routeId: string,
|
|
728
|
+
values: Iterable<DurableQueueItem>,
|
|
729
|
+
): Promise<void> {
|
|
730
|
+
const items = [...values];
|
|
731
|
+
const completedItems = items.filter((item) => item.state === "completed");
|
|
732
|
+
if (completedItems.length === 0) {
|
|
733
|
+
return;
|
|
734
|
+
}
|
|
735
|
+
|
|
736
|
+
const dedupeIndex = await this.readDedupeIndex(routeId);
|
|
737
|
+
const recent = new Map(dedupeIndex.entries.map((entry) => [entry.messageHash, entry]));
|
|
738
|
+
for (const item of completedItems) {
|
|
739
|
+
const messageHash = hashMessageId(item.messageId);
|
|
740
|
+
recent.delete(messageHash);
|
|
741
|
+
recent.set(messageHash, {
|
|
742
|
+
messageHash,
|
|
743
|
+
completedAt: item.updatedAt,
|
|
744
|
+
});
|
|
745
|
+
}
|
|
746
|
+
await this.writeDedupeIndexUnlocked(routeId, {
|
|
747
|
+
schemaVersion: 1,
|
|
748
|
+
entries: [...recent.values()].slice(-MAX_RECENT_DEDUPE_IDS),
|
|
749
|
+
});
|
|
750
|
+
|
|
751
|
+
const retainedItems = items.filter((item) => item.state !== "completed");
|
|
752
|
+
const queuePath = this.routeFilePath(routeId);
|
|
753
|
+
if (retainedItems.length === 0) {
|
|
754
|
+
try {
|
|
755
|
+
await unlink(queuePath);
|
|
756
|
+
} catch (error) {
|
|
757
|
+
if (!isNodeError(error) || error.code !== "ENOENT") {
|
|
758
|
+
throw error;
|
|
759
|
+
}
|
|
760
|
+
}
|
|
761
|
+
return;
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
const retainedIds = new Set(retainedItems.map((item) => item.id));
|
|
765
|
+
const rawContents = await readFile(queuePath, "utf8");
|
|
766
|
+
const rawLines = rawContents.split("\n");
|
|
767
|
+
if (rawLines.at(-1) === "") {
|
|
768
|
+
rawLines.pop();
|
|
769
|
+
}
|
|
770
|
+
const preservedLines = rawLines.filter((line) => {
|
|
771
|
+
if (!line.trim()) {
|
|
772
|
+
return false;
|
|
773
|
+
}
|
|
774
|
+
const event = JSON.parse(line) as QueueEvent;
|
|
775
|
+
return retainedIds.has(event.id);
|
|
776
|
+
});
|
|
777
|
+
if (preservedLines.length === 0) {
|
|
778
|
+
throw new QueueCorruptionError("route queue 压缩时未找到待处理记录。");
|
|
779
|
+
}
|
|
780
|
+
await this.writeFileAtomically(queuePath, `${preservedLines.join("\n")}\n`);
|
|
781
|
+
}
|
|
782
|
+
|
|
783
|
+
/**
|
|
784
|
+
* 记录一次自动跳过提示, 同一条消息不会被重复提示。
|
|
785
|
+
*
|
|
786
|
+
* @param routeId route 稳定 ID。
|
|
787
|
+
* @param item 被跳过的 queue 项。
|
|
788
|
+
* @returns 无返回值。
|
|
789
|
+
*/
|
|
790
|
+
private recordSkippedNotice(routeId: string, item: DurableQueueItem): void {
|
|
791
|
+
const notices = this.skippedNotices.get(routeId) ?? [];
|
|
792
|
+
if (notices.some((notice) => notice.id === item.id)) {
|
|
793
|
+
return;
|
|
794
|
+
}
|
|
795
|
+
notices.push(item);
|
|
796
|
+
this.skippedNotices.set(routeId, notices.slice(-MAX_RETAINED_SKIPPED_ITEMS));
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
/**
|
|
800
|
+
* 将超出保留上限的 skipped 项转为 completed, 避免队列无限增长。
|
|
801
|
+
*
|
|
802
|
+
* @param routeId route 稳定 ID。
|
|
803
|
+
* @returns 无返回值。
|
|
804
|
+
*/
|
|
805
|
+
private async pruneSkippedUnlocked(routeId: string): Promise<void> {
|
|
806
|
+
const items = await this.loadRoute(routeId);
|
|
807
|
+
const skippedItems = [...items.values()].filter((item) => item.state === "skipped");
|
|
808
|
+
if (skippedItems.length <= MAX_RETAINED_SKIPPED_ITEMS) {
|
|
809
|
+
return;
|
|
810
|
+
}
|
|
811
|
+
const expired = skippedItems.slice(0, skippedItems.length - MAX_RETAINED_SKIPPED_ITEMS);
|
|
812
|
+
for (const item of expired) {
|
|
813
|
+
await this.writeState(routeId, item, "completed");
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
|
|
817
|
+
/**
|
|
818
|
+
* 列出近期被自动跳过的消息, 供 /status 展示。
|
|
819
|
+
*
|
|
820
|
+
* @param routeId route 稳定 ID。
|
|
821
|
+
* @returns 最近跳过的 queue 项, 按入队顺序排列。
|
|
822
|
+
*/
|
|
823
|
+
async listSkipped(routeId: string): Promise<DurableQueueItem[]> {
|
|
824
|
+
return this.withWriteQueue(async () => {
|
|
825
|
+
await this.lease.assertOwned();
|
|
826
|
+
const items = await this.loadRoute(routeId);
|
|
827
|
+
return [...items.values()].filter((item) => item.state === "skipped");
|
|
828
|
+
});
|
|
829
|
+
}
|
|
830
|
+
|
|
831
|
+
/**
|
|
832
|
+
* 原子写入 route 去重索引。
|
|
833
|
+
*
|
|
834
|
+
* @param routeId route 稳定 ID。
|
|
835
|
+
* @param index 去重索引。
|
|
836
|
+
* @returns 无返回值。
|
|
837
|
+
*/
|
|
838
|
+
private async writeDedupeIndexUnlocked(routeId: string, index: DedupeIndex): Promise<void> {
|
|
839
|
+
await this.writeFileAtomically(
|
|
840
|
+
this.routeDedupeFilePath(routeId),
|
|
841
|
+
`${JSON.stringify(index, null, 2)}\n`,
|
|
842
|
+
);
|
|
843
|
+
}
|
|
844
|
+
|
|
845
|
+
/**
|
|
846
|
+
* 原子替换文件, 临时文件与目标文件位于同一目录。
|
|
847
|
+
*
|
|
848
|
+
* @param filePath 目标文件。
|
|
849
|
+
* @param contents 文件内容。
|
|
850
|
+
* @returns 无返回值。
|
|
851
|
+
*/
|
|
852
|
+
private async writeFileAtomically(filePath: string, contents: string): Promise<void> {
|
|
853
|
+
await mkdir(dirname(filePath), { recursive: true });
|
|
854
|
+
const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
|
|
855
|
+
const handle = await open(temporaryPath, "wx", 0o600);
|
|
856
|
+
try {
|
|
857
|
+
await handle.writeFile(contents, "utf8");
|
|
858
|
+
await handle.sync();
|
|
859
|
+
} catch (error) {
|
|
860
|
+
await handle.close();
|
|
861
|
+
try {
|
|
862
|
+
await unlink(temporaryPath);
|
|
863
|
+
} catch {
|
|
864
|
+
throw new Error("queue 文件写入失败, 且无法清理临时文件。");
|
|
865
|
+
}
|
|
866
|
+
throw error;
|
|
867
|
+
}
|
|
868
|
+
await handle.close();
|
|
869
|
+
try {
|
|
870
|
+
await rename(temporaryPath, filePath);
|
|
871
|
+
} catch (error) {
|
|
872
|
+
try {
|
|
873
|
+
await unlink(temporaryPath);
|
|
874
|
+
} catch (cleanupError) {
|
|
875
|
+
if (!isNodeError(cleanupError) || cleanupError.code !== "ENOENT") {
|
|
876
|
+
throw cleanupError;
|
|
877
|
+
}
|
|
878
|
+
}
|
|
879
|
+
throw error;
|
|
880
|
+
}
|
|
881
|
+
}
|
|
882
|
+
|
|
883
|
+
/**
|
|
884
|
+
* 原子写入 route queue 快照, 使用 SHA-256 避免 route ID 出现在文件名。
|
|
885
|
+
*
|
|
886
|
+
* @param routeId route 稳定 ID。
|
|
887
|
+
* @returns dedupe 文件绝对路径。
|
|
888
|
+
*/
|
|
889
|
+
private routeDedupeFilePath(routeId: string): string {
|
|
890
|
+
const routeHash = hashRouteId(routeId);
|
|
891
|
+
return join(this.directory, "queue", `${routeHash}.dedupe.json`);
|
|
892
|
+
}
|
|
893
|
+
|
|
894
|
+
/**
|
|
895
|
+
* 追加状态事件并返回更新后的内存状态。
|
|
896
|
+
*
|
|
897
|
+
* @param routeId route 稳定 ID。
|
|
898
|
+
* @param current 当前队列项。
|
|
899
|
+
* @param state 新状态。
|
|
900
|
+
* @param extra 可选状态字段。
|
|
901
|
+
* @returns 更新后的队列项。
|
|
902
|
+
*/
|
|
903
|
+
private async writeState(
|
|
904
|
+
routeId: string,
|
|
905
|
+
current: DurableQueueItem,
|
|
906
|
+
state: QueueItemState,
|
|
907
|
+
extra: { attempts?: number; errorCode?: string } = {},
|
|
908
|
+
): Promise<DurableQueueItem> {
|
|
909
|
+
validateTransition(current.state, state);
|
|
910
|
+
const updatedAt = new Date().toISOString();
|
|
911
|
+
const hasErrorCodeOverride = Object.hasOwn(extra, "errorCode");
|
|
912
|
+
const errorCode = hasErrorCodeOverride ? extra.errorCode : current.errorCode;
|
|
913
|
+
const event: StateEvent = {
|
|
914
|
+
type: "state",
|
|
915
|
+
id: current.id,
|
|
916
|
+
state,
|
|
917
|
+
updatedAt,
|
|
918
|
+
attempts: extra.attempts ?? current.attempts,
|
|
919
|
+
...(errorCode ? { errorCode } : {}),
|
|
920
|
+
};
|
|
921
|
+
await this.appendEvent(routeId, event);
|
|
922
|
+
return {
|
|
923
|
+
...current,
|
|
924
|
+
state,
|
|
925
|
+
updatedAt,
|
|
926
|
+
attempts: event.attempts,
|
|
927
|
+
...(event.errorCode ? { errorCode: event.errorCode } : { errorCode: undefined }),
|
|
928
|
+
};
|
|
929
|
+
}
|
|
930
|
+
|
|
931
|
+
/**
|
|
932
|
+
* 从 append-only JSONL 重建 route 队列状态。
|
|
933
|
+
*
|
|
934
|
+
* @param routeId route 稳定 ID。
|
|
935
|
+
* @returns 按入队顺序排列的当前状态 map。
|
|
936
|
+
*/
|
|
937
|
+
private async loadRoute(routeId: string): Promise<Map<string, DurableQueueItem>> {
|
|
938
|
+
const filePath = this.routeFilePath(routeId);
|
|
939
|
+
let contents: string;
|
|
940
|
+
try {
|
|
941
|
+
contents = await readFile(filePath, "utf8");
|
|
942
|
+
} catch (error) {
|
|
943
|
+
if (isNodeError(error) && error.code === "ENOENT") {
|
|
944
|
+
return new Map();
|
|
945
|
+
}
|
|
946
|
+
throw error;
|
|
947
|
+
}
|
|
948
|
+
|
|
949
|
+
const items = new Map<string, DurableQueueItem>();
|
|
950
|
+
const lines = contents.split("\n");
|
|
951
|
+
if (lines.at(-1) === "") {
|
|
952
|
+
lines.pop();
|
|
953
|
+
}
|
|
954
|
+
for (const line of lines) {
|
|
955
|
+
if (!line.trim()) {
|
|
956
|
+
continue;
|
|
957
|
+
}
|
|
958
|
+
let event: QueueEvent;
|
|
959
|
+
try {
|
|
960
|
+
event = JSON.parse(line) as QueueEvent;
|
|
961
|
+
} catch {
|
|
962
|
+
throw new QueueCorruptionError("route queue JSONL 有损坏记录, 已拒绝继续处理。");
|
|
963
|
+
}
|
|
964
|
+
if (event.type !== "enqueue" && event.type !== "state") {
|
|
965
|
+
throw new QueueCorruptionError("route queue 包含未知事件类型。");
|
|
966
|
+
}
|
|
967
|
+
if (event.type === "enqueue") {
|
|
968
|
+
if (
|
|
969
|
+
typeof event.id !== "string" ||
|
|
970
|
+
typeof event.messageId !== "string" ||
|
|
971
|
+
typeof event.text !== "string" ||
|
|
972
|
+
typeof event.receivedAt !== "string" ||
|
|
973
|
+
items.has(event.id)
|
|
974
|
+
) {
|
|
975
|
+
throw new QueueCorruptionError("route queue 入队记录字段无效或 ID 重复。");
|
|
976
|
+
}
|
|
977
|
+
items.set(event.id, {
|
|
978
|
+
...event,
|
|
979
|
+
routeId,
|
|
980
|
+
updatedAt: event.receivedAt,
|
|
981
|
+
state: "queued",
|
|
982
|
+
attempts: 0,
|
|
983
|
+
});
|
|
984
|
+
continue;
|
|
985
|
+
}
|
|
986
|
+
const current = items.get(event.id);
|
|
987
|
+
if (
|
|
988
|
+
!current ||
|
|
989
|
+
!isQueueItemState(event.state) ||
|
|
990
|
+
!Number.isInteger(event.attempts) ||
|
|
991
|
+
event.attempts < 0 ||
|
|
992
|
+
typeof event.updatedAt !== "string"
|
|
993
|
+
) {
|
|
994
|
+
throw new QueueCorruptionError("route queue 状态事件无法匹配入队记录。");
|
|
995
|
+
}
|
|
996
|
+
try {
|
|
997
|
+
validateTransition(current.state, event.state);
|
|
998
|
+
} catch {
|
|
999
|
+
throw new QueueCorruptionError("route queue 存在非法状态转换。");
|
|
1000
|
+
}
|
|
1001
|
+
items.set(event.id, {
|
|
1002
|
+
...current,
|
|
1003
|
+
state: event.state,
|
|
1004
|
+
updatedAt: event.updatedAt,
|
|
1005
|
+
attempts: event.attempts,
|
|
1006
|
+
...(event.errorCode ? { errorCode: event.errorCode } : { errorCode: undefined }),
|
|
1007
|
+
});
|
|
1008
|
+
}
|
|
1009
|
+
return items;
|
|
1010
|
+
}
|
|
1011
|
+
|
|
1012
|
+
/**
|
|
1013
|
+
* 将队列事件追加到 route 专属文件并同步到磁盘。
|
|
1014
|
+
*
|
|
1015
|
+
* @param routeId route 稳定 ID。
|
|
1016
|
+
* @param event 队列事件。
|
|
1017
|
+
* @returns 无返回值。
|
|
1018
|
+
*/
|
|
1019
|
+
private async appendEvent(routeId: string, event: QueueEvent): Promise<void> {
|
|
1020
|
+
const filePath = this.routeFilePath(routeId);
|
|
1021
|
+
await mkdir(join(this.directory, "queue"), { recursive: true });
|
|
1022
|
+
const handle = await open(filePath, "a", 0o600);
|
|
1023
|
+
try {
|
|
1024
|
+
await handle.writeFile(`${JSON.stringify(event)}\n`, "utf8");
|
|
1025
|
+
await handle.sync();
|
|
1026
|
+
} finally {
|
|
1027
|
+
await handle.close();
|
|
1028
|
+
}
|
|
1029
|
+
}
|
|
1030
|
+
|
|
1031
|
+
/**
|
|
1032
|
+
* 将 routeId 哈希为安全文件名。
|
|
1033
|
+
*
|
|
1034
|
+
* @param routeId route 稳定 ID。
|
|
1035
|
+
* @returns queue JSONL 文件绝对路径。
|
|
1036
|
+
*/
|
|
1037
|
+
private routeFilePath(routeId: string): string {
|
|
1038
|
+
return join(this.directory, "queue", `${hashRouteId(routeId)}.jsonl`);
|
|
1039
|
+
}
|
|
1040
|
+
|
|
1041
|
+
/**
|
|
1042
|
+
* 串行执行当前进程的 queue 文件更新。
|
|
1043
|
+
*
|
|
1044
|
+
* @param operation queue 更新操作。
|
|
1045
|
+
* @returns 操作结果。
|
|
1046
|
+
*/
|
|
1047
|
+
private async withWriteQueue<T>(operation: () => Promise<T>): Promise<T> {
|
|
1048
|
+
const previous = this.writeQueue;
|
|
1049
|
+
let release = (): void => undefined;
|
|
1050
|
+
this.writeQueue = new Promise<void>((resolveQueue) => {
|
|
1051
|
+
release = resolveQueue;
|
|
1052
|
+
});
|
|
1053
|
+
await previous;
|
|
1054
|
+
try {
|
|
1055
|
+
return await operation();
|
|
1056
|
+
} finally {
|
|
1057
|
+
release();
|
|
1058
|
+
}
|
|
1059
|
+
}
|
|
1060
|
+
}
|
|
1061
|
+
|
|
1062
|
+
/**
|
|
1063
|
+
* 哈希 channel message ID, 去重索引中不保存原始值。
|
|
1064
|
+
*
|
|
1065
|
+
* @param messageId channel message ID。
|
|
1066
|
+
* @returns SHA-256 十六进制摘要。
|
|
1067
|
+
*/
|
|
1068
|
+
function hashMessageId(messageId: string): string {
|
|
1069
|
+
return createHash("sha256").update(messageId).digest("hex");
|
|
1070
|
+
}
|
|
1071
|
+
|
|
1072
|
+
/**
|
|
1073
|
+
* 哈希 route ID, 避免 route 内容出现在数据文件名中。
|
|
1074
|
+
*
|
|
1075
|
+
* @param routeId route 稳定 ID。
|
|
1076
|
+
* @returns SHA-256 十六进制摘要。
|
|
1077
|
+
*/
|
|
1078
|
+
function hashRouteId(routeId: string): string {
|
|
1079
|
+
return createHash("sha256").update(routeId).digest("hex");
|
|
1080
|
+
}
|
|
1081
|
+
|
|
1082
|
+
/**
|
|
1083
|
+
* 校验 queue 状态转换。
|
|
1084
|
+
*
|
|
1085
|
+
* @param current 当前状态。
|
|
1086
|
+
* @param next 目标状态。
|
|
1087
|
+
* @returns 无返回值。
|
|
1088
|
+
* @throws {DurableQueueError} 状态转换非法时抛出。
|
|
1089
|
+
*/
|
|
1090
|
+
function validateTransition(current: QueueItemState, next: QueueItemState): void {
|
|
1091
|
+
const allowed: Record<QueueItemState, QueueItemState[]> = {
|
|
1092
|
+
queued: ["processing", "skipped"],
|
|
1093
|
+
processing: ["completed", "failed", "interrupted", "skipped"],
|
|
1094
|
+
completed: [],
|
|
1095
|
+
failed: ["queued", "skipped"],
|
|
1096
|
+
interrupted: ["queued", "skipped"],
|
|
1097
|
+
skipped: ["completed", "queued"],
|
|
1098
|
+
};
|
|
1099
|
+
if (!allowed[current].includes(next)) {
|
|
1100
|
+
throw new DurableQueueError(
|
|
1101
|
+
"invalid_queue_transition",
|
|
1102
|
+
`不允许 queue 状态从 ${current} 转为 ${next}。`,
|
|
1103
|
+
);
|
|
1104
|
+
}
|
|
1105
|
+
}
|
|
1106
|
+
|
|
1107
|
+
/**
|
|
1108
|
+
* 判断未知字符串是否为 queue 状态。
|
|
1109
|
+
*
|
|
1110
|
+
* @param value 待检查状态。
|
|
1111
|
+
* @returns 状态属于 QueueItemState 时返回 true。
|
|
1112
|
+
*/
|
|
1113
|
+
function isQueueItemState(value: unknown): value is QueueItemState {
|
|
1114
|
+
return value === "queued" ||
|
|
1115
|
+
value === "processing" ||
|
|
1116
|
+
value === "completed" ||
|
|
1117
|
+
value === "failed" ||
|
|
1118
|
+
value === "interrupted" ||
|
|
1119
|
+
value === "skipped";
|
|
1120
|
+
}
|
|
1121
|
+
|
|
1122
|
+
function asError(error: unknown): Error {
|
|
1123
|
+
return error instanceof Error ? error : new Error("未知 queue 处理错误。");
|
|
1124
|
+
}
|
|
1125
|
+
|
|
1126
|
+
/**
|
|
1127
|
+
* 将处理异常转换为可持久化的稳定错误码。
|
|
1128
|
+
*
|
|
1129
|
+
* 优先使用异常自带的 `code` 字段 (如 iLink 的 session_expired / api_error),
|
|
1130
|
+
* 以便事后能区分“回复投递失败”和“Pi turn 失败”; 都没有时退回异常类型名。
|
|
1131
|
+
*
|
|
1132
|
+
* @param error 处理阶段抛出的异常。
|
|
1133
|
+
* @returns 只含字母数字下划线点的错误码。
|
|
1134
|
+
*/
|
|
1135
|
+
function describeFailureCode(error: unknown): string {
|
|
1136
|
+
if (error instanceof Error) {
|
|
1137
|
+
const code = (error as { code?: unknown }).code;
|
|
1138
|
+
if (typeof code === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(code)) {
|
|
1139
|
+
return code;
|
|
1140
|
+
}
|
|
1141
|
+
return error.name;
|
|
1142
|
+
}
|
|
1143
|
+
return "UnknownError";
|
|
1144
|
+
}
|
|
1145
|
+
|
|
1146
|
+
/**
|
|
1147
|
+
* 判断值是否为 Node.js 文件系统错误。
|
|
1148
|
+
*
|
|
1149
|
+
* @param error 待检查值。
|
|
1150
|
+
* @returns 值带有 Node.js 错误代码时返回 true。
|
|
1151
|
+
*/
|
|
1152
|
+
function isNodeError(error: unknown): error is NodeJS.ErrnoException {
|
|
1153
|
+
return error instanceof Error && "code" in error;
|
|
1154
|
+
}
|