Execution Modes

Scripts in DieselEngine can run in several modes beyond HTTP ingress. Each mode shares the same diesel API and global bindings — only the trigger and entry point differ.

Overview

Mode	Trigger	Entry Point	Context Lifecycle	Results Available
HTTP Ingress	HTTP request matches route	export function handleRequest(context)	New per request	Yes
WebSocket	Client connects to WS route	export function onOpen/onMessage/onClose(session)	Persistent for connection	No
Static Folder	HTTP GET matches prefix	N/A (direct file serving)	N/A	N/A
On-demand	User/agent triggers run	Top-level module code	New per run	Yes
Cron job	Schedule fires	Top-level module code	New per execution	Yes
Startup	Engine boots	Top-level module code	New per execution	Yes

On-Demand Runs

Scripts can be triggered manually from the DieselEngine UI or via the MCP script_run_js tool. The script's top-level module code executes:

// report.js — run on demand to generate a report
import { ReportService } from '../services/ReportService.js';

const report = ReportService.generateMonthlyReport();
console.log("Report generated:", report.summary);
console.log("Total records:", report.count);

On-demand runs are useful for:

• One-off data migrations
• Manual report generation
• Debugging and testing
• Administrative tasks

Cron Jobs

Cron scripts execute on a schedule defined by a cron expression. Like on-demand runs, they execute their top-level code directly.

Cron Expression Format

DieselEngine uses Quartz cron expressions with 6 fields:

┌───────── seconds (0-59)
│ ┌─────── minutes (0-59)
│ │ ┌───── hours (0-23)
│ │ │ ┌─── day of month (1-31)
│ │ │ │ ┌─ month (1-12 or JAN-DEC)
│ │ │ │ │ ┌ day of week (1-7 or SUN-SAT)
│ │ │ │ │ │
* * * * * *

WARNING

Quartz cron uses 6 fields (seconds included), unlike Unix cron which uses 5 fields. The seconds field comes first.

Examples

Expression	Schedule
0 0 * * * *	Every hour at :00
0 */15 * * * *	Every 15 minutes
0 0 9 * * *	Every day at 9:00 AM
0 0 0 * * MON	Every Monday at midnight
0 30 8 1 * *	First of every month at 8:30 AM
0 0 */2 * * *	Every 2 hours

Cron Script Example

// /cronjobs/send_reminders.js
import { NotificationService } from '../services/NotificationService.js';

const pending = NotificationService.getDueNotifications();

for (const notification of pending) {
  NotificationService.sendNotification(notification);
  console.log("Sent notification to:", notification.email);
}

console.log(`Processed ${pending.length} notifications`);

Cron Properties

Each cron entry has:

Property	Type	Description
uuid	string	Unique identifier
scriptUUID	string	UUID of the script to run
cronConfig	string	Quartz cron expression
enabled	boolean	Whether the cron is active

Startup Scripts

Startup scripts run once when DieselEngine boots. They are ordered by a configurable order field (lower numbers run first).

Common Use Cases

Connect to external services:

// /startup/connect_redis.js
const redis = diesel.getRedisService();
redis.connect("redis://redis:6379");
console.log("Redis connected:", redis.isConnected());

// /startup/connect_minio.js
const minio = diesel.getMinIOService();
minio.connect("http://minio:9000", "minioadmin", "minioadmin");
minio.ensureBucketExists("uploads");
console.log("MinIO connected, 'uploads' bucket ready");

Initialize database tables:

// /startup/init_tables.js
import { UserService } from '../services/UserService.js';
import { ItemService } from '../services/ItemService.js';

UserService.createTable();
ItemService.createTable();
console.log("Database tables initialized");

Start background services:

// /startup/start_services.js
import { PriceService } from '../services/PriceService.js';

diesel.registerService("price-updater",
  () => {
    PriceService.startPolling();
    console.log("Price updater started");
  },
  () => {
    PriceService.stopPolling();
    console.log("Price updater stopped");
  }
);

Startup Properties

Each startup entry has:

Property	Type	Description
uuid	string	Unique identifier
scriptUUID	string	UUID of the script to run
order	number	Execution order (lower = earlier)
enabled	boolean	Whether the startup entry is active

TIP

Order your startup scripts carefully. Service connections (Redis, MinIO) should run before scripts that depend on them.

Console Output

In all execution modes, console.log(), console.error(), and print() output is sent to the DieselEngine UI console via RabbitMQ. Each log line carries:

• Source — the script filename
• Extra data — the trigger context ("USER-RUN", "MCP-RUN", "CRON-JOB", or the ingress route)
• Severity — INFO, ERROR, WARNING, or DEBUG

Script exceptions are also captured with file and line information, making it easy to debug issues across all execution modes.