Introducing a new way to review your PRs.

Read the announcement

appwrite / appwrite

The open-source cloud for agents & devs. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime, WAF and more

View on GitHub

59 documents · Updated Nov 20, 2026

docs / worker-job-families

Worker job families

Workers run platform work outside the request path. A shared entrypoint selects either all configured queues or one named job family, while each family applies one kind of delayed work and records its result for later system actions. See Background processing for the queue model and Queue library for queue behavior.

Worker entrypoint

The worker entrypoint starts the queue service and maps a worker name to the queue and concurrency rules for that family. The default command serves all configured families. A named command serves one family so its load and failures can be managed apart from other work.

flowchart LR
    Command[Worker command] --> Entry[Shared worker entrypoint]
    Entry --> Select{Worker name}
    Select -->|all| Queues[Configured queues]
    Select -->|one family| Queue[One queue]
    Queues --> Server[Queue service]
    Queue --> Server
    Server --> Job[Specialized worker action]
    Job --> State[Platform state and follow-up events]

The entrypoint rejects an unknown family before it listens for jobs. Each family has a queue name and a default concurrency limit. Dedicated workers can override most limits, while database work stays single-threaded because its order matters.

References: app/worker.php• L51-85 app/worker.php• L108-126 src/…/Jobs.php• L7-57 app/…/workers.php• L13-106

Worker command families

Worker commands are selectors for the shared entrypoint. The selected family defines the product work that the queue service performs.

FamilyProduct responsibility
buildsPrepare source and send deployments to the build service.
certificatesVerify domains and issue or renew certificates.
databasesApply queued database and schema changes.
deletesRemove project resources and related stored data.
executionsKeep execution state and execution storage aligned.
functionsRun function work and publish its results.
jobsApply build-service callbacks to deployment state.
mailsRender and send system email.
messagingSend project email, push, and SMS messages.
migrationsMove project data between supported systems.
notificationsDeliver notices through supported channels.
screenshotsCapture and store deployment previews.
webhooksSend matching project events to configured endpoints.
alertsEvaluate usage monitors and announce alert state changes.
stats-usageRecord project-scoped usage events.
stats-resourcesMeasure project resources and write usage gauges.

For example, worker-builds and worker-messaging pass their family names to the same entrypoint. This keeps queue startup, job context, tracing, and error reporting consistent across families.

References: app/…/workers.php• L13-106 bin/worker• L1-3 bin/worker-builds• L1-3 bin/worker-messaging• L1-3 bin/worker-screenshots• L1-3

Build and deployment families

Build and deployment workers turn source changes and build results into a usable deployment. They also maintain domain access and site previews as follow-up work.

The builds family prepares source and hands it to the build service. The jobs family joins build callbacks into a final deployment state even when callbacks repeat or arrive out of order. A ready deployment can update routing and schedules. It can also publish usage and trigger screenshots, webhooks, and event-driven functions.

The screenshots family captures light and dark site previews after deployment. A failed preview does not make the deployment fail. The certificates family has two stages: domain verification and certificate generation. It skips DNS checks for the main platform domain and platform-owned subdomains. Custom domains still need valid public DNS records.

Certificate providers can finish later. The worker records a future check instead of creating a second order. A renewal can keep serving its current certificate while the provider works. Final failures update certificate state and notify the security address. A first successful issuance also notifies project owners.

References: src/…/Jobs.php• L43-65 src/…/Jobs.php• L177-271 src/…/Jobs.php• L467-677 src/…/Screenshots.php• L83-267 src/…/Certificates.php• L103-228 src/…/Certificates.php• L257-318 src/…/Certificates.php• L335-504 src/…/Certificates.php• L653-680

Data and lifecycle families

Data and lifecycle workers apply work that can be large or must follow a safe order. They protect API requests from long data changes while keeping project state complete.

The databases family processes schema and database changes with one concurrent job. The deletes family handles resource removal and deferred cleanup. It stops project schedules before deletion. It removes related data, old sessions, exports, executions, deployments, and other expired records. It also removes deployment runtimes and cleans usage data before and after project removal when self-hosted usage is enabled.

Maintenance delete work retires deployments that are outside retention rules but keeps active and rule-protected deployments. It marks stale migrations as failed and parks stalled video rendition and caption work. The migrations family validates source and destination context, claims each migration once, reports progress, and finishes with a completed or failed record. The executions family keeps single executions, batches, and cancellations aligned with the execution store.

References: src/…/Databases.php• L53-99 src/…/Deletes.php• L115-195 src/…/Deletes.php• L295-430 src/…/Deletes.php• L505-605 src/…/Deletes.php• L673-905 src/…/Deletes.php• L907-1082 src/…/Migrations.php• L146-222 src/…/Migrations.php• L630-837

Delivery and integration families

Delivery and integration workers move system or project events to users and external services. Each family uses a delivery contract that controls retries and duplicate work.

The functions family runs HTTP, scheduled, and event-triggered function work. A scheduled function is claimed before its execution message is published. A failed publish releases the claim. A successful publish leaves the schedule inactive so the execution is not published twice. The mails family renders system email and sends it through the configured mail path.

The notifications family delivers notices through console, email, push, or webhook channels. It uses a stable delivery key and continues with other recipients when one recipient fails. The messaging family sends project email, push, and SMS messages. It resolves recipients in pages, groups them by provider, and sends provider-sized batches. A retry sends only recipients that still need delivery. Appwrite push can deliver the message through MQTT and send a separate wake signal to supported push devices. Expired device tokens are marked for later cleanup. Email attachments are prepared for the provider and removed after the send attempt.

The webhooks family matches event patterns, signs requests, and records a stable delivery ID. It retries only failed deliveries and pauses a webhook after its failure limit. It checks that a destination is public before connecting. See Event bus and webhooks for the event delivery model.

References: src/…/Functions.php• L88-169 src/…/Functions.php• L183-281 src/…/Mails.php• L72-203 src/…/Notifications.php• L84-144 src/…/Notifications.php• L192-224 src/…/Messaging.php• L109-179 src/…/Messaging.php• L203-245 src/…/Messaging.php• L299-495 src/…/Messaging.php• L498-701 src/…/Messaging.php• L1053-1222 src/…/Webhooks.php• L74-135 src/…/Webhooks.php• L152-397

Alert and usage families

Alert and usage workers turn project activity or resource state into records used for limits, reports, and user notices. They avoid creating false readings when the source data is not ready.

The alerts family compares a usage value with a monitor threshold. It opens or resolves an alert and sends project events and notices for a state change. Cooldowns and stable keys prevent repeated notices after queue redelivery.

The stats-usage family records project events in time-based batches. The stats-resources family writes resource gauges for project objects, storage, databases, deployments, functions, sites, photos, videos, messages, and webhooks. It can use gauges supplied by another producer or measure current project data. If one bucket or database cannot be measured, it keeps the per-resource readings but omits the affected project total. Both families stop or fail safely when usage is disabled or its schema is not ready.

References: src/…/Alerts.php• L37-44 src/…/Alerts.php• L86-131 src/…/Alerts.php• L144-252 src/…/StatsUsage.php• L16-41 src/…/StatsUsage.php• L78-220 src/…/StatsResources.php• L39-104 src/…/StatsResources.php• L107-185 src/…/StatsResources.php• L197-255 src/…/StatsResources.php• L264-331

Job context and results

Each message gets a fresh context for its job. The context resolves the project and the services that the selected family needs, so a job uses the correct project without carrying state from an earlier message.

Workers record queue traces and report failures to the console and logger. A family can save its result or publish another message. For example, a certificate update can publish events, a deployment can request a screenshot, and a resource reading can write usage gauges.

References: app/worker.php• L108-126 app/worker.php• L154-198 app/…/message.php• L31-76 app/…/message.php• L145-195

Worker deployment modes

Workers can run in combined mode or separate mode. Combined mode serves many families through one queue service. Separate mode runs one family per service, which limits the effect of load or failure in that family.

Both modes use the same image and shared entrypoint. Separate services select a family such as worker-webhooks or worker-functions and provide the resources that family needs.

References: app/worker.php• L69-85 app/worker.php• L137-152 docker-compose.yml• L504-624 docker-compose.yml• L762-879 docker-compose.yml• L920-1179

Change checklist

When these files or sections are changed, remember to consider these:

  • When adding or renaming a family, update the worker configuration, command wrapper, and service entrypoint.
  • When changing a queue name, update both its publisher and consumer. Check family-specific overrides.
  • When changing concurrency, review combined and dedicated modes separately. Keep database work single-threaded.
  • When changing a message payload, update its producer, family action, and follow-up publishers.
  • When changing certificate state, keep domain verification, provider polling, renewal state, owner notices, and rule events aligned.
  • When changing delete behavior, keep schedule deactivation, usage capture, pre-delete purge, resource removal, runtime cleanup, and post-delete sweep aligned.
  • When changing messaging delivery, keep provider results, partial retries, wake signals, expired-token state, attachment cleanup, and terminal status aligned.
  • When changing resource gauges, keep project identity, metric tags, partial-sweep handling, usage readiness, and the usage adapter contract aligned.

Important failure modes

TriggerConsequenceGuard
A command selects an unknown family.The worker exits before it consumes jobs.Keep command names and worker configuration keys aligned.
A publisher and worker use different queue names.Jobs remain unprocessed.Treat publisher settings and worker settings as one contract.
Database concurrency rises above one.Ordered schema work can conflict or deadlock.Preserve the database concurrency exception.
A delayed certificate provider is ordered again before its first order finishes.Provider work can conflict and certificate state can become unclear.Store a future check and poll the existing order.
A custom domain fails DNS or public-domain validation.The failure is recorded without rapid queue redelivery.Keep configuration failures distinct from resolver and provider errors.
A project is deleted while its schedules remain active.Schedulers can continue firing removed project work.Deactivate schedules before removal and sweep them later.
Usage purge fails before project deletion.The delete stops while tenant mappings still exist.Purge before deletion and allow the queue to retry.
A message has no provider or valid recipient.The message is marked failed without delivery.Keep provider selection, recipient resolution, and terminal status together.
A provider partially delivers a message.A retry can send a successful recipient twice.Retry only recipients that still fail.
Attachment cleanup fails after a message send.Decrypted attachment data can remain on local storage.Remove the temporary path and report a path that still exists.
A webhook target resolves to a private address.Delivery is blocked before it can reach an internal service.Validate public destinations before connecting.
A resource sweep cannot measure one bucket or database.A project total could be understated.Omit the incomplete total and keep valid resource readings.
The usage schema is not ready.Usage jobs cannot make valid writes or readings.Check readiness and retry from a later job or cycle.

Key files

FileWhy to read it
app/worker.phpShared worker entrypoint, queue selection, context setup, and error reporting.
app/…/workers.phpSupported families, queue names, and concurrency defaults.
src/…/Jobs.phpQueue resolution and combined versus dedicated concurrency.
app/…/message.phpPer-job project, database, storage, and publisher context.
src/…/Jobs.phpBuild callbacks, deployment readiness, activation, and follow-up events.
src/…/Certificates.phpDomain verification, certificate issuance, renewal polling, and notices.
src/…/Deletes.phpResource deletion, maintenance cleanup, retention, and usage purge.
src/…/Messaging.phpProject message delivery, provider batching, retries, MQTT wake signals, and attachment handling.
src/…/Functions.phpFunction execution and scheduled handoff.
src/…/Webhooks.phpEvent matching, signed delivery, redelivery, destination checks, and pause behavior.
src/…/StatsUsage.phpUsage event batching and retained write retries.
src/…/StatsResources.phpResource measurement and usage gauge writes.
docker-compose.ymlCombined and separate worker services and their required resources.