Worker Scripts

Workers are one of the key execution primitives in Lombok’s app platform.

In the current source-aligned model, workers are best understood as runtime workers declared in the app manifest and executed by Lombok’s worker runtime.

This is more specific than the older draft docs, which described workers as if they were generic in-process event handlers.

Where workers are defined

The current manifest model defines workers under runtimeWorkers.

Example:

{
  "runtimeWorkers": {
    "demo_object_added_worker": {
      "entrypoint": "demo_object_added_worker/index.js",
      "description": "Runs for every newly added object.",
      "environmentVariables": {
        "MY_CUSTOM_ENV_VAR": "_some_non_secret_env_var_value_"
      }
    }
  }
}

Each runtime worker has:

an identifier
an entrypoint
a description
optional environment variables

What workers do

Workers are used to execute app logic for things such as:

object-related event handling
scheduled jobs
completion handlers
request/API handling
async task execution

The demo app includes examples like:

demo_object_added_worker
demo_scheduled_worker
demo_on_complete_worker
demo_api_request_worker
demo_async_worker

How workers are reached

Workers are not the first thing that happens in the system.

The usual flow is:

an event occurs or a schedule matches
a trigger selects a task
the task resolves to a handler
the handler points to a runtime worker
Lombok executes that worker in the worker runtime

That means workers are part of a broader pipeline:

events
triggers
tasks
runtime workers

Worker categories to understand

Event workers

These run in response to core platform events.

Example from the demo app:

object added event → task → runtime worker

Scheduled workers

These run from interval or cron-based schedules.

Example from the demo app:

hourly job
weekday morning job

Request workers

These service request/response style interactions.

The demo app includes a demo_api_request_worker, which is important because it shows the app platform is not only background automation — it also supports app-facing request handling.

Completion workers

These run after other tasks complete.

The demo app includes a completion handler pattern through onComplete, which routes follow-up execution into another worker-backed task.

Worker runtime boundary

The Lombok architecture includes a dedicated core worker runtime.

That is an important architectural boundary because app code is not simply treated as part of the main API process documentation model.

The worker layer is responsible for actual execution of app work, which is one reason worker docs should stay tightly aligned with the source code and execution model.

Environment variables

Workers can declare worker-specific environment variables in the manifest.

Example:

"environmentVariables": {
  "MY_CUSTOM_ENV_VAR": "_some_non_secret_env_var_value_"
}

This makes the worker definition more than just an entrypoint registry; it is also part of runtime configuration.

Important correction

Older draft docs described workers as objects with generic event arrays and handler naming conventions such as:

events: ['file.uploaded']
onFileUploaded()

That may be useful as a conceptual teaching style in some ecosystems, but it is not a reliable representation of the current Lombok worker model documented by the inspected repository.

The current docs should instead teach workers through:

manifest-defined runtime workers
trigger-to-task-to-worker flow
demo-app-backed examples
the broader worker runtime architecture