@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.
@@ -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
  ```
@@ -7,6 +7,7 @@ export type TenantDestroyHookResult = {
7
7
  } | {
8
8
  readonly done: false;
9
9
  readonly processed: number;
10
+ readonly pending?: boolean;
10
11
  };
11
12
  export interface TenantResourceHookCtx {
12
13
  readonly tenantId: TenantId;
@@ -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
- return `scheduler-${jobName.replace(/[.:]/g, "-")}`;
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
- if (key in seenAt && now - lastSeen < ORPHAN_SCHEDULER_GRACE_MS)
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);
@@ -294,11 +294,14 @@ export function createJobRunner(options) {
294
294
  }
295
295
  }
296
296
  }
297
- function cronSchedulerIdsForLane(lane) {
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
- ids.add(schedulerIdForJobName(name));
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.405.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.405.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.405.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",