navidrome/plugins/capabilities/taskworker.yaml

version: v1-draft
exports:
    nd_task_execute:
        description: |-
            OnTaskExecute is called when a queued task is ready to run.
            The returned string is a status/result message stored in the tasks table.
            Return an error to trigger retry (if retries are configured).
        input:
            $ref: '#/components/schemas/TaskExecuteRequest'
            contentType: application/json
        output:
            type: string
            contentType: application/json
components:
    schemas:
        TaskExecuteRequest:
            description: TaskExecuteRequest is the request provided when a task is ready to execute.
            properties:
                queueName:
                    type: string
                    description: QueueName is the name of the queue this task belongs to.
                taskId:
                    type: string
                    description: TaskID is the unique identifier for this task.
                payload:
                    type: string
                    format: byte
                    description: Payload is the opaque data provided when the task was enqueued.
                attempt:
                    type: integer
                    format: int32
                    description: 'Attempt is the current attempt number (1-based: first attempt = 1).'
            required:
                - queueName
                - taskId
                - payload
                - attempt
feat(plugins): add TaskQueue host service for persistent background task queues (#5116) * feat(plugins): define TaskQueue host service interface Add the TaskQueueService interface with CreateQueue, Enqueue, GetTaskStatus, and CancelTask methods plus QueueConfig struct. * feat(plugins): define TaskWorker capability for task execution callbacks * feat(plugins): add taskqueue permission to manifest schema Add TaskQueuePermission with maxConcurrency option. * feat(plugins): implement TaskQueue service with SQLite persistence and workers Per-plugin SQLite database with queues and tasks tables. Worker goroutines dequeue tasks and invoke nd_task_execute callback. Exponential backoff retries, rate limiting via delayMs, automatic cleanup of terminal tasks. * feat(plugins): require TaskWorker capability for taskqueue permission * feat(plugins): register TaskQueue host service in manager * feat(plugins): add test-taskqueue plugin for integration testing * feat(plugins): add integration tests for TaskQueue host service * docs: document TaskQueue module for persistent task queues Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): harden TaskQueue host service with validation and safety improvements Add input validation (queue name length, payload size limits), extract status string constants to eliminate raw SQL literals, make CreateQueue idempotent via upsert for crash recovery, fix RetentionMs default check for negative values, cap exponential backoff at 1 hour to prevent overflow, and replace manual mutex-based delay enforcement with rate.Limiter from golang.org/x/time/rate for correct concurrent worker serialization. * refactor(plugins): remove capability check for TaskWorker in TaskQueue host service Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): use context-aware database execution in TaskQueue host service Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): streamline task queue configuration and error handling Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): increase maxConcurrency for task queue and handle budget exhaustion Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): simplify goroutine management in task queue service Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): update TaskWorker interface to return status messages and refactor task queue service Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add ClearQueue function to remove pending tasks from a specified queue Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): use migrateDB for task queue schema and fix constant name collision Replaced the raw db.Exec call in createTaskQueueSchema with migrateDB, matching the pattern used by createKVStoreSchema. This enables version-tracked schema migrations via SQLite's PRAGMA user_version, allowing future schema changes to be appended incrementally. Also renamed cleanupInterval to taskCleanupInterval to resolve a redeclaration conflict with host_kvstore.go. * regenerate PDKs Signed-off-by: Deluan <deluan@navidrome.org> --------- Signed-off-by: Deluan <deluan@navidrome.org> 2026-03-03 13:48:49 -05:00			`version: v1-draft`
			`exports:`
			`nd_task_execute:`
			`description: \|-`
			`OnTaskExecute is called when a queued task is ready to run.`
			`The returned string is a status/result message stored in the tasks table.`
			`Return an error to trigger retry (if retries are configured).`
			`input:`
			`$ref: '#/components/schemas/TaskExecuteRequest'`
			`contentType: application/json`
			`output:`
			`type: string`
			`contentType: application/json`
			`components:`
			`schemas:`
			`TaskExecuteRequest:`
			`description: TaskExecuteRequest is the request provided when a task is ready to execute.`
			`properties:`
			`queueName:`
			`type: string`
			`description: QueueName is the name of the queue this task belongs to.`
			`taskId:`
			`type: string`
			`description: TaskID is the unique identifier for this task.`
			`payload:`
fix(plugins): update payload type to string with byte format for task data Signed-off-by: Deluan <deluan@navidrome.org> 2026-03-03 13:54:43 -05:00			`type: string`
			`format: byte`
feat(plugins): add TaskQueue host service for persistent background task queues (#5116) * feat(plugins): define TaskQueue host service interface Add the TaskQueueService interface with CreateQueue, Enqueue, GetTaskStatus, and CancelTask methods plus QueueConfig struct. * feat(plugins): define TaskWorker capability for task execution callbacks * feat(plugins): add taskqueue permission to manifest schema Add TaskQueuePermission with maxConcurrency option. * feat(plugins): implement TaskQueue service with SQLite persistence and workers Per-plugin SQLite database with queues and tasks tables. Worker goroutines dequeue tasks and invoke nd_task_execute callback. Exponential backoff retries, rate limiting via delayMs, automatic cleanup of terminal tasks. * feat(plugins): require TaskWorker capability for taskqueue permission * feat(plugins): register TaskQueue host service in manager * feat(plugins): add test-taskqueue plugin for integration testing * feat(plugins): add integration tests for TaskQueue host service * docs: document TaskQueue module for persistent task queues Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): harden TaskQueue host service with validation and safety improvements Add input validation (queue name length, payload size limits), extract status string constants to eliminate raw SQL literals, make CreateQueue idempotent via upsert for crash recovery, fix RetentionMs default check for negative values, cap exponential backoff at 1 hour to prevent overflow, and replace manual mutex-based delay enforcement with rate.Limiter from golang.org/x/time/rate for correct concurrent worker serialization. * refactor(plugins): remove capability check for TaskWorker in TaskQueue host service Signed-off-by: Deluan <deluan@navidrome.org> * fix(plugins): use context-aware database execution in TaskQueue host service Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): streamline task queue configuration and error handling Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): increase maxConcurrency for task queue and handle budget exhaustion Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): simplify goroutine management in task queue service Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): update TaskWorker interface to return status messages and refactor task queue service Signed-off-by: Deluan <deluan@navidrome.org> * feat(plugins): add ClearQueue function to remove pending tasks from a specified queue Signed-off-by: Deluan <deluan@navidrome.org> * refactor(plugins): use migrateDB for task queue schema and fix constant name collision Replaced the raw db.Exec call in createTaskQueueSchema with migrateDB, matching the pattern used by createKVStoreSchema. This enables version-tracked schema migrations via SQLite's PRAGMA user_version, allowing future schema changes to be appended incrementally. Also renamed cleanupInterval to taskCleanupInterval to resolve a redeclaration conflict with host_kvstore.go. * regenerate PDKs Signed-off-by: Deluan <deluan@navidrome.org> --------- Signed-off-by: Deluan <deluan@navidrome.org> 2026-03-03 13:48:49 -05:00			`description: Payload is the opaque data provided when the task was enqueued.`
			`attempt:`
			`type: integer`
			`format: int32`
			`description: 'Attempt is the current attempt number (1-based: first attempt = 1).'`
			`required:`
			`- queueName`
			`- taskId`
			`- payload`
			`- attempt`