Queue processing settings

Processing implementations supply code defaults. The new Admin UI's Processing tab can save overrides for an individual concrete queue without redeploying the application. Overrides are shared across instances and survive restarts.

Settings for each processing model

Setting	Queue job	Distributed processor
NumberOfProcessingThreads	Threads within the single active run	Not applicable
ConcurrencyPerInstance	Not applicable	Workers on every instance
LeaseSize	Not exposed as a runtime override	Messages per leased chunk
BatchSize	Batch jobs only	Batch processors only
MessageLeaseTime	Duration for future leases	Duration for future leases

Counts and lease time must be positive. A non-batch implementation cannot accept a batch-size override, and settings for the other processing model are rejected. Virtual queues have no processing settings of their own.

Distributed concurrency multiplies across queues and hosts. Four workers on each of three instances can process up to twelve chunks for one queue. Ten such named queues can have ten independent pools. Size this against the capacity of downstream systems and the database.

Choose a lease time longer than the worst expected processing time of a whole leased chunk or batch. Lease expiry can permit another worker to process the message while the original handler is still running. More workers or a larger batch does not renew existing leases automatically.

Code defaults and saved overrides

Each setting has a nullable saved override. Null uses the implementation's current code default. Clearing a field in the Processing tab restores that default; Use code defaults clears all overrides. A code change only changes an effective setting when no saved override replaces it.

Active queue jobs keep the settings captured at the start of the run; new settings apply on the next run. Distributed processors finish current work and rebuild their pools before leasing more work with changed settings. The queue does not need to become empty first. New lease times apply to future leases; existing lease expiry dates stay unchanged.

The legacy Admin UI does not expose these controls. Schedules, activation/processing delay, pause state, maximum messages per job run, retry policy, and automatic progress are separate settings, not fields in this override record.

HTTP API

Routes are relative to NexusApiOptions.BasePath:

GET  /api/queues/{queueName}/processing-settings
POST /api/queues/{queueName}/processing-settings

Reads include kind (Job or Distributed), processesBatches, defaults, overrides, effective, and pendingChanges. For distributed processors, pendingChanges indicates running instances still reporting older active settings. It is not an acknowledgement that a running queue job has adopted new values.

For example, set distributed worker count and lease time:

{
  "concurrencyPerInstance": 4,
  "messageLeaseTime": "00:10:00"
}

The POST replaces the saved override record. Omitted/null fields revert to code defaults; it is not a partial patch preserving other overrides. Include every override that should remain. Posting {} clears them all.

Application code can use the scoped IQueueMetaDataRepository:

await queueMetaDataRepository.SetProcessingSettingsAsync("order_exports",
    new QueueProcessingSettings
    {
        NumberOfProcessingThreads = 4,
        MessageLeaseTime = TimeSpan.FromMinutes(10)
    });

This example applies to a queue job. GetProcessingSettingsAsync() returns the saved overrides, not resolved code defaults. Built-in executors apply overrides automatically; custom processing loops must read and apply the relevant settings themselves. Custom metadata repositories must implement persistence if they support these controls.

Processor status and pause controls

Distributed processors appear on the queue page rather than in the jobs list. The API provides:

GET  /api/queues/{queueName}/processor
POST /api/queues/{queueName}/processor/pause
POST /api/queues/{queueName}/processor/resume
POST /api/queues/{queueName}/processor/wake

Status includes workers, in-flight messages, recent errors, and instance reports. Pause is durable across the cluster: workers finish or release current work and stop taking leases. Resume requests readiness again. Wake requests a readiness check and does not bypass pause or message eligibility. Queue jobs use job enable/disable and start controls instead.