[bpamiri]

Closes #4483

Problem

Jobs had no lifecycle hooks and no stored result. A failure was silent unless every job wrapped its own perform(), and perform()'s return value was thrown away.

Change

Per-job hooks (all optional)

component extends="wheels.Job" {
    public void function beforePerform(struct data) {}                     // part of the work
    public any function perform(struct data) { return {sent = 12}; }
    public void function afterPerform(struct data, any result) {}         // part of the work
    public void function onSuccess(any result) {}                         // best-effort
    public void function onFailure(struct error, numeric attempt, boolean isFinal) {} // best-effort
}

beforePerform / afterPerform.

• They run with perform() inside the timed run, so the job's timeout covers them.
• A throw from either fails the attempt, exactly as a throw from perform() does.
• afterPerform runs only when perform() returned normally.

onSuccess(result).

• It runs once the job is recorded as completed.
• result is perform()'s return value, absent when it returned nothing.

onFailure(error, attempt, isFinal).

• It runs after a failed attempt is recorded.
• error is {type, message, detail}. type is the original exception's type, for example Wheels.JobTimeout for a timeout.
• isFinal is false when a retry was scheduled and true when the job is marked failed.
• The hook is called positionally, so its parameters can have any names. Not final, though: Adobe CF doesn't accept a parameter with that name.

What's best-effort. onSuccess and onFailure are best-effort: a throw is logged and never changes the job's outcome.

What fires no hooks. A fenced attempt fires none, because its outcome wasn't the one recorded.

Tenant context. For tenant jobs, the tenant context is still restored while the hooks run.

Reaped jobs

When the reaper marks a crashed worker's job failed (its last attempt), onFailure(isFinal = true) fires on the reaping server.

• Error. The error type is Wheels.JobTimeout.
• Best-effort. It never blocks the reap loop.
• No tenant context. The job class is loaded on that server and no tenant context is restored, because the row's data isn't read.
• Retries. A reap that schedules a retry fires nothing.

App-wide failure hook

set(jobsOnFailure = "app.lib.JobAlerts.record");
// app/lib/JobAlerts.cfc
public void function record(required struct event) { ... }

• When. It is called on every failure, final or not, after the job's own onFailure.
• Format. The setting is a "component.path.method" string, not a closure; function values in application-scope settings break Adobe CF.
• Argument. The method gets one struct as its event argument: {jobId, jobClass, queue, attempt, maxRetries, isFinal, error}. Job data is never included, because it can hold secrets.
• When it can't be called. A hook that can't be called is logged once per application and never affects the job.

result column

• wheels_jobs.result (NVARCHAR(4000) on SQL Server, whose VARCHAR silently mangles non-ASCII text; VARCHAR(4000), or VARCHAR2 on Oracle, elsewhere) is added by the same guarded auto-ALTER as the other job columns: never inside a Wheels transaction, with a back-off and one logged warning if it fails.
• It is written in the completion update itself.
• Format. Simple values are stored as-is, anything else as JSON, and a void return as NULL. An empty-string return is stored as NULL too: Oracle can't tell the two apart anyway.
• Truncation. A longer value is cut to what the column counts and ends with a visible ...[truncated] marker: 4000 characters on SQL Server's NVARCHAR, and 4000 UTF-8 bytes elsewhere (Oracle's VARCHAR2 counts bytes; for the databases that count characters, bytes is the safe bound). The cut always falls on a character boundary. The trimming loop only runs for a value over the limit.

Both processing paths

The worker (wheels jobs work) and processQueue() share the hook helpers in Job.cfc. On the worker, the failure branch moved into $recordFailedAttempt(), which records the retry or failure, runs the hooks, and then clears the tenant context in a finally.

Split out

The opt-in per-attempt history (wheels_job_attempts) is now #4497, to keep this change small.

Tests

JobLifecycleHooksSpec (14 specs):

• Success path: the order before → perform → after → onSuccess, and the result stored.
• Stored results: a complex result stored as JSON, a void return stored as NULL, a long result truncated with the marker, a non-ASCII result stored intact, and a long non-ASCII result cut on a character boundary (whole on SQL Server's NVARCHAR).
• Failure hooks: onFailure plus the app-wide hook with isFinal = false on a retry and isFinal = true on the last attempt. That covers the event's fields, the original error type and detail, and no job data.
• Hooks that throw: a throwing beforePerform fails the attempt without running perform(), and a throwing onSuccess leaves the job completed.
• Unreachable app hook: the failure is still recorded.
• processQueue(): runs the hooks and stores the result.
• Reaper: a reaped last attempt fires the hooks with isFinal = true and Wheels.JobTimeout, and a reap that retries fires nothing.

On develop:

• 2 fail: no hooks run, and a throwing beforePerform doesn't fail the job.
• 9 error: there is no result column.

Local results:

• Full core suite, Lucee 7 + SQLite: 7152 pass, 0 fail, 0 error (582 bundles).
• Jobs specs, Lucee 7: green on SQLite, H2, MySQL, PostgreSQL, CockroachDB, SQL Server and Oracle. PostgreSQL, CockroachDB and SQL Server were also green on a second run against the same database.
• Jobs specs, BoxLang: green on SQLite, PostgreSQL, CockroachDB, SQL Server and Oracle.
• Jobs specs, Adobe 2023: green on SQLite and MySQL.
• Jobs specs, Adobe 2025: green on SQLite, PostgreSQL and SQL Server.
• Complexity gate: passes.

Merge notes

• Interrupted jobs. Done here: a non-idempotent job the reaper ends as interrupted (feat(job): heartbeat() + heartbeat-aware reaping; idempotent gating of retries after a reap #4477) fires onFailure(isFinal = true) and the app-wide hook.
• processNext(). Carried in the develop merge below.
• Schema. feat(cli): wheels jobs install migration generator + jobsAutoCreateTables #4484 puts every job column into one schema definition. result joins it there.

Docs

The guide section (hooks, the app-wide hook, the stored result) goes into the 4.2 guide (#4485). Changelog fragment included.

🤖 Generated with Claude Code

Develop merge (4.2.0)

Merged develop (#4490, #4491, #4492, #4493, #4494, #4495, #4496) with a merge commit. Job.cfc and JobWorker.cfc start from develop and this PR's own changes go on top. The pieces that needed placing by hand:

• Table creation. result sits next to feat(job): heartbeat() and idempotency-aware reaping #4490's heartbeatAt in CREATE TABLE and in the column ensures.
• $executeJob(). Its result carries both feat(job): exclusive jobs and concurrency keys on a shared lease lock #4496's lease fields (busy, leaseLost, …) and this PR's hook fields. A busy lease still returns before any hook runs.
• Worker failure path. It moved into $recordFailedAttempt(), called from $runClaimedJob(), the run half of feat(job): per-host concurrency cap, drain/resume and JobRunner.tick() #4491's processNext() split.
• $processJob() complexity. The lease and the hooks together pushed it over the complexity gate, so two small helpers come out of it: $backoffSettings() and $deferBusyRun().

A separate commit makes an interrupted job (non-idempotent, reaped) fire onFailure(isFinal = true) and jobsOnFailure, with a spec.

Local results:

• Full core suite, Lucee 7 + SQLite: 7225 pass, 0 fail, 0 error (590 bundles).
• Jobs specs, Lucee 7: green on all seven databases. PostgreSQL and SQL Server were also green on a second run against the same database.
• Jobs specs, BoxLang: green on SQLite, SQL Server and Oracle.
• Jobs specs, Adobe 2023: green on SQLite and MySQL.
• Jobs specs, Adobe 2025: green on SQLite and SQL Server.
• Complexity gate: passes.

[bpamiri]

rev1-r3 review @ 62ffcad: code APPROVE (draft, v4.3.0; final = ready after matrix 37728260161 + PR CI, held until the 4.2.0 cut)

Hook ordering and isolation

• Inside the timed run: beforePerform, then perform, then afterPerform (with result only when perform returned something) all run in $runPerformWithTimeout's thread. A throw from either hook fails the attempt, and the new spec shows perform doesn't run when beforePerform throws.
• onSuccess(result): fires only after the completion UPDATE has matched the claim, and runs in its own try, so a throw is logged and the job stays completed.
• Failed attempts: $recordFailedAttempt records the retry or the failure first, then calls $fireJobFailure, but only when the attempt wasn't fenced. So a hook never sees, or acts on, an outcome that was discarded.
• Hook failures never reach the row or the loop: onFailure and the global hook each have their own try. The global hook logs once per app. $recordFailedAttempt uses try/finally with no catch, which satisfies the BoxLang finally rule, and the finally clears the tenant context the failed attempt kept for the hooks.
• The failure details reach the hooks through var structs (failure, outcome, resolved), not local. writes in a catch (invariant 11).
• Reaper: fires onFailure(…, isFinal = true) only when its $markFailed wins (won > 0), not on a reaper retry, which matches the agreed scope. The job class is loaded best-effort and jobInstance = "" on a load failure, so the global hook still runs. Everything is wrapped so the reap loop never breaks. attempt is row.attempts, which $claimJob has already bumped, so it agrees with the worker path's currentAttempts.

Portability

• onFailure(error, attempt, isFinal) is called positionally, so apps can name the parameters freely (final is reserved on Adobe).
• The global hook is a component.path.method string, resolved with CreateObject and Invoke(…, {event = …}). Malformed strings (fewer than 2 parts) are skipped, and resolution or call errors are logged once. The event carries {jobId, jobClass, queue, attempt, maxRetries, isFinal, error} and no job data, as agreed. Both processQueue (Job.$processJob) and the worker path call the same $fireJobSuccess / $fireJobFailure.

The result column

• It's VARCHAR(4000) (Oracle VARCHAR2(4000), at the maximum). The column ensure is guarded against open transactions, backs off, and warns once. CREATE TABLE includes it, and the completion UPDATE writes it only when the column exists.
• Truncation counts UTF-8 bytes (CharsetDecode), which matches Oracle's default byte semantics and stays at or under 4000 characters for MySQL and PostgreSQL. The ...[truncated] marker fits inside the limit.

Notes, not blocking:

• An empty-string result is stored as NULL (null = !Len(text)), the same as a void perform(). That's probably fine, but worth a line in the docs.
• SQL Server: VARCHAR takes the database's code page, so non-ASCII text in a result (from SerializeJSON of user data, say) can be stored as ? on a non-UTF-8 collation. NVARCHAR(4000) on SQL Server would avoid that at no cost (the byte budget still fits). Worth considering before 4.3 ships.
• The truncation loop trims one character at a time and re-encodes each time: quadratic, but only on results over 4000 bytes, so it's fine in practice.
• result isn't a reserved word on any of the 7 databases, as far as I know. The matrix confirms.

Specs (JobLifecycleHooksSpec, 12 cases): ordering, JSON, NULL and truncation results, retry versus final isFinal, a throwing beforePerform, a throwing onSuccess, an uncallable global hook, processQueue, and the reaper's final versus retry.

The final reads every leg of matrix 37728260161 (in progress) and PR CI (7 pending).

[bpamiri]

rev1-r3 review @ 53acfa6: delta APPROVE.

• result is now NVARCHAR(4000) on SQL Server, bound as cf_sql_nvarchar, in both CREATE TABLE and the ALTER ($resultColumnType / $resultAlterSql), and VARCHAR(4000) (VARCHAR2 on Oracle) elsewhere. So non-ASCII results survive on SQL Server.
• The truncation limit now matches what each column counts: characters (UTF-16 units) for NVARCHAR, UTF-8 bytes elsewhere. Bytes is the safe bound on the character-counting databases.
• The database type is memoised per instance, so detection isn't repeated on every completion.
• The empty-string-as-NULL behaviour is documented, with Oracle's '' = NULL as the reason.
• The two new specs (non-ASCII kept intact, and a long non-ASCII value cut correctly) cover it.

Tiny edge, not blocking: Left() counts UTF-16 units, so a cut could in theory split a surrogate pair (astral-plane emoji) right at the limit. That only affects a value already marked ...[truncated].

The final reads a run on this head (it should include sqlserver and oracle) plus full 37728260161 on 62ffcad, plus PR CI.

[github-actions]

Wheels Test Results

184 220 tests   180 662 ✅  1h 10m 15s ⏱️
 14 750 suites    3 558 💤
     25 files          0 ❌

Results for commit 260506d.

♻️ This comment has been updated with latest results.

[bpamiri]

rev1-r3 review @ 53acfa6: APPROVE (final = ready; draft, v4.3.0, held until the 4.2.0 cut)

Run	Head	Result
narrowed 37729362928	this head (engines × sqlite / sqlserver / oracle / postgres, plus rustcfml)	success. 20 of 20 junit legs, tests > 0 (7292–7302), 0 failures and 0 errors on every leg; the rustcfml job also succeeded. JobLifecycleHooksSpec passed 14/14 on every leg, including the two non-ASCII cases on SQL Server (NVARCHAR) and Oracle (VARCHAR2 bytes). JobWorkerSpec 53/53.
full 37728260161	62ffcad, before the NVARCHAR fix	success. 32 of 32 legs, 0 failures and 0 errors. JobLifecycleHooksSpec 12/12 and JobWorkerSpec 53/53 on every leg, including Adobe 2023/2025, BoxLang, CockroachDB and MySQL.

Why the narrowed coverage is enough: the delta is the result column's type and its truncation unit per database. The narrowed set runs exactly the databases where those differ (SQL Server, Oracle) next to SQLite and PostgreSQL, on every engine.

PR CI on this head: 17 pass, 0 fail, 0 pending; 4 skipped.

[bpamiri]

rev1-r3 review @ 260506d: APPROVE (delta final, against my approval at 53acfa6)

The delta is the develop merge d3bbdab (base e63973b, with #4490–#4496 in) and the reaper commit 260506d.

Merge resolution, read with git show --remerge-diff:

• Job.cfc: result sits beside heartbeatAt, both in CREATE TABLE and in the column-ensure list ($ensureHeartbeatColumn() then $ensureResultColumn()).
• $processJob extracts $backoffSettings() and $deferBusyRun() (complexity gate). Both behave exactly like the inline code they replace: the same per-class backoff overrides, and the same defer plus tenant clear on a busy lease.
• JobWorker.$executeJob: the result struct carries both the lease fields (feat(job): exclusive jobs and concurrency keys on a shared lease lock #4496) and the hook fields (this PR).
• A busy lease returns inside the try before $fireJobSuccess, before the failure capture, and before the tenantPending handoff, so a deferred run fires no hooks and clears its own tenant context.
• jobInstance is set before the busy check, which is harmless because a busy outcome never reaches a hook.
• The worker's failure path is $runClaimedJob → $recordFailedAttempt, after the busy and fenced returns. So fenced attempts still fire no hooks, and a lost lease still reaches the hooks on the real outcome.

260506d, the reaper:

• A non-idempotent job reaped to interrupted now calls $fireReapedFailure(..., isFinal = true), gated on won > 0 like the retries-exhausted branch. Only the reaper that wins the row fires.
• $fireReapedFailure takes the message instead of the seconds, so each branch reports its own text. It is still best-effort and contained (load failure → hooks with no instance; any error is logged, and the reap loop continues).
• New spec: NonIdempotentHookJob (this.idempotent = false over HookProbeJob), a stale processing row, then checkTimeouts(). It checks status = interrupted, the hook log failure:1:true:Wheels.JobTimeout and the global hook's isFinal.

Matrix 37821594006 (full, dispatched on this head), read with my leg reader: 25 legs, all tests > 0 (7365–7375), 0 legs with fail or error. JobLifecycleHooksSpec runs 15 specs on every leg, 0 bad, including the new interrupt spec. The lease specs run 13 on every leg, 0 bad.

PR CI on this head: 17 pass, 4 skipping, 0 fail/pending. The branch is up to date with develop and MERGEABLE.

[bpamiri]

Correction to my delta final: develop moved after I posted. It now has #4505 (f3ed23b, distribution-install-smoke.yml only), so the branch is one CI-workflow commit behind. Nothing overlaps Job.cfc, JobWorker.cfc or the jobs specs. The PR is MERGEABLE, and the approval stands.