Worker schema — System Protocol reference Background task processing system with queues, priorities, and retry logic.
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
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 integeroptional (default: 0) Items processed succeeded integeroptional (default: 0) Items succeeded failed integeroptional (default: 0) Items failed percentage number✅ Progress percentage status Enum<'pending' | 'running' | 'completed' | 'failed' | 'cancelled'>✅ Batch status startedAt stringoptional When batch started completedAt stringoptional When batch completed
Property Type Required Description name string✅ Queue name (snake_case) concurrency integeroptional (default: 5) Max concurrent task executions rateLimit { max: integer; durationMs: integer }optional Rate limit configuration defaultRetryPolicy { maxRetries?: integer; backoffStrategy?: Enum<'fixed' | 'linear' | 'exponential'>; initialDelayMs?: integer; maxDelayMs?: integer; … }optional Default retry policy for tasks deadLetterQueue stringoptional Dead letter queue name priority integeroptional (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 durationMs integer✅ Duration in milliseconds duration neveroptional [REMOVED] QueueConfig.rateLimit.duration was renamed to durationMs in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose, and TaskResult.durationMs on this same file already spelled it that way. Rename the key to durationMs; the value (milliseconds) is unchanged.
Property Type Required Description maxRetries integeroptional (default: 3) Maximum retry attempts backoffStrategy Enum<'fixed' | 'linear' | 'exponential'>optional (default: "exponential") Backoff strategy between retries initialDelayMs integeroptional (default: 1000) Initial retry delay in milliseconds maxDelayMs integeroptional (default: 60000) Maximum retry delay in milliseconds backoffMultiplier numberoptional (default: 2) Multiplier for exponential backoff
Property Type Required Description enabled booleanoptional (default: false) Enable auto-scaling minWorkers integeroptional (default: 1) Minimum workers maxWorkers integeroptional (default: 10) Maximum workers scaleUpThreshold integeroptional (default: 100) Queue size to scale up scaleDownThreshold integeroptional (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 stringoptional (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 integeroptional Task timeout in milliseconds scheduledAt stringoptional ISO 8601 datetime to execute task attempts integeroptional (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 integeroptional (default: 3) Maximum retry attempts backoffStrategy Enum<'fixed' | 'linear' | 'exponential'>optional (default: "exponential") Backoff strategy between retries initialDelayMs integeroptional (default: 1000) Initial retry delay in milliseconds maxDelayMs integeroptional (default: 60000) Maximum retry delay in milliseconds backoffMultiplier numberoptional (default: 2) Multiplier for exponential backoff
Property Type Required Description createdAt stringoptional When task was created updatedAt stringoptional Last update time createdBy stringoptional 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 anyoptional Execution result data error { message: string; stack?: string; code?: string }optional Error details if failed durationMs integeroptional Execution duration in milliseconds startedAt string✅ When execution started completedAt stringoptional 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 stringoptional Error stack trace code stringoptional Error code
criticalhighnormallowbackground
Property Type Required Description maxRetries integeroptional (default: 3) Maximum retry attempts backoffStrategy Enum<'fixed' | 'linear' | 'exponential'>optional (default: "exponential") Backoff strategy between retries initialDelayMs integeroptional (default: 1000) Initial retry delay in milliseconds maxDelayMs integeroptional (default: 60000) Maximum retry delay in milliseconds backoffMultiplier numberoptional (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 numberoptional 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