@cosmicdrift/kumiko-framework 0.405.0 → 0.406.0
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/agents/api/framework-engine.md +3 -0
- package/agents/examples/lane-routing.md +13 -0
- package/dist/engine/extensions/tenant-resource.d.ts +1 -0
- package/dist/engine/feature-config-events-jobs.js +7 -0
- package/dist/jobs/job-runner-schedulers.d.ts +2 -2
- package/dist/jobs/job-runner-schedulers.js +8 -4
- package/dist/jobs/job-runner.js +7 -4
- package/package.json +3 -3
- package/src/changes.json +12 -0
|
@@ -970,9 +970,11 @@ type JobTrigger =
|
|
|
970
970
|
| {
|
|
971
971
|
cron: string;
|
|
972
972
|
tz?: string;
|
|
973
|
+
wakesSleepingApp?: false;
|
|
973
974
|
}
|
|
974
975
|
| {
|
|
975
976
|
maintenance: true;
|
|
977
|
+
wakesSleepingApp?: false;
|
|
976
978
|
}
|
|
977
979
|
| {
|
|
978
980
|
manual: true;
|
|
@@ -1649,6 +1651,7 @@ type TenantDestroyHookResult =
|
|
|
1649
1651
|
| {
|
|
1650
1652
|
done: false;
|
|
1651
1653
|
processed: number;
|
|
1654
|
+
pending?: boolean;
|
|
1652
1655
|
}
|
|
1653
1656
|
;
|
|
1654
1657
|
type TenantId = string;
|
|
@@ -14,6 +14,7 @@ Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
|
|
|
14
14
|
|
|
15
15
|
- `r.job({ runIn: "worker" })` after an HTTP write
|
|
16
16
|
- `trigger: { maintenance: true }` for a daily housekeeping job in the app's maintenance window (`KUMIKO_MAINTENANCE_WINDOW`)
|
|
17
|
+
- `wakesSleepingApp: false` on a cron trigger for upkeep that must not wake a sleeping shared app
|
|
17
18
|
- End-to-end verification via `createAllInOneEntrypoint`
|
|
18
19
|
|
|
19
20
|
## Source
|
|
@@ -145,6 +146,10 @@ describe("lane-routing sample", () => {
|
|
|
145
146
|
expect(registry.getJob("orders:job:prune-old-receipts")?.trigger).toEqual({
|
|
146
147
|
maintenance: true,
|
|
147
148
|
});
|
|
149
|
+
expect(registry.getJob("orders:job:warm-receipt-cache")?.trigger).toEqual({
|
|
150
|
+
cron: "*/15 * * * *",
|
|
151
|
+
wakesSleepingApp: false,
|
|
152
|
+
});
|
|
148
153
|
const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
|
|
149
154
|
const entry = createAllInOneEntrypoint({
|
|
150
155
|
rowLevelSecurity: "off",
|
|
@@ -279,6 +284,14 @@ export function createLaneRoutingFeature(): FeatureDefinition {
|
|
|
279
284
|
r.job("prune-old-receipts", { trigger: { maintenance: true }, runIn: "worker" }, async () => {
|
|
280
285
|
pruneRuns.push(Date.now());
|
|
281
286
|
});
|
|
287
|
+
|
|
288
|
+
// Optional upkeep: `wakesSleepingApp: false` keeps a sleeping shared app asleep when a run is
|
|
289
|
+
// due; the run happens on the next wake instead.
|
|
290
|
+
r.job(
|
|
291
|
+
"warm-receipt-cache",
|
|
292
|
+
{ trigger: { cron: "*/15 * * * *", wakesSleepingApp: false }, runIn: "worker" },
|
|
293
|
+
async () => {},
|
|
294
|
+
);
|
|
282
295
|
});
|
|
283
296
|
}
|
|
284
297
|
```
|
|
@@ -11,6 +11,13 @@ function assertScheduleTrigger(featureName, jobName, trigger) {
|
|
|
11
11
|
throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { maintenance: ${JSON.stringify(trigger.maintenance)} } — ` +
|
|
12
12
|
"the only valid value is true; the run time comes from KUMIKO_MAINTENANCE_WINDOW.");
|
|
13
13
|
}
|
|
14
|
+
if ("wakesSleepingApp" in trigger && trigger.wakesSleepingApp !== undefined) {
|
|
15
|
+
const isScheduled = "cron" in trigger || "maintenance" in trigger;
|
|
16
|
+
if (!isScheduled || trigger.wakesSleepingApp !== false) {
|
|
17
|
+
throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { wakesSleepingApp: ${JSON.stringify(trigger.wakesSleepingApp)} } — ` +
|
|
18
|
+
"only false is valid, and only on a cron or maintenance trigger; leave it out to wake the app.");
|
|
19
|
+
}
|
|
20
|
+
}
|
|
14
21
|
if ("cron" in trigger && trigger.tz !== undefined && !isValidIanaTimeZone(trigger.tz)) {
|
|
15
22
|
throw new Error(`[Feature ${featureName}] r.job("${jobName}") declares trigger { cron, tz: ${JSON.stringify(trigger.tz)} } — ` +
|
|
16
23
|
'tz must be an IANA time zone name such as "Europe/Berlin".');
|
|
@@ -10,7 +10,7 @@ export declare const ACTIVE_TENANT_IDS_QUERY_NAME = "tenant:query:active-tenant-
|
|
|
10
10
|
* leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828,
|
|
11
11
|
* publicstatus Redis OOM). Strip `.` and `:` from the job QN.
|
|
12
12
|
*/
|
|
13
|
-
export declare function schedulerIdForJobName(jobName: string): string;
|
|
13
|
+
export declare function schedulerIdForJobName(jobName: string, wakesSleepingApp?: boolean): string;
|
|
14
14
|
export declare function bootJobIdForJobName(jobName: string): string;
|
|
15
15
|
export declare const ORPHAN_SCHEDULER_GRACE_MS: number;
|
|
16
16
|
export declare function markSchedulersSeen(queue: Queue, schedulerIds: ReadonlySet<string>): Promise<void>;
|
|
@@ -18,6 +18,6 @@ type OrphanSchedulerLog = {
|
|
|
18
18
|
info(msg: string, data?: Record<string, unknown>): void;
|
|
19
19
|
warn(msg: string, data?: Record<string, unknown>): void;
|
|
20
20
|
};
|
|
21
|
-
export declare function removeOrphanJobSchedulers(queue: Queue, expectedSchedulerIds: ReadonlySet<string>, lane: JobRunIn, log: OrphanSchedulerLog): Promise<void>;
|
|
21
|
+
export declare function removeOrphanJobSchedulers(queue: Queue, expectedSchedulerIds: ReadonlySet<string>, supersededSchedulerIds: ReadonlySet<string>, lane: JobRunIn, log: OrphanSchedulerLog): Promise<void>;
|
|
22
22
|
export declare function perTenantChildJobId(wrapperJobId: string, tenantId: string): string;
|
|
23
23
|
export {};
|
|
@@ -22,9 +22,12 @@ export const ACTIVE_TENANT_IDS_QUERY_NAME = "tenant:query:active-tenant-ids";
|
|
|
22
22
|
* leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828,
|
|
23
23
|
* publicstatus Redis OOM). Strip `.` and `:` from the job QN.
|
|
24
24
|
*/
|
|
25
|
-
export function schedulerIdForJobName(jobName) {
|
|
26
|
-
|
|
25
|
+
export function schedulerIdForJobName(jobName, wakesSleepingApp = true) {
|
|
26
|
+
const prefix = wakesSleepingApp ? "scheduler-" : NO_WAKE_SCHEDULER_PREFIX;
|
|
27
|
+
return `${prefix}${jobName.replace(/[.:]/g, "-")}`;
|
|
27
28
|
}
|
|
29
|
+
// Contract with the infra waker of sleeping shared apps: it skips due jobs under this prefix.
|
|
30
|
+
const NO_WAKE_SCHEDULER_PREFIX = "scheduler-nowake-";
|
|
28
31
|
// Same colon-in-BullMQ-id hazard as schedulerIdForJobName —
|
|
29
32
|
// a QN like "publicstatus:job:uptime-probe" must not leave ":" in the id.
|
|
30
33
|
export function bootJobIdForJobName(jobName) {
|
|
@@ -53,7 +56,7 @@ export async function markSchedulersSeen(queue, schedulerIds) {
|
|
|
53
56
|
// A cron job dropped from the app (or an older scheduler-id format) leaves its
|
|
54
57
|
// scheduler in Redis, where it keeps firing jobs the worker no longer knows
|
|
55
58
|
// ("Unknown job"). Best-effort: a Redis hiccup here must not stop the start.
|
|
56
|
-
export async function removeOrphanJobSchedulers(queue, expectedSchedulerIds, lane, log) {
|
|
59
|
+
export async function removeOrphanJobSchedulers(queue, expectedSchedulerIds, supersededSchedulerIds, lane, log) {
|
|
57
60
|
try {
|
|
58
61
|
// Collect first: removing while paging would shift the indices.
|
|
59
62
|
const existingKeys = [];
|
|
@@ -71,7 +74,8 @@ export async function removeOrphanJobSchedulers(queue, expectedSchedulerIds, lan
|
|
|
71
74
|
if (expectedSchedulerIds.has(key))
|
|
72
75
|
continue;
|
|
73
76
|
const lastSeen = Number(seenAt[key]);
|
|
74
|
-
|
|
77
|
+
const isWithinGrace = key in seenAt && now - lastSeen < ORPHAN_SCHEDULER_GRACE_MS;
|
|
78
|
+
if (isWithinGrace && !supersededSchedulerIds.has(key))
|
|
75
79
|
continue;
|
|
76
80
|
await queue.removeJobScheduler(key);
|
|
77
81
|
await client.hdel(schedulerSeenKey(queue), key);
|
package/dist/jobs/job-runner.js
CHANGED
|
@@ -294,11 +294,14 @@ export function createJobRunner(options) {
|
|
|
294
294
|
}
|
|
295
295
|
}
|
|
296
296
|
}
|
|
297
|
-
|
|
297
|
+
// `superseded`: the id the job would have with the other wake flag. No runner of any version
|
|
298
|
+
// expects both ids of one job, so a leftover under that id goes without the orphan grace period.
|
|
299
|
+
function cronSchedulerIdsForLane(lane, superseded = false) {
|
|
298
300
|
const ids = new Set();
|
|
299
301
|
for (const [name, jobDef] of allJobs) {
|
|
300
302
|
if (laneForJob(jobDef) === lane && isScheduledTrigger(jobDef.trigger)) {
|
|
301
|
-
|
|
303
|
+
const wakesSleepingApp = jobDef.trigger.wakesSleepingApp !== false;
|
|
304
|
+
ids.add(schedulerIdForJobName(name, superseded ? !wakesSleepingApp : wakesSleepingApp));
|
|
302
305
|
}
|
|
303
306
|
}
|
|
304
307
|
return ids;
|
|
@@ -308,7 +311,7 @@ export function createJobRunner(options) {
|
|
|
308
311
|
if (laneForJob(jobDef) !== lane)
|
|
309
312
|
continue;
|
|
310
313
|
if (isScheduledTrigger(jobDef.trigger)) {
|
|
311
|
-
await queue.upsertJobScheduler(schedulerIdForJobName(name), scheduleRepeatOptions(jobDef.trigger, options.maintenanceWindow), {
|
|
314
|
+
await queue.upsertJobScheduler(schedulerIdForJobName(name, jobDef.trigger.wakesSleepingApp !== false), scheduleRepeatOptions(jobDef.trigger, options.maintenanceWindow), {
|
|
312
315
|
name: jobDef.perTenant ? `${PER_TENANT_PREFIX}${name}` : name,
|
|
313
316
|
data: {},
|
|
314
317
|
// Queue-level defaultJobOptions (jobRetentionOpts) covers
|
|
@@ -423,7 +426,7 @@ export function createJobRunner(options) {
|
|
|
423
426
|
});
|
|
424
427
|
});
|
|
425
428
|
await upsertCronSchedulers(consumerQueue, consumerLane);
|
|
426
|
-
await removeOrphanJobSchedulers(consumerQueue, expectedSchedulerIds, consumerLane, {
|
|
429
|
+
await removeOrphanJobSchedulers(consumerQueue, expectedSchedulerIds, cronSchedulerIdsForLane(consumerLane, true), consumerLane, {
|
|
427
430
|
info: (msg, data) => context.log ? context.log.info(msg, data) : errorLogger.debug(msg, data),
|
|
428
431
|
warn: errorLogger.warn,
|
|
429
432
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cosmicdrift/kumiko-framework",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.406.0",
|
|
4
4
|
"description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
|
|
@@ -203,7 +203,7 @@
|
|
|
203
203
|
"./package.json": "./package.json"
|
|
204
204
|
},
|
|
205
205
|
"dependencies": {
|
|
206
|
-
"@cosmicdrift/kumiko-types": "0.
|
|
206
|
+
"@cosmicdrift/kumiko-types": "0.406.0",
|
|
207
207
|
"bullmq": "^5.81.5",
|
|
208
208
|
"hono": "^4.13.14",
|
|
209
209
|
"i18next": "^26.5.12",
|
|
@@ -225,7 +225,7 @@
|
|
|
225
225
|
}
|
|
226
226
|
},
|
|
227
227
|
"devDependencies": {
|
|
228
|
-
"@cosmicdrift/kumiko-testing": "0.
|
|
228
|
+
"@cosmicdrift/kumiko-testing": "0.406.0",
|
|
229
229
|
"bun-types": "^1.4.4",
|
|
230
230
|
"fflate": "^0.8.3",
|
|
231
231
|
"meilisearch": "^0.62.0",
|
package/src/changes.json
CHANGED
|
@@ -1,4 +1,16 @@
|
|
|
1
1
|
[
|
|
2
|
+
{
|
|
3
|
+
"version": "0.406.0",
|
|
4
|
+
"type": "improvement",
|
|
5
|
+
"title": "pending flag on TenantDestroyHookResult",
|
|
6
|
+
"detail": "A destroy hook may return { done: false, processed: 0, pending: true } when it waits on an external operation it has already started, for example a remote teardown job. The field is optional, so existing hooks keep compiling and keep their behavior."
|
|
7
|
+
},
|
|
8
|
+
{
|
|
9
|
+
"version": "0.406.0",
|
|
10
|
+
"type": "improvement",
|
|
11
|
+
"title": "wakesSleepingApp false on cron and maintenance triggers",
|
|
12
|
+
"detail": "A job declared with trigger { cron, wakesSleepingApp: false } or { maintenance: true, wakesSleepingApp: false } is scheduled under the BullMQ scheduler id scheduler-nowake-<job> instead of scheduler-<job>, so its delayed jobs are repeat:scheduler-nowake-<job>:<ts> and the waker of sleeping shared apps skips them; the run happens on the next wake. Leaving the flag out keeps waking the app. Any other value, or the flag on an event or manual trigger, stops the registration. On start the runner removes the scheduler the job had under its other id at once, without the orphan grace period, so flipping the flag never leaves the old scheduler firing."
|
|
13
|
+
},
|
|
2
14
|
{
|
|
3
15
|
"version": "0.405.0",
|
|
4
16
|
"type": "improvement",
|