Skip to content

Add task processing streaming support #60500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DaphneMuller merged 14 commits into from
Jun 11, 2026
Merged

Add task processing streaming support #60500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
7870537
feat(task-streaming): allow the Php providers to set intermediate res…
julien-nc May 11, 2026
74d078e
fix(task-streaming): and test sending data via notify_push
julien-nc May 11, 2026
e4bea82
feat(task-streaming): add an endpoint to set a task intermediate output
julien-nc May 12, 2026
d65252b
fix(task-streaming): make the notify_push message shorter
julien-nc May 16, 2026
a6e6d92
feat(task-streaming): do not update the task in DB when setting inter…
julien-nc May 21, 2026
ddf9142
feat(task-streaming): add preferStreaming boolean attribute to taskpr…
julien-nc May 27, 2026
207f347
feat(task-streaming): add new provider interface
julien-nc May 28, 2026
b04de05
fix(task-streaming): fix psalm issues, run cs:fix, gen openapi specs
julien-nc Jun 1, 2026
8ee0281
feat(task-streaming): rename ISynchronousOptionsProvider to ISynchron…
julien-nc Jun 1, 2026
4da89e9
feat(task-streaming): send a notify_push message whenever a task stat…
julien-nc Jun 3, 2026
c7d8369
feat(task-streaming): adjust notify push messages, add sort of a name…
julien-nc Jun 5, 2026
3f4eae2
feat(task-streaming): only send notify_push status updates after we a…
julien-nc Jun 5, 2026
0bd6072
feat(task-streaming): fix tests
julien-nc Jun 5, 2026
76709d7
feat(task-streaming): address review comments
julien-nc Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions core/Controller/TaskProcessingApiController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -643,6 +643,37 @@ public function setResult(int $taskId, ?array $output = null, ?string $errorMess
}
}

/**
* Sets the task intermediate result while it is running
*
* @param int $taskId The id of the task
* @param array<string,mixed> $output The intermediate task output, files are represented by their IDs
* @return DataResponse<Http::STATUS_OK, array{task: CoreTaskProcessingTask}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NOT_FOUND, array{message: string}, array{}>
*
* 200: Result updated successfully
* 404: Task not found
*/
#[ExAppRequired]
#[ApiRoute(verb: 'POST', url: '/tasks_provider/{taskId}/stream-result', root: '/taskprocessing')]
public function setIntermediateResult(int $taskId, array $output): DataResponse {
try {
// set result
$this->taskProcessingManager->setTaskIntermediateOutput($taskId, $output);
$task = $this->taskProcessingManager->getTask($taskId);

/** @var CoreTaskProcessingTask $json */
$json = $task->jsonSerialize();

return new DataResponse([
'task' => $json,
]);
} catch (NotFoundException) {
return new DataResponse(['message' => $this->l->t('Not found')], Http::STATUS_NOT_FOUND);
} catch (Exception) {
return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
}
}

/**
* @return DataResponse<Http::STATUS_OK, array{task: CoreTaskProcessingTask}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NOT_FOUND, array{message: string}, array{}>
*/
Expand Down
51 changes: 51 additions & 0 deletions core/Migrations/Version35000Date20260527162338.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<?php

declare(strict_types=1);

/**
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/

namespace OC\Core\Migrations;

use Closure;
use OCP\DB\ISchemaWrapper;
use OCP\DB\Types;
use OCP\Migration\Attributes\AddColumn;
use OCP\Migration\Attributes\ColumnType;
use OCP\Migration\IOutput;
use OCP\Migration\SimpleMigrationStep;

/**
*
*/
#[AddColumn(table: 'taskprocessing_tasks', name: 'prefer_streaming', type: ColumnType::SMALLINT)]
class Version35000Date20260527162338 extends SimpleMigrationStep {

/**
* @param IOutput $output
* @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
* @param array $options
* @return null|ISchemaWrapper
*/
#[\Override]
public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
/** @var ISchemaWrapper $schema */
$schema = $schemaClosure();

if ($schema->hasTable('taskprocessing_tasks')) {
$table = $schema->getTable('taskprocessing_tasks');
if (!$table->hasColumn('prefer_streaming')) {
$table->addColumn('prefer_streaming', Types::SMALLINT, [
'notnull' => true,
'default' => 1,

@kyteinsky kyteinsky Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wdyt of making it 0 by default since streaming can be seen as a higher priority task than the normal requests so only the things that need the streamed response should manually activate it?

@julien-nc julien-nc Jun 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In most of the cases, we want streaming. We want to disable it only in background tasks or sub tasks. I think it's fine to keep it enabled by default. Also, the providers still return the exact same result at the end of a streaming task. Even if streaming is enabled when we don't want it, nothing gets broken. The opposite is not true, if we miss a spot where we want streaming, we just don't get a streamed output...

@kyteinsky kyteinsky Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe so but this way even calls not wanting the streamed output get it, since it's the default and the only task processing interface now.
and the streaming result makes sense most for the assistant where it can always pass stream = true anyway.
but maybe we need real world use of the api to really know the impact.

'unsigned' => true,
]);
return $schema;
}
}

return null;
}
}
1 change: 1 addition & 0 deletions core/ResponseDefinitions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@
* allowCleanup: bool,
* includeWatermark: bool,
* userFacingErrorMessage: ?string,
* preferStreaming: bool,
* }
*
* @psalm-type CoreProfileAction = array{
Expand Down
240 changes: 239 additions & 1 deletion core/openapi-ex_app.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,8 @@
"endedAt",
"allowCleanup",
"includeWatermark",
"userFacingErrorMessage"
"userFacingErrorMessage",
"preferStreaming"
],
"properties": {
"id": {
Expand Down Expand Up @@ -285,6 +286,9 @@
"userFacingErrorMessage": {
"type": "string",
"nullable": true
},
"preferStreaming": {
"type": "boolean"
}
}
},
Expand Down Expand Up @@ -2207,6 +2211,240 @@
}
}
},
"/ocs/v2.php/taskprocessing/tasks_provider/{taskId}/stream-result": {
"post": {
"operationId": "task_processing_api-set-intermediate-result",
"summary": "Sets the task intermediate result while it is running",
"description": "This endpoint requires admin access",
"tags": [
"task_processing_api"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"output"
],
"properties": {
"output": {
"type": "object",
"description": "The intermediate task output, files are represented by their IDs",
"additionalProperties": {
"type": "object"
}
}
}
}
}
}
},
"parameters": [
{
"name": "taskId",
"in": "path",
"description": "The id of the task",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"description": "Required to be true for the API request to pass",
"required": true,
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "Result updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"task"
],
"properties": {
"task": {
"$ref": "#/components/schemas/TaskProcessingTask"
}
}
}
}
}
}
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"404": {
"description": "Task not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"401": {
"description": "Current user is not logged in",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
},
"403": {
"description": "Logged in account must be an admin",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/taskprocessing/tasks_consumer/tasks/{taskId}/cancel": {
"post": {
"operationId": "task_processing_api-cancel-task-ex-app-endpoint",
Expand Down
Loading
Loading