Worker
Discover, register, schedule and execute persistent background jobs with APPNETOS workers, queues and runners.
Workers are application-owned executable PHP classes. The shared APPNETOS Worker Core provides metadata, scheduling, persistent job documents, dispatching, execution, retries and lifecycle management.
Architecture
Worker discovery and generation follow the same general model as Cmd: annotated PHP classes are discovered and compiled into an application-specific definition file. Unlike a directly executed CLI command, a worker can be dispatched into a persistent queue and executed later by a runner.
| Component | Responsibility |
|---|---|
| Discovery / Generator | Find annotated worker classes, validate implementations and generate definitions. |
| Registry / Metadata | Resolve registered worker keys and execution settings. |
| Dispatcher | Enqueue a worker key with an object payload, optionally for later availability. |
| Scheduler | Evaluate configured cron schedules or intervals and enqueue due occurrences. |
| Queue | Persist jobs, reserve work and maintain execution states. |
| Runner | Execute reserved jobs, interpret results and update their lifecycle. |
| Runtime | Coordinate the worker execution environment. |
Core, application and custom definitions
Worker definitions belong to the relevant application. A shipped application keeps its registry in
its
own .files/Worker/workers.php. Generated customizations are written under custom/<application>/.files/Worker/workers.php;
application authors copy reviewed generated definitions into the distributable application when
publishing a new release. Do not edit vendor/application files to implement site-specific changes.
appnetos-dns-control/.files/Worker/workers.php
custom/appnetos-dns-control/.files/Worker/workers.php
Worker discovery validates executable classes and requires a concrete subclass of Core\Worker\Worker
with a compatible __invoke(): Core\Worker\Result method. The generator restricts
discovered
worker sources to the target application's permitted directories.
Worker annotation
#[Core\Worker\Annotation\Worker] declares the stable worker key, queue, scheduling rule,
execution priority, timeout, retry allowance and activation state.
| Parameter | Type / default | Description |
|---|---|---|
key |
string (required) |
Unique worker identity |
queue |
string = 'default' |
Target execution queue |
schedule |
string|null = null |
Cron expression |
interval |
int|null = null |
Interval in seconds |
priority |
WorkerPriority::Normal |
Queue ordering |
timeout |
int = 300 |
Execution timeout in seconds |
retries |
int = 3 |
Permitted retries beyond the initial attempt |
active |
bool = true |
Enable or disable the definition |
Real application example: DNS Control
The shipped appnetos-dns-control registry declares four active workers in the
dns queue:
| Worker key | Schedule | Timeout | Retries |
|---|---|---|---|
appnetos-dns-control.deploy-configuration |
* * * * * |
300 s | 3 |
appnetos-dns-control.deployment-history-cleanup |
0 3 * * * |
300 s | 1 |
appnetos-dns-control.monitoring |
* * * * * |
60 s | 0 |
appnetos-dns-control.monitoring-history-cleanup |
15 3 * * * |
300 s | 1 |
All four use WorkerPriority::Low. These values are taken from the application definition
and
illustrate how one queue can serve both frequent checks and daily cleanup.
Discovery, generation and operations
# Generate application worker definitions
php bin/appnetos cmd appnetos:worker:generate appnetos-dns-control
# Inspect registered workers
php bin/appnetos cmd appnetos:worker:list appnetos-dns-control
# Worker runtime commands
php bin/appnetos cmd appnetos:worker:run --help
php bin/appnetos cmd appnetos:worker:cleanup --help
Check the runtime command help for supported queue and execution options before configuring
production
processes. Generating definitions updates the custom application registry; move them into the
application's distributed .files directory only when developing and publishing that
application itself.
Dispatching and payloads
Dispatcher::dispatch() resolves a registered worker key and creates a persistent job
with an
object payload. Its optional availableAt argument delays eligibility for execution. The
queue also supports scheduled jobs with a schedule identity and occurrence timestamp.
$job = $dispatcher->dispatch(
workerKey: 'appnetos-dns-control.monitoring',
payload: (object) ['source' => 'manual'],
);
The concrete dispatcher instance is obtained through the application's APPNETOS service/runtime integration; this snippet illustrates the public dispatch signature, not a standalone bootstrap.
Scheduling and execution
The Scheduler evaluates due worker definitions and creates queued occurrences. Cron expression evaluation is provided by the reusable Core Cron utility, which is documented separately under Utilities. The Runner reserves eligible jobs, initializes the worker document and invokes the implementation. Worker results carry success, optional message/data and a retry indication; the runner and persistent queue decide whether another attempt is allowed.
Priority uses numeric ordering, with lower values executed first when other queue constraints permit:
| Priority | Value |
|---|---|
| Critical | 0 |
| High | 25 |
| Normal | 50 |
| Low | 75 |
| Background | 100 |
Persistent job lifecycle
| Status | Meaning |
|---|---|
Queued |
Waiting for execution or retry |
Running |
Reserved and being executed |
Finished |
Completed successfully |
Failed |
Failed permanently |
Cancelled |
Cancelled without further normal execution |
Queued and Running are active states; Finished, Failed and Cancelled are terminal states. Queue
operations include reservation, finish, retry, fail, cancellation and release of expired
reservations.
Retries are bounded by the configured limit; the queue stores retries + 1 as the
maximum
number of attempts.
Production and Docker
Schedule the worker runtime and run dedicated processes for the required queues. Configure process supervision, restarts, log collection and concurrency to match workload and deployment capacity. The existing APPNETOS Docker setup requires explicit worker-process registration. Application-supplied Docker Compose or build fragments are a future integration concept, not an existing worker feature.
Public API Reference
Core\Worker\Annotation\Worker
Class & Usage
Class: Core\Worker\Annotation\Worker
Type: PHP class attribute (not a Registry service)
use Core\Worker\Annotation\Worker;
#[Worker(key: 'example.job', queue: 'default')]
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
getKey() |
Get worker job key. Returns: string. |
getQueue() |
Get worker queue. Returns: string. |
getSchedule() |
Get worker schedule. Returns: string|null.
|
getInterval() |
Get worker interval in seconds. Returns: int|null.
|
getPriority() |
Get worker priority. Returns: WorkerPriority.
|
getTimeout() |
Get worker timeout in seconds. Returns: int. |
getRetries() |
Get worker retry attempts. Returns: int.
|
getActive() |
Get worker job activation state. Returns: bool. |
isActive() |
Check if worker job is active. Returns: bool. |
Core\Worker\Worker
Class & Registry
Class: Core\Worker\Worker
Extends: Core\Worker\Worker\Base
use Core\Worker\Worker;
use Core\Registry;
$worker = Registry::get(Worker::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker. Returns: void. |
getDocument() |
Execute worker. Returns: Document|null.
|
getWorkerKey() |
Get worker key. Returns: string|null.
|
getPayload() |
Get worker payload. Returns: object|null.
|
getInitialized() |
Get worker initialization state. Returns: bool. |
isInitialized() |
Check if worker is initialized. Returns: bool. |
Core\Worker\Registry
Class & Registry
Class: Core\Worker\Registry
Extends: Core\Worker\Registry\Base
use Core\Worker\Registry;
use Core\Registry as CoreRegistry;
$registry = CoreRegistry::get(Registry::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker registry. Returns: void.
|
has() |
Discover worker metadata. Returns: bool.
|
get() |
Get worker metadata. Returns: Metadata|null.
|
getWorkers() |
Get registered worker metadata. Returns: array. |
count() |
Get registered worker count. Returns: int.
|
getCron() |
Get cron controller. Returns: Cron|null.
|
getInitialized() |
Get registry initialization state. Returns: bool.
|
isInitialized() |
Check if registry is initialized. Returns: bool. |
Core\Worker\Discovery
Class & Registry
Class: Core\Worker\Discovery
Extends: Core\Worker\Discovery\Base
use Core\Worker\Discovery;
use Core\Registry;
$discovery = Registry::get(Discovery::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker discovery. Returns: void.
|
discover() |
Discover worker definitions. Returns: array.
|
autoloadDiscoveryClass() |
Resolve worker source directories. Returns: void.
|
setApplication() |
Validate unique worker key. Returns: static.
|
getApplication() |
Get target application. Returns: string|null.
|
getDirectories() |
Get worker source directories. Returns: array. |
getAutoloadClasses() |
Get temporary discovery autoload classes. Returns: array.
|
getInitialized() |
Check whether controller is initialized. Returns: bool.
|
Core\Worker\Generator
Class & Registry
Class: Core\Worker\Generator
Extends: Core\Worker\Generator\Base
use Core\Worker\Generator;
use Core\Registry;
$generator = Registry::get(Generator::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker generator. Returns: void.
|
generate() |
Generate application worker definition file. Returns: string. |
getGeneratedFile() |
Filter discovered application workers. Returns: string.
|
exists() |
Check whether generated worker definition exists. Returns: bool. |
getInitialized() |
Check whether generator is initialized. Returns: bool.
|
Core\Worker\Metadata
Class & Registry
Class: Core\Worker\Metadata
Extends: Core\Worker\Metadata\Base
use Core\Worker\Metadata;
use Core\Registry;
$metadata = Registry::get(Metadata::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker metadata. Returns: void.
|
getKey() |
Get worker key. Returns: string.
|
getClass() |
Get worker class. Returns: string. |
getQueue() |
Get worker queue. Returns: string. |
getSchedule() |
Get worker schedule. Returns: string|null.
|
getInterval() |
Get worker interval in seconds. Returns: int|null.
|
getPriority() |
Get worker priority. Returns: WorkerPriority.
|
getTimeout() |
Get worker timeout in seconds. Returns: int. |
getRetries() |
Get worker retry attempts. Returns: int.
|
getActive() |
Get worker activation state. Returns: bool.
|
isActive() |
Check if worker is active. Returns: bool.
|
Core\Worker\Dispatcher
Class & Registry
Class: Core\Worker\Dispatcher
Extends: Core\Worker\Dispatcher\Base
use Core\Worker\Dispatcher;
use Core\Registry;
$dispatcher = Registry::get(Dispatcher::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker dispatcher. Returns: void. |
dispatch() |
Dispatch worker job. Returns: AppnetosWorker.
|
Core\Worker\Queue
Class & Registry
Class: Core\Worker\Queue
Extends: Core\Worker\Queue\Base
use Core\Worker\Queue;
use Core\Registry;
$queue = Registry::get(Queue::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker queue. Returns: void. |
push() |
Push worker job into queue. Returns: AppnetosWorker.
|
pushScheduled() |
Push scheduled worker job into queue. Returns: AppnetosWorker.
|
reserve() |
Reserve next worker job. Returns: AppnetosWorker|null.
|
finish() |
Complete worker job. Returns: AppnetosWorker.
|
retry() |
Retry worker job. Returns: AppnetosWorker.
|
fail() |
Fail worker job. Returns: AppnetosWorker.
|
cancel() |
Cancel worker job. Returns: AppnetosWorker.
|
releaseExpired() |
Release expired worker reservations. Returns: array.
|
countByQueue() |
Count worker jobs by queue. Returns: int.
|
isEmpty() |
Check whether queue is empty. Returns: bool. |
getCollection() |
Get worker collection. Returns: AppnetosWorkerCollection|null.
|
getInitialized() |
Get queue initialization state. Returns: bool. |
isInitialized() |
Check if queue is initialized. Returns: bool. |
Core\Worker\Scheduler
Class & Registry
Class: Core\Worker\Scheduler
Extends: Core\Worker\Scheduler\Base
use Core\Worker\Scheduler;
use Core\Registry;
$scheduler = Registry::get(Scheduler::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
__invoke() |
Execute worker scheduler. Returns: int. |
init() |
Initialize worker scheduler. Returns: void.
|
getRegistry() |
Get worker registry. Returns: Registry|null.
|
getQueue() |
Get worker queue. Returns: Queue|null.
|
getCron() |
Get cron controller. Returns: Cron|null.
|
getDateTime() |
Get current scheduler DateTime. Returns: DateTime|null.
|
getInitialized() |
Get scheduler initialization state. Returns: bool.
|
isInitialized() |
Check if scheduler is initialized. Returns: bool.
|
Core\Worker\Runner
Class & Registry
Class: Core\Worker\Runner
Extends: Core\Worker\Runner\Base
use Core\Worker\Runner;
use Core\Registry;
$runner = Registry::get(Runner::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
__invoke() |
Execute worker runner. Returns: int. |
init() |
Initialize worker runner. Returns: void.
|
execute() |
Execute runtime worker document. Returns: Result. |
getRegistry() |
Get worker registry. Returns: Registry|null.
|
getQueue() |
Get worker queue. Returns: Queue|null.
|
getDocumentFactory() |
Get worker document factory. Returns: DocumentFactory|null.
|
getRunnerId() |
Get worker runner ID. Returns: string|null.
|
getInitialized() |
Get runner initialization state. Returns: bool. |
isInitialized() |
Check if runner is initialized. Returns: bool. |
Core\Worker\Runtime
Class & Registry
Class: Core\Worker\Runtime
Extends: Core\Worker\Runtime\Base
use Core\Worker\Runtime;
use Core\Registry;
$runtime = Registry::get(Runtime::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
__invoke() |
Execute worker runtime. Returns: int. |
init() |
Initialize worker runtime. Returns: void.
|
getRegistry() |
Run worker runtime. Returns: Registry|null.
|
getQueue() |
Get worker queue. Returns: Queue|null.
|
getScheduler() |
Get worker scheduler. Returns: Scheduler|null.
|
getRunner() |
Get worker runner. Returns: Runner|null.
|
getInitialized() |
Get runtime initialization state. Returns: bool. |
isInitialized() |
Check if runtime is initialized. Returns: bool. |
Core\Worker\Document
Class & Registry
Class: Core\Worker\Document
Extends: Core\Worker\Document\Base
use Core\Worker\Document;
use Core\Registry;
$document = Registry::get(Document::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker document. Returns: void.
|
getWorkerKey() |
Get worker key. Returns: string|null.
|
getPayload() |
Get worker payload. Returns: object|null.
|
getInitialized() |
Get document initialization state. Returns: bool.
|
isInitialized() |
Check if document is initialized. Returns: bool. |
Core\Worker\DocumentFactory
Class & Registry
Class: Core\Worker\DocumentFactory
Extends: Core\Worker\DocumentFactory\Base
use Core\Worker\DocumentFactory;
use Core\Registry;
$documentFactory = Registry::get(DocumentFactory::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
create() |
Create runtime worker document. Returns: Document.
|
createFromJson() |
Create runtime worker document from JSON payload. Returns: Document.
|
createFromFile() |
Create runtime worker document from JSON file. Returns: Document.
|
Core\Worker\Result
Class & Registry
Class: Core\Worker\Result
Extends: Core\Worker\Result\Base
use Core\Worker\Result;
use Core\Registry;
$result = Registry::get(Result::class);
| Method | Description |
|---|---|
__construct() |
This file is a part of APPNETOS® (Application Internet Operating System). Returns: —. |
init() |
Initialize worker result. Returns: void.
|
getInitialized() |
Get result initialization state. Returns: bool. |
isInitialized() |
Check if result is initialized. Returns: bool. |
getSuccess() |
Get worker execution success state. Returns: bool.
|
isSuccess() |
Check if worker execution succeeded. Returns: bool.
|
getMessage() |
Get worker message. Returns: string|null.
|
getData() |
Get worker result data. Returns: object|null.
|
getRetry() |
Get retry state. Returns: bool.
|
isRetry() |
Check if worker execution should be retried. Returns: bool. |
The listed methods belong to the supplied shared Worker Core implementations. Concrete runtime classes and their Registry availability should be verified against the application bootstrap and class mapping. The Worker annotation is applied as a PHP attribute rather than resolved through the Registry.
Atomic reservations and recovery
Worker jobs are persisted as Core\Document\AppnetosWorker documents. A runner atomically
reserves an eligible job rather than selecting and updating it in separate operations. This allows
multiple runner processes to consume the same queue safely.
Persistent job fields
| Field | Description |
|---|---|
workerKey, scheduleKey |
Registered worker identifier and unique scheduled-slot identifier |
scheduledAt, availableAt |
Scheduled time and earliest time at which the job may be reserved |
queue, payload, priority |
Queue routing, input and reservation ordering |
status, attempt, maxAttempts,
timeout
|
Execution state, attempts and reservation duration |
workerId, reservedAt, reservedUntil,
startedAt |
Reservation owner, acquisition, expiry and execution start |
finishedAt, failedAt, cancelledAt |
Terminal-state timestamps |
result, error |
Persisted result data and error information |
Reservation conditions and ownership
A job is eligible when it is queued, its availableAt time has been reached,
its
attempt is below maxAttempts, and it matches any requested queue filter.
Reserving it sets running, assigns a unique workerId, increments
attempt and establishes reservedUntil from the timeout.
reservedUntil = reservedAt + max(1, timeout) seconds
Completion filter: _id + status=running + workerId
Completion, retry and failure updates must match the reservation owner. A runner that has lost its reservation cannot safely overwrite a newer runner's result.
Expired reservations
If a process exits while a job is running, releaseExpired() handles jobs whose
reservation
has expired: running → queued when attempts remain, or running → failed
when
they do not. Recovery and retention cleanup are separate operations. Never delete an active or
expired
running job as part of cleanup.
Delivery guarantee: atomic reservation prevents concurrent ownership of one queue document, but does not guarantee exactly-once external side effects. Use business-level idempotency keys, transactional state changes and idempotent external APIs.
Scheduling, parallel runners and process control
The scheduler only enqueues due jobs; it never executes them. The runner only reserves and executes queued jobs; it does not calculate schedules. Cron expressions use minute-level slots, while interval definitions support second-level scheduling in watch mode.
Scheduled slots must be deduplicated using a stable scheduleKey, including when two
scheduler processes overlap. Persistent scheduler and runner processes should respond to
SIGTERM and SIGINT for controlled shutdown. Signal support depends on the
CLI
environment and relevant PHP extensions such as pcntl.
Runner selection
php bin/appnetos worker appnetos-dns-control runner
php bin/appnetos worker appnetos-dns-control runner dns
php bin/appnetos worker appnetos-dns-control scheduler watch
A runner without a queue argument consumes all queues of its application, not only
default. General and queue-specific runners can run concurrently, but a general runner
can
also reserve jobs from a specialized queue. Configure runner pools deliberately when resource
isolation
matters.
Lower numeric priority values are processed first: Critical=0, High=25,
Normal=50,
Low=75, Background=100. The documented reservation sort order is priority,
availableAt, created, then _id. Priority does not interrupt
an
already running job.
Operations, monitoring and safety
Production supervision
Run long-lived scheduler and runner processes under a supervisor such as Docker, systemd or Kubernetes. Restart terminated processes, keep web and worker deployments on compatible application releases, and use structured logs with application, worker key, job ID, queue, runner ID and attempt.
Indexes and retention
The pre-documentation recommends validating MongoDB query plans for these index patterns rather than assuming they are optimal for every workload:
status + queue + availableAt + priority + created
status + availableAt + priority + created
scheduleKey (unique)
status + reservedUntil
status + finishedAt / failedAt / cancelledAt
Retention cleanup must only consider sufficiently old terminal jobs (finished,
failed, cancelled); it must never remove queued or
running jobs. The August 2026 pre-documentation describes a cleanup command and its
options
as proposed work, not as a verified current CLI contract. Check the installed command's help before
documenting exact flags.
Security and observability
- Validate all payload fields; queue payloads are untrusted input.
- Resolve executable workers only through the registry, never from a payload-supplied class name.
- Keep credentials out of queue documents, result data and error messages.
- Grant runner processes only the required database and network permissions.
- Monitor waiting, running and failed counts, the oldest waiting job, reservation expiry, execution duration and retry rate.
Potential future improvements described in the pre-documentation include configurable retry backoff, dead-letter handling, tracing and a platform administration view. These are design ideas, not guarantees of current implementation.