APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

APPNETOS worker discovery, registry, scheduler, queue and runner architecture
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.

Next Steps

Previous

Cmd

Explore Cmd

Next

Install

Explore Install