Configuration

You can pass an optional configuration object as the second argument to EdgeWorker.start() to tweak the worker’s behavior.

Zero Configuration

Edge Worker comes with sensible defaults for all configuration options.

You only need to provide a handler function:

EdgeWorker.start(console.log);

Configuration Validation

Currently, configuration options are not validated at runtime. Please double-check your settings carefully.

Runtime validation is planned as part of the upcoming configuration system improvements.

Default configuration

EdgeWorker.start(handler, {
  // name of the queue to poll for messages
  queueName: 'tasks',

  // how many tasks are processed at the same time
  maxConcurrent: 10,

  // how many connections to the database are opened
  maxPgConnections: 4,

  // in-worker polling interval
  maxPollSeconds: 5,

  // in-database polling interval
  pollIntervalMs: 200,

  // how long to wait before retrying a failed job
  retryDelay: 5,

  // how many times to retry a failed job
  retryLimit: 5,

  // how long a job is invisible after reading
  // if not successful, will reappear after this time
  visibilityTimeout: 3,
});

Queue configuration

You don’t need to create queues manually

The worker will automatically create a logged, non-partitioned queue with configured name during startup if it does not exist.

queueName

Type: string Default: 'tasks'

The name of the PGMQ queue to listen to for messages.

EdgeWorker.start(handler, {
  queueName: 'my_custom_queue'
});

Message Processing

visibilityTimeout

Type: number Default: 3

The duration (in seconds) that a message remains invisible to other consumers while being processed.

Message Visibility and Processing

Keep visibilityTimeout higher than your task’s maximum processing time.

Here’s why:

• When a worker picks up a message, it becomes invisible for visibilityTimeout seconds
• If processing takes longer than visibilityTimeout, the message becomes visible again
• Other workers can then pick up and process the same message
• This leads to duplicate processing of the same task
• For example: with visibilityTimeout: 3 and a task that takes 5 seconds, the message could be processed twice

EdgeWorker.start(handler, {
  visibilityTimeout: 5 // message will re-appear in queue after 5 seconds if not processed
});

maxConcurrent

Type: number Default: 10

This option limits concurrency - the maximum number of messages that can be processed at the same time. Increase for IO-heavy tasks (network or db calls), decrease for CPU-heavy tasks.

EdgeWorker.start(handler, {
  maxConcurrent: 10 // Process up to 10 messages at once
});

maxPgConnections

Type: number Default: 4

Maximum number of concurrent database connections. Increase for IO-heavy tasks (network or database operations), decrease for CPU-heavy tasks.

EdgeWorker.start(handler, {
  maxPgConnections: 10 // Use up to 10 connections to the database
});

Polling Behavior

maxPollSeconds

Type: number Default: 5

Amount of seconds to wait for a message to be available in the queue.

Polling and Worker Health

Keep maxPollSeconds at 5 seconds or lower.

Here’s why:

• Heartbeats are sent once per main loop iteration
• Each iteration can take up to maxPollSeconds to complete
• Workers are considered inactive after 6 seconds without a heartbeat
• Therefore, maxPollSeconds must be lower than 5 seconds to account for any additional delays

EdgeWorker.start(handler, {
  maxPollSeconds: 5 // Long-poll for 5 seconds waiting for a message
});

pollIntervalMs

Type: number Default: 200

The interval (in milliseconds) between database polling attempts by pgmq.read_with_poll. The default value is suitable for most use cases.

Polling Intervals

Keep pollIntervalMs lower than maxPollSeconds * 1000.

Here’s why:

• The worker polls the database every pollIntervalMs milliseconds
• This polling continues until maxPollSeconds is reached
• If pollIntervalMs is too high, the worker might exit after just one poll
• For example: with maxPollSeconds: 5 and pollIntervalMs: 6000, only one poll would occur

EdgeWorker.start(handler, {
  pollIntervalMs: 300 // Poll every 300ms
});

Retries

retryDelay

Type: number Default: 5

Amount of seconds to wait between retry attempts.

EdgeWorker.start(handler, {
  retryDelay: 5 // Wait 5 seconds between retries
});

retryLimit

Type: number Default: 5

Maximum number of retry attempts for failed message processing before marking the message as dead.

Set to 0 to disable retries.

EdgeWorker.start(handler, {
  retryLimit: 0 // retries are disabled
});