Download the PHP package citomni/jobrunner without Composer

CitOmni JobRunner

DB-backed long-running job execution for CitOmni.

citomni/jobrunner is a small provider package for explicit long-running jobs with durable state, registered handlers, structured logs, progress, heartbeat, cancellation, and terminal result/error persistence.

JobRunner supports two execution ownership models:

Both modes execute the actual application handler in a fresh PHP process.

The package is deliberately scoped. It is not a generic message queue, scheduler, retry framework, distributed worker farm, arbitrary command runner, or general daemon framework.

Highlights

• Runs application-defined long jobs outside request handling.
• Supports token/push execution through StartJob.
• Supports trusted/pull execution through EnqueueTrustedJob and job:work.
• Executes every actual job handler in a fresh PHP process.
• Uses atomic, mode-specific worker claims.
• Preserves opaque capability-based worker ownership in both execution modes.
• Exposes status, progress, logs, result, and errors through GetJobStatus.
• Supports cooperative cancellation through CancelJob.
• Supports active lock keys to prevent duplicate active work.
• Persists jobs and logs through repository-owned SQL.
• Uses CitOmni provider registration and explicit configuration.

Documentation

Start here:

• JobRunner usage guide
• JobRunner execution ownership architecture
• End-to-end smoke test

Long-form documentation lives in the separate citomni/docs repository.

This README stays focused on package purpose, installation, runtime shape, and the main public surface.

Requirements

• PHP 8.5+
• Composer
• A CitOmni application using citomni/kernel
• CitOmni CLI mode for worker execution
• A database connection supplied through citomni/infrastructure

citomni/jobrunner must be installed as a Composer dependency. Do not copy package source into an application.

Installation

Install the database schema from:

The schema creates:

What this package provides

Durable lifecycle

JobRunner persists:

• Job identity and type.
• Lifecycle status.
• Execution claim mode.
• Optional payload.
• Optional active lock key.
• Progress and heartbeat.
• Result data.
• Error metadata.
• Job logs.
• Execution attempts.
• Lifecycle timestamps.

Current statuses:

Current claim modes:

Execution

JobRunner provides:

• Detached token/push worker launch.
• Persistent trusted queue supervision.
• Fresh trusted child-process launch.
• Atomic token-mode claim.
• Atomic trusted-mode claim.
• Shared post-claim handler execution.
• Deterministic terminal state handling.

Observability

JobRunner provides:

• Structured job logs.
• stdout/stderr-oriented log streams.
• Step key, label, index, and total.
• Heartbeat timestamps.
• Incremental log polling through afterSeq / last_log_seq.
• Persisted result and error data.

Cancellation

JobRunner supports cooperative cancellation:

Handlers observe cancellation through JobContext::isCancellationRequested().

Provider integration

The package contributes:

Execution modes

Token / push

Use token/push when the producer should immediately launch the dedicated worker and that child will inherit the intended execution environment.

Public operation:

Example:

Runtime:

StartJob mints a cryptographically random worker token, persists only its SHA-256 hash, and passes the raw token only to the fixed worker command.

Possible StartJob result statuses:

Trusted / pull

Use trusted/pull when queue production and final execution must be separated and a pre-established trusted supervisor should own dispatch.

Public operation:

Example:

Runtime:

Possible EnqueueTrustedJob result statuses:

A trusted job may remain queued while no trusted supervisor is running. There is no implicit fallback to token/push execution.

Persistent trusted supervisor

Start the trusted supervisor with:

The supervisor:

• Selects the oldest queued job with claim_mode = trusted.
• Uses created_at, then id, for deterministic ordering.
• Creates an ephemeral handoff token for the selected job.
• Persists only the SHA-256 hash of that capability.
• Keeps the row in queued state during dispatch preparation.
• Starts one fresh job:run-trusted child.
• Waits for the child to exit.
• Checks for the next job immediately.
• Sleeps only when the trusted queue is empty.

Default idle sleep:

configured through:

The intended V1 operating model is one trusted supervisor processing one trusted child at a time.

The supervisor does not execute application handlers in-process.

Fresh process per job

Both execution modes preserve fresh-process isolation.

Token/push:

Trusted/pull:

The persistent supervisor therefore does not retain application handler state between jobs.

Each actual job receives a fresh:

• PHP runtime.
• CitOmni App.
• Service graph.
• JobRegistry.
• Handler instance.

Worker ownership

Both modes require the concrete child process to prove ownership before handler execution.

Token-mode claim

The child must match:

Trusted-mode claim

The child must match:

Only the successful claim changes:

and records:

This keeps dispatch attempts separate from actual execution attempts.

For the full ownership and race model, see the execution ownership architecture.

Shared execution lifecycle

After a successful claim, both worker types converge on the same execution path.

Conceptually:

The shared execution lifecycle owns:

• Job loading.
• Payload decoding.
• Handler lookup.
• JobContext.
• Handler execution.
• Cancellation resolution.
• Result encoding.
• Failure persistence.
• Terminal transitions.
• Terminal logging.

Token/push and trusted/pull therefore differ in ownership acquisition, not handler semantics.

Public operations

StartJob

Creates a token-mode queued job and launches its detached worker.

Use when immediate push execution is appropriate.

EnqueueTrustedJob

Creates a trusted-mode queued job without launching a worker.

Use when a separately running job:work supervisor should dispatch the job.

GetJobStatus

Reads one job, a bounded log slice, result data, and error data.

Use last_log_seq as the next incremental polling cursor.

CancelJob

Cancels queued jobs immediately or requests cooperative cancellation for running jobs.

Internal and operational CLI commands

job:run

Internal token/push worker entrypoint:

Normal application code should use StartJob, not construct this command.

job:run-trusted

Internal trusted child entrypoint:

Normal application code should not construct this command. job:work owns trusted dispatch.

job:work

Operational trusted supervisor:

Run it under the process identity and environment intended to execute trusted jobs.

JobRunner does not switch operating-system users or install/manage host services.

Registering job handlers

Register explicit job types in CitOmni config:

Handlers must implement:

Example:

Handlers are currently instantiated without constructor arguments.

Use:

when the handler needs application services, repositories, or config.

JobContext

Handlers use JobContext for job-aware execution.

Identity and payload:

Logging:

Progress:

Heartbeat:

Cancellation:

Cancellation is cooperative. Check between bounded work units.

Active locks

A job may use a logical lock key to prevent duplicate active work.

Active statuses:

Terminal statuses:

Example:

The generated active_lock_key and its unique index provide the authoritative duplicate guard.

The application-level pre-check exists as a friendly fast path, not as the final race guard.

Both execution modes share the same active-lock behavior.

Status and incremental logs

Use:

Example:

For incremental polling:

Do not add one manually.

The underlying query already uses:

The public status read model includes lifecycle state, progress, timestamps, logs, result, and errors without exposing worker ownership material.

Cancellation

Use:

Current behavior:

A running job is not hard-killed by CancelJob.

The handler cooperates by checking:

between meaningful work units.

Database model

jobrun_jobs contains lifecycle and ownership state.

Important fields include:

The database enforces claim mode values:

and token-mode jobs must carry a worker-token hash.

Trusted jobs are enqueued without one and receive a temporary handoff hash during trusted dispatch preparation.

jobrun_logs provides deterministic per-job sequence ordering.

Runtime configuration

Default package configuration includes:

Applications normally override handler registration and only change launcher/runtime settings when their environment requires it.

Security guidance

Registered intent, not arbitrary commands

Expose bounded registered job types.

Good:

Do not make JobRunner a generic transport for arbitrary command strings.

Keep payloads narrow

Prefer intent:

over arbitrary execution details.

Handlers should resolve authoritative hosts, paths, credentials, and options from application-owned data.

Do not persist secrets in JobRunner

Do not place raw secrets in:

Prefer stable references or identifiers and resolve the real credential inside the intended execution context.

Treat trusted queue writers as privileged action producers

Trusted/pull separates queue production from execution, but a caller that can enqueue a trusted registered job can request the action represented by that job type.

Authentication, authorization, and payload validation remain application responsibilities.

What this package owns

citomni/jobrunner owns:

• Generic job lifecycle.
• Claim mode persistence.
• Worker ownership gates.
• Trusted queue dispatch protocol.
• Worker process launch mechanics for fixed internal worker commands.
• Handler lookup.
• JobContext.
• Job logs.
• Progress and heartbeat persistence.
• Cancellation request state.
• Result/error persistence.
• Terminal transitions.

What this package does not own

JobRunner does not own:

• Application workflow semantics.
• HTTP authentication or authorization.
• Application-specific routes or UI.
• Arbitrary shell execution.
• Credential storage.
• Operating-system user switching.
• Operating-system service/scheduler installation.
• Scheduled job creation.
• Automatic retry policy.
• Multiple queue backends.
• Distributed worker coordination.
• Parallel trusted worker pools.
• Domain-specific persistence.

The host environment decides how job:work is started and kept alive.

Consumer packages decide what registered jobs actually do.

Operational notes

Token/push

A successful StartJob normally launches the fresh worker immediately.

If the environment cannot submit the detached process, JobRunner returns or surfaces launch failure. It does not silently run the job inline.

Trusted/pull

A trusted job may remain queued until job:work is available.

This is normal trusted/pull behavior.

The supervisor should run in the execution environment intended for trusted jobs.

One trusted supervisor

The current V1 model is one trusted supervisor and one trusted child at a time.

The atomic child claim still protects against duplicate execution ownership, but deliberately running several supervisors is outside the intended V1 operating model.

Failed trusted child

A handler failure may cause job:run-trusted to exit non-zero after correctly persisting the job as failed.

job:work continues to later jobs.

Cleanup and retention

Cleanup and retention policy remain outside the core lifecycle.

Applications may define retention rules appropriate to their operational needs.

Troubleshooting

Token job stays queued

Check:

Token/push expects the dedicated child to be submitted immediately.

Trusted job stays queued

First verify:

is running.

Then check:

Do not manually mark the row running. The child must win the guarded claim.

Job fails immediately

Inspect through GetJobStatus:

Common causes include invalid payload, missing handler, handler contract mismatch, handler exception, or non-encodable result.

Cancellation is slow

The handler is probably not checking:

frequently enough.

Incremental logs repeat or skip

Use:

exactly as returned.

Smoke testing

For the existing app-local end-to-end smoke-test guide, see:

CitOmni JobRunner - End-to-End Smoke Test

For current practical usage of both execution modes, see:

CitOmni JobRunner - Usage, Execution Modes, Handlers, Status, and Cancellation

For the detailed trusted/pull ownership model, capability handoff, fencing, race handling, and fresh-process rationale, see:

JobRunner Execution Ownership Architecture

Architecture rules

citomni/jobrunner follows normal CitOmni boundaries:

• Controllers own HTTP transport.
• Commands own CLI transport.
• Operations own orchestration.
• Repositories own SQL and persistence.
• Services provide reusable App-aware runtime tools.
• Job handlers own application/package workflow.

In particular:

• Keep SQL in repositories.
• Keep transport shaping in controllers and commands.
• Keep queue/execution orchestration in operations.
• Keep process launch mechanics in JobLauncher.
• Do not expose arbitrary command execution.
• Do not put raw credentials in JobRunner persistence.
• Do not add generic queue machinery without a concrete requirement.

Performance notes

• Service resolution uses explicit CitOmni maps.
• Trusted idle polling performs a small indexed lookup and sleeps when no work exists.
• Busy trusted queues are drained without an intentional idle delay between jobs.
• Fresh PHP process startup is deliberately retained for per-job runtime isolation.
• No distributed queue infrastructure is required for the current model.
• Production should use normal PHP/Composer optimization appropriate to the application.

Contributing

• PHP 8.5+
• PSR-1 / PSR-4
• Tabs for indentation
• K&R brace style
• PHPDoc and inline comments in English
• Keep ownership boundaries explicit
• Keep SQL in repositories
• Keep transport in controllers/commands
• Keep orchestration in operations
• Avoid speculative queue, retry, or parallel-worker machinery

Shared conventions:

CitOmni Coding and Documentation Conventions

License

CitOmni JobRunner is open-source under the MIT License.

See LICENSE.

Trademark notice: "CitOmni" and the CitOmni logo are trademarks of Lars Grove Mortensen. Usage of the name or logo must follow the policy in NOTICE. Do not imply endorsement or affiliation without prior written permission.

Trademarks

"CitOmni" and the CitOmni logo are trademarks of Lars Grove Mortensen.

You may make factual references to "CitOmni", but do not modify the marks, create confusingly similar logos, or imply sponsorship, endorsement, or affiliation without prior written permission.

Do not register or use "citomni" (or confusingly similar terms) in company names, domains, social handles, or top-level vendor/package names.

For details, see TRADEMARKS.md.

Author

Developed by Lars Grove Mortensen © 2012-present.

CitOmni - low overhead, high performance, ready for anything.