Skip to content

Lane Routing

Pin jobs to deploy lanes (api | worker) with event-triggered fan-out.

  • r.job({ runIn: "worker" }) after an HTTP write
  • trigger: { maintenance: true } for a daily housekeeping job in the app’s maintenance window (KUMIKO_MAINTENANCE_WINDOW)
  • wakesSleepingApp: false on a cron trigger for upkeep that must not wake a sleeping shared app
  • End-to-end verification via createAllInOneEntrypoint

Feature entry point: src/feature.ts.

Needs the Postgres from the repo root’s docker-compose.yml (docker compose up -d); TEST_DATABASE_URL defaults to postgresql://kumiko:kumiko@localhost:15432/kumiko_test.

Terminal window
cd samples/recipes/lane-routing
bun test

The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

// Lane-Routing Sample
//
// Shows `r.job({ runIn: "worker" })` end-to-end: an HTTP write emits an
// event, the event fans out to two worker-lane jobs via BullMQ, and the
// jobs actually execute on the worker lane (kumiko-jobs-worker queue).
//
// Deploy-shape: any of the three entrypoints. The test uses
// createAllInOneEntrypoint so the Single Integration-Test covers the full
// path without having to coordinate two processes.
import {
createEntity,
createNumberField,
createTextField,
defineFeature,
emitEvent,
type FeatureDefinition,
} from "@cosmicdrift/kumiko-framework/engine";
import { z } from "zod";
// In-memory collectors so the integration-test can assert both jobs ran
// and got the right payload. A real app would do DB writes, HTTP calls,
// PDF rendering, mail sending — whatever the side-effect is, it's
// opaque to the framework.
export const renderedReceipts: Array<{ orderId: string; amount: number }> = [];
export const sentConfirmations: Array<{ orderId: string; amount: number }> = [];
export const pruneRuns: number[] = [];
// The entity declaration secures the qualified-name prefix "orders:write:order:create"
// for the write handler below. The handler does not persist the entity — it
// appends the "order-placed" event the jobs trigger on; in a real app an
// entityWriteHandler would write to the DB.
const orderEntity = createEntity({
name: "order",
table: "read_orders",
fields: {
customerName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
amount: createNumberField({ required: true }),
},
});
export function createLaneRoutingFeature(): FeatureDefinition {
return defineFeature("orders", (r) => {
r.entity(orderEntity);
// The event both jobs trigger on. No PII: customerName stays out of it.
const orderPlaced = r.defineEvent(
"order-placed",
z.object({ orderId: z.string(), amount: z.number() }),
{
piiFields: "none",
},
);
// Write handler — runs in the API process (or wherever the command
// lands) and appends the event the jobs consume.
r.writeHandler({
name: "order:create",
schema: z.object({
customerName: z.string().min(1),
amount: z.number().positive(),
}),
handler: async (event, ctx) => {
const orderId = crypto.randomUUID();
await emitEvent(ctx, orderPlaced, {
aggregateId: orderId,
aggregateType: "order",
payload: { orderId, amount: event.payload.amount },
expectedVersion: 0,
});
return {
isSuccess: true as const,
data: {
id: orderId,
customerName: event.payload.customerName,
amount: event.payload.amount,
},
};
},
access: {
openToAll: {
reason:
"demo recipe: any signed-in user may place an order; the handler is a stub with no persistence",
},
},
});
// Receipt-rendering: heavy CPU work. Pinned to `worker` so the
// BullMQ consumer on the API process never picks it up — even if the
// API happens to run runLocalJobs for something else. `runIn` is the
// Welle-2.6 contract that makes this stable across deploy shapes.
r.job({
name: "render-receipt",
trigger: { on: "order-placed" },
runIn: "worker",
handler: async (payload) => {
renderedReceipts.push({
orderId: payload["orderId"] as string,
amount: payload["amount"] as number,
});
},
});
// Confirmation-mail: external I/O. Also worker-lane. Both jobs fan
// out from the same event in parallel — BullMQ handles their order
// independently.
r.job({
name: "send-confirmation",
trigger: { on: "order-placed" },
runIn: "worker",
handler: async (payload) => {
sentConfirmations.push({
orderId: payload["orderId"] as string,
amount: payload["amount"] as number,
});
},
});
// Housekeeping: `maintenance` runs once a day in the app's maintenance window
// (KUMIKO_MAINTENANCE_WINDOW, UTC, default 03:00) instead of a cron time of its own, so a
// sleeping app wakes once a day for all its cleanup jobs.
r.job({
name: "prune-old-receipts",
trigger: { maintenance: true },
runIn: "worker",
handler: async () => {
pruneRuns.push(Date.now());
},
});
// Optional upkeep: `wakesSleepingApp: false` keeps a sleeping shared app asleep when a run is
// due; the run happens on the next wake instead.
r.job({
name: "warm-receipt-cache",
trigger: { cron: "*/15 * * * *", wakesSleepingApp: false },
runIn: "worker",
handler: async () => {},
});
});
}

📄 On GitHub: samples/recipes/lane-routing/src/feature.ts