Worker
Worker protocol schemas
Worker System Protocol
Background task processing system with queues, priorities, and retry logic.
Provides a robust foundation for async task execution similar to:
- Sidekiq (Ruby)
- Celery (Python)
- Bull/BullMQ (Node.js)
- AWS SQS/Lambda
Features:
- Task queues with priorities
- Task scheduling and retry logic
- Batch processing
- Dead letter queues
- Task monitoring and logging
@example Basic task
const task: Task = {
id: 'task-123',
type: 'send_email',
payload: { to: 'user@example.com', subject: 'Welcome' },
queue: 'notifications',
priority: 5
};
Source: packages/spec/src/system/worker.zod.ts
import { BatchProgressSchema, QueueConfigSchema, TaskSchema, TaskExecutionResultSchema, TaskPriority, TaskRetryPolicySchema, TaskStatus, WorkerStatsSchema } from '@objectstack/spec/system';
import type { BatchProgress, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerStats } from '@objectstack/spec/system';
// Validate data
const result = BatchProgressSchema.parse(data);
| Property | Type | Required | Description |
|---|
| batchId | string | ✅ | Batch job identifier |
| total | integer | ✅ | Total number of items |
| processed | integer | optional (default: 0) | Items processed |
| succeeded | integer | optional (default: 0) | Items succeeded |
| failed | integer | optional (default: 0) | Items failed |
| percentage | number | ✅ | Progress percentage |
| status | Enum<'pending' | 'running' | 'completed' | 'failed' | 'cancelled'> | ✅ | Batch status |
| startedAt | string | optional | When batch started |
| completedAt | string | optional | When batch completed |
| Property | Type | Required | Description |
|---|
| name | string | ✅ | Queue name (snake_case) |
| concurrency | integer | optional (default: 5) | Max concurrent task executions |
| rateLimit | { max: integer; duration: integer } | optional | Rate limit configuration |
| defaultRetryPolicy | { maxRetries: integer; backoffStrategy: Enum<'fixed' | 'linear' | 'exponential'>; initialDelayMs: integer; maxDelayMs: integer; … } | optional | Default retry policy for tasks |
| deadLetterQueue | string | optional | Dead letter queue name |
| priority | integer | optional (default: 0) | Queue priority (lower = higher priority) |
| autoScale | { enabled: boolean; minWorkers: integer; maxWorkers: integer; scaleUpThreshold: integer; … } | optional | Auto-scaling configuration |
| Property | Type | Required | Description |
|---|
| max | integer | ✅ | Maximum tasks per duration |
| duration | integer | ✅ | Duration in milliseconds |
| Property | Type | Required | Description |
|---|
| maxRetries | integer | optional (default: 3) | Maximum retry attempts |
| backoffStrategy | Enum<'fixed' | 'linear' | 'exponential'> | optional (default: "exponential") | Backoff strategy between retries |
| initialDelayMs | integer | optional (default: 1000) | Initial retry delay in milliseconds |
| maxDelayMs | integer | optional (default: 60000) | Maximum retry delay in milliseconds |
| backoffMultiplier | number | optional (default: 2) | Multiplier for exponential backoff |
| Property | Type | Required | Description |
|---|
| enabled | boolean | optional (default: false) | Enable auto-scaling |
| minWorkers | integer | optional (default: 1) | Minimum workers |
| maxWorkers | integer | optional (default: 10) | Maximum workers |
| scaleUpThreshold | integer | optional (default: 100) | Queue size to scale up |
| scaleDownThreshold | integer | optional (default: 10) | Queue size to scale down |
| Property | Type | Required | Description |
|---|
| id | string | ✅ | Unique task identifier |
| type | string | ✅ | Task type (snake_case) |
| payload | any | ✅ | Task payload data |
| queue | string | optional (default: "default") | Queue name |
| priority | Enum<'critical' | 'high' | 'normal' | 'low' | 'background'> | optional (default: "normal") | Task priority level |
| retryPolicy | { maxRetries: integer; backoffStrategy: Enum<'fixed' | 'linear' | 'exponential'>; initialDelayMs: integer; maxDelayMs: integer; … } | optional | Retry policy configuration |
| timeoutMs | integer | optional | Task timeout in milliseconds |
| scheduledAt | string | optional | ISO 8601 datetime to execute task |
| attempts | integer | optional (default: 0) | Number of execution attempts |
| status | Enum<'pending' | 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'timeout' | 'dead'> | optional (default: "pending") | Current task status |
| metadata | { createdAt?: string; updatedAt?: string; createdBy?: string; tags?: string[] } | optional | Task metadata |
| Property | Type | Required | Description |
|---|
| maxRetries | integer | optional (default: 3) | Maximum retry attempts |
| backoffStrategy | Enum<'fixed' | 'linear' | 'exponential'> | optional (default: "exponential") | Backoff strategy between retries |
| initialDelayMs | integer | optional (default: 1000) | Initial retry delay in milliseconds |
| maxDelayMs | integer | optional (default: 60000) | Maximum retry delay in milliseconds |
| backoffMultiplier | number | optional (default: 2) | Multiplier for exponential backoff |
| Property | Type | Required | Description |
|---|
| createdAt | string | optional | When task was created |
| updatedAt | string | optional | Last update time |
| createdBy | string | optional | User who created task |
| tags | string[] | optional | Task tags for filtering |
| Property | Type | Required | Description |
|---|
| taskId | string | ✅ | Task identifier |
| status | Enum<'pending' | 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'timeout' | 'dead'> | ✅ | Execution status |
| result | any | optional | Execution result data |
| error | { message: string; stack?: string; code?: string } | optional | Error details if failed |
| durationMs | integer | optional | Execution duration in milliseconds |
| startedAt | string | ✅ | When execution started |
| completedAt | string | optional | When execution completed |
| attempt | integer | ✅ | Attempt number (1-indexed) |
| willRetry | boolean | ✅ | Whether task will be retried |
| Property | Type | Required | Description |
|---|
| message | string | ✅ | Error message |
| stack | string | optional | Error stack trace |
| code | string | optional | Error code |
criticalhighnormallowbackground
| Property | Type | Required | Description |
|---|
| maxRetries | integer | optional (default: 3) | Maximum retry attempts |
| backoffStrategy | Enum<'fixed' | 'linear' | 'exponential'> | optional (default: "exponential") | Backoff strategy between retries |
| initialDelayMs | integer | optional (default: 1000) | Initial retry delay in milliseconds |
| maxDelayMs | integer | optional (default: 60000) | Maximum retry delay in milliseconds |
| backoffMultiplier | number | optional (default: 2) | Multiplier for exponential backoff |
pendingqueuedprocessingcompletedfailedcancelledtimeoutdead
| Property | Type | Required | Description |
|---|
| workerName | string | ✅ | Worker name |
| totalProcessed | integer | ✅ | Total tasks processed |
| succeeded | integer | ✅ | Successful tasks |
| failed | integer | ✅ | Failed tasks |
| active | integer | ✅ | Currently active tasks |
| avgExecutionMs | number | optional | Average execution time in milliseconds |
| uptimeMs | integer | ✅ | Worker uptime in milliseconds |
| queues | Record<string, { pending: integer; active: integer; completed: integer; failed: integer }> | optional | Per-queue statistics |
| Property | Type | Required | Description |
|---|
| pending | integer | ✅ | Pending tasks |
| active | integer | ✅ | Active tasks |
| completed | integer | ✅ | Completed tasks |
| failed | integer | ✅ | Failed tasks |
ObjectStack