Skip to content

Events and jobs

Use Minidesk for complete executable declarations and functions. Events, schedules, receipts and business rows persist in the app database. One worker in the app process handles this work. There is no per-app broker.

An emitting transaction writes the event and its handler deliveries together. A handler executes business writes in its own transaction. A failure rolls back those writes and records a bounded failed attempt.

// @on TicketCreated
// @once key=e.ticket
func NotifyTicketCreated(e TicketCreated) {
database.notifications.create(Notification{
user: e.owner,
title: "Ticket created",
body: "Your ticket was created: " + e.title,
})
}

This excerpt uses models and events from the complete Minidesk source. @once commits a receipt with successful local SQLite effects. Duplicate delivery skips those effects. It is not exactly-once delivery to an external service.

The worker tries five times with delays of 1, 2, 4 and 8 seconds. Exhausted work stays failed. Restart recovers interrupted claims and retains attempt history.

Terminal window
bfast events list --app my-desk
bfast events get --app my-desk --id '<event ID>'
bfast events replay --app my-desk --id '<failed event ID>'
bfast events skip --app my-desk --id '<failed event ID>'

Fix and update the app before replaying failed work. Replay preserves successful deliveries and once receipts. Owner changes do not retry automatically after a lost response; inspect history before another change.

// @job every 1d
func CleanupOldReadNotifications() {
database.notifications.
where(read == true).
where(createdAt < now() - 30d).
delete()
}

Hourly/daily schedules use UTC. Every-duration schedules retain phase in SQLite. Missed intervals produce one catch-up run. The same job cannot overlap itself. An interrupted invocation becomes explicit history; restart does not silently repeat that invocation.

Terminal window
bfast jobs list --app my-desk
bfast jobs run --app my-desk --name CleanupOldReadNotifications

A manual run preserves the next automatic schedule. A failed manual run returns a nonzero exit code. The dashboard also exposes work history and owner actions.

Work Current bound
Pending/failed events 1,000
Event payload 64 KiB
Completed events retained 1,000
Finished delivery attempts retained 5,000
Finished job runs retained 1,000
Once receipts 10,000; no automatic eviction
Owner list/detail rows 100 per list

The once ledger rejects additional distinct keys at capacity. These resource bounds need explicit retention design for larger workloads. An app administrator does not receive the platform owner’s work-control authority.