From 6724dab9cca191a65558f0a3d14baaa6caf0e715 Mon Sep 17 00:00:00 2001 From: Roey Berman Date: Mon, 8 Dec 2025 16:44:47 -0800 Subject: [PATCH 01/21] Standalone Nexus Operations --- buf.lock | 5 - openapi/openapiv2.json | 2212 +++++++++++++---- openapi/openapiv3.yaml | 1042 +++++++- temporal/api/common/v1/message.proto | 8 + temporal/api/enums/v1/nexus.proto | 61 + temporal/api/errordetails/v1/message.proto | 8 + temporal/api/nexus/v1/message.proto | 137 + .../workflowservice/v1/request_response.proto | 208 ++ temporal/api/workflowservice/v1/service.proto | 91 + 9 files changed, 3261 insertions(+), 511 deletions(-) diff --git a/buf.lock b/buf.lock index fccbfb89d..6c4355d41 100644 --- a/buf.lock +++ b/buf.lock @@ -6,8 +6,3 @@ deps: repository: googleapis commit: 28151c0d0a1641bf938a7672c500e01d digest: shake256:49215edf8ef57f7863004539deff8834cfb2195113f0b890dd1f67815d9353e28e668019165b9d872395871eeafcbab3ccfdb2b5f11734d3cca95be9e8d139de - - remote: buf.build - owner: grpc-ecosystem - repository: grpc-gateway - commit: 048ae6ff94ca4476b3225904b1078fad - digest: shake256:e5250bf2d999516c02206d757502b902e406f35c099d0e869dc3e4f923f6870fe0805a9974c27df0695462937eae90cd4d9db90bb9a03489412560baa74a87b6 diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 2e9a6a64b..563c04614 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1095,15 +1095,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules": { + "/api/v1/namespaces/{namespace}/nexus-operation-count": { "get": { - "summary": "List all schedules in a namespace.", - "operationId": "ListSchedules2", + "summary": "CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace.", + "operationId": "CountNexusOperations2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSchedulesResponse" + "$ref": "#/definitions/v1CountNexusOperationsResponse" } }, "default": { @@ -1116,14 +1116,51 @@ "parameters": [ { "name": "namespace", - "description": "The namespace to list schedules in.", "in": "path", "required": true, "type": "string" }, { - "name": "maximumPageSize", - "description": "How many to return at once.", + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationsRequest for search attributes available for Nexus operations.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/nexus-operations": { + "get": { + "summary": "ListNexusOperations is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperations2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListNexusOperationsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of operations to return per page.", "in": "query", "required": false, "type": "integer", @@ -1131,7 +1168,7 @@ }, { "name": "nextPageToken", - "description": "Token to get the next page of results.", + "description": "Token returned in ListNexusOperationsResponse.", "in": "query", "required": false, "type": "string", @@ -1139,7 +1176,7 @@ }, { "name": "query", - "description": "Query to filter schedules.", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSearch attributes that are avaialble for Nexus operations include:\n- OperationId\n- RunId\n- Endpoint\n- Service\n- Operation\n- RequestId\n- StartTime\n- ExecutionTime\n- CloseTime\n- ExecutionStatus\n- ExecutionDuration\n- StateTransitionCount", "in": "query", "required": false, "type": "string" @@ -1150,15 +1187,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}": { + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}": { "get": { - "summary": "Returns the schedule description and current state of an existing schedule.", - "operationId": "DescribeSchedule2", + "summary": "DescribeNexusOperation returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", + "operationId": "DescribeNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeScheduleResponse" + "$ref": "#/definitions/v1DescribeNexusOperationResponse" } }, "default": { @@ -1171,31 +1208,59 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to describe.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to describe.", + "name": "operationId", "in": "path", "required": true, "type": "string" + }, + { + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the operation has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ "WorkflowService" ] }, - "delete": { - "summary": "Deletes a schedule, removing it from the system.", - "operationId": "DeleteSchedule2", + "post": { + "summary": "StartNexusOperation starts a new Nexus operation.", + "description": "Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", + "operationId": "StartNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteScheduleResponse" + "$ref": "#/definitions/v1StartNexusOperationResponse" } }, "default": { @@ -1208,38 +1273,40 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to delete.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to delete.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "identity", - "description": "The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartNexusOperationBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { "post": { - "summary": "Creates a new schedule.", - "operationId": "CreateSchedule2", + "summary": "RequestCancelNexusOperation requests cancellation of a Nexus operation.", + "description": "Requesting to cancel an operation does not automatically transition the operation to canceled status.\nThe operation will only transition to canceled status if it supports cancellation and the handler\nprocesses the cancellation request.", + "operationId": "RequestCancelNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateScheduleResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationResponse" } }, "default": { @@ -1252,14 +1319,12 @@ "parameters": [ { "name": "namespace", - "description": "The namespace the schedule should be created in.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the new schedule.", + "name": "operationId", "in": "path", "required": true, "type": "string" @@ -1269,7 +1334,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationBody" } } ], @@ -1278,15 +1343,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/matching-times": { + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/poll": { "get": { - "summary": "Lists matching times within a range.", - "operationId": "ListScheduleMatchingTimes2", + "summary": "PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", + "operationId": "PollNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListScheduleMatchingTimesResponse" + "$ref": "#/definitions/v1PollNexusOperationResponse" } }, "default": { @@ -1299,32 +1364,35 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to query.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to query.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "startTime", - "description": "Time range to query.", + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", "in": "query", "required": false, - "type": "string", - "format": "date-time" + "type": "string" }, { - "name": "endTime", + "name": "waitStage", + "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked.\n\n - NEXUS_OPERATION_WAIT_STAGE_STARTED: Wait for the operation to be started.\n - NEXUS_OPERATION_WAIT_STAGE_CLOSED: Wait for the operation to be in a terminal state, either successful or unsuccessful.", "in": "query", "required": false, "type": "string", - "format": "date-time" + "enum": [ + "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "NEXUS_OPERATION_WAIT_STAGE_STARTED", + "NEXUS_OPERATION_WAIT_STAGE_CLOSED" + ], + "default": "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED" } ], "tags": [ @@ -1332,15 +1400,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/patch": { + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/terminate": { "post": { - "summary": "Makes a specific change to a schedule or triggers an immediate action.", - "operationId": "PatchSchedule2", + "summary": "TerminateNexusOperation terminates an existing Nexus operation immediately.", + "description": "Termination happens immediately and the operation handler cannot react to it. A terminated operation will have\nits outcome set to a failure with a termination reason.", + "operationId": "TerminateNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PatchScheduleResponse" + "$ref": "#/definitions/v1TerminateNexusOperationResponse" } }, "default": { @@ -1353,14 +1422,12 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to patch.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to patch.", + "name": "operationId", "in": "path", "required": true, "type": "string" @@ -1370,7 +1437,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePatchScheduleBody" + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationBody" } } ], @@ -1379,15 +1446,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/update": { - "post": { - "summary": "Changes the configuration or state of an existing schedule.", - "operationId": "UpdateSchedule2", + "/api/v1/namespaces/{namespace}/schedules": { + "get": { + "summary": "List all schedules in a namespace.", + "operationId": "ListSchedules2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateScheduleResponse" + "$ref": "#/definitions/v1ListSchedulesResponse" } }, "default": { @@ -1400,25 +1467,33 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to update.", + "description": "The namespace to list schedules in.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to update.", - "in": "path", - "required": true, - "type": "string" + "name": "maximumPageSize", + "description": "How many to return at once.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateScheduleBody" - } + "name": "nextPageToken", + "description": "Token to get the next page of results.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Query to filter schedules.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -1426,15 +1501,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/search-attributes": { + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}": { "get": { - "summary": "ListSearchAttributes returns comprehensive information about search attributes.", - "operationId": "ListSearchAttributes2", + "summary": "Returns the schedule description and current state of an existing schedule.", + "operationId": "DescribeSchedule2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSearchAttributesResponse" + "$ref": "#/definitions/v1DescribeScheduleResponse" } }, "default": { @@ -1447,25 +1522,31 @@ "parameters": [ { "name": "namespace", + "description": "The namespace of the schedule to describe.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to describe.", "in": "path", "required": true, "type": "string" } ], "tags": [ - "OperatorService" + "WorkflowService" ] - } - }, - "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": { - "get": { - "summary": "DescribeTaskQueue returns the following information about the target task queue, broken down by Build ID:\n - List of pollers\n - Workflow Reachability status\n - Backlog info for Workflow and/or Activity tasks", - "operationId": "DescribeTaskQueue2", + }, + "delete": { + "summary": "Deletes a schedule, removing it from the system.", + "operationId": "DeleteSchedule2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeTaskQueueResponse" + "$ref": "#/definitions/v1DeleteScheduleResponse" } }, "default": { @@ -1478,49 +1559,319 @@ "parameters": [ { "name": "namespace", + "description": "The namespace of the schedule to delete.", "in": "path", "required": true, "type": "string" }, { - "name": "taskQueue.name", + "name": "scheduleId", + "description": "The id of the schedule to delete.", "in": "path", "required": true, "type": "string" }, { - "name": "taskQueue.kind", - "description": "Default: TASK_QUEUE_KIND_NORMAL.\n\n - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities.", - "in": "query", - "required": false, - "type": "string", - "enum": [ - "TASK_QUEUE_KIND_UNSPECIFIED", - "TASK_QUEUE_KIND_NORMAL", - "TASK_QUEUE_KIND_STICKY" - ], - "default": "TASK_QUEUE_KIND_UNSPECIFIED" - }, - { - "name": "taskQueue.normalName", - "description": "Iff kind == TASK_QUEUE_KIND_STICKY, then this field contains the name of\nthe normal task queue that the sticky worker is running on.", + "name": "identity", + "description": "The identity of the client who initiated this request.", "in": "query", "required": false, "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "Creates a new schedule.", + "operationId": "CreateSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CreateScheduleResponse" + } }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ { - "name": "taskQueueType", - "description": "If unspecified (TASK_QUEUE_TYPE_UNSPECIFIED), then default value (TASK_QUEUE_TYPE_WORKFLOW) will be used.\nOnly supported in default mode (use `task_queue_types` in ENHANCED mode instead).\n\n - TASK_QUEUE_TYPE_WORKFLOW: Workflow type of task queue.\n - TASK_QUEUE_TYPE_ACTIVITY: Activity type of task queue.\n - TASK_QUEUE_TYPE_NEXUS: Task queue type for dispatching Nexus requests.", - "in": "query", - "required": false, - "type": "string", - "enum": [ - "TASK_QUEUE_TYPE_UNSPECIFIED", - "TASK_QUEUE_TYPE_WORKFLOW", - "TASK_QUEUE_TYPE_ACTIVITY", - "TASK_QUEUE_TYPE_NEXUS" - ], - "default": "TASK_QUEUE_TYPE_UNSPECIFIED" + "name": "namespace", + "description": "The namespace the schedule should be created in.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the new schedule.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/matching-times": { + "get": { + "summary": "Lists matching times within a range.", + "operationId": "ListScheduleMatchingTimes2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListScheduleMatchingTimesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to query.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to query.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "startTime", + "description": "Time range to query.", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + }, + { + "name": "endTime", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/patch": { + "post": { + "summary": "Makes a specific change to a schedule or triggers an immediate action.", + "operationId": "PatchSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PatchScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to patch.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to patch.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServicePatchScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/update": { + "post": { + "summary": "Changes the configuration or state of an existing schedule.", + "operationId": "UpdateSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1UpdateScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to update.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to update.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUpdateScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/search-attributes": { + "get": { + "summary": "ListSearchAttributes returns comprehensive information about search attributes.", + "operationId": "ListSearchAttributes2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListSearchAttributesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": { + "get": { + "summary": "DescribeTaskQueue returns the following information about the target task queue, broken down by Build ID:\n - List of pollers\n - Workflow Reachability status\n - Backlog info for Workflow and/or Activity tasks", + "operationId": "DescribeTaskQueue2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeTaskQueueResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "taskQueue.name", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "taskQueue.kind", + "description": "Default: TASK_QUEUE_KIND_NORMAL.\n\n - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "TASK_QUEUE_KIND_UNSPECIFIED", + "TASK_QUEUE_KIND_NORMAL", + "TASK_QUEUE_KIND_STICKY" + ], + "default": "TASK_QUEUE_KIND_UNSPECIFIED" + }, + { + "name": "taskQueue.normalName", + "description": "Iff kind == TASK_QUEUE_KIND_STICKY, then this field contains the name of\nthe normal task queue that the sticky worker is running on.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "taskQueueType", + "description": "If unspecified (TASK_QUEUE_TYPE_UNSPECIFIED), then default value (TASK_QUEUE_TYPE_WORKFLOW) will be used.\nOnly supported in default mode (use `task_queue_types` in ENHANCED mode instead).\n\n - TASK_QUEUE_TYPE_WORKFLOW: Workflow type of task queue.\n - TASK_QUEUE_TYPE_ACTIVITY: Activity type of task queue.\n - TASK_QUEUE_TYPE_NEXUS: Task queue type for dispatching Nexus requests.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "TASK_QUEUE_TYPE_UNSPECIFIED", + "TASK_QUEUE_TYPE_WORKFLOW", + "TASK_QUEUE_TYPE_ACTIVITY", + "TASK_QUEUE_TYPE_NEXUS" + ], + "default": "TASK_QUEUE_TYPE_UNSPECIFIED" }, { "name": "reportStats", @@ -3650,21 +4001,190 @@ "$ref": "#/definitions/rpcStatus" } } - }, + }, + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster": { + "get": { + "summary": "GetClusterInfo returns information about temporal cluster", + "operationId": "GetClusterInfo", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetClusterInfoResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster/namespaces": { + "get": { + "summary": "ListNamespaces returns the information and configuration for all namespaces.", + "operationId": "ListNamespaces", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListNamespacesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "namespaceFilter.includeDeleted", + "description": "By default namespaces in NAMESPACE_STATE_DELETED state are not included.\nSetting include_deleted to true will include deleted namespaces.\nNote: Namespace is in NAMESPACE_STATE_DELETED state when it was deleted from the system but associated data is not deleted yet.", + "in": "query", + "required": false, + "type": "boolean" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "RegisterNamespace creates a new namespace which can be used as a container for all resources.", + "description": "A Namespace is a top level entity within Temporal, and is used as a container for resources\nlike workflow executions, task queues, etc. A Namespace acts as a sandbox and provides\nisolation for all resources within the namespace. All resources belongs to exactly one\nnamespace.", + "operationId": "RegisterNamespace", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1RegisterNamespaceResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/v1RegisterNamespaceRequest" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster/namespaces/{namespace}": { + "get": { + "summary": "DescribeNamespace returns the information and configuration for a registered namespace.", + "operationId": "DescribeNamespace", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeNamespaceResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "id", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster/namespaces/{namespace}/search-attributes": { + "get": { + "summary": "ListSearchAttributes returns comprehensive information about search attributes.", + "operationId": "ListSearchAttributes", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListSearchAttributesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + } + ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster": { - "get": { - "summary": "GetClusterInfo returns information about temporal cluster", - "operationId": "GetClusterInfo", + "/cluster/namespaces/{namespace}/update": { + "post": { + "summary": "UpdateNamespace is used to update the information and configuration of a registered\nnamespace.", + "operationId": "UpdateNamespace", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetClusterInfoResponse" + "$ref": "#/definitions/v1UpdateNamespaceResponse" } }, "default": { @@ -3674,20 +4194,36 @@ } } }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" + } + } + ], "tags": [ "WorkflowService" ] } }, - "/cluster/namespaces": { + "/cluster/nexus/endpoints": { "get": { - "summary": "ListNamespaces returns the information and configuration for all namespaces.", - "operationId": "ListNamespaces", + "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", + "operationId": "ListNexusEndpoints", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNamespacesResponse" + "$ref": "#/definitions/v1ListNexusEndpointsResponse" } }, "default": { @@ -3707,32 +4243,32 @@ }, { "name": "nextPageToken", + "description": "To get the next page, pass in `ListNexusEndpointsResponse.next_page_token` from the previous page's\nresponse, the token will be empty if there's no other page.\nNote: the last page may be empty if the total number of endpoints registered is a multiple of the page size.", "in": "query", "required": false, "type": "string", "format": "byte" }, { - "name": "namespaceFilter.includeDeleted", - "description": "By default namespaces in NAMESPACE_STATE_DELETED state are not included.\nSetting include_deleted to true will include deleted namespaces.\nNote: Namespace is in NAMESPACE_STATE_DELETED state when it was deleted from the system but associated data is not deleted yet.", + "name": "name", + "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", "in": "query", "required": false, - "type": "boolean" + "type": "string" } ], "tags": [ - "WorkflowService" + "OperatorService" ] }, "post": { - "summary": "RegisterNamespace creates a new namespace which can be used as a container for all resources.", - "description": "A Namespace is a top level entity within Temporal, and is used as a container for resources\nlike workflow executions, task queues, etc. A Namespace acts as a sandbox and provides\nisolation for all resources within the namespace. All resources belongs to exactly one\nnamespace.", - "operationId": "RegisterNamespace", + "summary": "Create a Nexus endpoint. This will fail if an endpoint with the same name is already registered with a status of\nALREADY_EXISTS.\nReturns the created endpoint with its initial version. You may use this version for subsequent updates.", + "operationId": "CreateNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RegisterNamespaceResponse" + "$ref": "#/definitions/v1CreateNexusEndpointResponse" } }, "default": { @@ -3748,24 +4284,24 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/v1RegisterNamespaceRequest" + "$ref": "#/definitions/v1CreateNexusEndpointRequest" } } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster/namespaces/{namespace}": { + "/cluster/nexus/endpoints/{id}": { "get": { - "summary": "DescribeNamespace returns the information and configuration for a registered namespace.", - "operationId": "DescribeNamespace", + "summary": "Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.", + "operationId": "GetNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeNamespaceResponse" + "$ref": "#/definitions/v1GetNexusEndpointResponse" } }, "default": { @@ -3777,32 +4313,65 @@ }, "parameters": [ { - "name": "namespace", + "name": "id", + "description": "Server-generated unique endpoint ID.", "in": "path", "required": true, "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + }, + "delete": { + "summary": "Delete an incoming Nexus service by ID.", + "operationId": "DeleteNexusEndpoint", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DeleteNexusEndpointResponse" + } }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ { "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "version", + "description": "Data version for this endpoint. Must match current version.", "in": "query", "required": false, - "type": "string" + "type": "string", + "format": "int64" } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster/namespaces/{namespace}/search-attributes": { - "get": { - "summary": "ListSearchAttributes returns comprehensive information about search attributes.", - "operationId": "ListSearchAttributes", + "/cluster/nexus/endpoints/{id}/update": { + "post": { + "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", + "operationId": "UpdateNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSearchAttributesResponse" + "$ref": "#/definitions/v1UpdateNexusEndpointResponse" } }, "default": { @@ -3814,10 +4383,19 @@ }, "parameters": [ { - "name": "namespace", + "name": "id", + "description": "Server-generated unique endpoint ID.", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + } } ], "tags": [ @@ -3825,15 +4403,16 @@ ] } }, - "/cluster/namespaces/{namespace}/update": { + "/namespaces/{namespace}/activities/cancel": { "post": { - "summary": "UpdateNamespace is used to update the information and configuration of a registered\nnamespace.", - "operationId": "UpdateNamespace", + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCanceled", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNamespaceResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" } }, "default": { @@ -3855,7 +4434,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" } } ], @@ -3864,15 +4443,15 @@ ] } }, - "/cluster/nexus/endpoints": { - "get": { - "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", - "operationId": "ListNexusEndpoints", + "/namespaces/{namespace}/activities/cancel-by-id": { + "post": { + "summary": "See `RecordActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCanceledById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNexusEndpointsResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" } }, "default": { @@ -3884,40 +4463,75 @@ }, "parameters": [ { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", - "description": "To get the next page, pass in `ListNexusEndpointsResponse.next_page_token` from the previous page's\nresponse, the token will be empty if there's no other page.\nNote: the last page may be empty if the total number of endpoints registered is a multiple of the page size.", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/activities/complete": { + "post": { + "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", + "description": "This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCompleted", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + } }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ { - "name": "name", - "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", - "in": "query", - "required": false, + "name": "namespace", + "in": "path", + "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, + } + }, + "/namespaces/{namespace}/activities/complete-by-id": { "post": { - "summary": "Create a Nexus endpoint. This will fail if an endpoint with the same name is already registered with a status of\nALREADY_EXISTS.\nReturns the created endpoint with its initial version. You may use this version for subsequent updates.", - "operationId": "CreateNexusEndpoint", + "summary": "See `RecordActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCompletedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" } }, "default": { @@ -3928,29 +4542,37 @@ } }, "parameters": [ + { + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointRequest" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/nexus/endpoints/{id}": { - "get": { - "summary": "Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.", - "operationId": "GetNexusEndpoint", + "/namespaces/{namespace}/activities/fail": { + "post": { + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskFailed", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" } }, "default": { @@ -3962,25 +4584,34 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, - "delete": { - "summary": "Delete an incoming Nexus service by ID.", - "operationId": "DeleteNexusEndpoint", + } + }, + "/namespaces/{namespace}/activities/fail-by-id": { + "post": { + "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskFailedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" } }, "default": { @@ -3992,35 +4623,36 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "version", - "description": "Data version for this endpoint. Must match current version.", - "in": "query", - "required": false, - "type": "string", - "format": "int64" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/nexus/endpoints/{id}/update": { + "/namespaces/{namespace}/activities/heartbeat": { "post": { - "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", - "operationId": "UpdateNexusEndpoint", + "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", + "description": "If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to\nthe workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in\nsuch situations, in that event, the SDK should request cancellation of the activity.", + "operationId": "RecordActivityTaskHeartbeat", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNexusEndpointResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" } }, "default": { @@ -4032,8 +4664,7 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "in": "path", "required": true, "type": "string" @@ -4043,25 +4674,24 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/namespaces/{namespace}/activities/cancel": { + "/namespaces/{namespace}/activities/heartbeat-by-id": { "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCanceled", + "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RecordActivityTaskHeartbeatById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" } }, "default": { @@ -4074,6 +4704,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -4083,7 +4714,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" } } ], @@ -4092,15 +4723,16 @@ ] } }, - "/namespaces/{namespace}/activities/cancel-by-id": { + "/namespaces/{namespace}/activities/pause": { "post": { - "summary": "See `RecordActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCanceledById", + "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", + "operationId": "PauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" + "$ref": "#/definitions/v1PauseActivityResponse" } }, "default": { @@ -4113,7 +4745,7 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4123,7 +4755,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" + "$ref": "#/definitions/WorkflowServicePauseActivityBody" } } ], @@ -4132,16 +4764,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete": { + "/namespaces/{namespace}/activities/reset": { "post": { - "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", - "description": "This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCompleted", + "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", + "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.", + "operationId": "ResetActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + "$ref": "#/definitions/v1ResetActivityResponse" } }, "default": { @@ -4154,6 +4786,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4163,7 +4796,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" + "$ref": "#/definitions/WorkflowServiceResetActivityBody" } } ], @@ -4172,15 +4805,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete-by-id": { + "/namespaces/{namespace}/activities/unpause": { "post": { - "summary": "See `RecordActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById", + "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", + "operationId": "UnpauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1UnpauseActivityResponse" } }, "default": { @@ -4193,7 +4827,7 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4203,7 +4837,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" } } ], @@ -4212,16 +4846,15 @@ ] } }, - "/namespaces/{namespace}/activities/fail": { + "/namespaces/{namespace}/activities/update-options": { "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskFailed", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.", + "operationId": "UpdateActivityOptions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" + "$ref": "#/definitions/v1UpdateActivityOptionsResponse" } }, "default": { @@ -4234,6 +4867,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -4243,7 +4877,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" } } ], @@ -4252,15 +4886,15 @@ ] } }, - "/namespaces/{namespace}/activities/fail-by-id": { - "post": { - "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskFailedById", + "/namespaces/{namespace}/archived-workflows": { + "get": { + "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", + "operationId": "ListArchivedWorkflowExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" } }, "default": { @@ -4273,18 +4907,29 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" - } + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -4292,16 +4937,15 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat": { - "post": { - "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", - "description": "If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to\nthe workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in\nsuch situations, in that event, the SDK should request cancellation of the activity.", - "operationId": "RecordActivityTaskHeartbeat", + "/namespaces/{namespace}/batch-operations": { + "get": { + "summary": "ListBatchOperations returns a list of batch operations", + "operationId": "ListBatchOperations", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" + "$ref": "#/definitions/v1ListBatchOperationsResponse" } }, "default": { @@ -4314,17 +4958,26 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" - } + "name": "pageSize", + "description": "List page size", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Next page token", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ @@ -4332,15 +4985,15 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat-by-id": { - "post": { - "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RecordActivityTaskHeartbeatById", + "/namespaces/{namespace}/batch-operations/{jobId}": { + "get": { + "summary": "DescribeBatchOperation returns the information about a batch operation", + "operationId": "DescribeBatchOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1DescribeBatchOperationResponse" } }, "default": { @@ -4353,35 +5006,31 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "jobId", + "description": "Batch job id", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" - } + "type": "string" } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/activities/pause": { + }, "post": { - "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", - "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", - "operationId": "PauseActivity", + "summary": "StartBatchOperation starts a new batch operation", + "operationId": "StartBatchOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PauseActivityResponse" + "$ref": "#/definitions/v1StartBatchOperationResponse" } }, "default": { @@ -4394,7 +5043,14 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Job ID defines the unique ID for the batch job", "in": "path", "required": true, "type": "string" @@ -4404,7 +5060,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" } } ], @@ -4413,16 +5069,15 @@ ] } }, - "/namespaces/{namespace}/activities/reset": { + "/namespaces/{namespace}/batch-operations/{jobId}/stop": { "post": { - "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", - "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.", - "operationId": "ResetActivity", + "summary": "StopBatchOperation stops a batch operation", + "operationId": "StopBatchOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ResetActivityResponse" + "$ref": "#/definitions/v1StopBatchOperationResponse" } }, "default": { @@ -4435,7 +5090,14 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Batch job id", "in": "path", "required": true, "type": "string" @@ -4445,7 +5107,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" } } ], @@ -4454,16 +5116,15 @@ ] } }, - "/namespaces/{namespace}/activities/unpause": { + "/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { "post": { - "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", - "operationId": "UnpauseActivity", + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", + "operationId": "SetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UnpauseActivityResponse" + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" } }, "default": { @@ -4476,7 +5137,13 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" @@ -4486,7 +5153,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" } } ], @@ -4495,15 +5162,15 @@ ] } }, - "/namespaces/{namespace}/activities/update-options": { - "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.", - "operationId": "UpdateActivityOptions", + "/namespaces/{namespace}/current-deployment/{seriesName}": { + "get": { + "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `current_version` returned by `DescribeWorkerDeployment`.", + "operationId": "GetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsResponse" + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" } }, "default": { @@ -4516,18 +5183,15 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "seriesName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" - } + "type": "string" } ], "tags": [ @@ -4535,15 +5199,15 @@ ] } }, - "/namespaces/{namespace}/archived-workflows": { + "/namespaces/{namespace}/deployments": { "get": { - "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", - "operationId": "ListArchivedWorkflowExecutions", + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `ListWorkerDeployments`.", + "operationId": "ListDeployments", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + "$ref": "#/definitions/v1ListDeploymentsResponse" } }, "default": { @@ -4575,7 +5239,8 @@ "format": "byte" }, { - "name": "query", + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", "in": "query", "required": false, "type": "string" @@ -4586,15 +5251,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations": { + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { - "summary": "ListBatchOperations returns a list of batch operations", - "operationId": "ListBatchOperations", + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", + "operationId": "DescribeDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListBatchOperationsResponse" + "$ref": "#/definitions/v1DescribeDeploymentResponse" } }, "default": { @@ -4607,26 +5272,23 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "pageSize", - "description": "List page size", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", - "description": "Next page token", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", + "required": true, + "type": "string" } ], "tags": [ @@ -4634,15 +5296,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}": { + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { "get": { - "summary": "DescribeBatchOperation returns the information about a batch operation", - "operationId": "DescribeBatchOperation", + "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DrainageInfo` returned by `DescribeWorkerDeploymentVersion`.", + "operationId": "GetDeploymentReachability", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeBatchOperationResponse" + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" } }, "default": { @@ -4655,14 +5317,20 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", "in": "path", "required": true, "type": "string" @@ -4671,15 +5339,17 @@ "tags": [ "WorkflowService" ] - }, - "post": { - "summary": "StartBatchOperation starts a new batch operation", - "operationId": "StartBatchOperation", + } + }, + "/namespaces/{namespace}/nexus-operation-count": { + "get": { + "summary": "CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace.", + "operationId": "CountNexusOperations", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartBatchOperationResponse" + "$ref": "#/definitions/v1CountNexusOperationsResponse" } }, "default": { @@ -4692,25 +5362,16 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Job ID defines the unique ID for the batch job", - "in": "path", - "required": true, + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationsRequest for search attributes available for Nexus operations.", + "in": "query", + "required": false, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" - } } ], "tags": [ @@ -4718,15 +5379,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}/stop": { - "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation", + "/namespaces/{namespace}/nexus-operations": { + "get": { + "summary": "ListNexusOperations is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperations", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1ListNexusOperationsResponse" } }, "default": { @@ -4739,25 +5400,32 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", - "in": "path", - "required": true, - "type": "string" + "name": "pageSize", + "description": "Max number of operations to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" - } + "name": "nextPageToken", + "description": "Token returned in ListNexusOperationsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSearch attributes that are avaialble for Nexus operations include:\n- OperationId\n- RunId\n- Endpoint\n- Service\n- Operation\n- RequestId\n- StartTime\n- ExecutionTime\n- CloseTime\n- ExecutionStatus\n- ExecutionDuration\n- StateTransitionCount", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -4765,15 +5433,15 @@ ] } }, - "/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { - "post": { - "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", - "operationId": "SetCurrentDeployment", + "/namespaces/{namespace}/nexus-operations/{operationId}": { + "get": { + "summary": "DescribeNexusOperation returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", + "operationId": "DescribeNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetCurrentDeploymentResponse" + "$ref": "#/definitions/v1DescribeNexusOperationResponse" } }, "default": { @@ -4791,35 +5459,54 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" - } + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the operation has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/current-deployment/{seriesName}": { - "get": { - "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `current_version` returned by `DescribeWorkerDeployment`.", - "operationId": "GetCurrentDeployment", + }, + "post": { + "summary": "StartNexusOperation starts a new Nexus operation.", + "description": "Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", + "operationId": "StartNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetCurrentDeploymentResponse" + "$ref": "#/definitions/v1StartNexusOperationResponse" } }, "default": { @@ -4837,10 +5524,18 @@ "type": "string" }, { - "name": "seriesName", + "name": "operationId", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartNexusOperationBody" + } } ], "tags": [ @@ -4848,15 +5543,16 @@ ] } }, - "/namespaces/{namespace}/deployments": { - "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `ListWorkerDeployments`.", - "operationId": "ListDeployments", + "/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { + "post": { + "summary": "RequestCancelNexusOperation requests cancellation of a Nexus operation.", + "description": "Requesting to cancel an operation does not automatically transition the operation to canceled status.\nThe operation will only transition to canceled status if it supports cancellation and the handler\nprocesses the cancellation request.", + "operationId": "RequestCancelNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListDeploymentsResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationResponse" } }, "default": { @@ -4874,25 +5570,18 @@ "type": "string" }, { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" - }, - { - "name": "nextPageToken", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "operationId", + "in": "path", + "required": true, + "type": "string" }, { - "name": "seriesName", - "description": "Optional. Use to filter based on exact series name match.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationBody" + } } ], "tags": [ @@ -4900,15 +5589,15 @@ ] } }, - "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "/namespaces/{namespace}/nexus-operations/{operationId}/poll": { "get": { - "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", - "operationId": "DescribeDeployment", + "summary": "PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", + "operationId": "PollNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeDeploymentResponse" + "$ref": "#/definitions/v1PollNexusOperationResponse" } }, "default": { @@ -4926,18 +5615,30 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", - "in": "path", - "required": true, + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, "type": "string" + }, + { + "name": "waitStage", + "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked.\n\n - NEXUS_OPERATION_WAIT_STAGE_STARTED: Wait for the operation to be started.\n - NEXUS_OPERATION_WAIT_STAGE_CLOSED: Wait for the operation to be in a terminal state, either successful or unsuccessful.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "NEXUS_OPERATION_WAIT_STAGE_STARTED", + "NEXUS_OPERATION_WAIT_STAGE_CLOSED" + ], + "default": "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED" } ], "tags": [ @@ -4945,15 +5646,16 @@ ] } }, - "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { - "get": { - "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DrainageInfo` returned by `DescribeWorkerDeploymentVersion`.", - "operationId": "GetDeploymentReachability", + "/namespaces/{namespace}/nexus-operations/{operationId}/terminate": { + "post": { + "summary": "TerminateNexusOperation terminates an existing Nexus operation immediately.", + "description": "Termination happens immediately and the operation handler cannot react to it. A terminated operation will have\nits outcome set to a failure with a termination reason.", + "operationId": "TerminateNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + "$ref": "#/definitions/v1TerminateNexusOperationResponse" } }, "default": { @@ -4971,18 +5673,18 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "name": "operationId", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationBody" + } } ], "tags": [ @@ -7428,22 +8130,6 @@ } } }, - "CountWorkflowExecutionsResponseAggregationGroup": { - "type": "object", - "properties": { - "groupValues": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1Payload" - } - }, - "count": { - "type": "string", - "format": "int64" - } - } - }, "DeploymentInfoTaskQueueInfo": { "type": "object", "properties": { @@ -7542,6 +8228,21 @@ }, "description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job." }, + "LinkNexusOperation": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "operationId": { + "type": "string" + }, + "runId": { + "type": "string" + } + }, + "description": "A link to a standalone Nexus operation." + }, "LinkWorkflowEvent": { "type": "object", "properties": { @@ -8270,6 +8971,27 @@ } } }, + "WorkflowServiceRequestCancelNexusOperationBody": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "Operation run ID, targets the latest run if empty." + }, + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe cancellation requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API." + } + } + }, "WorkflowServiceRequestCancelWorkflowExecutionBody": { "type": "object", "properties": { @@ -8880,6 +9602,62 @@ } } }, + "WorkflowServiceStartNexusOperationBody": { + "type": "object", + "properties": { + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "A unique identifier for this start request. Typically UUIDv4." + }, + "endpoint": { + "type": "string", + "description": "Endpoint name, resolved to a URL via the cluster's endpoint registry." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this operation.\nThis is the only timeout settable for a Nexus operation." + }, + "input": { + "$ref": "#/definitions/v1Payload", + "description": "Serialized input to the operation. Passed as the request payload." + }, + "idReusePolicy": { + "$ref": "#/definitions/v1NexusOperationIdReusePolicy", + "description": "Defines whether to allow re-using the operation id from a previously *closed* operation.\nThe default policy is NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE." + }, + "idConflictPolicy": { + "$ref": "#/definitions/v1NexusOperationIdConflictPolicy", + "description": "Defines how to resolve an operation id conflict with a *running* operation.\nThe default policy is NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes for indexing." + }, + "nexusHeader": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Header to attach to the Nexus request.\nUsers are responsible for encrypting sensitive data in this header as it is stored in workflow history and\ntransmitted to external services as-is.\nThis is useful for propagating tracing information.\nNote these headers are not the same as Temporal headers on internal activities and child workflows, these are\ntransmitted to Nexus operations that may be external and are not traditional payloads." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation." + } + } + }, "WorkflowServiceStartWorkflowExecutionBody": { "type": "object", "properties": { @@ -9004,6 +9782,27 @@ } } }, + "WorkflowServiceTerminateNexusOperationBody": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "Operation run ID, targets the latest run if empty." + }, + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe termination requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the termination, recorded in the operation's result failure outcome." + } + } + }, "WorkflowServiceTerminateWorkflowExecutionBody": { "type": "object", "properties": { @@ -9385,6 +10184,9 @@ }, "batchJob": { "$ref": "#/definitions/LinkBatchJob" + }, + "nexusOperation": { + "$ref": "#/definitions/LinkNexusOperation" } }, "description": "Link can be associated with history events. It might contain information about an external entity\nrelated to the history event. For example, workflow A makes a Nexus call that starts workflow B:\nin this case, a history event in workflow A could contain a Link to the workflow started event in\nworkflow B, and vice-versa." @@ -9473,6 +10275,47 @@ } } }, + "apinexusv1NexusOperationCancellationInfo": { + "type": "object", + "properties": { + "requestedTime": { + "type": "string", + "format": "date-time", + "description": "The time when cancellation was requested." + }, + "state": { + "$ref": "#/definitions/v1NexusOperationCancellationState" + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + }, + "reason": { + "type": "string", + "description": "A reason that may be specified in the CancelNexusOpertionRequest." + } + }, + "description": "NexusOperationCancellationInfo contains the state of a Nexus operation cancellation." + }, "apinexusv1Request": { "type": "object", "properties": { @@ -9525,6 +10368,43 @@ }, "description": "The client request that triggers a Workflow Update." }, + "apiworkflowv1NexusOperationCancellationInfo": { + "type": "object", + "properties": { + "requestedTime": { + "type": "string", + "format": "date-time", + "description": "The time when cancellation was requested." + }, + "state": { + "$ref": "#/definitions/v1NexusOperationCancellationState" + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + } + }, + "description": "NexusOperationCancellationInfo contains the state of a nexus operation cancellation." + }, "protobufAny": { "type": "object", "properties": { @@ -10878,6 +11758,40 @@ } } }, + "v1CountNexusOperationsResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "int64", + "description": "If `query` is not grouping by any field, the count is an approximate number\nof operations that match the query.\nIf `query` is grouping by a field, the count is simply the sum of the counts\nof the groups returned in the response. This number can be smaller than the\ntotal number of operations matching the query." + }, + "groups": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CountNexusOperationsResponseAggregationGroup" + }, + "description": "Contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." + } + } + }, + "v1CountNexusOperationsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CountWorkflowExecutionsResponse": { "type": "object", "properties": { @@ -10890,12 +11804,28 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/CountWorkflowExecutionsResponseAggregationGroup" + "$ref": "#/definitions/v1CountWorkflowExecutionsResponseAggregationGroup" }, "description": "`groups` contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." } } }, + "v1CountWorkflowExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CreateNexusEndpointRequest": { "type": "object", "properties": { @@ -11151,16 +12081,46 @@ "type": "string", "format": "int64" }, - "isGlobalNamespace": { - "type": "boolean" + "isGlobalNamespace": { + "type": "boolean" + }, + "failoverHistory": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1FailoverStatus" + }, + "description": "Contains the historical state of failover_versions for the cluster, truncated to contain only the last N\nstates to ensure that the list does not grow unbounded." + } + } + }, + "v1DescribeNexusOperationResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the operation, useful when run_id was not specified in the request." + }, + "info": { + "$ref": "#/definitions/v1NexusOperationInfo", + "description": "Information about the operation." + }, + "input": { + "$ref": "#/definitions/v1Payload", + "description": "Serialized operation input, passed as the request payload.\nOnly set if include_input was true in the request." + }, + "result": { + "$ref": "#/definitions/v1Payload", + "description": "The result if the operation completed successfully." }, - "failoverHistory": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1FailoverStatus" - }, - "description": "Contains the historical state of failover_versions for the cluster, truncated to contain only the last N\nstates to ensure that the list does not grow unbounded." + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The failure if the operation completed unsuccessfully." + }, + "longPollToken": { + "type": "string", + "format": "byte", + "description": "Token for follow-on long-poll requests. Absent only if the operation is complete." } } }, @@ -12259,6 +13219,23 @@ } } }, + "v1ListNexusOperationsResponse": { + "type": "object", + "properties": { + "operations": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1NexusOperationListInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte", + "description": "Token to use to fetch the next page. If empty, there is no next page." + } + } + }, "v1ListOpenWorkflowExecutionsResponse": { "type": "object", "properties": { @@ -12816,43 +13793,6 @@ }, "description": "Nexus operation completed as canceled. May or may not have been due to a cancellation request by the workflow." }, - "v1NexusOperationCancellationInfo": { - "type": "object", - "properties": { - "requestedTime": { - "type": "string", - "format": "date-time", - "description": "The time when cancellation was requested." - }, - "state": { - "$ref": "#/definitions/v1NexusOperationCancellationState" - }, - "attempt": { - "type": "integer", - "format": "int32", - "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." - }, - "lastAttemptCompleteTime": { - "type": "string", - "format": "date-time", - "description": "The time when the last attempt completed." - }, - "lastAttemptFailure": { - "$ref": "#/definitions/apifailurev1Failure", - "description": "The last attempt's failure, if any." - }, - "nextAttemptScheduleTime": { - "type": "string", - "format": "date-time", - "description": "The time when the next attempt is scheduled." - }, - "blockedReason": { - "type": "string", - "description": "If the state is BLOCKED, blocked reason provides additional information." - } - }, - "description": "NexusOperationCancellationInfo contains the state of a nexus operation cancellation." - }, "v1NexusOperationCancellationState": { "type": "string", "enum": [ @@ -12935,6 +13875,202 @@ } } }, + "v1NexusOperationIdConflictPolicy": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", + "NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL", + "NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING" + ], + "default": "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", + "description": "Defines what to do when trying to start a Nexus operation with the same ID as a *running* operation.\nNote that it is *never* valid to have two running instances of the same operation ID.\n\nSee `NexusOperationIdReusePolicy` for handling operation ID duplication with a *closed* operation.\n\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL: Don't start a new operation; instead return `NexusOperationAlreadyStarted` error.\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new operation; instead return a handle for the running operation." + }, + "v1NexusOperationIdReusePolicy": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", + "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE", + "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY", + "NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE" + ], + "default": "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", + "description": "Defines whether to allow re-using an operation ID from a previously *closed* Nexus operation.\nIf the request is denied, the server returns a `NexusOperationAlreadyStarted` error.\n\nSee `NexusOperationIdConflictPolicy` for handling ID duplication with a *running* operation.\n\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE: Always allow starting an operation using the same operation ID.\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting an operation using the same ID only when the last operation's final state is one\nof {failed, canceled, terminated, timed out}.\n - NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the ID for this operation. Future start requests could potentially change the policy,\nallowing re-use of the ID." + }, + "v1NexusOperationInfo": { + "type": "object", + "properties": { + "operationId": { + "type": "string", + "description": "Unique identifier of this Nexus operation within its namespace along with run ID (below)." + }, + "runId": { + "type": "string" + }, + "endpoint": { + "type": "string", + "description": "Endpoint name, resolved to a URL via the cluster's endpoint registry." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "status": { + "$ref": "#/definitions/v1NexusOperationStatus", + "description": "A general status for this operation, indicates whether it is currently running or in one of the terminal statuses." + }, + "state": { + "$ref": "#/definitions/v1PendingNexusOperationState", + "description": "More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this operation.\nThis is the only timeout settable for a Nexus operation." + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to start/deliver the operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "scheduleTime": { + "type": "string", + "format": "date-time", + "description": "Time the operation was originally scheduled via a StartNexusOperation request." + }, + "expirationTime": { + "type": "string", + "format": "date-time", + "description": "Scheduled time + schedule to close timeout." + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "Time when the operation transitioned to a closed state." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "executionDuration": { + "type": "string", + "description": "How long this operation has been running for, including all attempts and backoff between attempts." + }, + "cancellationInfo": { + "$ref": "#/definitions/apinexusv1NexusOperationCancellationInfo" + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + }, + "requestId": { + "type": "string", + "description": "Request ID allocated by the server when handling the StartNexusOperation request.\nUsed as an idempotency token for submitting start requests to the handler." + }, + "operationToken": { + "type": "string", + "description": "Operation token. Only set for asynchronous operations after a successful StartOperation call." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Incremented each time the operation's state is mutated in persistence." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + }, + "nexusHeader": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Header for context propagation and tracing purposes." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apicommonv1Link" + }, + "description": "Links attached by the handler of this operation on start or completion." + } + }, + "description": "Information about a standalone Nexus operation." + }, + "v1NexusOperationListInfo": { + "type": "object", + "properties": { + "operationId": { + "type": "string", + "description": "A unique identifier of this operation within its namespace along with run ID (below)." + }, + "runId": { + "type": "string", + "description": "The run ID of the standalone Nexus operation." + }, + "endpoint": { + "type": "string", + "description": "Endpoint name." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "scheduleTime": { + "type": "string", + "format": "date-time", + "description": "Time the operation was originally scheduled via a StartNexusOperation request." + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "If the operation is in a terminal status, this field represents the time the operation transitioned to that status." + }, + "status": { + "$ref": "#/definitions/v1NexusOperationStatus", + "description": "Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not\navailable in the list response." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes from the start request." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Updated on terminal status." + }, + "stateSizeBytes": { + "type": "string", + "format": "int64", + "description": "Updated once on scheduled and once on terminal status." + }, + "executionDuration": { + "type": "string", + "description": "The difference between close time and scheduled time.\nThis field is only populated if the operation is closed." + } + }, + "description": "Limited Nexus operation information returned in the list response.\nWhen adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in\nNexusOperationInfo but not at the top-level)." + }, "v1NexusOperationScheduledEventAttributes": { "type": "object", "properties": { @@ -13004,6 +14140,20 @@ }, "description": "Event marking an asynchronous operation was started by the responding Nexus handler.\nIf the operation completes synchronously, this event is not generated.\nIn rare situations, such as request timeouts, the service may fail to record the actual start time and will fabricate\nthis event upon receiving the operation completion via callback." }, + "v1NexusOperationStatus": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_STATUS_UNSPECIFIED", + "NEXUS_OPERATION_STATUS_RUNNING", + "NEXUS_OPERATION_STATUS_COMPLETED", + "NEXUS_OPERATION_STATUS_FAILED", + "NEXUS_OPERATION_STATUS_CANCELED", + "NEXUS_OPERATION_STATUS_TERMINATED", + "NEXUS_OPERATION_STATUS_TIMED_OUT" + ], + "default": "NEXUS_OPERATION_STATUS_UNSPECIFIED", + "description": "Status of a standalone Nexus operation.\nThe status is updated once, when the operation is originally scheduled, and again when the operation reaches a\nterminal status.\n\n - NEXUS_OPERATION_STATUS_RUNNING: The operation is not in a terminal status. The operation may attempting to start, backing off between attempts,\nor already started.\n - NEXUS_OPERATION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." + }, "v1NexusOperationTimedOutEventAttributes": { "type": "object", "properties": { @@ -13023,6 +14173,16 @@ }, "description": "Nexus operation timed out." }, + "v1NexusOperationWaitStage": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "NEXUS_OPERATION_WAIT_STAGE_STARTED", + "NEXUS_OPERATION_WAIT_STAGE_CLOSED" + ], + "default": "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "description": "Stage that can be specified when waiting on a nexus operation.\n\n - NEXUS_OPERATION_WAIT_STAGE_STARTED: Wait for the operation to be started.\n - NEXUS_OPERATION_WAIT_STAGE_CLOSED: Wait for the operation to be in a terminal state, either successful or unsuccessful." + }, "v1OnConflictOptions": { "type": "object", "properties": { @@ -13278,7 +14438,7 @@ "description": "The time when the next attempt is scheduled." }, "cancellationInfo": { - "$ref": "#/definitions/v1NexusOperationCancellationInfo" + "$ref": "#/definitions/apiworkflowv1NexusOperationCancellationInfo" }, "scheduledEventId": { "type": "string", @@ -13440,6 +14600,31 @@ } } }, + "v1PollNexusOperationResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the operation, useful when run_id was not specified in the request." + }, + "waitStage": { + "$ref": "#/definitions/v1NexusOperationWaitStage", + "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked." + }, + "operationToken": { + "type": "string", + "description": "Operation token. Only populated for asynchronous operations after a successful StartOperation call." + }, + "result": { + "$ref": "#/definitions/v1Payload", + "description": "The result if the operation completed successfully." + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The failure if the operation completed unsuccessfully." + } + } + }, "v1PollNexusTaskQueueResponse": { "type": "object", "properties": { @@ -13990,6 +15175,9 @@ } } }, + "v1RequestCancelNexusOperationResponse": { + "type": "object" + }, "v1RequestCancelWorkflowExecutionResponse": { "type": "object" }, @@ -15183,6 +16371,19 @@ } } }, + "v1StartNexusOperationResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the operation that was started - or used (via NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING)." + }, + "started": { + "type": "boolean", + "description": "If true, a new operation was started." + } + } + }, "v1StartOperationRequest": { "type": "object", "properties": { @@ -15753,6 +16954,9 @@ "default": "TASK_REACHABILITY_UNSPECIFIED", "description": "Specifies which category of tasks may reach a worker on a versioned task queue.\nUsed both in a reachability query and its response.\nDeprecated.\n\n - TASK_REACHABILITY_NEW_WORKFLOWS: There's a possiblity for a worker to receive new workflow tasks. Workers should *not* be retired.\n - TASK_REACHABILITY_EXISTING_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from existing workflows. Workers\nshould *not* be retired.\nThis enum value does not distinguish between open and closed workflows.\n - TASK_REACHABILITY_OPEN_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from open workflows. Workers\nshould *not* be retired.\n - TASK_REACHABILITY_CLOSED_WORKFLOWS: There's a possiblity for a worker to receive existing workflow tasks from closed workflows. Workers may be\nretired dependending on application requirements. For example, if there's no need to query closed workflows." }, + "v1TerminateNexusOperationResponse": { + "type": "object" + }, "v1TerminateWorkflowExecutionResponse": { "type": "object" }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 045315d92..5062fc680 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1008,6 +1008,323 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operation-count: + get: + tags: + - WorkflowService + description: CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + operationId: CountNexusOperations + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + See also ListNexusOperationsRequest for search attributes available for Nexus operations. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations: + get: + tags: + - WorkflowService + description: ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperations + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of operations to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListNexusOperationsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + Search attributes that are avaialble for Nexus operations include: + - OperationId + - RunId + - Endpoint + - Service + - Operation + - RequestId + - StartTime + - ExecutionTime + - CloseTime + - ExecutionStatus + - ExecutionDuration + - StateTransitionCount + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}: + get: + tags: + - WorkflowService + description: |- + DescribeNexusOperation returns information about a Nexus operation. + Supported use cases include: + - Get current operation info without waiting + - Long-poll for next state change and return new operation info + Response can optionally include operation input or outcome (if the operation has completed). + operationId: DescribeNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the operation has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that operation state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartNexusOperation starts a new Nexus operation. + + Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + namespace unless permitted by the specified ID conflict policy. + operationId: StartNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}/cancel: + post: + tags: + - WorkflowService + description: |- + RequestCancelNexusOperation requests cancellation of a Nexus operation. + + Requesting to cancel an operation does not automatically transition the operation to canceled status. + The operation will only transition to canceled status if it supports cancellation and the handler + processes the cancellation request. + operationId: RequestCancelNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}/poll: + get: + tags: + - WorkflowService + description: |- + PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + the outcome (result or failure). + operationId: PollNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: waitStage + in: query + description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + schema: + enum: + - NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED + - NEXUS_OPERATION_WAIT_STAGE_STARTED + - NEXUS_OPERATION_WAIT_STAGE_CLOSED + type: string + format: enum + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateNexusOperation terminates an existing Nexus operation immediately. + + Termination happens immediately and the operation handler cannot react to it. A terminated operation will have + its outcome set to a failure with a termination reason. + operationId: TerminateNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/schedules: get: tags: @@ -4491,6 +4808,323 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operation-count: + get: + tags: + - WorkflowService + description: CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + operationId: CountNexusOperations + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + See also ListNexusOperationsRequest for search attributes available for Nexus operations. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations: + get: + tags: + - WorkflowService + description: ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperations + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of operations to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListNexusOperationsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + Search attributes that are avaialble for Nexus operations include: + - OperationId + - RunId + - Endpoint + - Service + - Operation + - RequestId + - StartTime + - ExecutionTime + - CloseTime + - ExecutionStatus + - ExecutionDuration + - StateTransitionCount + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}: + get: + tags: + - WorkflowService + description: |- + DescribeNexusOperation returns information about a Nexus operation. + Supported use cases include: + - Get current operation info without waiting + - Long-poll for next state change and return new operation info + Response can optionally include operation input or outcome (if the operation has completed). + operationId: DescribeNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the operation has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that operation state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartNexusOperation starts a new Nexus operation. + + Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + namespace unless permitted by the specified ID conflict policy. + operationId: StartNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/cancel: + post: + tags: + - WorkflowService + description: |- + RequestCancelNexusOperation requests cancellation of a Nexus operation. + + Requesting to cancel an operation does not automatically transition the operation to canceled status. + The operation will only transition to canceled status if it supports cancellation and the handler + processes the cancellation request. + operationId: RequestCancelNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/poll: + get: + tags: + - WorkflowService + description: |- + PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + the outcome (result or failure). + operationId: PollNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: waitStage + in: query + description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + schema: + enum: + - NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED + - NEXUS_OPERATION_WAIT_STAGE_STARTED + - NEXUS_OPERATION_WAIT_STAGE_CLOSED + type: string + format: enum + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateNexusOperation terminates an existing Nexus operation immediately. + + Termination happens immediately and the operation handler cannot react to it. A terminated operation will have + its outcome set to a failure with a termination reason. + operationId: TerminateNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/schedules: get: tags: @@ -7688,6 +8322,33 @@ components: type: string description: Time of the last update. format: date-time + CountNexusOperationsResponse: + type: object + properties: + count: + type: string + description: |- + If `query` is not grouping by any field, the count is an approximate number + of operations that match the query. + If `query` is grouping by a field, the count is simply the sum of the counts + of the groups returned in the response. This number can be smaller than the + total number of operations matching the query. + groups: + type: array + items: + $ref: '#/components/schemas/CountNexusOperationsResponse_AggregationGroup' + description: |- + Contains the groups if the request is grouping by a field. + The list might not be complete, and the counts of each group is approximate. + CountNexusOperationsResponse_AggregationGroup: + type: object + properties: + groupValues: + type: array + items: + $ref: '#/components/schemas/Payload' + count: + type: string CountWorkflowExecutionsResponse: type: object properties: @@ -8014,8 +8675,36 @@ components: items: $ref: '#/components/schemas/FailoverStatus' description: |- - Contains the historical state of failover_versions for the cluster, truncated to contain only the last N - states to ensure that the list does not grow unbounded. + Contains the historical state of failover_versions for the cluster, truncated to contain only the last N + states to ensure that the list does not grow unbounded. + DescribeNexusOperationResponse: + type: object + properties: + runId: + type: string + description: The run ID of the operation, useful when run_id was not specified in the request. + info: + allOf: + - $ref: '#/components/schemas/NexusOperationInfo' + description: Information about the operation. + input: + allOf: + - $ref: '#/components/schemas/Payload' + description: |- + Serialized operation input, passed as the request payload. + Only set if include_input was true in the request. + result: + allOf: + - $ref: '#/components/schemas/Payload' + description: The result if the operation completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the operation completed unsuccessfully. + longPollToken: + type: string + description: Token for follow-on long-poll requests. Absent only if the operation is complete. + format: bytes DescribeScheduleResponse: type: object properties: @@ -8979,6 +9668,8 @@ components: $ref: '#/components/schemas/Link_WorkflowEvent' batchJob: $ref: '#/components/schemas/Link_BatchJob' + nexusOperation: + $ref: '#/components/schemas/Link_NexusOperation' description: |- Link can be associated with history events. It might contain information about an external entity related to the history event. For example, workflow A makes a Nexus call that starts workflow B: @@ -8993,6 +9684,16 @@ components: A link to a built-in batch job. Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc). This link can be put on workflow history events generated by actions taken by a batch job. + Link_NexusOperation: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: A link to a standalone Nexus operation. Link_WorkflowEvent: type: object properties: @@ -9059,6 +9760,17 @@ components: type: array items: $ref: '#/components/schemas/Endpoint' + ListNexusOperationsResponse: + type: object + properties: + operations: + type: array + items: + $ref: '#/components/schemas/NexusOperationListInfo' + nextPageToken: + type: string + description: Token to use to fetch the next page. If empty, there is no next page. + format: bytes ListScheduleMatchingTimesResponse: type: object properties: @@ -9611,6 +10323,180 @@ components: operationToken: type: string description: Operation token - may be empty if the operation completed synchronously. + NexusOperationInfo: + type: object + properties: + operationId: + type: string + description: Unique identifier of this Nexus operation within its namespace along with run ID (below). + runId: + type: string + endpoint: + type: string + description: Endpoint name, resolved to a URL via the cluster's endpoint registry. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + status: + enum: + - NEXUS_OPERATION_STATUS_UNSPECIFIED + - NEXUS_OPERATION_STATUS_RUNNING + - NEXUS_OPERATION_STATUS_COMPLETED + - NEXUS_OPERATION_STATUS_FAILED + - NEXUS_OPERATION_STATUS_CANCELED + - NEXUS_OPERATION_STATUS_TERMINATED + - NEXUS_OPERATION_STATUS_TIMED_OUT + type: string + description: A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. + format: enum + state: + enum: + - PENDING_NEXUS_OPERATION_STATE_UNSPECIFIED + - PENDING_NEXUS_OPERATION_STATE_SCHEDULED + - PENDING_NEXUS_OPERATION_STATE_BACKING_OFF + - PENDING_NEXUS_OPERATION_STATE_STARTED + - PENDING_NEXUS_OPERATION_STATE_BLOCKED + type: string + description: More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. + format: enum + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Schedule-to-close timeout for this operation. + This is the only timeout settable for a Nexus operation. + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + attempt: + type: integer + description: |- + The number of attempts made to start/deliver the operation request. + This number represents a minimum bound since the attempt is incremented after the request completes. + format: int32 + scheduleTime: + type: string + description: Time the operation was originally scheduled via a StartNexusOperation request. + format: date-time + expirationTime: + type: string + description: Scheduled time + schedule to close timeout. + format: date-time + closeTime: + type: string + description: Time when the operation transitioned to a closed state. + format: date-time + lastAttemptCompleteTime: + type: string + description: The time when the last attempt completed. + format: date-time + lastAttemptFailure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The last attempt's failure, if any. + nextAttemptScheduleTime: + type: string + description: The time when the next attempt is scheduled. + format: date-time + executionDuration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: How long this operation has been running for, including all attempts and backoff between attempts. + cancellationInfo: + $ref: '#/components/schemas/NexusOperationCancellationInfo' + blockedReason: + type: string + description: If the state is BLOCKED, blocked reason provides additional information. + requestId: + type: string + description: |- + Request ID allocated by the server when handling the StartNexusOperation request. + Used as an idempotency token for submitting start requests to the handler. + operationToken: + type: string + description: Operation token. Only set for asynchronous operations after a successful StartOperation call. + stateTransitionCount: + type: string + description: Incremented each time the operation's state is mutated in persistence. + searchAttributes: + $ref: '#/components/schemas/SearchAttributes' + nexusHeader: + type: object + additionalProperties: + type: string + description: Header for context propagation and tracing purposes. + userMetadata: + allOf: + - $ref: '#/components/schemas/UserMetadata' + description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + links: + type: array + items: + $ref: '#/components/schemas/Link' + description: Links attached by the handler of this operation on start or completion. + description: Information about a standalone Nexus operation. + NexusOperationListInfo: + type: object + properties: + operationId: + type: string + description: A unique identifier of this operation within its namespace along with run ID (below). + runId: + type: string + description: The run ID of the standalone Nexus operation. + endpoint: + type: string + description: Endpoint name. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + scheduleTime: + type: string + description: Time the operation was originally scheduled via a StartNexusOperation request. + format: date-time + closeTime: + type: string + description: If the operation is in a terminal status, this field represents the time the operation transitioned to that status. + format: date-time + status: + enum: + - NEXUS_OPERATION_STATUS_UNSPECIFIED + - NEXUS_OPERATION_STATUS_RUNNING + - NEXUS_OPERATION_STATUS_COMPLETED + - NEXUS_OPERATION_STATUS_FAILED + - NEXUS_OPERATION_STATUS_CANCELED + - NEXUS_OPERATION_STATUS_TERMINATED + - NEXUS_OPERATION_STATUS_TIMED_OUT + type: string + description: |- + Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not + available in the list response. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes from the start request. + stateTransitionCount: + type: string + description: Updated on terminal status. + stateSizeBytes: + type: string + description: Updated once on scheduled and once on terminal status. + executionDuration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + The difference between close time and scheduled time. + This field is only populated if the operation is closed. + description: |- + Limited Nexus operation information returned in the list response. + When adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in + NexusOperationInfo but not at the top-level). NexusOperationScheduledEventAttributes: type: object properties: @@ -10090,6 +10976,31 @@ components: version: type: string description: The version of the plugin, may be empty. + PollNexusOperationResponse: + type: object + properties: + runId: + type: string + description: The run ID of the operation, useful when run_id was not specified in the request. + waitStage: + enum: + - NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED + - NEXUS_OPERATION_WAIT_STAGE_STARTED + - NEXUS_OPERATION_WAIT_STAGE_CLOSED + type: string + description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + format: enum + operationToken: + type: string + description: Operation token. Only populated for asynchronous operations after a successful StartOperation call. + result: + allOf: + - $ref: '#/components/schemas/Payload' + description: The result if the operation completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the operation completed unsuccessfully. PollWorkflowTaskQueueResponse: type: object properties: @@ -10650,6 +11561,28 @@ components: reason: type: string description: Reason for requesting the cancellation + RequestCancelNexusOperationRequest: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: Operation run ID, targets the latest run if empty. + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: Used to de-dupe cancellation requests. + reason: + type: string + description: Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API. + RequestCancelNexusOperationResponse: + type: object + properties: {} RequestCancelWorkflowExecutionRequest: type: object properties: @@ -12245,6 +13178,89 @@ components: allOf: - $ref: '#/components/schemas/Priority' description: Priority metadata + StartNexusOperationRequest: + type: object + properties: + namespace: + type: string + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: A unique identifier for this start request. Typically UUIDv4. + operationId: + type: string + endpoint: + type: string + description: Endpoint name, resolved to a URL via the cluster's endpoint registry. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Schedule-to-close timeout for this operation. + This is the only timeout settable for a Nexus operation. + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + input: + allOf: + - $ref: '#/components/schemas/Payload' + description: Serialized input to the operation. Passed as the request payload. + idReusePolicy: + enum: + - NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED + - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE + - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY + - NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE + type: string + description: |- + Defines whether to allow re-using the operation id from a previously *closed* operation. + The default policy is NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE. + format: enum + idConflictPolicy: + enum: + - NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED + - NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL + - NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING + type: string + description: |- + Defines how to resolve an operation id conflict with a *running* operation. + The default policy is NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes for indexing. + nexusHeader: + type: object + additionalProperties: + type: string + description: |- + Header to attach to the Nexus request. + Users are responsible for encrypting sensitive data in this header as it is stored in workflow history and + transmitted to external services as-is. + This is useful for propagating tracing information. + Note these headers are not the same as Temporal headers on internal activities and child workflows, these are + transmitted to Nexus operations that may be external and are not traditional payloads. + userMetadata: + allOf: + - $ref: '#/components/schemas/UserMetadata' + description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + StartNexusOperationResponse: + type: object + properties: + runId: + type: string + description: The run ID of the operation that was started - or used (via NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING). + started: + type: boolean + description: If true, a new operation was started. StartWorkflowExecutionRequest: type: object properties: @@ -12726,6 +13742,28 @@ components: description: Last time versioning information of this Task Queue changed. format: date-time description: Experimental. Worker Deployments are experimental and might significantly change in the future. + TerminateNexusOperationRequest: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: Operation run ID, targets the latest run if empty. + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: Used to de-dupe termination requests. + reason: + type: string + description: Reason for requesting the termination, recorded in the operation's result failure outcome. + TerminateNexusOperationResponse: + type: object + properties: {} TerminateWorkflowExecutionRequest: type: object properties: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 03b640a2f..a58e48880 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -240,9 +240,17 @@ message Link { string job_id = 1; } + // A link to a standalone Nexus operation. + message NexusOperation { + string namespace = 1; + string operation_id = 2; + string run_id = 3; + } + oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; + NexusOperation nexus_operation = 3; } } diff --git a/temporal/api/enums/v1/nexus.proto b/temporal/api/enums/v1/nexus.proto index 3a3087716..c378bf9b4 100644 --- a/temporal/api/enums/v1/nexus.proto +++ b/temporal/api/enums/v1/nexus.proto @@ -20,3 +20,64 @@ enum NexusHandlerErrorRetryBehavior { NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE = 2; } +// Status of a standalone Nexus operation. +// The status is updated once, when the operation is originally scheduled, and again when the operation reaches a +// terminal status. +// (-- api-linter: core::0216::synonyms=disabled +// aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) +enum NexusOperationStatus { + NEXUS_OPERATION_STATUS_UNSPECIFIED = 0; + // The operation is not in a terminal status. The operation may attempting to start, backing off between attempts, + // or already started. + NEXUS_OPERATION_STATUS_RUNNING = 1; + // The operation completed successfully. + NEXUS_OPERATION_STATUS_COMPLETED = 2; + // The operation completed with failure. + NEXUS_OPERATION_STATUS_FAILED = 3; + // The operation completed as canceled. + // Requesting to cancel an operation does not automatically transition the operation to canceled status, depending + // on the current operation status and the cancelation type used. + NEXUS_OPERATION_STATUS_CANCELED = 4; + // The operation was terminated. Termination happens immediately without notifying the handler. + NEXUS_OPERATION_STATUS_TERMINATED = 5; + // The operation has timed out by reaching the specified schedule-to-close timeout. + NEXUS_OPERATION_STATUS_TIMED_OUT = 6; +} + +// Stage that can be specified when waiting on a nexus operation. +enum NexusOperationWaitStage { + NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED = 0; + // Wait for the operation to be started. + NEXUS_OPERATION_WAIT_STAGE_STARTED = 1; + // Wait for the operation to be in a terminal state, either successful or unsuccessful. + NEXUS_OPERATION_WAIT_STAGE_CLOSED = 2; +} + +// Defines whether to allow re-using an operation ID from a previously *closed* Nexus operation. +// If the request is denied, the server returns a `NexusOperationAlreadyStarted` error. +// +// See `NexusOperationIdConflictPolicy` for handling ID duplication with a *running* operation. +enum NexusOperationIdReusePolicy { + NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED = 0; + // Always allow starting an operation using the same operation ID. + NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1; + // Allow starting an operation using the same ID only when the last operation's final state is one + // of {failed, canceled, terminated, timed out}. + NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2; + // Do not permit re-use of the ID for this operation. Future start requests could potentially change the policy, + // allowing re-use of the ID. + NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE = 3; +} + +// Defines what to do when trying to start a Nexus operation with the same ID as a *running* operation. +// Note that it is *never* valid to have two running instances of the same operation ID. +// +// See `NexusOperationIdReusePolicy` for handling operation ID duplication with a *closed* operation. +enum NexusOperationIdConflictPolicy { + NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED = 0; + // Don't start a new operation; instead return `NexusOperationAlreadyStarted` error. + NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL = 1; + // Don't start a new operation; instead return a handle for the running operation. + NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING = 2; +} + diff --git a/temporal/api/errordetails/v1/message.proto b/temporal/api/errordetails/v1/message.proto index 315d30c57..952202652 100644 --- a/temporal/api/errordetails/v1/message.proto +++ b/temporal/api/errordetails/v1/message.proto @@ -121,3 +121,11 @@ message MultiOperationExecutionFailure { repeated google.protobuf.Any details = 3; } } + +// An error indicating that a Nexus operation failed to start. Returned when there is an existing operation with the +// given operation ID, and the given ID reuse and conflict policies do not permit starting a new one or attaching to an +// existing one. +message NexusOperationAlreadyStartedFailure { + string start_request_id = 1; + string run_id = 2; +} diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index bfad6102a..0ed465a04 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -9,9 +9,13 @@ option java_outer_classname = "MessageProto"; option ruby_package = "Temporalio::Api::Nexus::V1"; option csharp_namespace = "Temporalio.Api.Nexus.V1"; +import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; import "temporal/api/common/v1/message.proto"; +import "temporal/api/enums/v1/common.proto"; import "temporal/api/enums/v1/nexus.proto"; +import "temporal/api/failure/v1/message.proto"; +import "temporal/api/sdk/v1/user_metadata.proto"; // A general purpose failure message. // See: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure @@ -198,3 +202,136 @@ message EndpointTarget { External external = 2; } } + +// NexusOperationCancellationInfo contains the state of a Nexus operation cancellation. +message NexusOperationCancellationInfo { + // The time when cancellation was requested. + google.protobuf.Timestamp requested_time = 1; + + temporal.api.enums.v1.NexusOperationCancellationState state = 2; + + // The number of attempts made to deliver the cancel operation request. + // This number represents a minimum bound since the attempt is incremented after the request completes. + int32 attempt = 3; + + // The time when the last attempt completed. + google.protobuf.Timestamp last_attempt_complete_time = 4; + // The last attempt's failure, if any. + temporal.api.failure.v1.Failure last_attempt_failure = 5; + // The time when the next attempt is scheduled. + google.protobuf.Timestamp next_attempt_schedule_time = 6; + + // If the state is BLOCKED, blocked reason provides additional information. + string blocked_reason = 7; + + // A reason that may be specified in the CancelNexusOpertionRequest. + string reason = 24; +} + +// Information about a standalone Nexus operation. +message NexusOperationInfo { + // Unique identifier of this Nexus operation within its namespace along with run ID (below). + string operation_id = 1; + string run_id = 2; + + // Endpoint name, resolved to a URL via the cluster's endpoint registry. + string endpoint = 3; + // Service name. + string service = 4; + // Operation name. + string operation = 5; + + // A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. + temporal.api.enums.v1.NexusOperationStatus status = 6; + // More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. + temporal.api.enums.v1.PendingNexusOperationState state = 7; + + // Schedule-to-close timeout for this operation. + // This is the only timeout settable for a Nexus operation. + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" is used to indicate interval. --) + google.protobuf.Duration schedule_to_close_timeout = 8; + + // The number of attempts made to start/deliver the operation request. + // This number represents a minimum bound since the attempt is incremented after the request completes. + int32 attempt = 9; + + // Time the operation was originally scheduled via a StartNexusOperation request. + google.protobuf.Timestamp schedule_time = 10; + // Scheduled time + schedule to close timeout. + google.protobuf.Timestamp expiration_time = 11; + // Time when the operation transitioned to a closed state. + google.protobuf.Timestamp close_time = 12; + + // The time when the last attempt completed. + google.protobuf.Timestamp last_attempt_complete_time = 13; + // The last attempt's failure, if any. + temporal.api.failure.v1.Failure last_attempt_failure = 14; + // The time when the next attempt is scheduled. + google.protobuf.Timestamp next_attempt_schedule_time = 15; + + // How long this operation has been running for, including all attempts and backoff between attempts. + google.protobuf.Duration execution_duration = 16; + + NexusOperationCancellationInfo cancellation_info = 17; + + // If the state is BLOCKED, blocked reason provides additional information. + string blocked_reason = 18; + + // Request ID allocated by the server when handling the StartNexusOperation request. + // Used as an idempotency token for submitting start requests to the handler. + string request_id = 19; + + // Operation token. Only set for asynchronous operations after a successful StartOperation call. + string operation_token = 20; + + // Incremented each time the operation's state is mutated in persistence. + int64 state_transition_count = 21; + + temporal.api.common.v1.SearchAttributes search_attributes = 22; + + // Header for context propagation and tracing purposes. + map nexus_header = 23; + + // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + temporal.api.sdk.v1.UserMetadata user_metadata = 24; + + // Links attached by the handler of this operation on start or completion. + repeated temporal.api.common.v1.Link links = 25; +} + +// Limited Nexus operation information returned in the list response. +// When adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in +// NexusOperationInfo but not at the top-level). +message NexusOperationListInfo { + // A unique identifier of this operation within its namespace along with run ID (below). + string operation_id = 1; + // The run ID of the standalone Nexus operation. + string run_id = 2; + + // Endpoint name. + string endpoint = 3; + // Service name. + string service = 4; + // Operation name. + string operation = 5; + + // Time the operation was originally scheduled via a StartNexusOperation request. + google.protobuf.Timestamp schedule_time = 6; + // If the operation is in a terminal status, this field represents the time the operation transitioned to that status. + google.protobuf.Timestamp close_time = 7; + // Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not + // available in the list response. + temporal.api.enums.v1.NexusOperationStatus status = 8; + + // Search attributes from the start request. + temporal.api.common.v1.SearchAttributes search_attributes = 9; + + // Updated on terminal status. + int64 state_transition_count = 10; + // Updated once on scheduled and once on terminal status. + int64 state_size_bytes = 11; + // The difference between close time and scheduled time. + // This field is only populated if the operation is closed. + google.protobuf.Duration execution_duration = 12; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 69b673c81..0c9e3d470 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -19,6 +19,7 @@ import "temporal/api/enums/v1/reset.proto"; import "temporal/api/enums/v1/task_queue.proto"; import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/update.proto"; +import "temporal/api/enums/v1/nexus.proto"; import "temporal/api/activity/v1/message.proto"; import "temporal/api/common/v1/message.proto"; import "temporal/api/history/v1/message.proto"; @@ -2651,3 +2652,210 @@ message UnpauseWorkflowExecutionRequest { // Response to a successful UnpauseWorkflowExecution request. message UnpauseWorkflowExecutionResponse { } + +message StartNexusOperationRequest { + string namespace = 1; + // The identity of the client who initiated this request. + string identity = 2; + // A unique identifier for this start request. Typically UUIDv4. + string request_id = 3; + + string operation_id = 4; + // Endpoint name, resolved to a URL via the cluster's endpoint registry. + string endpoint = 5; + // Service name. + string service = 6; + // Operation name. + string operation = 7; + + // Schedule-to-close timeout for this operation. + // This is the only timeout settable for a Nexus operation. + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" is used to indicate interval. --) + google.protobuf.Duration schedule_to_close_timeout = 8; + + // Serialized input to the operation. Passed as the request payload. + temporal.api.common.v1.Payload input = 9; + + // Defines whether to allow re-using the operation id from a previously *closed* operation. + // The default policy is NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE. + temporal.api.enums.v1.NexusOperationIdReusePolicy id_reuse_policy = 10; + // Defines how to resolve an operation id conflict with a *running* operation. + // The default policy is NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL. + temporal.api.enums.v1.NexusOperationIdConflictPolicy id_conflict_policy = 11; + + // Search attributes for indexing. + temporal.api.common.v1.SearchAttributes search_attributes = 12; + // Header to attach to the Nexus request. + // Users are responsible for encrypting sensitive data in this header as it is stored in workflow history and + // transmitted to external services as-is. + // This is useful for propagating tracing information. + // Note these headers are not the same as Temporal headers on internal activities and child workflows, these are + // transmitted to Nexus operations that may be external and are not traditional payloads. + map nexus_header = 13; + // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + temporal.api.sdk.v1.UserMetadata user_metadata = 14; +} + +message StartNexusOperationResponse { + // The run ID of the operation that was started - or used (via NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING). + string run_id = 1; + // If true, a new operation was started. + bool started = 2; +} + +message DescribeNexusOperationRequest { + string namespace = 1; + string operation_id = 2; + // Operation run ID. If empty the request targets the latest run. + string run_id = 3; + // Include the input field in the response. + bool include_input = 4; + // Include the outcome (result/failure) in the response if the operation has completed. + bool include_outcome = 5; + // Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + // state changes from the state encoded in this token. If absent, return current state immediately. + // If present, run_id must also be present. + // Note that operation state may change multiple times between requests, therefore it is not + // guaranteed that a client making a sequence of long-poll requests will see a complete + // sequence of state changes. + bytes long_poll_token = 6; +} + +message DescribeNexusOperationResponse { + // The run ID of the operation, useful when run_id was not specified in the request. + string run_id = 1; + + // Information about the operation. + temporal.api.nexus.v1.NexusOperationInfo info = 2; + + // Serialized operation input, passed as the request payload. + // Only set if include_input was true in the request. + temporal.api.common.v1.Payload input = 3; + + // Only set if the operation is completed and include_outcome was true in the request. + oneof outcome { + // The result if the operation completed successfully. + temporal.api.common.v1.Payload result = 4; + // The failure if the operation completed unsuccessfully. + temporal.api.failure.v1.Failure failure = 5; + } + + // Token for follow-on long-poll requests. Absent only if the operation is complete. + bytes long_poll_token = 6; +} + +message PollNexusOperationRequest { + string namespace = 1; + string operation_id = 2; + // Operation run ID. If empty the request targets the latest run. + string run_id = 3; + + // Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + temporal.api.enums.v1.NexusOperationWaitStage wait_stage = 4; +} + +message PollNexusOperationResponse { + // The run ID of the operation, useful when run_id was not specified in the request. + string run_id = 1; + + // Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + temporal.api.enums.v1.NexusOperationWaitStage wait_stage = 2; + + // Operation token. Only populated for asynchronous operations after a successful StartOperation call. + string operation_token = 3; + + // The operation outcome, available if the operation is in a closed state. + oneof outcome { + // The result if the operation completed successfully. + temporal.api.common.v1.Payload result = 4; + // The failure if the operation completed unsuccessfully. + temporal.api.failure.v1.Failure failure = 5; + } +} + +message ListNexusOperationsRequest { + string namespace = 1; + // Max number of operations to return per page. + int32 page_size = 2; + // Token returned in ListNexusOperationsResponse. + bytes next_page_token = 3; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + // Search attributes that are avaialble for Nexus operations include: + // - OperationId + // - RunId + // - Endpoint + // - Service + // - Operation + // - RequestId + // - StartTime + // - ExecutionTime + // - CloseTime + // - ExecutionStatus + // - ExecutionDuration + // - StateTransitionCount + string query = 4; +} + +message ListNexusOperationsResponse { + repeated temporal.api.nexus.v1.NexusOperationListInfo operations = 1; + // Token to use to fetch the next page. If empty, there is no next page. + bytes next_page_token = 2; +} + +message CountNexusOperationsRequest { + string namespace = 1; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + // See also ListNexusOperationsRequest for search attributes available for Nexus operations. + string query = 2; +} + +message CountNexusOperationsResponse { + // If `query` is not grouping by any field, the count is an approximate number + // of operations that match the query. + // If `query` is grouping by a field, the count is simply the sum of the counts + // of the groups returned in the response. This number can be smaller than the + // total number of operations matching the query. + int64 count = 1; + + // Contains the groups if the request is grouping by a field. + // The list might not be complete, and the counts of each group is approximate. + repeated AggregationGroup groups = 2; + + message AggregationGroup { + repeated temporal.api.common.v1.Payload group_values = 1; + int64 count = 2; + } +} + +message RequestCancelNexusOperationRequest { + string namespace = 1; + string operation_id = 2; + // Operation run ID, targets the latest run if empty. + string run_id = 3; + // The identity of the client who initiated this request. + string identity = 4; + // Used to de-dupe cancellation requests. + string request_id = 5; + // Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API. + string reason = 6; +} + +message RequestCancelNexusOperationResponse { +} + +message TerminateNexusOperationRequest { + string namespace = 1; + string operation_id = 2; + // Operation run ID, targets the latest run if empty. + string run_id = 3; + // The identity of the client who initiated this request. + string identity = 4; + // Used to de-dupe termination requests. + string request_id = 5; + // Reason for requesting the termination, recorded in the operation's result failure outcome. + string reason = 6; +} + +message TerminateNexusOperationResponse { +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 33304937a..8f3955a6a 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1287,4 +1287,95 @@ service WorkflowService { body: "*" }; } + + // StartNexusOperation starts a new Nexus operation. + // + // Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + // namespace unless permitted by the specified ID conflict policy. + rpc StartNexusOperation (StartNexusOperationRequest) returns (StartNexusOperationResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/nexus-operations/{operation_id}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}" + body: "*" + } + }; + } + + // DescribeNexusOperation returns information about a Nexus operation. + // Supported use cases include: + // - Get current operation info without waiting + // - Long-poll for next state change and return new operation info + // Response can optionally include operation input or outcome (if the operation has completed). + rpc DescribeNexusOperation (DescribeNexusOperationRequest) returns (DescribeNexusOperationResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/nexus-operations/{operation_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}" + } + }; + } + + // PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + // the outcome (result or failure). + rpc PollNexusOperation (PollNexusOperationRequest) returns (PollNexusOperationResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/nexus-operations/{operation_id}/poll" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}/poll" + } + }; + } + + // ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. + rpc ListNexusOperations (ListNexusOperationsRequest) returns (ListNexusOperationsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/nexus-operations" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/nexus-operations" + } + }; + } + + // CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + rpc CountNexusOperations (CountNexusOperationsRequest) returns (CountNexusOperationsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/nexus-operation-count" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/nexus-operation-count" + } + }; + } + + // RequestCancelNexusOperation requests cancellation of a Nexus operation. + // + // Requesting to cancel an operation does not automatically transition the operation to canceled status. + // The operation will only transition to canceled status if it supports cancellation and the handler + // processes the cancellation request. + rpc RequestCancelNexusOperation (RequestCancelNexusOperationRequest) returns (RequestCancelNexusOperationResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/nexus-operations/{operation_id}/cancel" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}/cancel" + body: "*" + } + }; + } + + // TerminateNexusOperation terminates an existing Nexus operation immediately. + // + // Termination happens immediately and the operation handler cannot react to it. A terminated operation will have + // its outcome set to a failure with a termination reason. + rpc TerminateNexusOperation (TerminateNexusOperationRequest) returns (TerminateNexusOperationResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/nexus-operations/{operation_id}/terminate" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}/terminate" + body: "*" + } + }; + } } From 6e7c81cb36e10d7959141361a1c7a49ebaddd3d4 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Mon, 23 Feb 2026 12:55:24 -0800 Subject: [PATCH 02/21] Regenerate OpenAPI docs after merge conflict resolution Co-Authored-By: Claude Opus 4.6 --- openapi/openapiv2.json | 2250 ++++++++++++++++++++++++++++++---------- openapi/openapiv3.yaml | 1066 ++++++++++++++++++- 2 files changed, 2779 insertions(+), 537 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 2f21bedcc..35b758f05 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1462,15 +1462,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedule-count": { + "/api/v1/namespaces/{namespace}/nexus-operation-count": { "get": { - "summary": "CountSchedules is a visibility API to count schedules in a specific namespace.", - "operationId": "CountSchedules2", + "summary": "CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace.", + "operationId": "CountNexusOperations2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CountSchedulesResponse" + "$ref": "#/definitions/v1CountNexusOperationsResponse" } }, "default": { @@ -1489,7 +1489,7 @@ }, { "name": "query", - "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationsRequest for search attributes available for Nexus operations.", "in": "query", "required": false, "type": "string" @@ -1500,15 +1500,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules": { + "/api/v1/namespaces/{namespace}/nexus-operations": { "get": { - "summary": "List all schedules in a namespace.", - "operationId": "ListSchedules2", + "summary": "ListNexusOperations is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperations2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSchedulesResponse" + "$ref": "#/definitions/v1ListNexusOperationsResponse" } }, "default": { @@ -1521,14 +1521,13 @@ "parameters": [ { "name": "namespace", - "description": "The namespace to list schedules in.", "in": "path", "required": true, "type": "string" }, { - "name": "maximumPageSize", - "description": "How many to return at once.", + "name": "pageSize", + "description": "Max number of operations to return per page.", "in": "query", "required": false, "type": "integer", @@ -1536,7 +1535,7 @@ }, { "name": "nextPageToken", - "description": "Token to get the next page of results.", + "description": "Token returned in ListNexusOperationsResponse.", "in": "query", "required": false, "type": "string", @@ -1544,7 +1543,7 @@ }, { "name": "query", - "description": "Query to filter schedules.", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSearch attributes that are avaialble for Nexus operations include:\n- OperationId\n- RunId\n- Endpoint\n- Service\n- Operation\n- RequestId\n- StartTime\n- ExecutionTime\n- CloseTime\n- ExecutionStatus\n- ExecutionDuration\n- StateTransitionCount", "in": "query", "required": false, "type": "string" @@ -1555,15 +1554,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}": { + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}": { "get": { - "summary": "Returns the schedule description and current state of an existing schedule.", - "operationId": "DescribeSchedule2", + "summary": "DescribeNexusOperation returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", + "operationId": "DescribeNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeScheduleResponse" + "$ref": "#/definitions/v1DescribeNexusOperationResponse" } }, "default": { @@ -1576,31 +1575,59 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to describe.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to describe.", + "name": "operationId", "in": "path", "required": true, "type": "string" + }, + { + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the operation has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ "WorkflowService" ] }, - "delete": { - "summary": "Deletes a schedule, removing it from the system.", - "operationId": "DeleteSchedule2", + "post": { + "summary": "StartNexusOperation starts a new Nexus operation.", + "description": "Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", + "operationId": "StartNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteScheduleResponse" + "$ref": "#/definitions/v1StartNexusOperationResponse" } }, "default": { @@ -1613,38 +1640,40 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to delete.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to delete.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "identity", - "description": "The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartNexusOperationBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { "post": { - "summary": "Creates a new schedule.", - "operationId": "CreateSchedule2", + "summary": "RequestCancelNexusOperation requests cancellation of a Nexus operation.", + "description": "Requesting to cancel an operation does not automatically transition the operation to canceled status.\nThe operation will only transition to canceled status if it supports cancellation and the handler\nprocesses the cancellation request.", + "operationId": "RequestCancelNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateScheduleResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationResponse" } }, "default": { @@ -1657,14 +1686,12 @@ "parameters": [ { "name": "namespace", - "description": "The namespace the schedule should be created in.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the new schedule.", + "name": "operationId", "in": "path", "required": true, "type": "string" @@ -1674,7 +1701,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationBody" } } ], @@ -1683,15 +1710,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/matching-times": { + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/poll": { "get": { - "summary": "Lists matching times within a range.", - "operationId": "ListScheduleMatchingTimes2", + "summary": "PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", + "operationId": "PollNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListScheduleMatchingTimesResponse" + "$ref": "#/definitions/v1PollNexusOperationResponse" } }, "default": { @@ -1704,32 +1731,35 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to query.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to query.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "startTime", - "description": "Time range to query.", + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", "in": "query", "required": false, - "type": "string", - "format": "date-time" + "type": "string" }, { - "name": "endTime", + "name": "waitStage", + "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked.\n\n - NEXUS_OPERATION_WAIT_STAGE_STARTED: Wait for the operation to be started.\n - NEXUS_OPERATION_WAIT_STAGE_CLOSED: Wait for the operation to be in a terminal state, either successful or unsuccessful.", "in": "query", "required": false, "type": "string", - "format": "date-time" + "enum": [ + "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "NEXUS_OPERATION_WAIT_STAGE_STARTED", + "NEXUS_OPERATION_WAIT_STAGE_CLOSED" + ], + "default": "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED" } ], "tags": [ @@ -1737,15 +1767,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/patch": { + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/terminate": { "post": { - "summary": "Makes a specific change to a schedule or triggers an immediate action.", - "operationId": "PatchSchedule2", + "summary": "TerminateNexusOperation terminates an existing Nexus operation immediately.", + "description": "Termination happens immediately and the operation handler cannot react to it. A terminated operation will have\nits outcome set to a failure with a termination reason.", + "operationId": "TerminateNexusOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PatchScheduleResponse" + "$ref": "#/definitions/v1TerminateNexusOperationResponse" } }, "default": { @@ -1758,14 +1789,12 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to patch.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to patch.", + "name": "operationId", "in": "path", "required": true, "type": "string" @@ -1775,7 +1804,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePatchScheduleBody" + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationBody" } } ], @@ -1784,15 +1813,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/update": { - "post": { - "summary": "Changes the configuration or state of an existing schedule.", - "operationId": "UpdateSchedule2", + "/api/v1/namespaces/{namespace}/schedule-count": { + "get": { + "summary": "CountSchedules is a visibility API to count schedules in a specific namespace.", + "operationId": "CountSchedules2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateScheduleResponse" + "$ref": "#/definitions/v1CountSchedulesResponse" } }, "default": { @@ -1805,25 +1834,16 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to update.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to update.", - "in": "path", - "required": true, + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateScheduleBody" - } } ], "tags": [ @@ -1831,15 +1851,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/search-attributes": { + "/api/v1/namespaces/{namespace}/schedules": { "get": { - "summary": "ListSearchAttributes returns comprehensive information about search attributes.", - "operationId": "ListSearchAttributes2", + "summary": "List all schedules in a namespace.", + "operationId": "ListSchedules2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSearchAttributesResponse" + "$ref": "#/definitions/v1ListSchedulesResponse" } }, "default": { @@ -1852,25 +1872,49 @@ "parameters": [ { "name": "namespace", + "description": "The namespace to list schedules in.", "in": "path", "required": true, "type": "string" + }, + { + "name": "maximumPageSize", + "description": "How many to return at once.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token to get the next page of results.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Query to filter schedules.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": { + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}": { "get": { - "summary": "DescribeTaskQueue returns the following information about the target task queue, broken down by Build ID:\n - List of pollers\n - Workflow Reachability status\n - Backlog info for Workflow and/or Activity tasks", - "operationId": "DescribeTaskQueue2", + "summary": "Returns the schedule description and current state of an existing schedule.", + "operationId": "DescribeSchedule2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeTaskQueueResponse" + "$ref": "#/definitions/v1DescribeScheduleResponse" } }, "default": { @@ -1883,56 +1927,363 @@ "parameters": [ { "name": "namespace", + "description": "The namespace of the schedule to describe.", "in": "path", "required": true, "type": "string" }, { - "name": "taskQueue.name", + "name": "scheduleId", + "description": "The id of the schedule to describe.", "in": "path", "required": true, "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "delete": { + "summary": "Deletes a schedule, removing it from the system.", + "operationId": "DeleteSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DeleteScheduleResponse" + } }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ { - "name": "taskQueue.kind", - "description": "Default: TASK_QUEUE_KIND_NORMAL.\n\n - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities.", - "in": "query", - "required": false, - "type": "string", - "enum": [ - "TASK_QUEUE_KIND_UNSPECIFIED", - "TASK_QUEUE_KIND_NORMAL", - "TASK_QUEUE_KIND_STICKY" - ], - "default": "TASK_QUEUE_KIND_UNSPECIFIED" - }, - { - "name": "taskQueue.normalName", - "description": "Iff kind == TASK_QUEUE_KIND_STICKY, then this field contains the name of\nthe normal task queue that the sticky worker is running on.", - "in": "query", - "required": false, + "name": "namespace", + "description": "The namespace of the schedule to delete.", + "in": "path", + "required": true, "type": "string" }, { - "name": "taskQueueType", - "description": "If unspecified (TASK_QUEUE_TYPE_UNSPECIFIED), then default value (TASK_QUEUE_TYPE_WORKFLOW) will be used.\nOnly supported in default mode (use `task_queue_types` in ENHANCED mode instead).\n\n - TASK_QUEUE_TYPE_WORKFLOW: Workflow type of task queue.\n - TASK_QUEUE_TYPE_ACTIVITY: Activity type of task queue.\n - TASK_QUEUE_TYPE_NEXUS: Task queue type for dispatching Nexus requests.", - "in": "query", - "required": false, - "type": "string", - "enum": [ - "TASK_QUEUE_TYPE_UNSPECIFIED", - "TASK_QUEUE_TYPE_WORKFLOW", - "TASK_QUEUE_TYPE_ACTIVITY", - "TASK_QUEUE_TYPE_NEXUS" - ], - "default": "TASK_QUEUE_TYPE_UNSPECIFIED" + "name": "scheduleId", + "description": "The id of the schedule to delete.", + "in": "path", + "required": true, + "type": "string" }, { - "name": "reportStats", - "description": "Report stats for the requested task queue type(s).", + "name": "identity", + "description": "The identity of the client who initiated this request.", "in": "query", "required": false, - "type": "boolean" + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "Creates a new schedule.", + "operationId": "CreateSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CreateScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace the schedule should be created in.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the new schedule.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/matching-times": { + "get": { + "summary": "Lists matching times within a range.", + "operationId": "ListScheduleMatchingTimes2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListScheduleMatchingTimesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to query.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to query.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "startTime", + "description": "Time range to query.", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + }, + { + "name": "endTime", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/patch": { + "post": { + "summary": "Makes a specific change to a schedule or triggers an immediate action.", + "operationId": "PatchSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PatchScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to patch.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to patch.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServicePatchScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/update": { + "post": { + "summary": "Changes the configuration or state of an existing schedule.", + "operationId": "UpdateSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1UpdateScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to update.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to update.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUpdateScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/search-attributes": { + "get": { + "summary": "ListSearchAttributes returns comprehensive information about search attributes.", + "operationId": "ListSearchAttributes2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListSearchAttributesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": { + "get": { + "summary": "DescribeTaskQueue returns the following information about the target task queue, broken down by Build ID:\n - List of pollers\n - Workflow Reachability status\n - Backlog info for Workflow and/or Activity tasks", + "operationId": "DescribeTaskQueue2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeTaskQueueResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "taskQueue.name", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "taskQueue.kind", + "description": "Default: TASK_QUEUE_KIND_NORMAL.\n\n - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "TASK_QUEUE_KIND_UNSPECIFIED", + "TASK_QUEUE_KIND_NORMAL", + "TASK_QUEUE_KIND_STICKY" + ], + "default": "TASK_QUEUE_KIND_UNSPECIFIED" + }, + { + "name": "taskQueue.normalName", + "description": "Iff kind == TASK_QUEUE_KIND_STICKY, then this field contains the name of\nthe normal task queue that the sticky worker is running on.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "taskQueueType", + "description": "If unspecified (TASK_QUEUE_TYPE_UNSPECIFIED), then default value (TASK_QUEUE_TYPE_WORKFLOW) will be used.\nOnly supported in default mode (use `task_queue_types` in ENHANCED mode instead).\n\n - TASK_QUEUE_TYPE_WORKFLOW: Workflow type of task queue.\n - TASK_QUEUE_TYPE_ACTIVITY: Activity type of task queue.\n - TASK_QUEUE_TYPE_NEXUS: Task queue type for dispatching Nexus requests.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "TASK_QUEUE_TYPE_UNSPECIFIED", + "TASK_QUEUE_TYPE_WORKFLOW", + "TASK_QUEUE_TYPE_ACTIVITY", + "TASK_QUEUE_TYPE_NEXUS" + ], + "default": "TASK_QUEUE_TYPE_UNSPECIFIED" + }, + { + "name": "reportStats", + "description": "Report stats for the requested task queue type(s).", + "in": "query", + "required": false, + "type": "boolean" }, { "name": "reportConfig", @@ -4683,19 +5034,236 @@ } ], "tags": [ - "OperatorService" + "OperatorService" + ] + } + }, + "/cluster/nexus/endpoints/{id}/update": { + "post": { + "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", + "operationId": "UpdateNexusEndpoint", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1UpdateNexusEndpointResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + } + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/namespaces/{namespace}/activities": { + "get": { + "summary": "ListActivityExecutions is a visibility API to list activity executions in a specific namespace.", + "operationId": "ListActivityExecutions", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListActivityExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListActivityExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/activities-deprecated/pause": { + "post": { + "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "PauseActivity", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PauseActivityResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServicePauseActivityBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/activities-deprecated/reset": { + "post": { + "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", + "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "ResetActivity", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ResetActivityResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceResetActivityBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/activities-deprecated/unpause": { + "post": { + "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "UnpauseActivity", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1UnpauseActivityResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + } + } + ], + "tags": [ + "WorkflowService" ] } }, - "/cluster/nexus/endpoints/{id}/update": { + "/namespaces/{namespace}/activities-deprecated/update-options": { "post": { - "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", - "operationId": "UpdateNexusEndpoint", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", + "operationId": "UpdateActivityOptions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNexusEndpointResponse" + "$ref": "#/definitions/v1UpdateActivityOptionsResponse" } }, "default": { @@ -4707,8 +5275,8 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -4718,24 +5286,24 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/namespaces/{namespace}/activities": { + "/namespaces/{namespace}/activities/{activityId}": { "get": { - "summary": "ListActivityExecutions is a visibility API to list activity executions in a specific namespace.", - "operationId": "ListActivityExecutions", + "summary": "DescribeActivityExecution returns information about an activity execution.\nIt can be used to:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", + "operationId": "DescribeActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListActivityExecutionsResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -4753,27 +5321,84 @@ "type": "string" }, { - "name": "pageSize", - "description": "Max number of executions to return per page.", + "name": "activityId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", "in": "query", "required": false, - "type": "integer", - "format": "int32" + "type": "string" }, { - "name": "nextPageToken", - "description": "Token returned in ListActivityExecutionsResponse.", + "name": "includeInput", + "description": "Include the input field in the response.", "in": "query", "required": false, - "type": "string", - "format": "byte" + "type": "boolean" }, { - "name": "query", - "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the activity has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", "in": "query", "required": false, + "type": "string", + "format": "byte" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "StartActivityExecution starts a new activity execution.", + "description": "Returns an `ActivityExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", + "operationId": "StartActivityExecution", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StartActivityExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", + "description": "Identifier for this activity. Required. This identifier should be meaningful in the user's\nown system. It must be unique among activities in the same namespace, subject to the rules\nimposed by id_reuse_policy and id_conflict_policy.", + "in": "path", + "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" + } } ], "tags": [ @@ -4781,16 +5406,16 @@ ] } }, - "/namespaces/{namespace}/activities-deprecated/pause": { + "/namespaces/{namespace}/activities/{activityId}/cancel": { "post": { - "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", - "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "PauseActivity", + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Cancellation is cooperative: this call records the request, but the activity must detect and\nacknowledge it for the activity to reach CANCELED status. The cancellation signal is\ndelivered via `cancel_requested` in the heartbeat response; SDKs surface this via\nlanguage-idiomatic mechanisms (context cancellation, exceptions, abort signals).", + "operationId": "RequestCancelActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PauseActivityResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -4803,7 +5428,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", "in": "path", "required": true, "type": "string" @@ -4813,7 +5443,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -4822,16 +5452,15 @@ ] } }, - "/namespaces/{namespace}/activities-deprecated/reset": { + "/namespaces/{namespace}/activities/{activityId}/complete": { "post": { - "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", - "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "ResetActivity", + "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCompletedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ResetActivityResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" } }, "default": { @@ -4844,7 +5473,14 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", + "description": "Id of the activity to complete", "in": "path", "required": true, "type": "string" @@ -4854,7 +5490,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" } } ], @@ -4863,16 +5499,15 @@ ] } }, - "/namespaces/{namespace}/activities-deprecated/unpause": { + "/namespaces/{namespace}/activities/{activityId}/fail": { "post": { - "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "UnpauseActivity", + "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskFailedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UnpauseActivityResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" } }, "default": { @@ -4885,7 +5520,14 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", + "description": "Id of the activity to fail", "in": "path", "required": true, "type": "string" @@ -4895,7 +5537,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" } } ], @@ -4904,15 +5546,15 @@ ] } }, - "/namespaces/{namespace}/activities-deprecated/update-options": { + "/namespaces/{namespace}/activities/{activityId}/heartbeat": { "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", - "operationId": "UpdateActivityOptions", + "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RecordActivityTaskHeartbeatById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" } }, "default": { @@ -4930,12 +5572,19 @@ "required": true, "type": "string" }, + { + "name": "activityId", + "description": "Id of the activity we're heartbeating", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" } } ], @@ -4944,15 +5593,15 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}": { + "/namespaces/{namespace}/activities/{activityId}/outcome": { "get": { - "summary": "DescribeActivityExecution returns information about an activity execution.\nIt can be used to:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", - "operationId": "DescribeActivityExecution", + "summary": "PollActivityExecution long-polls for an activity execution to complete and returns the\noutcome (result or failure).", + "operationId": "PollActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeActivityExecutionResponse" + "$ref": "#/definitions/v1PollActivityExecutionResponse" } }, "default": { @@ -4981,43 +5630,70 @@ "in": "query", "required": false, "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/activities/{activityId}/resolve-as-canceled": { + "post": { + "summary": "See `RespondActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCanceledById", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" + } }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ { - "name": "includeInput", - "description": "Include the input field in the response.", - "in": "query", - "required": false, - "type": "boolean" + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" }, { - "name": "includeOutcome", - "description": "Include the outcome (result/failure) in the response if the activity has completed.", - "in": "query", - "required": false, - "type": "boolean" + "name": "activityId", + "description": "Id of the activity to confirm is cancelled", + "in": "path", + "required": true, + "type": "string" }, { - "name": "longPollToken", - "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/namespaces/{namespace}/activities/{activityId}/terminate": { "post": { - "summary": "StartActivityExecution starts a new activity execution.", - "description": "Returns an `ActivityExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", - "operationId": "StartActivityExecution", + "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", + "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt.", + "operationId": "TerminateActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartActivityExecutionResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -5036,7 +5712,6 @@ }, { "name": "activityId", - "description": "Identifier for this activity. Required. This identifier should be meaningful in the user's\nown system. It must be unique among activities in the same namespace, subject to the rules\nimposed by id_reuse_policy and id_conflict_policy.", "in": "path", "required": true, "type": "string" @@ -5046,7 +5721,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -5055,16 +5730,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/cancel": { + "/namespaces/{namespace}/activity-complete": { "post": { - "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", - "description": "Cancellation is cooperative: this call records the request, but the activity must detect and\nacknowledge it for the activity to reach CANCELED status. The cancellation signal is\ndelivered via `cancel_requested` in the heartbeat response; SDKs surface this via\nlanguage-idiomatic mechanisms (context cancellation, exceptions, abort signals).", - "operationId": "RequestCancelActivityExecution", + "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", + "description": "For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCompleted", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" } }, "default": { @@ -5081,18 +5756,12 @@ "required": true, "type": "string" }, - { - "name": "activityId", - "in": "path", - "required": true, - "type": "string" - }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" } } ], @@ -5101,15 +5770,15 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/complete": { - "post": { - "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById", + "/namespaces/{namespace}/activity-count": { + "get": { + "summary": "CountActivityExecutions is a visibility API to count activity executions in a specific namespace.", + "operationId": "CountActivityExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1CountActivityExecutionsResponse" } }, "default": { @@ -5122,25 +5791,16 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "description": "Id of the activity to complete", - "in": "path", - "required": true, + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" - } } ], "tags": [ @@ -5148,15 +5808,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/fail": { + "/namespaces/{namespace}/activity-fail": { "post": { - "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskFailedById", + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskFailed", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" } }, "default": { @@ -5169,14 +5830,6 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "activityId", - "description": "Id of the activity to fail", "in": "path", "required": true, "type": "string" @@ -5186,7 +5839,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" } } ], @@ -5195,15 +5848,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/heartbeat": { + "/namespaces/{namespace}/activity-heartbeat": { "post": { - "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RecordActivityTaskHeartbeatById", + "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", + "description": "If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen the current attempt times out. Depending on RetryPolicy, this may trigger a retry or\ntime out the activity.\n\nFor workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow\nhistory. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,\nin that event, the SDK should request cancellation of the activity.\n\nThe request may contain response `details` which will be persisted by the server and may be\nused by the activity to checkpoint progress. The `cancel_requested` field in the response\nindicates whether cancellation has been requested for the activity.", + "operationId": "RecordActivityTaskHeartbeat", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" } }, "default": { @@ -5216,14 +5870,6 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "activityId", - "description": "Id of the activity we're heartbeating", "in": "path", "required": true, "type": "string" @@ -5233,7 +5879,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], @@ -5242,15 +5888,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/outcome": { - "get": { - "summary": "PollActivityExecution long-polls for an activity execution to complete and returns the\noutcome (result or failure).", - "operationId": "PollActivityExecution", + "/namespaces/{namespace}/activity-resolve-as-canceled": { + "post": { + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "For workflow activities, this results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCanceled", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PollActivityExecutionResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" } }, "default": { @@ -5268,17 +5915,12 @@ "type": "string" }, { - "name": "activityId", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "runId", - "description": "Activity run ID. If empty the request targets the latest run.", - "in": "query", - "required": false, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" + } } ], "tags": [ @@ -5286,15 +5928,15 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/resolve-as-canceled": { - "post": { - "summary": "See `RespondActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCanceledById", + "/namespaces/{namespace}/archived-workflows": { + "get": { + "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", + "operationId": "ListArchivedWorkflowExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" + "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" } }, "default": { @@ -5307,25 +5949,29 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "description": "Id of the activity to confirm is cancelled", - "in": "path", - "required": true, - "type": "string" + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" - } + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5333,16 +5979,15 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/terminate": { - "post": { - "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", - "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt.", - "operationId": "TerminateActivityExecution", + "/namespaces/{namespace}/batch-operations": { + "get": { + "summary": "ListBatchOperations returns a list of batch operations", + "operationId": "ListBatchOperations", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1TerminateActivityExecutionResponse" + "$ref": "#/definitions/v1ListBatchOperationsResponse" } }, "default": { @@ -5355,23 +6000,26 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "in": "path", - "required": true, - "type": "string" + "name": "pageSize", + "description": "List page size", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" - } + "name": "nextPageToken", + "description": "Next page token", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ @@ -5379,16 +6027,15 @@ ] } }, - "/namespaces/{namespace}/activity-complete": { - "post": { - "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", - "description": "For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCompleted", + "/namespaces/{namespace}/batch-operations/{jobId}": { + "get": { + "summary": "DescribeBatchOperation returns the information about a batch operation", + "operationId": "DescribeBatchOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + "$ref": "#/definitions/v1DescribeBatchOperationResponse" } }, "default": { @@ -5401,33 +6048,31 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "jobId", + "description": "Batch job id", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" - } + "type": "string" } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/activity-count": { - "get": { - "summary": "CountActivityExecutions is a visibility API to count activity executions in a specific namespace.", - "operationId": "CountActivityExecutions", + }, + "post": { + "summary": "StartBatchOperation starts a new batch operation", + "operationId": "StartBatchOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CountActivityExecutionsResponse" + "$ref": "#/definitions/v1StartBatchOperationResponse" } }, "default": { @@ -5440,16 +6085,25 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "query", - "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", - "in": "query", - "required": false, + "name": "jobId", + "description": "Job ID defines the unique ID for the batch job", + "in": "path", + "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" + } } ], "tags": [ @@ -5457,16 +6111,15 @@ ] } }, - "/namespaces/{namespace}/activity-fail": { + "/namespaces/{namespace}/batch-operations/{jobId}/stop": { "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskFailed", + "summary": "StopBatchOperation stops a batch operation", + "operationId": "StopBatchOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" + "$ref": "#/definitions/v1StopBatchOperationResponse" } }, "default": { @@ -5479,6 +6132,14 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Batch job id", "in": "path", "required": true, "type": "string" @@ -5488,7 +6149,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" } } ], @@ -5497,16 +6158,15 @@ ] } }, - "/namespaces/{namespace}/activity-heartbeat": { + "/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { "post": { - "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", - "description": "If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen the current attempt times out. Depending on RetryPolicy, this may trigger a retry or\ntime out the activity.\n\nFor workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow\nhistory. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,\nin that event, the SDK should request cancellation of the activity.\n\nThe request may contain response `details` which will be persisted by the server and may be\nused by the activity to checkpoint progress. The `cancel_requested` field in the response\nindicates whether cancellation has been requested for the activity.", - "operationId": "RecordActivityTaskHeartbeat", + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", + "operationId": "SetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" } }, "default": { @@ -5523,12 +6183,19 @@ "required": true, "type": "string" }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" } } ], @@ -5537,16 +6204,15 @@ ] } }, - "/namespaces/{namespace}/activity-resolve-as-canceled": { - "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "For workflow activities, this results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCanceled", + "/namespaces/{namespace}/current-deployment/{seriesName}": { + "get": { + "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `current_version` returned by `DescribeWorkerDeployment`.", + "operationId": "GetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" } }, "default": { @@ -5564,12 +6230,10 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "seriesName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" - } + "type": "string" } ], "tags": [ @@ -5577,15 +6241,15 @@ ] } }, - "/namespaces/{namespace}/archived-workflows": { + "/namespaces/{namespace}/deployments": { "get": { - "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", - "operationId": "ListArchivedWorkflowExecutions", + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `ListWorkerDeployments`.", + "operationId": "ListDeployments", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + "$ref": "#/definitions/v1ListDeploymentsResponse" } }, "default": { @@ -5617,7 +6281,8 @@ "format": "byte" }, { - "name": "query", + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", "in": "query", "required": false, "type": "string" @@ -5628,15 +6293,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations": { + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { - "summary": "ListBatchOperations returns a list of batch operations", - "operationId": "ListBatchOperations", + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", + "operationId": "DescribeDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListBatchOperationsResponse" + "$ref": "#/definitions/v1DescribeDeploymentResponse" } }, "default": { @@ -5649,26 +6314,23 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "pageSize", - "description": "List page size", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", - "description": "Next page token", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", + "required": true, + "type": "string" } ], "tags": [ @@ -5676,15 +6338,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}": { + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { "get": { - "summary": "DescribeBatchOperation returns the information about a batch operation", - "operationId": "DescribeBatchOperation", + "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DrainageInfo` returned by `DescribeWorkerDeploymentVersion`.", + "operationId": "GetDeploymentReachability", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeBatchOperationResponse" + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" } }, "default": { @@ -5697,14 +6359,20 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", "in": "path", "required": true, "type": "string" @@ -5713,15 +6381,17 @@ "tags": [ "WorkflowService" ] - }, - "post": { - "summary": "StartBatchOperation starts a new batch operation", - "operationId": "StartBatchOperation", + } + }, + "/namespaces/{namespace}/nexus-operation-count": { + "get": { + "summary": "CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace.", + "operationId": "CountNexusOperations", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartBatchOperationResponse" + "$ref": "#/definitions/v1CountNexusOperationsResponse" } }, "default": { @@ -5734,25 +6404,16 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Job ID defines the unique ID for the batch job", - "in": "path", - "required": true, + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationsRequest for search attributes available for Nexus operations.", + "in": "query", + "required": false, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" - } } ], "tags": [ @@ -5760,15 +6421,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}/stop": { - "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation", + "/namespaces/{namespace}/nexus-operations": { + "get": { + "summary": "ListNexusOperations is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperations", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1ListNexusOperationsResponse" } }, "default": { @@ -5781,25 +6442,32 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", - "in": "path", - "required": true, - "type": "string" + "name": "pageSize", + "description": "Max number of operations to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" - } + "name": "nextPageToken", + "description": "Token returned in ListNexusOperationsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSearch attributes that are avaialble for Nexus operations include:\n- OperationId\n- RunId\n- Endpoint\n- Service\n- Operation\n- RequestId\n- StartTime\n- ExecutionTime\n- CloseTime\n- ExecutionStatus\n- ExecutionDuration\n- StateTransitionCount", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5807,15 +6475,15 @@ ] } }, - "/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { - "post": { - "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", - "operationId": "SetCurrentDeployment", + "/namespaces/{namespace}/nexus-operations/{operationId}": { + "get": { + "summary": "DescribeNexusOperation returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", + "operationId": "DescribeNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetCurrentDeploymentResponse" + "$ref": "#/definitions/v1DescribeNexusOperationResponse" } }, "default": { @@ -5833,35 +6501,54 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" - } + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the operation has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/current-deployment/{seriesName}": { - "get": { - "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `current_version` returned by `DescribeWorkerDeployment`.", - "operationId": "GetCurrentDeployment", + }, + "post": { + "summary": "StartNexusOperation starts a new Nexus operation.", + "description": "Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", + "operationId": "StartNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetCurrentDeploymentResponse" + "$ref": "#/definitions/v1StartNexusOperationResponse" } }, "default": { @@ -5879,10 +6566,18 @@ "type": "string" }, { - "name": "seriesName", + "name": "operationId", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartNexusOperationBody" + } } ], "tags": [ @@ -5890,15 +6585,16 @@ ] } }, - "/namespaces/{namespace}/deployments": { - "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `ListWorkerDeployments`.", - "operationId": "ListDeployments", + "/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { + "post": { + "summary": "RequestCancelNexusOperation requests cancellation of a Nexus operation.", + "description": "Requesting to cancel an operation does not automatically transition the operation to canceled status.\nThe operation will only transition to canceled status if it supports cancellation and the handler\nprocesses the cancellation request.", + "operationId": "RequestCancelNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListDeploymentsResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationResponse" } }, "default": { @@ -5916,25 +6612,18 @@ "type": "string" }, { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" - }, - { - "name": "nextPageToken", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "operationId", + "in": "path", + "required": true, + "type": "string" }, { - "name": "seriesName", - "description": "Optional. Use to filter based on exact series name match.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationBody" + } } ], "tags": [ @@ -5942,15 +6631,15 @@ ] } }, - "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "/namespaces/{namespace}/nexus-operations/{operationId}/poll": { "get": { - "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", - "operationId": "DescribeDeployment", + "summary": "PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", + "operationId": "PollNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeDeploymentResponse" + "$ref": "#/definitions/v1PollNexusOperationResponse" } }, "default": { @@ -5968,18 +6657,30 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "name": "operationId", "in": "path", "required": true, "type": "string" + }, + { + "name": "runId", + "description": "Operation run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "waitStage", + "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked.\n\n - NEXUS_OPERATION_WAIT_STAGE_STARTED: Wait for the operation to be started.\n - NEXUS_OPERATION_WAIT_STAGE_CLOSED: Wait for the operation to be in a terminal state, either successful or unsuccessful.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "NEXUS_OPERATION_WAIT_STAGE_STARTED", + "NEXUS_OPERATION_WAIT_STAGE_CLOSED" + ], + "default": "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED" } ], "tags": [ @@ -5987,15 +6688,16 @@ ] } }, - "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { - "get": { - "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DrainageInfo` returned by `DescribeWorkerDeploymentVersion`.", - "operationId": "GetDeploymentReachability", + "/namespaces/{namespace}/nexus-operations/{operationId}/terminate": { + "post": { + "summary": "TerminateNexusOperation terminates an existing Nexus operation immediately.", + "description": "Termination happens immediately and the operation handler cannot react to it. A terminated operation will have\nits outcome set to a failure with a termination reason.", + "operationId": "TerminateNexusOperation", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + "$ref": "#/definitions/v1TerminateNexusOperationResponse" } }, "default": { @@ -6013,18 +6715,18 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "name": "operationId", "in": "path", "required": true, "type": "string" }, { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationBody" + } } ], "tags": [ @@ -8769,6 +9471,21 @@ }, "description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job." }, + "LinkNexusOperation": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "operationId": { + "type": "string" + }, + "runId": { + "type": "string" + } + }, + "description": "A link to a standalone Nexus operation." + }, "LinkWorkflowEvent": { "type": "object", "properties": { @@ -9353,6 +10070,27 @@ } } }, + "WorkflowServiceRequestCancelNexusOperationBody": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "Operation run ID, targets the latest run if empty." + }, + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe cancellation requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API." + } + } + }, "WorkflowServiceRequestCancelWorkflowExecutionBody": { "type": "object", "properties": { @@ -10007,6 +10745,62 @@ } } }, + "WorkflowServiceStartNexusOperationBody": { + "type": "object", + "properties": { + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "A unique identifier for this start request. Typically UUIDv4." + }, + "endpoint": { + "type": "string", + "description": "Endpoint name, resolved to a URL via the cluster's endpoint registry." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this operation.\nThis is the only timeout settable for a Nexus operation." + }, + "input": { + "$ref": "#/definitions/v1Payload", + "description": "Serialized input to the operation. Passed as the request payload." + }, + "idReusePolicy": { + "$ref": "#/definitions/v1NexusOperationIdReusePolicy", + "description": "Defines whether to allow re-using the operation id from a previously *closed* operation.\nThe default policy is NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE." + }, + "idConflictPolicy": { + "$ref": "#/definitions/v1NexusOperationIdConflictPolicy", + "description": "Defines how to resolve an operation id conflict with a *running* operation.\nThe default policy is NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes for indexing." + }, + "nexusHeader": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Header to attach to the Nexus request.\nUsers are responsible for encrypting sensitive data in this header as it is stored in workflow history and\ntransmitted to external services as-is.\nThis is useful for propagating tracing information.\nNote these headers are not the same as Temporal headers on internal activities and child workflows, these are\ntransmitted to Nexus operations that may be external and are not traditional payloads." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation." + } + } + }, "WorkflowServiceStartWorkflowExecutionBody": { "type": "object", "properties": { @@ -10152,6 +10946,27 @@ } } }, + "WorkflowServiceTerminateNexusOperationBody": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "Operation run ID, targets the latest run if empty." + }, + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe termination requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the termination, recorded in the operation's result failure outcome." + } + } + }, "WorkflowServiceTerminateWorkflowExecutionBody": { "type": "object", "properties": { @@ -10524,6 +11339,84 @@ }, "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationUpdateWorkflowExecutionOptions.\n - temporal.api.workflow.v1.PostResetOperation.UpdateWorkflowOptions." }, + "apiNexusV1NexusOperationCancellationInfo": { + "type": "object", + "properties": { + "requestedTime": { + "type": "string", + "format": "date-time", + "description": "The time when cancellation was requested." + }, + "state": { + "$ref": "#/definitions/v1NexusOperationCancellationState" + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/v1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + }, + "reason": { + "type": "string", + "description": "A reason that may be specified in the CancelNexusOpertionRequest." + } + }, + "description": "NexusOperationCancellationInfo contains the state of a Nexus operation cancellation." + }, + "apiWorkflowV1NexusOperationCancellationInfo": { + "type": "object", + "properties": { + "requestedTime": { + "type": "string", + "format": "date-time", + "description": "The time when cancellation was requested." + }, + "state": { + "$ref": "#/definitions/v1NexusOperationCancellationState" + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/v1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + } + }, + "description": "NexusOperationCancellationInfo contains the state of a nexus operation cancellation." + }, "protobufAny": { "type": "object", "properties": { @@ -11920,6 +12813,40 @@ } } }, + "v1CountNexusOperationsResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "int64", + "description": "If `query` is not grouping by any field, the count is an approximate number\nof operations that match the query.\nIf `query` is grouping by a field, the count is simply the sum of the counts\nof the groups returned in the response. This number can be smaller than the\ntotal number of operations matching the query." + }, + "groups": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CountNexusOperationsResponseAggregationGroup" + }, + "description": "Contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." + } + } + }, + "v1CountNexusOperationsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CountSchedulesResponse": { "type": "object", "properties": { @@ -12256,13 +13183,43 @@ "isGlobalNamespace": { "type": "boolean" }, - "failoverHistory": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1FailoverStatus" - }, - "description": "Contains the historical state of failover_versions for the cluster, truncated to contain only the last N\nstates to ensure that the list does not grow unbounded." + "failoverHistory": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1FailoverStatus" + }, + "description": "Contains the historical state of failover_versions for the cluster, truncated to contain only the last N\nstates to ensure that the list does not grow unbounded." + } + } + }, + "v1DescribeNexusOperationResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the operation, useful when run_id was not specified in the request." + }, + "info": { + "$ref": "#/definitions/v1NexusOperationInfo", + "description": "Information about the operation." + }, + "input": { + "$ref": "#/definitions/v1Payload", + "description": "Serialized operation input, passed as the request payload.\nOnly set if include_input was true in the request." + }, + "result": { + "$ref": "#/definitions/v1Payload", + "description": "The result if the operation completed successfully." + }, + "failure": { + "$ref": "#/definitions/v1Failure", + "description": "The failure if the operation completed unsuccessfully." + }, + "longPollToken": { + "type": "string", + "format": "byte", + "description": "Token for follow-on long-poll requests. Absent only if the operation is complete." } } }, @@ -13246,6 +14203,9 @@ }, "batchJob": { "$ref": "#/definitions/LinkBatchJob" + }, + "nexusOperation": { + "$ref": "#/definitions/LinkNexusOperation" } }, "description": "Link can be associated with history events. It might contain information about an external entity\nrelated to the history event. For example, workflow A makes a Nexus call that starts workflow B:\nin this case, a history event in workflow A could contain a Link to the workflow started event in\nworkflow B, and vice-versa." @@ -13350,6 +14310,23 @@ } } }, + "v1ListNexusOperationsResponse": { + "type": "object", + "properties": { + "operations": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1NexusOperationListInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte", + "description": "Token to use to fetch the next page. If empty, there is no next page." + } + } + }, "v1ListScheduleMatchingTimesResponse": { "type": "object", "properties": { @@ -13871,43 +14848,6 @@ }, "description": "Nexus operation completed as canceled. May or may not have been due to a cancellation request by the workflow." }, - "v1NexusOperationCancellationInfo": { - "type": "object", - "properties": { - "requestedTime": { - "type": "string", - "format": "date-time", - "description": "The time when cancellation was requested." - }, - "state": { - "$ref": "#/definitions/v1NexusOperationCancellationState" - }, - "attempt": { - "type": "integer", - "format": "int32", - "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." - }, - "lastAttemptCompleteTime": { - "type": "string", - "format": "date-time", - "description": "The time when the last attempt completed." - }, - "lastAttemptFailure": { - "$ref": "#/definitions/v1Failure", - "description": "The last attempt's failure, if any." - }, - "nextAttemptScheduleTime": { - "type": "string", - "format": "date-time", - "description": "The time when the next attempt is scheduled." - }, - "blockedReason": { - "type": "string", - "description": "If the state is BLOCKED, blocked reason provides additional information." - } - }, - "description": "NexusOperationCancellationInfo contains the state of a nexus operation cancellation." - }, "v1NexusOperationCancellationState": { "type": "string", "enum": [ @@ -13991,6 +14931,202 @@ }, "description": "Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers." }, + "v1NexusOperationIdConflictPolicy": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", + "NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL", + "NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING" + ], + "default": "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", + "description": "Defines what to do when trying to start a Nexus operation with the same ID as a *running* operation.\nNote that it is *never* valid to have two running instances of the same operation ID.\n\nSee `NexusOperationIdReusePolicy` for handling operation ID duplication with a *closed* operation.\n\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL: Don't start a new operation; instead return `NexusOperationAlreadyStarted` error.\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new operation; instead return a handle for the running operation." + }, + "v1NexusOperationIdReusePolicy": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", + "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE", + "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY", + "NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE" + ], + "default": "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", + "description": "Defines whether to allow re-using an operation ID from a previously *closed* Nexus operation.\nIf the request is denied, the server returns a `NexusOperationAlreadyStarted` error.\n\nSee `NexusOperationIdConflictPolicy` for handling ID duplication with a *running* operation.\n\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE: Always allow starting an operation using the same operation ID.\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting an operation using the same ID only when the last operation's final state is one\nof {failed, canceled, terminated, timed out}.\n - NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the ID for this operation. Future start requests could potentially change the policy,\nallowing re-use of the ID." + }, + "v1NexusOperationInfo": { + "type": "object", + "properties": { + "operationId": { + "type": "string", + "description": "Unique identifier of this Nexus operation within its namespace along with run ID (below)." + }, + "runId": { + "type": "string" + }, + "endpoint": { + "type": "string", + "description": "Endpoint name, resolved to a URL via the cluster's endpoint registry." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "status": { + "$ref": "#/definitions/v1NexusOperationStatus", + "description": "A general status for this operation, indicates whether it is currently running or in one of the terminal statuses." + }, + "state": { + "$ref": "#/definitions/v1PendingNexusOperationState", + "description": "More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this operation.\nThis is the only timeout settable for a Nexus operation." + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to start/deliver the operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "scheduleTime": { + "type": "string", + "format": "date-time", + "description": "Time the operation was originally scheduled via a StartNexusOperation request." + }, + "expirationTime": { + "type": "string", + "format": "date-time", + "description": "Scheduled time + schedule to close timeout." + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "Time when the operation transitioned to a closed state." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/v1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "executionDuration": { + "type": "string", + "description": "How long this operation has been running for, including all attempts and backoff between attempts." + }, + "cancellationInfo": { + "$ref": "#/definitions/apiNexusV1NexusOperationCancellationInfo" + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + }, + "requestId": { + "type": "string", + "description": "Request ID allocated by the server when handling the StartNexusOperation request.\nUsed as an idempotency token for submitting start requests to the handler." + }, + "operationToken": { + "type": "string", + "description": "Operation token. Only set for asynchronous operations after a successful StartOperation call." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Incremented each time the operation's state is mutated in persistence." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + }, + "nexusHeader": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Header for context propagation and tracing purposes." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Link" + }, + "description": "Links attached by the handler of this operation on start or completion." + } + }, + "description": "Information about a standalone Nexus operation." + }, + "v1NexusOperationListInfo": { + "type": "object", + "properties": { + "operationId": { + "type": "string", + "description": "A unique identifier of this operation within its namespace along with run ID (below)." + }, + "runId": { + "type": "string", + "description": "The run ID of the standalone Nexus operation." + }, + "endpoint": { + "type": "string", + "description": "Endpoint name." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "scheduleTime": { + "type": "string", + "format": "date-time", + "description": "Time the operation was originally scheduled via a StartNexusOperation request." + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "If the operation is in a terminal status, this field represents the time the operation transitioned to that status." + }, + "status": { + "$ref": "#/definitions/v1NexusOperationStatus", + "description": "Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not\navailable in the list response." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes from the start request." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Updated on terminal status." + }, + "stateSizeBytes": { + "type": "string", + "format": "int64", + "description": "Updated once on scheduled and once on terminal status." + }, + "executionDuration": { + "type": "string", + "description": "The difference between close time and scheduled time.\nThis field is only populated if the operation is closed." + } + }, + "description": "Limited Nexus operation information returned in the list response.\nWhen adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in\nNexusOperationInfo but not at the top-level)." + }, "v1NexusOperationScheduledEventAttributes": { "type": "object", "properties": { @@ -14068,6 +15204,20 @@ }, "description": "Event marking an asynchronous operation was started by the responding Nexus handler.\nIf the operation completes synchronously, this event is not generated.\nIn rare situations, such as request timeouts, the service may fail to record the actual start time and will fabricate\nthis event upon receiving the operation completion via callback." }, + "v1NexusOperationStatus": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_STATUS_UNSPECIFIED", + "NEXUS_OPERATION_STATUS_RUNNING", + "NEXUS_OPERATION_STATUS_COMPLETED", + "NEXUS_OPERATION_STATUS_FAILED", + "NEXUS_OPERATION_STATUS_CANCELED", + "NEXUS_OPERATION_STATUS_TERMINATED", + "NEXUS_OPERATION_STATUS_TIMED_OUT" + ], + "default": "NEXUS_OPERATION_STATUS_UNSPECIFIED", + "description": "Status of a standalone Nexus operation.\nThe status is updated once, when the operation is originally scheduled, and again when the operation reaches a\nterminal status.\n\n - NEXUS_OPERATION_STATUS_RUNNING: The operation is not in a terminal status. The operation may attempting to start, backing off between attempts,\nor already started.\n - NEXUS_OPERATION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." + }, "v1NexusOperationTimedOutEventAttributes": { "type": "object", "properties": { @@ -14087,6 +15237,16 @@ }, "description": "Nexus operation timed out." }, + "v1NexusOperationWaitStage": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "NEXUS_OPERATION_WAIT_STAGE_STARTED", + "NEXUS_OPERATION_WAIT_STAGE_CLOSED" + ], + "default": "NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED", + "description": "Stage that can be specified when waiting on a nexus operation.\n\n - NEXUS_OPERATION_WAIT_STAGE_STARTED: Wait for the operation to be started.\n - NEXUS_OPERATION_WAIT_STAGE_CLOSED: Wait for the operation to be in a terminal state, either successful or unsuccessful." + }, "v1OnConflictOptions": { "type": "object", "properties": { @@ -14342,7 +15502,7 @@ "description": "The time when the next attempt is scheduled." }, "cancellationInfo": { - "$ref": "#/definitions/v1NexusOperationCancellationInfo" + "$ref": "#/definitions/apiWorkflowV1NexusOperationCancellationInfo" }, "scheduledEventId": { "type": "string", @@ -14439,6 +15599,31 @@ } } }, + "v1PollNexusOperationResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the operation, useful when run_id was not specified in the request." + }, + "waitStage": { + "$ref": "#/definitions/v1NexusOperationWaitStage", + "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked." + }, + "operationToken": { + "type": "string", + "description": "Operation token. Only populated for asynchronous operations after a successful StartOperation call." + }, + "result": { + "$ref": "#/definitions/v1Payload", + "description": "The result if the operation completed successfully." + }, + "failure": { + "$ref": "#/definitions/v1Failure", + "description": "The failure if the operation completed unsuccessfully." + } + } + }, "v1PollWorkflowTaskQueueResponse": { "type": "object", "properties": { @@ -14879,6 +16064,9 @@ } } }, + "v1RequestCancelNexusOperationResponse": { + "type": "object" + }, "v1RequestCancelWorkflowExecutionResponse": { "type": "object" }, @@ -15836,6 +17024,19 @@ } } }, + "v1StartNexusOperationResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the operation that was started - or used (via NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING)." + }, + "started": { + "type": "boolean", + "description": "If true, a new operation was started." + } + } + }, "v1StartWorkflowExecutionResponse": { "type": "object", "properties": { @@ -16179,6 +17380,9 @@ "v1TerminateActivityExecutionResponse": { "type": "object" }, + "v1TerminateNexusOperationResponse": { + "type": "object" + }, "v1TerminateWorkflowExecutionResponse": { "type": "object" }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index c220f6773..b7caa3b10 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1343,6 +1343,323 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operation-count: + get: + tags: + - WorkflowService + description: CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + operationId: CountNexusOperations + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + See also ListNexusOperationsRequest for search attributes available for Nexus operations. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations: + get: + tags: + - WorkflowService + description: ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperations + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of operations to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListNexusOperationsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + Search attributes that are avaialble for Nexus operations include: + - OperationId + - RunId + - Endpoint + - Service + - Operation + - RequestId + - StartTime + - ExecutionTime + - CloseTime + - ExecutionStatus + - ExecutionDuration + - StateTransitionCount + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}: + get: + tags: + - WorkflowService + description: |- + DescribeNexusOperation returns information about a Nexus operation. + Supported use cases include: + - Get current operation info without waiting + - Long-poll for next state change and return new operation info + Response can optionally include operation input or outcome (if the operation has completed). + operationId: DescribeNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the operation has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that operation state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartNexusOperation starts a new Nexus operation. + + Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + namespace unless permitted by the specified ID conflict policy. + operationId: StartNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}/cancel: + post: + tags: + - WorkflowService + description: |- + RequestCancelNexusOperation requests cancellation of a Nexus operation. + + Requesting to cancel an operation does not automatically transition the operation to canceled status. + The operation will only transition to canceled status if it supports cancellation and the handler + processes the cancellation request. + operationId: RequestCancelNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}/poll: + get: + tags: + - WorkflowService + description: |- + PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + the outcome (result or failure). + operationId: PollNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: waitStage + in: query + description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + schema: + enum: + - NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED + - NEXUS_OPERATION_WAIT_STAGE_STARTED + - NEXUS_OPERATION_WAIT_STAGE_CLOSED + type: string + format: enum + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateNexusOperation terminates an existing Nexus operation immediately. + + Termination happens immediately and the operation handler cannot react to it. A terminated operation will have + its outcome set to a failure with a termination reason. + operationId: TerminateNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/schedule-count: get: tags: @@ -5436,12 +5753,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/schedule-count: + /namespaces/{namespace}/nexus-operation-count: get: tags: - WorkflowService - description: CountSchedules is a visibility API to count schedules in a specific namespace. - operationId: CountSchedules + description: CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + operationId: CountNexusOperations parameters: - name: namespace in: path @@ -5450,7 +5767,9 @@ paths: type: string - name: query in: query - description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + See also ListNexusOperationsRequest for search attributes available for Nexus operations. schema: type: string responses: @@ -5459,27 +5778,342 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CountSchedulesResponse' + $ref: '#/components/schemas/CountNexusOperationsResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/schedules: + /namespaces/{namespace}/nexus-operations: get: tags: - WorkflowService - description: List all schedules in a namespace. - operationId: ListSchedules + description: ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperations parameters: - name: namespace in: path - description: The namespace to list schedules in. required: true schema: type: string - - name: maximumPageSize + - name: pageSize + in: query + description: Max number of operations to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListNexusOperationsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: |- + Visibility query, see https://docs.temporal.io/list-filter for the syntax. + Search attributes that are avaialble for Nexus operations include: + - OperationId + - RunId + - Endpoint + - Service + - Operation + - RequestId + - StartTime + - ExecutionTime + - CloseTime + - ExecutionStatus + - ExecutionDuration + - StateTransitionCount + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListNexusOperationsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}: + get: + tags: + - WorkflowService + description: |- + DescribeNexusOperation returns information about a Nexus operation. + Supported use cases include: + - Get current operation info without waiting + - Long-poll for next state change and return new operation info + Response can optionally include operation input or outcome (if the operation has completed). + operationId: DescribeNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the operation has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that operation state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartNexusOperation starts a new Nexus operation. + + Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + namespace unless permitted by the specified ID conflict policy. + operationId: StartNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/cancel: + post: + tags: + - WorkflowService + description: |- + RequestCancelNexusOperation requests cancellation of a Nexus operation. + + Requesting to cancel an operation does not automatically transition the operation to canceled status. + The operation will only transition to canceled status if it supports cancellation and the handler + processes the cancellation request. + operationId: RequestCancelNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/poll: + get: + tags: + - WorkflowService + description: |- + PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + the outcome (result or failure). + operationId: PollNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Operation run ID. If empty the request targets the latest run. + schema: + type: string + - name: waitStage + in: query + description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + schema: + enum: + - NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED + - NEXUS_OPERATION_WAIT_STAGE_STARTED + - NEXUS_OPERATION_WAIT_STAGE_CLOSED + type: string + format: enum + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateNexusOperation terminates an existing Nexus operation immediately. + + Termination happens immediately and the operation handler cannot react to it. A terminated operation will have + its outcome set to a failure with a termination reason. + operationId: TerminateNexusOperation + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: operationId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/schedule-count: + get: + tags: + - WorkflowService + description: CountSchedules is a visibility API to count schedules in a specific namespace. + operationId: CountSchedules + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountSchedulesResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/schedules: + get: + tags: + - WorkflowService + description: List all schedules in a namespace. + operationId: ListSchedules + parameters: + - name: namespace + in: path + description: The namespace to list schedules in. + required: true + schema: + type: string + - name: maximumPageSize in: query description: How many to return at once. schema: @@ -9077,6 +9711,33 @@ components: $ref: '#/components/schemas/Payload' count: type: string + CountNexusOperationsResponse: + type: object + properties: + count: + type: string + description: |- + If `query` is not grouping by any field, the count is an approximate number + of operations that match the query. + If `query` is grouping by a field, the count is simply the sum of the counts + of the groups returned in the response. This number can be smaller than the + total number of operations matching the query. + groups: + type: array + items: + $ref: '#/components/schemas/CountNexusOperationsResponse_AggregationGroup' + description: |- + Contains the groups if the request is grouping by a field. + The list might not be complete, and the counts of each group is approximate. + CountNexusOperationsResponse_AggregationGroup: + type: object + properties: + groupValues: + type: array + items: + $ref: '#/components/schemas/Payload' + count: + type: string CountSchedulesResponse: type: object properties: @@ -9456,6 +10117,34 @@ components: description: |- Contains the historical state of failover_versions for the cluster, truncated to contain only the last N states to ensure that the list does not grow unbounded. + DescribeNexusOperationResponse: + type: object + properties: + runId: + type: string + description: The run ID of the operation, useful when run_id was not specified in the request. + info: + allOf: + - $ref: '#/components/schemas/NexusOperationInfo' + description: Information about the operation. + input: + allOf: + - $ref: '#/components/schemas/Payload' + description: |- + Serialized operation input, passed as the request payload. + Only set if include_input was true in the request. + result: + allOf: + - $ref: '#/components/schemas/Payload' + description: The result if the operation completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the operation completed unsuccessfully. + longPollToken: + type: string + description: Token for follow-on long-poll requests. Absent only if the operation is complete. + format: bytes DescribeScheduleResponse: type: object properties: @@ -10362,6 +11051,8 @@ components: $ref: '#/components/schemas/Link_WorkflowEvent' batchJob: $ref: '#/components/schemas/Link_BatchJob' + nexusOperation: + $ref: '#/components/schemas/Link_NexusOperation' description: |- Link can be associated with history events. It might contain information about an external entity related to the history event. For example, workflow A makes a Nexus call that starts workflow B: @@ -10372,10 +11063,20 @@ components: properties: jobId: type: string - description: |- - A link to a built-in batch job. - Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc). - This link can be put on workflow history events generated by actions taken by a batch job. + description: |- + A link to a built-in batch job. + Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc). + This link can be put on workflow history events generated by actions taken by a batch job. + Link_NexusOperation: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: A link to a standalone Nexus operation. Link_WorkflowEvent: type: object properties: @@ -10453,6 +11154,17 @@ components: type: array items: $ref: '#/components/schemas/Endpoint' + ListNexusOperationsResponse: + type: object + properties: + operations: + type: array + items: + $ref: '#/components/schemas/NexusOperationListInfo' + nextPageToken: + type: string + description: Token to use to fetch the next page. If empty, there is no next page. + format: bytes ListScheduleMatchingTimesResponse: type: object properties: @@ -11017,6 +11729,180 @@ components: type: string description: Operation token - may be empty if the operation completed synchronously. description: Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers. + NexusOperationInfo: + type: object + properties: + operationId: + type: string + description: Unique identifier of this Nexus operation within its namespace along with run ID (below). + runId: + type: string + endpoint: + type: string + description: Endpoint name, resolved to a URL via the cluster's endpoint registry. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + status: + enum: + - NEXUS_OPERATION_STATUS_UNSPECIFIED + - NEXUS_OPERATION_STATUS_RUNNING + - NEXUS_OPERATION_STATUS_COMPLETED + - NEXUS_OPERATION_STATUS_FAILED + - NEXUS_OPERATION_STATUS_CANCELED + - NEXUS_OPERATION_STATUS_TERMINATED + - NEXUS_OPERATION_STATUS_TIMED_OUT + type: string + description: A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. + format: enum + state: + enum: + - PENDING_NEXUS_OPERATION_STATE_UNSPECIFIED + - PENDING_NEXUS_OPERATION_STATE_SCHEDULED + - PENDING_NEXUS_OPERATION_STATE_BACKING_OFF + - PENDING_NEXUS_OPERATION_STATE_STARTED + - PENDING_NEXUS_OPERATION_STATE_BLOCKED + type: string + description: More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. + format: enum + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Schedule-to-close timeout for this operation. + This is the only timeout settable for a Nexus operation. + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + attempt: + type: integer + description: |- + The number of attempts made to start/deliver the operation request. + This number represents a minimum bound since the attempt is incremented after the request completes. + format: int32 + scheduleTime: + type: string + description: Time the operation was originally scheduled via a StartNexusOperation request. + format: date-time + expirationTime: + type: string + description: Scheduled time + schedule to close timeout. + format: date-time + closeTime: + type: string + description: Time when the operation transitioned to a closed state. + format: date-time + lastAttemptCompleteTime: + type: string + description: The time when the last attempt completed. + format: date-time + lastAttemptFailure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The last attempt's failure, if any. + nextAttemptScheduleTime: + type: string + description: The time when the next attempt is scheduled. + format: date-time + executionDuration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: How long this operation has been running for, including all attempts and backoff between attempts. + cancellationInfo: + $ref: '#/components/schemas/NexusOperationCancellationInfo' + blockedReason: + type: string + description: If the state is BLOCKED, blocked reason provides additional information. + requestId: + type: string + description: |- + Request ID allocated by the server when handling the StartNexusOperation request. + Used as an idempotency token for submitting start requests to the handler. + operationToken: + type: string + description: Operation token. Only set for asynchronous operations after a successful StartOperation call. + stateTransitionCount: + type: string + description: Incremented each time the operation's state is mutated in persistence. + searchAttributes: + $ref: '#/components/schemas/SearchAttributes' + nexusHeader: + type: object + additionalProperties: + type: string + description: Header for context propagation and tracing purposes. + userMetadata: + allOf: + - $ref: '#/components/schemas/UserMetadata' + description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + links: + type: array + items: + $ref: '#/components/schemas/Link' + description: Links attached by the handler of this operation on start or completion. + description: Information about a standalone Nexus operation. + NexusOperationListInfo: + type: object + properties: + operationId: + type: string + description: A unique identifier of this operation within its namespace along with run ID (below). + runId: + type: string + description: The run ID of the standalone Nexus operation. + endpoint: + type: string + description: Endpoint name. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + scheduleTime: + type: string + description: Time the operation was originally scheduled via a StartNexusOperation request. + format: date-time + closeTime: + type: string + description: If the operation is in a terminal status, this field represents the time the operation transitioned to that status. + format: date-time + status: + enum: + - NEXUS_OPERATION_STATUS_UNSPECIFIED + - NEXUS_OPERATION_STATUS_RUNNING + - NEXUS_OPERATION_STATUS_COMPLETED + - NEXUS_OPERATION_STATUS_FAILED + - NEXUS_OPERATION_STATUS_CANCELED + - NEXUS_OPERATION_STATUS_TERMINATED + - NEXUS_OPERATION_STATUS_TIMED_OUT + type: string + description: |- + Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not + available in the list response. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes from the start request. + stateTransitionCount: + type: string + description: Updated on terminal status. + stateSizeBytes: + type: string + description: Updated once on scheduled and once on terminal status. + executionDuration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + The difference between close time and scheduled time. + This field is only populated if the operation is closed. + description: |- + Limited Nexus operation information returned in the list response. + When adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in + NexusOperationInfo but not at the top-level). NexusOperationScheduledEventAttributes: type: object properties: @@ -11534,6 +12420,31 @@ components: description: The run ID of the activity, useful when run_id was not specified in the request. outcome: $ref: '#/components/schemas/ActivityExecutionOutcome' + PollNexusOperationResponse: + type: object + properties: + runId: + type: string + description: The run ID of the operation, useful when run_id was not specified in the request. + waitStage: + enum: + - NEXUS_OPERATION_WAIT_STAGE_UNSPECIFIED + - NEXUS_OPERATION_WAIT_STAGE_STARTED + - NEXUS_OPERATION_WAIT_STAGE_CLOSED + type: string + description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + format: enum + operationToken: + type: string + description: Operation token. Only populated for asynchronous operations after a successful StartOperation call. + result: + allOf: + - $ref: '#/components/schemas/Payload' + description: The result if the operation completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the operation completed unsuccessfully. PollWorkflowTaskQueueResponse: type: object properties: @@ -12120,6 +13031,28 @@ components: reason: type: string description: Reason for requesting the cancellation + RequestCancelNexusOperationRequest: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: Operation run ID, targets the latest run if empty. + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: Used to de-dupe cancellation requests. + reason: + type: string + description: Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API. + RequestCancelNexusOperationResponse: + type: object + properties: {} RequestCancelWorkflowExecutionRequest: type: object properties: @@ -13833,6 +14766,89 @@ components: allOf: - $ref: '#/components/schemas/Priority' description: Priority metadata + StartNexusOperationRequest: + type: object + properties: + namespace: + type: string + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: A unique identifier for this start request. Typically UUIDv4. + operationId: + type: string + endpoint: + type: string + description: Endpoint name, resolved to a URL via the cluster's endpoint registry. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Schedule-to-close timeout for this operation. + This is the only timeout settable for a Nexus operation. + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + input: + allOf: + - $ref: '#/components/schemas/Payload' + description: Serialized input to the operation. Passed as the request payload. + idReusePolicy: + enum: + - NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED + - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE + - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY + - NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE + type: string + description: |- + Defines whether to allow re-using the operation id from a previously *closed* operation. + The default policy is NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE. + format: enum + idConflictPolicy: + enum: + - NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED + - NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL + - NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING + type: string + description: |- + Defines how to resolve an operation id conflict with a *running* operation. + The default policy is NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes for indexing. + nexusHeader: + type: object + additionalProperties: + type: string + description: |- + Header to attach to the Nexus request. + Users are responsible for encrypting sensitive data in this header as it is stored in workflow history and + transmitted to external services as-is. + This is useful for propagating tracing information. + Note these headers are not the same as Temporal headers on internal activities and child workflows, these are + transmitted to Nexus operations that may be external and are not traditional payloads. + userMetadata: + allOf: + - $ref: '#/components/schemas/UserMetadata' + description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. + StartNexusOperationResponse: + type: object + properties: + runId: + type: string + description: The run ID of the operation that was started - or used (via NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING). + started: + type: boolean + description: If true, a new operation was started. StartWorkflowExecutionRequest: type: object properties: @@ -14336,6 +15352,28 @@ components: TerminateActivityExecutionResponse: type: object properties: {} + TerminateNexusOperationRequest: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: Operation run ID, targets the latest run if empty. + identity: + type: string + description: The identity of the client who initiated this request. + requestId: + type: string + description: Used to de-dupe termination requests. + reason: + type: string + description: Reason for requesting the termination, recorded in the operation's result failure outcome. + TerminateNexusOperationResponse: + type: object + properties: {} TerminateWorkflowExecutionRequest: type: object properties: From 0b8ceb6ee5dc212685deb721a19ab7d38f97d22d Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Mon, 23 Feb 2026 16:15:06 -0800 Subject: [PATCH 03/21] Fix buf.lock: restore grpc-gateway dependency from master Co-Authored-By: Claude Opus 4.6 --- buf.lock | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/buf.lock b/buf.lock index 6c4355d41..fccbfb89d 100644 --- a/buf.lock +++ b/buf.lock @@ -6,3 +6,8 @@ deps: repository: googleapis commit: 28151c0d0a1641bf938a7672c500e01d digest: shake256:49215edf8ef57f7863004539deff8834cfb2195113f0b890dd1f67815d9353e28e668019165b9d872395871eeafcbab3ccfdb2b5f11734d3cca95be9e8d139de + - remote: buf.build + owner: grpc-ecosystem + repository: grpc-gateway + commit: 048ae6ff94ca4476b3225904b1078fad + digest: shake256:e5250bf2d999516c02206d757502b902e406f35c099d0e869dc3e4f923f6870fe0805a9974c27df0695462937eae90cd4d9db90bb9a03489412560baa74a87b6 From 7fa3ce5a02d26ddcad8244001e92f7c8b5aeb82d Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 09:13:33 -0800 Subject: [PATCH 04/21] operation_id comment --- temporal/api/workflowservice/v1/request_response.proto | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c7185c4fe..ee749f2a5 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -276,7 +276,7 @@ message PollWorkflowTaskQueueRequest { temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 6; // Removed in 1.55.0; was temporal.api.worker.v1.WorkerHeartbeat worker_heartbeat - reserved 7; + reserved 7; reserved "worker_heartbeat"; } @@ -454,7 +454,7 @@ message PollActivityTaskQueueRequest { temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 6; // Removed in 1.55.0; was temporal.api.worker.v1.WorkerHeartbeat worker_heartbeat - reserved 7; + reserved 7; reserved "worker_heartbeat"; } @@ -2812,7 +2812,9 @@ message StartNexusOperationRequest { string identity = 2; // A unique identifier for this start request. Typically UUIDv4. string request_id = 3; - + // Identifier for this operation. This is a caller-side ID, distinct from any internal + // operation identifiers generated by the handler. Must be unique among operations in the + // same namespace, subject to the rules imposed by id_reuse_policy and id_conflict_policy. string operation_id = 4; // Endpoint name, resolved to a URL via the cluster's endpoint registry. string endpoint = 5; From 44adc50fba9bd49f257b2cdb73f687ff64a803ff Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 09:54:46 -0800 Subject: [PATCH 05/21] request_id comment --- temporal/api/workflowservice/v1/request_response.proto | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index ee749f2a5..da9e53adc 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2810,7 +2810,8 @@ message StartNexusOperationRequest { string namespace = 1; // The identity of the client who initiated this request. string identity = 2; - // A unique identifier for this start request. Typically UUIDv4. + // A unique identifier for this caller-side start request. Typically UUIDv4. + // StartOperation requests sent to the handler will use a server-generated request ID. string request_id = 3; // Identifier for this operation. This is a caller-side ID, distinct from any internal // operation identifiers generated by the handler. Must be unique among operations in the From af1af0e8b38cb263704593deb93fe0392f5236d6 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 12:17:46 -0800 Subject: [PATCH 06/21] wait_stage comment --- temporal/api/workflowservice/v1/request_response.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index da9e53adc..090d81e62 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2963,7 +2963,7 @@ message PollNexusOperationResponse { // The run ID of the operation, useful when run_id was not specified in the request. string run_id = 1; - // Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + // The current stage of the operation. May be more advanced than the stage requested in the poll. temporal.api.enums.v1.NexusOperationWaitStage wait_stage = 2; // Operation token. Only populated for asynchronous operations after a successful StartOperation call. From b0a71e405f24ef106a916ef9fa755d6d37676349 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 12:34:05 -0800 Subject: [PATCH 07/21] add DeleteNexusOperationRequest --- temporal/api/workflowservice/v1/request_response.proto | 10 ++++++++++ temporal/api/workflowservice/v1/service.proto | 8 ++++++++ 2 files changed, 18 insertions(+) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 090d81e62..a6a0e5faf 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -3130,3 +3130,13 @@ message TerminateNexusOperationRequest { message TerminateNexusOperationResponse { } + +message DeleteNexusOperationRequest { + string namespace = 1; + string operation_id = 2; + // Operation run ID, targets the latest run if empty. + string run_id = 3; +} + +message DeleteNexusOperationResponse { +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 0fe70c685..88a30ef81 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1549,4 +1549,12 @@ service WorkflowService { } }; } + + // DeleteNexusOperation asynchronously deletes a specific Nexus operation run (when + // run_id is provided) or the latest run (when run_id is not provided). If the operation + // is running, it will be terminated before deletion. + // + // (-- api-linter: core::0127::http-annotation=disabled + // aip.dev/not-precedent: Nexus operation deletion not exposed to HTTP, users should use cancel or terminate. --) + rpc DeleteNexusOperation (DeleteNexusOperationRequest) returns (DeleteNexusOperationResponse) {} } From 50e415e94dc282a60ca83eccbc21a3b176e4d372 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 12:37:04 -0800 Subject: [PATCH 08/21] regen --- openapi/openapiv2.json | 6 ++++-- openapi/openapiv3.yaml | 18 ++++++++++++++++-- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 35b758f05..5e2dee137 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1646,6 +1646,7 @@ }, { "name": "operationId", + "description": "Identifier for this operation. This is a caller-side ID, distinct from any internal\noperation identifiers generated by the handler. Must be unique among operations in the\nsame namespace, subject to the rules imposed by id_reuse_policy and id_conflict_policy.", "in": "path", "required": true, "type": "string" @@ -6567,6 +6568,7 @@ }, { "name": "operationId", + "description": "Identifier for this operation. This is a caller-side ID, distinct from any internal\noperation identifiers generated by the handler. Must be unique among operations in the\nsame namespace, subject to the rules imposed by id_reuse_policy and id_conflict_policy.", "in": "path", "required": true, "type": "string" @@ -10754,7 +10756,7 @@ }, "requestId": { "type": "string", - "description": "A unique identifier for this start request. Typically UUIDv4." + "description": "A unique identifier for this caller-side start request. Typically UUIDv4.\nStartOperation requests sent to the handler will use a server-generated request ID." }, "endpoint": { "type": "string", @@ -15608,7 +15610,7 @@ }, "waitStage": { "$ref": "#/definitions/v1NexusOperationWaitStage", - "description": "Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked." + "description": "The current stage of the operation. May be more advanced than the stage requested in the poll." }, "operationToken": { "type": "string", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b7caa3b10..4dc80696f 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1510,6 +1510,10 @@ paths: type: string - name: operationId in: path + description: |- + Identifier for this operation. This is a caller-side ID, distinct from any internal + operation identifiers generated by the handler. Must be unique among operations in the + same namespace, subject to the rules imposed by id_reuse_policy and id_conflict_policy. required: true schema: type: string @@ -5920,6 +5924,10 @@ paths: type: string - name: operationId in: path + description: |- + Identifier for this operation. This is a caller-side ID, distinct from any internal + operation identifiers generated by the handler. Must be unique among operations in the + same namespace, subject to the rules imposed by id_reuse_policy and id_conflict_policy. required: true schema: type: string @@ -12432,7 +12440,7 @@ components: - NEXUS_OPERATION_WAIT_STAGE_STARTED - NEXUS_OPERATION_WAIT_STAGE_CLOSED type: string - description: Stage to wait for. The operation may be in a more advanced stage when the poll is unblocked. + description: The current stage of the operation. May be more advanced than the stage requested in the poll. format: enum operationToken: type: string @@ -14776,9 +14784,15 @@ components: description: The identity of the client who initiated this request. requestId: type: string - description: A unique identifier for this start request. Typically UUIDv4. + description: |- + A unique identifier for this caller-side start request. Typically UUIDv4. + StartOperation requests sent to the handler will use a server-generated request ID. operationId: type: string + description: |- + Identifier for this operation. This is a caller-side ID, distinct from any internal + operation identifiers generated by the handler. Must be unique among operations in the + same namespace, subject to the rules imposed by id_reuse_policy and id_conflict_policy. endpoint: type: string description: Endpoint name, resolved to a URL via the cluster's endpoint registry. From 9b1baedf1a527e9c08f47db5d30886e6790b1476 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 17:44:40 -0800 Subject: [PATCH 09/21] fix reason field number --- temporal/api/nexus/v1/message.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index 804a7f0d1..f8d71e28a 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -202,7 +202,7 @@ message EndpointTarget { // Nexus task queue to route requests to. string task_queue = 2; } - + // Target an external server by URL. // At a later point, this will support providing credentials, in the meantime, an http.RoundTripper can be injected // into the server to modify the request. @@ -239,7 +239,7 @@ message NexusOperationCancellationInfo { string blocked_reason = 7; // A reason that may be specified in the CancelNexusOpertionRequest. - string reason = 24; + string reason = 8; } // Information about a standalone Nexus operation. From d1c5a6c14906429d8e14f97a2bd135e762b4407f Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 17:45:37 -0800 Subject: [PATCH 10/21] fix typo --- temporal/api/nexus/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index f8d71e28a..124bec919 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -238,7 +238,7 @@ message NexusOperationCancellationInfo { // If the state is BLOCKED, blocked reason provides additional information. string blocked_reason = 7; - // A reason that may be specified in the CancelNexusOpertionRequest. + // A reason that may be specified in the CancelNexusOperationRequest. string reason = 8; } From 3cbc3bcb0171c990b1f73097984819b0a697fa5a Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 17:46:00 -0800 Subject: [PATCH 11/21] missing word --- temporal/api/enums/v1/nexus.proto | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/temporal/api/enums/v1/nexus.proto b/temporal/api/enums/v1/nexus.proto index c378bf9b4..75d547d89 100644 --- a/temporal/api/enums/v1/nexus.proto +++ b/temporal/api/enums/v1/nexus.proto @@ -27,8 +27,8 @@ enum NexusHandlerErrorRetryBehavior { // aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) enum NexusOperationStatus { NEXUS_OPERATION_STATUS_UNSPECIFIED = 0; - // The operation is not in a terminal status. The operation may attempting to start, backing off between attempts, - // or already started. + // The operation is not in a terminal status. The operation may be attempting to start, + // backing off between attempts, or already started. NEXUS_OPERATION_STATUS_RUNNING = 1; // The operation completed successfully. NEXUS_OPERATION_STATUS_COMPLETED = 2; @@ -80,4 +80,3 @@ enum NexusOperationIdConflictPolicy { // Don't start a new operation; instead return a handle for the running operation. NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING = 2; } - From f494689dc50e8ce602cd89438db938ca492ee8f1 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 17:47:16 -0800 Subject: [PATCH 12/21] remove word --- temporal/api/workflowservice/v1/service.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 88a30ef81..e0f5a538e 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1468,7 +1468,7 @@ service WorkflowService { }; } - // CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + // CountNexusOperations is a visibility API to count Nexus operations in a specific namespace. rpc CountNexusOperations (CountNexusOperationsRequest) returns (CountNexusOperationsResponse) { option (google.api.http) = { get: "/namespaces/{namespace}/nexus-operation-count" From 4f7081a1bcf502c651b81628226f15556d86c697 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 17:47:44 -0800 Subject: [PATCH 13/21] fix enum name comment --- temporal/api/nexus/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index 124bec919..82b72245c 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -257,7 +257,7 @@ message NexusOperationInfo { // A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. temporal.api.enums.v1.NexusOperationStatus status = 6; - // More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. + // More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING.. temporal.api.enums.v1.PendingNexusOperationState state = 7; // Schedule-to-close timeout for this operation. From afe9ec5ae67a884d09abb8c1183d4779d902e6be Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Tue, 24 Feb 2026 17:52:51 -0800 Subject: [PATCH 14/21] group messages by feature --- .../workflowservice/v1/request_response.proto | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index a6a0e5faf..23a78a7eb 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2806,6 +2806,54 @@ message DescribeActivityExecutionRequest { bytes long_poll_token = 6; } +message DescribeActivityExecutionResponse { + // The run ID of the activity, useful when run_id was not specified in the request. + string run_id = 1; + + // Information about the activity execution. + temporal.api.activity.v1.ActivityExecutionInfo info = 2; + + // Serialized activity input, passed as arguments to the activity function. + // Only set if include_input was true in the request. + temporal.api.common.v1.Payloads input = 3; + + // Only set if the activity is completed and include_outcome was true in the request. + temporal.api.activity.v1.ActivityExecutionOutcome outcome = 4; + + // Token for follow-on long-poll requests. Absent only if the activity is complete. + bytes long_poll_token = 5; +} + +message PollActivityExecutionRequest { + string namespace = 1; + string activity_id = 2; + // Activity run ID. If empty the request targets the latest run. + string run_id = 3; +} + +message PollActivityExecutionResponse { + // The run ID of the activity, useful when run_id was not specified in the request. + string run_id = 1; + + temporal.api.activity.v1.ActivityExecutionOutcome outcome = 2; +} + +message ListActivityExecutionsRequest { + string namespace = 1; + // Max number of executions to return per page. + int32 page_size = 2; + // Token returned in ListActivityExecutionsResponse. + bytes next_page_token = 3; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + string query = 4; +} + +message ListActivityExecutionsResponse { + repeated temporal.api.activity.v1.ActivityExecutionListInfo executions = 1; + // Token to use to fetch the next page. If empty, there is no next page. + bytes next_page_token = 2; +} + message StartNexusOperationRequest { string namespace = 1; // The identity of the client who initiated this request. @@ -2878,54 +2926,6 @@ message DescribeNexusOperationRequest { bytes long_poll_token = 6; } -message DescribeActivityExecutionResponse { - // The run ID of the activity, useful when run_id was not specified in the request. - string run_id = 1; - - // Information about the activity execution. - temporal.api.activity.v1.ActivityExecutionInfo info = 2; - - // Serialized activity input, passed as arguments to the activity function. - // Only set if include_input was true in the request. - temporal.api.common.v1.Payloads input = 3; - - // Only set if the activity is completed and include_outcome was true in the request. - temporal.api.activity.v1.ActivityExecutionOutcome outcome = 4; - - // Token for follow-on long-poll requests. Absent only if the activity is complete. - bytes long_poll_token = 5; -} - -message PollActivityExecutionRequest { - string namespace = 1; - string activity_id = 2; - // Activity run ID. If empty the request targets the latest run. - string run_id = 3; -} - -message PollActivityExecutionResponse { - // The run ID of the activity, useful when run_id was not specified in the request. - string run_id = 1; - - temporal.api.activity.v1.ActivityExecutionOutcome outcome = 2; -} - -message ListActivityExecutionsRequest { - string namespace = 1; - // Max number of executions to return per page. - int32 page_size = 2; - // Token returned in ListActivityExecutionsResponse. - bytes next_page_token = 3; - // Visibility query, see https://docs.temporal.io/list-filter for the syntax. - string query = 4; -} - -message ListActivityExecutionsResponse { - repeated temporal.api.activity.v1.ActivityExecutionListInfo executions = 1; - // Token to use to fetch the next page. If empty, there is no next page. - bytes next_page_token = 2; -} - message DescribeNexusOperationResponse { // The run ID of the operation, useful when run_id was not specified in the request. string run_id = 1; From 1e570f8075fa28058fe51e3600fc0f2b57bd8271 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 11:40:46 -0800 Subject: [PATCH 15/21] trailing dot --- temporal/api/nexus/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index 82b72245c..f22bfeee4 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -257,7 +257,7 @@ message NexusOperationInfo { // A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. temporal.api.enums.v1.NexusOperationStatus status = 6; - // More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING.. + // More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING. temporal.api.enums.v1.PendingNexusOperationState state = 7; // Schedule-to-close timeout for this operation. From d99cea3fda021b1580998b576e818ebabadeb643 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 11:43:53 -0800 Subject: [PATCH 16/21] move comment to where it matters --- temporal/api/enums/v1/nexus.proto | 2 -- temporal/api/nexus/v1/message.proto | 6 +++--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/temporal/api/enums/v1/nexus.proto b/temporal/api/enums/v1/nexus.proto index 75d547d89..bb967c240 100644 --- a/temporal/api/enums/v1/nexus.proto +++ b/temporal/api/enums/v1/nexus.proto @@ -21,8 +21,6 @@ enum NexusHandlerErrorRetryBehavior { } // Status of a standalone Nexus operation. -// The status is updated once, when the operation is originally scheduled, and again when the operation reaches a -// terminal status. // (-- api-linter: core::0216::synonyms=disabled // aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) enum NexusOperationStatus { diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index f22bfeee4..ef0febe89 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -242,7 +242,7 @@ message NexusOperationCancellationInfo { string reason = 8; } -// Information about a standalone Nexus operation. +// Full current state of a standalone Nexus operation, as of the time of the request. message NexusOperationInfo { // Unique identifier of this Nexus operation within its namespace along with run ID (below). string operation_id = 1; @@ -334,8 +334,8 @@ message NexusOperationListInfo { google.protobuf.Timestamp schedule_time = 6; // If the operation is in a terminal status, this field represents the time the operation transitioned to that status. google.protobuf.Timestamp close_time = 7; - // Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not - // available in the list response. + // Set once when the operation is scheduled and updated once when it reaches a terminal status. + // Use DescribeNexusOperation for full current state. temporal.api.enums.v1.NexusOperationStatus status = 8; // Search attributes from the start request. From 31047d741de2fa0efa1b484ecb1755dbb73775a9 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 11:48:48 -0800 Subject: [PATCH 17/21] request_id details --- temporal/api/nexus/v1/message.proto | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index ef0febe89..df9419de6 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -292,8 +292,9 @@ message NexusOperationInfo { // If the state is BLOCKED, blocked reason provides additional information. string blocked_reason = 18; - // Request ID allocated by the server when handling the StartNexusOperation request. - // Used as an idempotency token for submitting start requests to the handler. + // Server-generated request ID used as an idempotency token when submitting start requests to + // the handler. Distinct from the request_id in StartNexusOperationRequest, which is the + // caller-side idempotency key for the StartNexusOperation RPC itself. string request_id = 19; // Operation token. Only set for asynchronous operations after a successful StartOperation call. From a1bac0c56e1792cd49a560643337d782b9843f0c Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 11:52:31 -0800 Subject: [PATCH 18/21] clarify --- temporal/api/nexus/v1/message.proto | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index df9419de6..59f1ec246 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -284,7 +284,8 @@ message NexusOperationInfo { // The time when the next attempt is scheduled. google.protobuf.Timestamp next_attempt_schedule_time = 15; - // How long this operation has been running for, including all attempts and backoff between attempts. + // Elapsed time from schedule_time to now for running operations or to close_time for closed + // operations, including all attempts and backoff between attempts. google.protobuf.Duration execution_duration = 16; NexusOperationCancellationInfo cancellation_info = 17; From 6b6a66674e01f0eb362bfe1a8c39a9994ad37e82 Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 12:01:23 -0800 Subject: [PATCH 19/21] gen --- openapi/openapiv2.json | 18 +++++++++--------- openapi/openapiv3.yaml | 21 ++++++++++++--------- 2 files changed, 21 insertions(+), 18 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 5e2dee137..bac96ffd3 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1464,7 +1464,7 @@ }, "/api/v1/namespaces/{namespace}/nexus-operation-count": { "get": { - "summary": "CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace.", + "summary": "CountNexusOperations is a visibility API to count Nexus operations in a specific namespace.", "operationId": "CountNexusOperations2", "responses": { "200": { @@ -6386,7 +6386,7 @@ }, "/namespaces/{namespace}/nexus-operation-count": { "get": { - "summary": "CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace.", + "summary": "CountNexusOperations is a visibility API to count Nexus operations in a specific namespace.", "operationId": "CountNexusOperations", "responses": { "200": { @@ -11377,7 +11377,7 @@ }, "reason": { "type": "string", - "description": "A reason that may be specified in the CancelNexusOpertionRequest." + "description": "A reason that may be specified in the CancelNexusOperationRequest." } }, "description": "NexusOperationCancellationInfo contains the state of a Nexus operation cancellation." @@ -14982,7 +14982,7 @@ }, "state": { "$ref": "#/definitions/v1PendingNexusOperationState", - "description": "More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING." + "description": "More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING." }, "scheduleToCloseTimeout": { "type": "string", @@ -15024,7 +15024,7 @@ }, "executionDuration": { "type": "string", - "description": "How long this operation has been running for, including all attempts and backoff between attempts." + "description": "Elapsed time from schedule_time to now for running operations or to close_time for closed\noperations, including all attempts and backoff between attempts." }, "cancellationInfo": { "$ref": "#/definitions/apiNexusV1NexusOperationCancellationInfo" @@ -15035,7 +15035,7 @@ }, "requestId": { "type": "string", - "description": "Request ID allocated by the server when handling the StartNexusOperation request.\nUsed as an idempotency token for submitting start requests to the handler." + "description": "Server-generated request ID used as an idempotency token when submitting start requests to\nthe handler. Distinct from the request_id in StartNexusOperationRequest, which is the\ncaller-side idempotency key for the StartNexusOperation RPC itself." }, "operationToken": { "type": "string", @@ -15069,7 +15069,7 @@ "description": "Links attached by the handler of this operation on start or completion." } }, - "description": "Information about a standalone Nexus operation." + "description": "Full current state of a standalone Nexus operation, as of the time of the request." }, "v1NexusOperationListInfo": { "type": "object", @@ -15106,7 +15106,7 @@ }, "status": { "$ref": "#/definitions/v1NexusOperationStatus", - "description": "Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not\navailable in the list response." + "description": "Set once when the operation is scheduled and updated once when it reaches a terminal status.\nUse DescribeNexusOperation for full current state." }, "searchAttributes": { "$ref": "#/definitions/v1SearchAttributes", @@ -15218,7 +15218,7 @@ "NEXUS_OPERATION_STATUS_TIMED_OUT" ], "default": "NEXUS_OPERATION_STATUS_UNSPECIFIED", - "description": "Status of a standalone Nexus operation.\nThe status is updated once, when the operation is originally scheduled, and again when the operation reaches a\nterminal status.\n\n - NEXUS_OPERATION_STATUS_RUNNING: The operation is not in a terminal status. The operation may attempting to start, backing off between attempts,\nor already started.\n - NEXUS_OPERATION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." + "description": "Status of a standalone Nexus operation.\n\n - NEXUS_OPERATION_STATUS_RUNNING: The operation is not in a terminal status. The operation may be attempting to start,\nbacking off between attempts, or already started.\n - NEXUS_OPERATION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." }, "v1NexusOperationTimedOutEventAttributes": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 4dc80696f..78a927169 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1347,7 +1347,7 @@ paths: get: tags: - WorkflowService - description: CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + description: CountNexusOperations is a visibility API to count Nexus operations in a specific namespace. operationId: CountNexusOperations parameters: - name: namespace @@ -5761,7 +5761,7 @@ paths: get: tags: - WorkflowService - description: CountNexusOperations is a visibility API to count of Nexus operations in a specific namespace. + description: CountNexusOperations is a visibility API to count Nexus operations in a specific namespace. operationId: CountNexusOperations parameters: - name: namespace @@ -11774,7 +11774,7 @@ components: - PENDING_NEXUS_OPERATION_STATE_STARTED - PENDING_NEXUS_OPERATION_STATE_BLOCKED type: string - description: More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. + description: More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING. format: enum scheduleToCloseTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ @@ -11817,7 +11817,9 @@ components: executionDuration: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string - description: How long this operation has been running for, including all attempts and backoff between attempts. + description: |- + Elapsed time from schedule_time to now for running operations or to close_time for closed + operations, including all attempts and backoff between attempts. cancellationInfo: $ref: '#/components/schemas/NexusOperationCancellationInfo' blockedReason: @@ -11826,8 +11828,9 @@ components: requestId: type: string description: |- - Request ID allocated by the server when handling the StartNexusOperation request. - Used as an idempotency token for submitting start requests to the handler. + Server-generated request ID used as an idempotency token when submitting start requests to + the handler. Distinct from the request_id in StartNexusOperationRequest, which is the + caller-side idempotency key for the StartNexusOperation RPC itself. operationToken: type: string description: Operation token. Only set for asynchronous operations after a successful StartOperation call. @@ -11850,7 +11853,7 @@ components: items: $ref: '#/components/schemas/Link' description: Links attached by the handler of this operation on start or completion. - description: Information about a standalone Nexus operation. + description: Full current state of a standalone Nexus operation, as of the time of the request. NexusOperationListInfo: type: object properties: @@ -11888,8 +11891,8 @@ components: - NEXUS_OPERATION_STATUS_TIMED_OUT type: string description: |- - Only scheduled and terminal statuses appear here. More detailed information in PendingNexusOperationInfo but not - available in the list response. + Set once when the operation is scheduled and updated once when it reaches a terminal status. + Use DescribeNexusOperation for full current state. format: enum searchAttributes: allOf: From c706e3445293a78b7cbfad27b98a20e48ee5e23c Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 15:33:37 -0800 Subject: [PATCH 20/21] add Execution --- openapi/openapiv2.json | 456 +++++++++--------- openapi/openapiv3.yaml | 293 ++++++----- temporal/api/common/v1/message.proto | 6 +- temporal/api/enums/v1/nexus.proto | 16 +- temporal/api/errordetails/v1/message.proto | 2 +- temporal/api/nexus/v1/message.proto | 20 +- .../workflowservice/v1/request_response.proto | 44 +- temporal/api/workflowservice/v1/service.proto | 34 +- 8 files changed, 457 insertions(+), 414 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index bac96ffd3..7f7421937 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1464,13 +1464,13 @@ }, "/api/v1/namespaces/{namespace}/nexus-operation-count": { "get": { - "summary": "CountNexusOperations is a visibility API to count Nexus operations in a specific namespace.", - "operationId": "CountNexusOperations2", + "summary": "CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace.", + "operationId": "CountNexusOperationExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CountNexusOperationsResponse" + "$ref": "#/definitions/v1CountNexusOperationExecutionsResponse" } }, "default": { @@ -1489,7 +1489,7 @@ }, { "name": "query", - "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationsRequest for search attributes available for Nexus operations.", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationExecutionsRequest for search attributes available for Nexus operations.", "in": "query", "required": false, "type": "string" @@ -1502,13 +1502,13 @@ }, "/api/v1/namespaces/{namespace}/nexus-operations": { "get": { - "summary": "ListNexusOperations is a visibility API to list Nexus operations in a specific namespace.", - "operationId": "ListNexusOperations2", + "summary": "ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperationExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNexusOperationsResponse" + "$ref": "#/definitions/v1ListNexusOperationExecutionsResponse" } }, "default": { @@ -1535,7 +1535,7 @@ }, { "name": "nextPageToken", - "description": "Token returned in ListNexusOperationsResponse.", + "description": "Token returned in ListNexusOperationExecutionsResponse.", "in": "query", "required": false, "type": "string", @@ -1556,13 +1556,13 @@ }, "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}": { "get": { - "summary": "DescribeNexusOperation returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", - "operationId": "DescribeNexusOperation2", + "summary": "DescribeNexusOperationExecution returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", + "operationId": "DescribeNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeNexusOperationResponse" + "$ref": "#/definitions/v1DescribeNexusOperationExecutionResponse" } }, "default": { @@ -1608,7 +1608,7 @@ }, { "name": "longPollToken", - "description": "Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "description": "Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", "in": "query", "required": false, "type": "string", @@ -1620,14 +1620,14 @@ ] }, "post": { - "summary": "StartNexusOperation starts a new Nexus operation.", - "description": "Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", - "operationId": "StartNexusOperation2", + "summary": "StartNexusOperationExecution starts a new Nexus operation.", + "description": "Returns a `NexusOperationExecutionAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", + "operationId": "StartNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartNexusOperationResponse" + "$ref": "#/definitions/v1StartNexusOperationExecutionResponse" } }, "default": { @@ -1656,7 +1656,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStartNexusOperationBody" + "$ref": "#/definitions/WorkflowServiceStartNexusOperationExecutionBody" } } ], @@ -1667,14 +1667,14 @@ }, "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { "post": { - "summary": "RequestCancelNexusOperation requests cancellation of a Nexus operation.", + "summary": "RequestCancelNexusOperationExecution requests cancellation of a Nexus operation.", "description": "Requesting to cancel an operation does not automatically transition the operation to canceled status.\nThe operation will only transition to canceled status if it supports cancellation and the handler\nprocesses the cancellation request.", - "operationId": "RequestCancelNexusOperation2", + "operationId": "RequestCancelNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RequestCancelNexusOperationResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationExecutionResponse" } }, "default": { @@ -1702,7 +1702,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationExecutionBody" } } ], @@ -1713,13 +1713,13 @@ }, "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/poll": { "get": { - "summary": "PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", - "operationId": "PollNexusOperation2", + "summary": "PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", + "operationId": "PollNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PollNexusOperationResponse" + "$ref": "#/definitions/v1PollNexusOperationExecutionResponse" } }, "default": { @@ -1770,14 +1770,14 @@ }, "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/terminate": { "post": { - "summary": "TerminateNexusOperation terminates an existing Nexus operation immediately.", + "summary": "TerminateNexusOperationExecution terminates an existing Nexus operation immediately.", "description": "Termination happens immediately and the operation handler cannot react to it. A terminated operation will have\nits outcome set to a failure with a termination reason.", - "operationId": "TerminateNexusOperation2", + "operationId": "TerminateNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1TerminateNexusOperationResponse" + "$ref": "#/definitions/v1TerminateNexusOperationExecutionResponse" } }, "default": { @@ -1805,7 +1805,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationBody" + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationExecutionBody" } } ], @@ -6386,13 +6386,13 @@ }, "/namespaces/{namespace}/nexus-operation-count": { "get": { - "summary": "CountNexusOperations is a visibility API to count Nexus operations in a specific namespace.", - "operationId": "CountNexusOperations", + "summary": "CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace.", + "operationId": "CountNexusOperationExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CountNexusOperationsResponse" + "$ref": "#/definitions/v1CountNexusOperationExecutionsResponse" } }, "default": { @@ -6411,7 +6411,7 @@ }, { "name": "query", - "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationsRequest for search attributes available for Nexus operations.", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.\nSee also ListNexusOperationExecutionsRequest for search attributes available for Nexus operations.", "in": "query", "required": false, "type": "string" @@ -6424,13 +6424,13 @@ }, "/namespaces/{namespace}/nexus-operations": { "get": { - "summary": "ListNexusOperations is a visibility API to list Nexus operations in a specific namespace.", - "operationId": "ListNexusOperations", + "summary": "ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperationExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNexusOperationsResponse" + "$ref": "#/definitions/v1ListNexusOperationExecutionsResponse" } }, "default": { @@ -6457,7 +6457,7 @@ }, { "name": "nextPageToken", - "description": "Token returned in ListNexusOperationsResponse.", + "description": "Token returned in ListNexusOperationExecutionsResponse.", "in": "query", "required": false, "type": "string", @@ -6478,13 +6478,13 @@ }, "/namespaces/{namespace}/nexus-operations/{operationId}": { "get": { - "summary": "DescribeNexusOperation returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", - "operationId": "DescribeNexusOperation", + "summary": "DescribeNexusOperationExecution returns information about a Nexus operation.\nSupported use cases include:\n- Get current operation info without waiting\n- Long-poll for next state change and return new operation info\nResponse can optionally include operation input or outcome (if the operation has completed).", + "operationId": "DescribeNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeNexusOperationResponse" + "$ref": "#/definitions/v1DescribeNexusOperationExecutionResponse" } }, "default": { @@ -6530,7 +6530,7 @@ }, { "name": "longPollToken", - "description": "Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "description": "Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that operation state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", "in": "query", "required": false, "type": "string", @@ -6542,14 +6542,14 @@ ] }, "post": { - "summary": "StartNexusOperation starts a new Nexus operation.", - "description": "Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", - "operationId": "StartNexusOperation", + "summary": "StartNexusOperationExecution starts a new Nexus operation.", + "description": "Returns a `NexusOperationExecutionAlreadyStarted` error if an instance already exists with same operation ID in this\nnamespace unless permitted by the specified ID conflict policy.", + "operationId": "StartNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartNexusOperationResponse" + "$ref": "#/definitions/v1StartNexusOperationExecutionResponse" } }, "default": { @@ -6578,7 +6578,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStartNexusOperationBody" + "$ref": "#/definitions/WorkflowServiceStartNexusOperationExecutionBody" } } ], @@ -6589,14 +6589,14 @@ }, "/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { "post": { - "summary": "RequestCancelNexusOperation requests cancellation of a Nexus operation.", + "summary": "RequestCancelNexusOperationExecution requests cancellation of a Nexus operation.", "description": "Requesting to cancel an operation does not automatically transition the operation to canceled status.\nThe operation will only transition to canceled status if it supports cancellation and the handler\nprocesses the cancellation request.", - "operationId": "RequestCancelNexusOperation", + "operationId": "RequestCancelNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RequestCancelNexusOperationResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationExecutionResponse" } }, "default": { @@ -6624,7 +6624,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationExecutionBody" } } ], @@ -6635,13 +6635,13 @@ }, "/namespaces/{namespace}/nexus-operations/{operationId}/poll": { "get": { - "summary": "PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", - "operationId": "PollNexusOperation", + "summary": "PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns\nthe outcome (result or failure).", + "operationId": "PollNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PollNexusOperationResponse" + "$ref": "#/definitions/v1PollNexusOperationExecutionResponse" } }, "default": { @@ -6692,14 +6692,14 @@ }, "/namespaces/{namespace}/nexus-operations/{operationId}/terminate": { "post": { - "summary": "TerminateNexusOperation terminates an existing Nexus operation immediately.", + "summary": "TerminateNexusOperationExecution terminates an existing Nexus operation immediately.", "description": "Termination happens immediately and the operation handler cannot react to it. A terminated operation will have\nits outcome set to a failure with a termination reason.", - "operationId": "TerminateNexusOperation", + "operationId": "TerminateNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1TerminateNexusOperationResponse" + "$ref": "#/definitions/v1TerminateNexusOperationExecutionResponse" } }, "default": { @@ -6727,7 +6727,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationBody" + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationExecutionBody" } } ], @@ -9473,7 +9473,7 @@ }, "description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job." }, - "LinkNexusOperation": { + "LinkNexusOperationExecution": { "type": "object", "properties": { "namespace": { @@ -9486,7 +9486,7 @@ "type": "string" } }, - "description": "A link to a standalone Nexus operation." + "description": "A link to a standalone Nexus operation execution." }, "LinkWorkflowEvent": { "type": "object", @@ -10072,7 +10072,7 @@ } } }, - "WorkflowServiceRequestCancelNexusOperationBody": { + "WorkflowServiceRequestCancelNexusOperationExecutionBody": { "type": "object", "properties": { "runId": { @@ -10089,7 +10089,7 @@ }, "reason": { "type": "string", - "description": "Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API." + "description": "Reason for requesting the cancellation, recorded and available via the DescribeNexusOperationExecution API." } } }, @@ -10747,7 +10747,7 @@ } } }, - "WorkflowServiceStartNexusOperationBody": { + "WorkflowServiceStartNexusOperationExecutionBody": { "type": "object", "properties": { "identity": { @@ -10948,7 +10948,7 @@ } } }, - "WorkflowServiceTerminateNexusOperationBody": { + "WorkflowServiceTerminateNexusOperationExecutionBody": { "type": "object", "properties": { "runId": { @@ -11341,84 +11341,6 @@ }, "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationUpdateWorkflowExecutionOptions.\n - temporal.api.workflow.v1.PostResetOperation.UpdateWorkflowOptions." }, - "apiNexusV1NexusOperationCancellationInfo": { - "type": "object", - "properties": { - "requestedTime": { - "type": "string", - "format": "date-time", - "description": "The time when cancellation was requested." - }, - "state": { - "$ref": "#/definitions/v1NexusOperationCancellationState" - }, - "attempt": { - "type": "integer", - "format": "int32", - "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." - }, - "lastAttemptCompleteTime": { - "type": "string", - "format": "date-time", - "description": "The time when the last attempt completed." - }, - "lastAttemptFailure": { - "$ref": "#/definitions/v1Failure", - "description": "The last attempt's failure, if any." - }, - "nextAttemptScheduleTime": { - "type": "string", - "format": "date-time", - "description": "The time when the next attempt is scheduled." - }, - "blockedReason": { - "type": "string", - "description": "If the state is BLOCKED, blocked reason provides additional information." - }, - "reason": { - "type": "string", - "description": "A reason that may be specified in the CancelNexusOperationRequest." - } - }, - "description": "NexusOperationCancellationInfo contains the state of a Nexus operation cancellation." - }, - "apiWorkflowV1NexusOperationCancellationInfo": { - "type": "object", - "properties": { - "requestedTime": { - "type": "string", - "format": "date-time", - "description": "The time when cancellation was requested." - }, - "state": { - "$ref": "#/definitions/v1NexusOperationCancellationState" - }, - "attempt": { - "type": "integer", - "format": "int32", - "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." - }, - "lastAttemptCompleteTime": { - "type": "string", - "format": "date-time", - "description": "The time when the last attempt completed." - }, - "lastAttemptFailure": { - "$ref": "#/definitions/v1Failure", - "description": "The last attempt's failure, if any." - }, - "nextAttemptScheduleTime": { - "type": "string", - "format": "date-time", - "description": "The time when the next attempt is scheduled." - }, - "blockedReason": { - "type": "string", - "description": "If the state is BLOCKED, blocked reason provides additional information." - } - }, - "description": "NexusOperationCancellationInfo contains the state of a nexus operation cancellation." - }, "protobufAny": { "type": "object", "properties": { @@ -12815,7 +12737,7 @@ } } }, - "v1CountNexusOperationsResponse": { + "v1CountNexusOperationExecutionsResponse": { "type": "object", "properties": { "count": { @@ -12827,13 +12749,13 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1CountNexusOperationsResponseAggregationGroup" + "$ref": "#/definitions/v1CountNexusOperationExecutionsResponseAggregationGroup" }, "description": "Contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." } } }, - "v1CountNexusOperationsResponseAggregationGroup": { + "v1CountNexusOperationExecutionsResponseAggregationGroup": { "type": "object", "properties": { "groupValues": { @@ -13195,7 +13117,7 @@ } } }, - "v1DescribeNexusOperationResponse": { + "v1DescribeNexusOperationExecutionResponse": { "type": "object", "properties": { "runId": { @@ -13203,7 +13125,7 @@ "description": "The run ID of the operation, useful when run_id was not specified in the request." }, "info": { - "$ref": "#/definitions/v1NexusOperationInfo", + "$ref": "#/definitions/v1NexusOperationExecutionInfo", "description": "Information about the operation." }, "input": { @@ -14207,7 +14129,7 @@ "$ref": "#/definitions/LinkBatchJob" }, "nexusOperation": { - "$ref": "#/definitions/LinkNexusOperation" + "$ref": "#/definitions/LinkNexusOperationExecution" } }, "description": "Link can be associated with history events. It might contain information about an external entity\nrelated to the history event. For example, workflow A makes a Nexus call that starts workflow B:\nin this case, a history event in workflow A could contain a Link to the workflow started event in\nworkflow B, and vice-versa." @@ -14312,14 +14234,14 @@ } } }, - "v1ListNexusOperationsResponse": { + "v1ListNexusOperationExecutionsResponse": { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1NexusOperationListInfo" + "$ref": "#/definitions/v1NexusOperationExecutionListInfo" } }, "nextPageToken": { @@ -14850,6 +14772,43 @@ }, "description": "Nexus operation completed as canceled. May or may not have been due to a cancellation request by the workflow." }, + "v1NexusOperationCancellationInfo": { + "type": "object", + "properties": { + "requestedTime": { + "type": "string", + "format": "date-time", + "description": "The time when cancellation was requested." + }, + "state": { + "$ref": "#/definitions/v1NexusOperationCancellationState" + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last attempt completed." + }, + "lastAttemptFailure": { + "$ref": "#/definitions/v1Failure", + "description": "The last attempt's failure, if any." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next attempt is scheduled." + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + } + }, + "description": "NexusOperationCancellationInfo contains the state of a nexus operation cancellation." + }, "v1NexusOperationCancellationState": { "type": "string", "enum": [ @@ -14883,78 +14842,48 @@ }, "description": "Nexus operation completed successfully." }, - "v1NexusOperationFailedEventAttributes": { + "v1NexusOperationExecutionCancellationInfo": { "type": "object", "properties": { - "scheduledEventId": { + "requestedTime": { "type": "string", - "format": "int64", - "description": "The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation." + "format": "date-time", + "description": "The time when cancellation was requested." }, - "failure": { - "$ref": "#/definitions/v1Failure", - "description": "Failure details. A NexusOperationFailureInfo wrapping an ApplicationFailureInfo." + "state": { + "$ref": "#/definitions/v1NexusOperationCancellationState" }, - "requestId": { - "type": "string", - "description": "The request ID allocated at schedule time." - } - }, - "description": "Nexus operation failed." - }, - "v1NexusOperationFailureInfo": { - "type": "object", - "properties": { - "scheduledEventId": { - "type": "string", - "format": "int64", - "description": "The NexusOperationScheduled event ID." + "attempt": { + "type": "integer", + "format": "int32", + "description": "The number of attempts made to deliver the cancel operation request.\nThis number represents a minimum bound since the attempt is incremented after the request completes." }, - "endpoint": { + "lastAttemptCompleteTime": { "type": "string", - "description": "Endpoint name." + "format": "date-time", + "description": "The time when the last attempt completed." }, - "service": { - "type": "string", - "description": "Service name." + "lastAttemptFailure": { + "$ref": "#/definitions/v1Failure", + "description": "The last attempt's failure, if any." }, - "operation": { + "nextAttemptScheduleTime": { "type": "string", - "description": "Operation name." + "format": "date-time", + "description": "The time when the next attempt is scheduled." }, - "operationId": { + "blockedReason": { "type": "string", - "description": "Operation ID - may be empty if the operation completed synchronously.\n\nDeprecated. Renamed to operation_token." + "description": "If the state is BLOCKED, blocked reason provides additional information." }, - "operationToken": { + "reason": { "type": "string", - "description": "Operation token - may be empty if the operation completed synchronously." + "description": "A reason that may be specified in the CancelNexusOperationRequest." } }, - "description": "Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers." + "description": "NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation." }, - "v1NexusOperationIdConflictPolicy": { - "type": "string", - "enum": [ - "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", - "NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL", - "NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING" - ], - "default": "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", - "description": "Defines what to do when trying to start a Nexus operation with the same ID as a *running* operation.\nNote that it is *never* valid to have two running instances of the same operation ID.\n\nSee `NexusOperationIdReusePolicy` for handling operation ID duplication with a *closed* operation.\n\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL: Don't start a new operation; instead return `NexusOperationAlreadyStarted` error.\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new operation; instead return a handle for the running operation." - }, - "v1NexusOperationIdReusePolicy": { - "type": "string", - "enum": [ - "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", - "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE", - "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY", - "NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE" - ], - "default": "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", - "description": "Defines whether to allow re-using an operation ID from a previously *closed* Nexus operation.\nIf the request is denied, the server returns a `NexusOperationAlreadyStarted` error.\n\nSee `NexusOperationIdConflictPolicy` for handling ID duplication with a *running* operation.\n\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE: Always allow starting an operation using the same operation ID.\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting an operation using the same ID only when the last operation's final state is one\nof {failed, canceled, terminated, timed out}.\n - NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the ID for this operation. Future start requests could potentially change the policy,\nallowing re-use of the ID." - }, - "v1NexusOperationInfo": { + "v1NexusOperationExecutionInfo": { "type": "object", "properties": { "operationId": { @@ -14977,12 +14906,12 @@ "description": "Operation name." }, "status": { - "$ref": "#/definitions/v1NexusOperationStatus", + "$ref": "#/definitions/v1NexusOperationExecutionStatus", "description": "A general status for this operation, indicates whether it is currently running or in one of the terminal statuses." }, "state": { "$ref": "#/definitions/v1PendingNexusOperationState", - "description": "More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING." + "description": "More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING." }, "scheduleToCloseTimeout": { "type": "string", @@ -15027,7 +14956,7 @@ "description": "Elapsed time from schedule_time to now for running operations or to close_time for closed\noperations, including all attempts and backoff between attempts." }, "cancellationInfo": { - "$ref": "#/definitions/apiNexusV1NexusOperationCancellationInfo" + "$ref": "#/definitions/v1NexusOperationExecutionCancellationInfo" }, "blockedReason": { "type": "string", @@ -15071,7 +15000,7 @@ }, "description": "Full current state of a standalone Nexus operation, as of the time of the request." }, - "v1NexusOperationListInfo": { + "v1NexusOperationExecutionListInfo": { "type": "object", "properties": { "operationId": { @@ -15105,7 +15034,7 @@ "description": "If the operation is in a terminal status, this field represents the time the operation transitioned to that status." }, "status": { - "$ref": "#/definitions/v1NexusOperationStatus", + "$ref": "#/definitions/v1NexusOperationExecutionStatus", "description": "Set once when the operation is scheduled and updated once when it reaches a terminal status.\nUse DescribeNexusOperation for full current state." }, "searchAttributes": { @@ -15127,7 +15056,92 @@ "description": "The difference between close time and scheduled time.\nThis field is only populated if the operation is closed." } }, - "description": "Limited Nexus operation information returned in the list response.\nWhen adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in\nNexusOperationInfo but not at the top-level)." + "description": "Limited Nexus operation information returned in the list response.\nWhen adding fields here, ensure that it is also present in NexusOperationExecutionInfo (note that it may already be present in\nNexusOperationExecutionInfo but not at the top-level)." + }, + "v1NexusOperationExecutionStatus": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED", + "NEXUS_OPERATION_EXECUTION_STATUS_RUNNING", + "NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED", + "NEXUS_OPERATION_EXECUTION_STATUS_FAILED", + "NEXUS_OPERATION_EXECUTION_STATUS_CANCELED", + "NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED", + "NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT" + ], + "default": "NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED", + "description": "Status of a standalone Nexus operation.\n\n - NEXUS_OPERATION_EXECUTION_STATUS_RUNNING: The operation is not in a terminal status. The operation may be attempting to start,\nbacking off between attempts, or already started.\n - NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_EXECUTION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_EXECUTION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." + }, + "v1NexusOperationFailedEventAttributes": { + "type": "object", + "properties": { + "scheduledEventId": { + "type": "string", + "format": "int64", + "description": "The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation." + }, + "failure": { + "$ref": "#/definitions/v1Failure", + "description": "Failure details. A NexusOperationFailureInfo wrapping an ApplicationFailureInfo." + }, + "requestId": { + "type": "string", + "description": "The request ID allocated at schedule time." + } + }, + "description": "Nexus operation failed." + }, + "v1NexusOperationFailureInfo": { + "type": "object", + "properties": { + "scheduledEventId": { + "type": "string", + "format": "int64", + "description": "The NexusOperationScheduled event ID." + }, + "endpoint": { + "type": "string", + "description": "Endpoint name." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "operationId": { + "type": "string", + "description": "Operation ID - may be empty if the operation completed synchronously.\n\nDeprecated. Renamed to operation_token." + }, + "operationToken": { + "type": "string", + "description": "Operation token - may be empty if the operation completed synchronously." + } + }, + "description": "Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers." + }, + "v1NexusOperationIdConflictPolicy": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", + "NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL", + "NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING" + ], + "default": "NEXUS_OPERATION_ID_CONFLICT_POLICY_UNSPECIFIED", + "description": "Defines what to do when trying to start a Nexus operation with the same ID as a *running* operation.\nNote that it is *never* valid to have two running instances of the same operation ID.\n\nSee `NexusOperationIdReusePolicy` for handling operation ID duplication with a *closed* operation.\n\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL: Don't start a new operation; instead return `NexusOperationAlreadyStarted` error.\n - NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new operation; instead return a handle for the running operation." + }, + "v1NexusOperationIdReusePolicy": { + "type": "string", + "enum": [ + "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", + "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE", + "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY", + "NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE" + ], + "default": "NEXUS_OPERATION_ID_REUSE_POLICY_UNSPECIFIED", + "description": "Defines whether to allow re-using an operation ID from a previously *closed* Nexus operation.\nIf the request is denied, the server returns a `NexusOperationAlreadyStarted` error.\n\nSee `NexusOperationIdConflictPolicy` for handling ID duplication with a *running* operation.\n\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE: Always allow starting an operation using the same operation ID.\n - NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting an operation using the same ID only when the last operation's final state is one\nof {failed, canceled, terminated, timed out}.\n - NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the ID for this operation. Future start requests could potentially change the policy,\nallowing re-use of the ID." }, "v1NexusOperationScheduledEventAttributes": { "type": "object", @@ -15206,20 +15220,6 @@ }, "description": "Event marking an asynchronous operation was started by the responding Nexus handler.\nIf the operation completes synchronously, this event is not generated.\nIn rare situations, such as request timeouts, the service may fail to record the actual start time and will fabricate\nthis event upon receiving the operation completion via callback." }, - "v1NexusOperationStatus": { - "type": "string", - "enum": [ - "NEXUS_OPERATION_STATUS_UNSPECIFIED", - "NEXUS_OPERATION_STATUS_RUNNING", - "NEXUS_OPERATION_STATUS_COMPLETED", - "NEXUS_OPERATION_STATUS_FAILED", - "NEXUS_OPERATION_STATUS_CANCELED", - "NEXUS_OPERATION_STATUS_TERMINATED", - "NEXUS_OPERATION_STATUS_TIMED_OUT" - ], - "default": "NEXUS_OPERATION_STATUS_UNSPECIFIED", - "description": "Status of a standalone Nexus operation.\n\n - NEXUS_OPERATION_STATUS_RUNNING: The operation is not in a terminal status. The operation may be attempting to start,\nbacking off between attempts, or already started.\n - NEXUS_OPERATION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." - }, "v1NexusOperationTimedOutEventAttributes": { "type": "object", "properties": { @@ -15504,7 +15504,7 @@ "description": "The time when the next attempt is scheduled." }, "cancellationInfo": { - "$ref": "#/definitions/apiWorkflowV1NexusOperationCancellationInfo" + "$ref": "#/definitions/v1NexusOperationCancellationInfo" }, "scheduledEventId": { "type": "string", @@ -15601,7 +15601,7 @@ } } }, - "v1PollNexusOperationResponse": { + "v1PollNexusOperationExecutionResponse": { "type": "object", "properties": { "runId": { @@ -16066,7 +16066,7 @@ } } }, - "v1RequestCancelNexusOperationResponse": { + "v1RequestCancelNexusOperationExecutionResponse": { "type": "object" }, "v1RequestCancelWorkflowExecutionResponse": { @@ -17026,7 +17026,7 @@ } } }, - "v1StartNexusOperationResponse": { + "v1StartNexusOperationExecutionResponse": { "type": "object", "properties": { "runId": { @@ -17382,7 +17382,7 @@ "v1TerminateActivityExecutionResponse": { "type": "object" }, - "v1TerminateNexusOperationResponse": { + "v1TerminateNexusOperationExecutionResponse": { "type": "object" }, "v1TerminateWorkflowExecutionResponse": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 78a927169..468dfcf1e 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1347,8 +1347,8 @@ paths: get: tags: - WorkflowService - description: CountNexusOperations is a visibility API to count Nexus operations in a specific namespace. - operationId: CountNexusOperations + description: CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace. + operationId: CountNexusOperationExecutions parameters: - name: namespace in: path @@ -1359,7 +1359,7 @@ paths: in: query description: |- Visibility query, see https://docs.temporal.io/list-filter for the syntax. - See also ListNexusOperationsRequest for search attributes available for Nexus operations. + See also ListNexusOperationExecutionsRequest for search attributes available for Nexus operations. schema: type: string responses: @@ -1368,7 +1368,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CountNexusOperationsResponse' + $ref: '#/components/schemas/CountNexusOperationExecutionsResponse' default: description: Default error response content: @@ -1379,8 +1379,8 @@ paths: get: tags: - WorkflowService - description: ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. - operationId: ListNexusOperations + description: ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperationExecutions parameters: - name: namespace in: path @@ -1395,7 +1395,7 @@ paths: format: int32 - name: nextPageToken in: query - description: Token returned in ListNexusOperationsResponse. + description: Token returned in ListNexusOperationExecutionsResponse. schema: type: string format: bytes @@ -1424,7 +1424,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListNexusOperationsResponse' + $ref: '#/components/schemas/ListNexusOperationExecutionsResponse' default: description: Default error response content: @@ -1436,12 +1436,12 @@ paths: tags: - WorkflowService description: |- - DescribeNexusOperation returns information about a Nexus operation. + DescribeNexusOperationExecution returns information about a Nexus operation. Supported use cases include: - Get current operation info without waiting - Long-poll for next state change and return new operation info Response can optionally include operation input or outcome (if the operation has completed). - operationId: DescribeNexusOperation + operationId: DescribeNexusOperationExecution parameters: - name: namespace in: path @@ -1471,7 +1471,7 @@ paths: - name: longPollToken in: query description: |- - Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation state changes from the state encoded in this token. If absent, return current state immediately. If present, run_id must also be present. Note that operation state may change multiple times between requests, therefore it is not @@ -1486,7 +1486,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/DescribeNexusOperationResponse' + $ref: '#/components/schemas/DescribeNexusOperationExecutionResponse' default: description: Default error response content: @@ -1497,11 +1497,11 @@ paths: tags: - WorkflowService description: |- - StartNexusOperation starts a new Nexus operation. + StartNexusOperationExecution starts a new Nexus operation. - Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + Returns a `NexusOperationExecutionAlreadyStarted` error if an instance already exists with same operation ID in this namespace unless permitted by the specified ID conflict policy. - operationId: StartNexusOperation + operationId: StartNexusOperationExecution parameters: - name: namespace in: path @@ -1521,7 +1521,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/StartNexusOperationRequest' + $ref: '#/components/schemas/StartNexusOperationExecutionRequest' required: true responses: "200": @@ -1529,7 +1529,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/StartNexusOperationResponse' + $ref: '#/components/schemas/StartNexusOperationExecutionResponse' default: description: Default error response content: @@ -1541,12 +1541,12 @@ paths: tags: - WorkflowService description: |- - RequestCancelNexusOperation requests cancellation of a Nexus operation. + RequestCancelNexusOperationExecution requests cancellation of a Nexus operation. Requesting to cancel an operation does not automatically transition the operation to canceled status. The operation will only transition to canceled status if it supports cancellation and the handler processes the cancellation request. - operationId: RequestCancelNexusOperation + operationId: RequestCancelNexusOperationExecution parameters: - name: namespace in: path @@ -1562,7 +1562,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RequestCancelNexusOperationRequest' + $ref: '#/components/schemas/RequestCancelNexusOperationExecutionRequest' required: true responses: "200": @@ -1570,7 +1570,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RequestCancelNexusOperationResponse' + $ref: '#/components/schemas/RequestCancelNexusOperationExecutionResponse' default: description: Default error response content: @@ -1582,9 +1582,9 @@ paths: tags: - WorkflowService description: |- - PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns the outcome (result or failure). - operationId: PollNexusOperation + operationId: PollNexusOperationExecution parameters: - name: namespace in: path @@ -1617,7 +1617,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/PollNexusOperationResponse' + $ref: '#/components/schemas/PollNexusOperationExecutionResponse' default: description: Default error response content: @@ -1629,11 +1629,11 @@ paths: tags: - WorkflowService description: |- - TerminateNexusOperation terminates an existing Nexus operation immediately. + TerminateNexusOperationExecution terminates an existing Nexus operation immediately. Termination happens immediately and the operation handler cannot react to it. A terminated operation will have its outcome set to a failure with a termination reason. - operationId: TerminateNexusOperation + operationId: TerminateNexusOperationExecution parameters: - name: namespace in: path @@ -1649,7 +1649,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TerminateNexusOperationRequest' + $ref: '#/components/schemas/TerminateNexusOperationExecutionRequest' required: true responses: "200": @@ -1657,7 +1657,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TerminateNexusOperationResponse' + $ref: '#/components/schemas/TerminateNexusOperationExecutionResponse' default: description: Default error response content: @@ -5761,8 +5761,8 @@ paths: get: tags: - WorkflowService - description: CountNexusOperations is a visibility API to count Nexus operations in a specific namespace. - operationId: CountNexusOperations + description: CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace. + operationId: CountNexusOperationExecutions parameters: - name: namespace in: path @@ -5773,7 +5773,7 @@ paths: in: query description: |- Visibility query, see https://docs.temporal.io/list-filter for the syntax. - See also ListNexusOperationsRequest for search attributes available for Nexus operations. + See also ListNexusOperationExecutionsRequest for search attributes available for Nexus operations. schema: type: string responses: @@ -5782,7 +5782,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CountNexusOperationsResponse' + $ref: '#/components/schemas/CountNexusOperationExecutionsResponse' default: description: Default error response content: @@ -5793,8 +5793,8 @@ paths: get: tags: - WorkflowService - description: ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. - operationId: ListNexusOperations + description: ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperationExecutions parameters: - name: namespace in: path @@ -5809,7 +5809,7 @@ paths: format: int32 - name: nextPageToken in: query - description: Token returned in ListNexusOperationsResponse. + description: Token returned in ListNexusOperationExecutionsResponse. schema: type: string format: bytes @@ -5838,7 +5838,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListNexusOperationsResponse' + $ref: '#/components/schemas/ListNexusOperationExecutionsResponse' default: description: Default error response content: @@ -5850,12 +5850,12 @@ paths: tags: - WorkflowService description: |- - DescribeNexusOperation returns information about a Nexus operation. + DescribeNexusOperationExecution returns information about a Nexus operation. Supported use cases include: - Get current operation info without waiting - Long-poll for next state change and return new operation info Response can optionally include operation input or outcome (if the operation has completed). - operationId: DescribeNexusOperation + operationId: DescribeNexusOperationExecution parameters: - name: namespace in: path @@ -5885,7 +5885,7 @@ paths: - name: longPollToken in: query description: |- - Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation state changes from the state encoded in this token. If absent, return current state immediately. If present, run_id must also be present. Note that operation state may change multiple times between requests, therefore it is not @@ -5900,7 +5900,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/DescribeNexusOperationResponse' + $ref: '#/components/schemas/DescribeNexusOperationExecutionResponse' default: description: Default error response content: @@ -5911,11 +5911,11 @@ paths: tags: - WorkflowService description: |- - StartNexusOperation starts a new Nexus operation. + StartNexusOperationExecution starts a new Nexus operation. - Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + Returns a `NexusOperationExecutionAlreadyStarted` error if an instance already exists with same operation ID in this namespace unless permitted by the specified ID conflict policy. - operationId: StartNexusOperation + operationId: StartNexusOperationExecution parameters: - name: namespace in: path @@ -5935,7 +5935,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/StartNexusOperationRequest' + $ref: '#/components/schemas/StartNexusOperationExecutionRequest' required: true responses: "200": @@ -5943,7 +5943,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/StartNexusOperationResponse' + $ref: '#/components/schemas/StartNexusOperationExecutionResponse' default: description: Default error response content: @@ -5955,12 +5955,12 @@ paths: tags: - WorkflowService description: |- - RequestCancelNexusOperation requests cancellation of a Nexus operation. + RequestCancelNexusOperationExecution requests cancellation of a Nexus operation. Requesting to cancel an operation does not automatically transition the operation to canceled status. The operation will only transition to canceled status if it supports cancellation and the handler processes the cancellation request. - operationId: RequestCancelNexusOperation + operationId: RequestCancelNexusOperationExecution parameters: - name: namespace in: path @@ -5976,7 +5976,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RequestCancelNexusOperationRequest' + $ref: '#/components/schemas/RequestCancelNexusOperationExecutionRequest' required: true responses: "200": @@ -5984,7 +5984,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RequestCancelNexusOperationResponse' + $ref: '#/components/schemas/RequestCancelNexusOperationExecutionResponse' default: description: Default error response content: @@ -5996,9 +5996,9 @@ paths: tags: - WorkflowService description: |- - PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns the outcome (result or failure). - operationId: PollNexusOperation + operationId: PollNexusOperationExecution parameters: - name: namespace in: path @@ -6031,7 +6031,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/PollNexusOperationResponse' + $ref: '#/components/schemas/PollNexusOperationExecutionResponse' default: description: Default error response content: @@ -6043,11 +6043,11 @@ paths: tags: - WorkflowService description: |- - TerminateNexusOperation terminates an existing Nexus operation immediately. + TerminateNexusOperationExecution terminates an existing Nexus operation immediately. Termination happens immediately and the operation handler cannot react to it. A terminated operation will have its outcome set to a failure with a termination reason. - operationId: TerminateNexusOperation + operationId: TerminateNexusOperationExecution parameters: - name: namespace in: path @@ -6063,7 +6063,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TerminateNexusOperationRequest' + $ref: '#/components/schemas/TerminateNexusOperationExecutionRequest' required: true responses: "200": @@ -6071,7 +6071,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TerminateNexusOperationResponse' + $ref: '#/components/schemas/TerminateNexusOperationExecutionResponse' default: description: Default error response content: @@ -9719,7 +9719,7 @@ components: $ref: '#/components/schemas/Payload' count: type: string - CountNexusOperationsResponse: + CountNexusOperationExecutionsResponse: type: object properties: count: @@ -9733,11 +9733,11 @@ components: groups: type: array items: - $ref: '#/components/schemas/CountNexusOperationsResponse_AggregationGroup' + $ref: '#/components/schemas/CountNexusOperationExecutionsResponse_AggregationGroup' description: |- Contains the groups if the request is grouping by a field. The list might not be complete, and the counts of each group is approximate. - CountNexusOperationsResponse_AggregationGroup: + CountNexusOperationExecutionsResponse_AggregationGroup: type: object properties: groupValues: @@ -10125,7 +10125,7 @@ components: description: |- Contains the historical state of failover_versions for the cluster, truncated to contain only the last N states to ensure that the list does not grow unbounded. - DescribeNexusOperationResponse: + DescribeNexusOperationExecutionResponse: type: object properties: runId: @@ -10133,7 +10133,7 @@ components: description: The run ID of the operation, useful when run_id was not specified in the request. info: allOf: - - $ref: '#/components/schemas/NexusOperationInfo' + - $ref: '#/components/schemas/NexusOperationExecutionInfo' description: Information about the operation. input: allOf: @@ -11060,7 +11060,7 @@ components: batchJob: $ref: '#/components/schemas/Link_BatchJob' nexusOperation: - $ref: '#/components/schemas/Link_NexusOperation' + $ref: '#/components/schemas/Link_NexusOperationExecution' description: |- Link can be associated with history events. It might contain information about an external entity related to the history event. For example, workflow A makes a Nexus call that starts workflow B: @@ -11075,7 +11075,7 @@ components: A link to a built-in batch job. Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc). This link can be put on workflow history events generated by actions taken by a batch job. - Link_NexusOperation: + Link_NexusOperationExecution: type: object properties: namespace: @@ -11084,7 +11084,7 @@ components: type: string runId: type: string - description: A link to a standalone Nexus operation. + description: A link to a standalone Nexus operation execution. Link_WorkflowEvent: type: object properties: @@ -11162,13 +11162,13 @@ components: type: array items: $ref: '#/components/schemas/Endpoint' - ListNexusOperationsResponse: + ListNexusOperationExecutionsResponse: type: object properties: operations: type: array items: - $ref: '#/components/schemas/NexusOperationListInfo' + $ref: '#/components/schemas/NexusOperationExecutionListInfo' nextPageToken: type: string description: Token to use to fetch the next page. If empty, there is no next page. @@ -11698,46 +11698,50 @@ components: type: string description: The request ID allocated at schedule time. description: Nexus operation completed successfully. - NexusOperationFailedEventAttributes: - type: object - properties: - scheduledEventId: - type: string - description: The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation. - failure: - allOf: - - $ref: '#/components/schemas/Failure' - description: Failure details. A NexusOperationFailureInfo wrapping an ApplicationFailureInfo. - requestId: - type: string - description: The request ID allocated at schedule time. - description: Nexus operation failed. - NexusOperationFailureInfo: + NexusOperationExecutionCancellationInfo: type: object properties: - scheduledEventId: + requestedTime: type: string - description: The NexusOperationScheduled event ID. - endpoint: + description: The time when cancellation was requested. + format: date-time + state: + enum: + - NEXUS_OPERATION_CANCELLATION_STATE_UNSPECIFIED + - NEXUS_OPERATION_CANCELLATION_STATE_SCHEDULED + - NEXUS_OPERATION_CANCELLATION_STATE_BACKING_OFF + - NEXUS_OPERATION_CANCELLATION_STATE_SUCCEEDED + - NEXUS_OPERATION_CANCELLATION_STATE_FAILED + - NEXUS_OPERATION_CANCELLATION_STATE_TIMED_OUT + - NEXUS_OPERATION_CANCELLATION_STATE_BLOCKED type: string - description: Endpoint name. - service: + format: enum + attempt: + type: integer + description: |- + The number of attempts made to deliver the cancel operation request. + This number represents a minimum bound since the attempt is incremented after the request completes. + format: int32 + lastAttemptCompleteTime: type: string - description: Service name. - operation: + description: The time when the last attempt completed. + format: date-time + lastAttemptFailure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The last attempt's failure, if any. + nextAttemptScheduleTime: type: string - description: Operation name. - operationId: + description: The time when the next attempt is scheduled. + format: date-time + blockedReason: type: string - description: |- - Operation ID - may be empty if the operation completed synchronously. - - Deprecated. Renamed to operation_token. - operationToken: + description: If the state is BLOCKED, blocked reason provides additional information. + reason: type: string - description: Operation token - may be empty if the operation completed synchronously. - description: Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers. - NexusOperationInfo: + description: A reason that may be specified in the CancelNexusOperationRequest. + description: NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation. + NexusOperationExecutionInfo: type: object properties: operationId: @@ -11756,13 +11760,13 @@ components: description: Operation name. status: enum: - - NEXUS_OPERATION_STATUS_UNSPECIFIED - - NEXUS_OPERATION_STATUS_RUNNING - - NEXUS_OPERATION_STATUS_COMPLETED - - NEXUS_OPERATION_STATUS_FAILED - - NEXUS_OPERATION_STATUS_CANCELED - - NEXUS_OPERATION_STATUS_TERMINATED - - NEXUS_OPERATION_STATUS_TIMED_OUT + - NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED + - NEXUS_OPERATION_EXECUTION_STATUS_RUNNING + - NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED + - NEXUS_OPERATION_EXECUTION_STATUS_FAILED + - NEXUS_OPERATION_EXECUTION_STATUS_CANCELED + - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED + - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT type: string description: A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. format: enum @@ -11774,7 +11778,7 @@ components: - PENDING_NEXUS_OPERATION_STATE_STARTED - PENDING_NEXUS_OPERATION_STATE_BLOCKED type: string - description: More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING. + description: More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. format: enum scheduleToCloseTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ @@ -11821,7 +11825,7 @@ components: Elapsed time from schedule_time to now for running operations or to close_time for closed operations, including all attempts and backoff between attempts. cancellationInfo: - $ref: '#/components/schemas/NexusOperationCancellationInfo' + $ref: '#/components/schemas/NexusOperationExecutionCancellationInfo' blockedReason: type: string description: If the state is BLOCKED, blocked reason provides additional information. @@ -11854,7 +11858,7 @@ components: $ref: '#/components/schemas/Link' description: Links attached by the handler of this operation on start or completion. description: Full current state of a standalone Nexus operation, as of the time of the request. - NexusOperationListInfo: + NexusOperationExecutionListInfo: type: object properties: operationId: @@ -11882,13 +11886,13 @@ components: format: date-time status: enum: - - NEXUS_OPERATION_STATUS_UNSPECIFIED - - NEXUS_OPERATION_STATUS_RUNNING - - NEXUS_OPERATION_STATUS_COMPLETED - - NEXUS_OPERATION_STATUS_FAILED - - NEXUS_OPERATION_STATUS_CANCELED - - NEXUS_OPERATION_STATUS_TERMINATED - - NEXUS_OPERATION_STATUS_TIMED_OUT + - NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED + - NEXUS_OPERATION_EXECUTION_STATUS_RUNNING + - NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED + - NEXUS_OPERATION_EXECUTION_STATUS_FAILED + - NEXUS_OPERATION_EXECUTION_STATUS_CANCELED + - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED + - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT type: string description: |- Set once when the operation is scheduled and updated once when it reaches a terminal status. @@ -11912,8 +11916,47 @@ components: This field is only populated if the operation is closed. description: |- Limited Nexus operation information returned in the list response. - When adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in - NexusOperationInfo but not at the top-level). + When adding fields here, ensure that it is also present in NexusOperationExecutionInfo (note that it may already be present in + NexusOperationExecutionInfo but not at the top-level). + NexusOperationFailedEventAttributes: + type: object + properties: + scheduledEventId: + type: string + description: The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: Failure details. A NexusOperationFailureInfo wrapping an ApplicationFailureInfo. + requestId: + type: string + description: The request ID allocated at schedule time. + description: Nexus operation failed. + NexusOperationFailureInfo: + type: object + properties: + scheduledEventId: + type: string + description: The NexusOperationScheduled event ID. + endpoint: + type: string + description: Endpoint name. + service: + type: string + description: Service name. + operation: + type: string + description: Operation name. + operationId: + type: string + description: |- + Operation ID - may be empty if the operation completed synchronously. + + Deprecated. Renamed to operation_token. + operationToken: + type: string + description: Operation token - may be empty if the operation completed synchronously. + description: Representation of the Temporal SDK NexusOperationError object that is returned to workflow callers. NexusOperationScheduledEventAttributes: type: object properties: @@ -12431,7 +12474,7 @@ components: description: The run ID of the activity, useful when run_id was not specified in the request. outcome: $ref: '#/components/schemas/ActivityExecutionOutcome' - PollNexusOperationResponse: + PollNexusOperationExecutionResponse: type: object properties: runId: @@ -13042,7 +13085,7 @@ components: reason: type: string description: Reason for requesting the cancellation - RequestCancelNexusOperationRequest: + RequestCancelNexusOperationExecutionRequest: type: object properties: namespace: @@ -13060,8 +13103,8 @@ components: description: Used to de-dupe cancellation requests. reason: type: string - description: Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API. - RequestCancelNexusOperationResponse: + description: Reason for requesting the cancellation, recorded and available via the DescribeNexusOperationExecution API. + RequestCancelNexusOperationExecutionResponse: type: object properties: {} RequestCancelWorkflowExecutionRequest: @@ -14777,7 +14820,7 @@ components: allOf: - $ref: '#/components/schemas/Priority' description: Priority metadata - StartNexusOperationRequest: + StartNexusOperationExecutionRequest: type: object properties: namespace: @@ -14857,7 +14900,7 @@ components: allOf: - $ref: '#/components/schemas/UserMetadata' description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation. - StartNexusOperationResponse: + StartNexusOperationExecutionResponse: type: object properties: runId: @@ -15369,7 +15412,7 @@ components: TerminateActivityExecutionResponse: type: object properties: {} - TerminateNexusOperationRequest: + TerminateNexusOperationExecutionRequest: type: object properties: namespace: @@ -15388,7 +15431,7 @@ components: reason: type: string description: Reason for requesting the termination, recorded in the operation's result failure outcome. - TerminateNexusOperationResponse: + TerminateNexusOperationExecutionResponse: type: object properties: {} TerminateWorkflowExecutionRequest: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index eac513bb5..63fa31aae 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -240,8 +240,8 @@ message Link { string job_id = 1; } - // A link to a standalone Nexus operation. - message NexusOperation { + // A link to a standalone Nexus operation execution. + message NexusOperationExecution { string namespace = 1; string operation_id = 2; string run_id = 3; @@ -250,7 +250,7 @@ message Link { oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; - NexusOperation nexus_operation = 3; + NexusOperationExecution nexus_operation = 3; } } diff --git a/temporal/api/enums/v1/nexus.proto b/temporal/api/enums/v1/nexus.proto index bb967c240..be5e44f13 100644 --- a/temporal/api/enums/v1/nexus.proto +++ b/temporal/api/enums/v1/nexus.proto @@ -23,23 +23,23 @@ enum NexusHandlerErrorRetryBehavior { // Status of a standalone Nexus operation. // (-- api-linter: core::0216::synonyms=disabled // aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) -enum NexusOperationStatus { - NEXUS_OPERATION_STATUS_UNSPECIFIED = 0; +enum NexusOperationExecutionStatus { + NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED = 0; // The operation is not in a terminal status. The operation may be attempting to start, // backing off between attempts, or already started. - NEXUS_OPERATION_STATUS_RUNNING = 1; + NEXUS_OPERATION_EXECUTION_STATUS_RUNNING = 1; // The operation completed successfully. - NEXUS_OPERATION_STATUS_COMPLETED = 2; + NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED = 2; // The operation completed with failure. - NEXUS_OPERATION_STATUS_FAILED = 3; + NEXUS_OPERATION_EXECUTION_STATUS_FAILED = 3; // The operation completed as canceled. // Requesting to cancel an operation does not automatically transition the operation to canceled status, depending // on the current operation status and the cancelation type used. - NEXUS_OPERATION_STATUS_CANCELED = 4; + NEXUS_OPERATION_EXECUTION_STATUS_CANCELED = 4; // The operation was terminated. Termination happens immediately without notifying the handler. - NEXUS_OPERATION_STATUS_TERMINATED = 5; + NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED = 5; // The operation has timed out by reaching the specified schedule-to-close timeout. - NEXUS_OPERATION_STATUS_TIMED_OUT = 6; + NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT = 6; } // Stage that can be specified when waiting on a nexus operation. diff --git a/temporal/api/errordetails/v1/message.proto b/temporal/api/errordetails/v1/message.proto index 5b3c4eccd..2abb60db6 100644 --- a/temporal/api/errordetails/v1/message.proto +++ b/temporal/api/errordetails/v1/message.proto @@ -133,7 +133,7 @@ message ActivityExecutionAlreadyStartedFailure { // An error indicating that a Nexus operation failed to start. Returned when there is an existing operation with the // given operation ID, and the given ID reuse and conflict policies do not permit starting a new one or attaching to an // existing one. -message NexusOperationAlreadyStartedFailure { +message NexusOperationExecutionAlreadyStartedFailure { string start_request_id = 1; string run_id = 2; } diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index 59f1ec246..dfde46f09 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -217,8 +217,8 @@ message EndpointTarget { } } -// NexusOperationCancellationInfo contains the state of a Nexus operation cancellation. -message NexusOperationCancellationInfo { +// NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation. +message NexusOperationExecutionCancellationInfo { // The time when cancellation was requested. google.protobuf.Timestamp requested_time = 1; @@ -243,7 +243,7 @@ message NexusOperationCancellationInfo { } // Full current state of a standalone Nexus operation, as of the time of the request. -message NexusOperationInfo { +message NexusOperationExecutionInfo { // Unique identifier of this Nexus operation within its namespace along with run ID (below). string operation_id = 1; string run_id = 2; @@ -256,8 +256,8 @@ message NexusOperationInfo { string operation = 5; // A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. - temporal.api.enums.v1.NexusOperationStatus status = 6; - // More detailed breakdown of NEXUS_OPERATION_STATUS_RUNNING. + temporal.api.enums.v1.NexusOperationExecutionStatus status = 6; + // More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. temporal.api.enums.v1.PendingNexusOperationState state = 7; // Schedule-to-close timeout for this operation. @@ -288,7 +288,7 @@ message NexusOperationInfo { // operations, including all attempts and backoff between attempts. google.protobuf.Duration execution_duration = 16; - NexusOperationCancellationInfo cancellation_info = 17; + NexusOperationExecutionCancellationInfo cancellation_info = 17; // If the state is BLOCKED, blocked reason provides additional information. string blocked_reason = 18; @@ -317,9 +317,9 @@ message NexusOperationInfo { } // Limited Nexus operation information returned in the list response. -// When adding fields here, ensure that it is also present in NexusOperationInfo (note that it may already be present in -// NexusOperationInfo but not at the top-level). -message NexusOperationListInfo { +// When adding fields here, ensure that it is also present in NexusOperationExecutionInfo (note that it may already be present in +// NexusOperationExecutionInfo but not at the top-level). +message NexusOperationExecutionListInfo { // A unique identifier of this operation within its namespace along with run ID (below). string operation_id = 1; // The run ID of the standalone Nexus operation. @@ -338,7 +338,7 @@ message NexusOperationListInfo { google.protobuf.Timestamp close_time = 7; // Set once when the operation is scheduled and updated once when it reaches a terminal status. // Use DescribeNexusOperation for full current state. - temporal.api.enums.v1.NexusOperationStatus status = 8; + temporal.api.enums.v1.NexusOperationExecutionStatus status = 8; // Search attributes from the start request. temporal.api.common.v1.SearchAttributes search_attributes = 9; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 23a78a7eb..64e7ba39b 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2854,7 +2854,7 @@ message ListActivityExecutionsResponse { bytes next_page_token = 2; } -message StartNexusOperationRequest { +message StartNexusOperationExecutionRequest { string namespace = 1; // The identity of the client who initiated this request. string identity = 2; @@ -2901,14 +2901,14 @@ message StartNexusOperationRequest { temporal.api.sdk.v1.UserMetadata user_metadata = 14; } -message StartNexusOperationResponse { +message StartNexusOperationExecutionResponse { // The run ID of the operation that was started - or used (via NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING). string run_id = 1; // If true, a new operation was started. bool started = 2; } -message DescribeNexusOperationRequest { +message DescribeNexusOperationExecutionRequest { string namespace = 1; string operation_id = 2; // Operation run ID. If empty the request targets the latest run. @@ -2917,7 +2917,7 @@ message DescribeNexusOperationRequest { bool include_input = 4; // Include the outcome (result/failure) in the response if the operation has completed. bool include_outcome = 5; - // Token from a previous DescribeNexusOperationResponse. If present, long-poll until operation + // Token from a previous DescribeNexusOperationExecutionResponse. If present, long-poll until operation // state changes from the state encoded in this token. If absent, return current state immediately. // If present, run_id must also be present. // Note that operation state may change multiple times between requests, therefore it is not @@ -2926,12 +2926,12 @@ message DescribeNexusOperationRequest { bytes long_poll_token = 6; } -message DescribeNexusOperationResponse { +message DescribeNexusOperationExecutionResponse { // The run ID of the operation, useful when run_id was not specified in the request. string run_id = 1; // Information about the operation. - temporal.api.nexus.v1.NexusOperationInfo info = 2; + temporal.api.nexus.v1.NexusOperationExecutionInfo info = 2; // Serialized operation input, passed as the request payload. // Only set if include_input was true in the request. @@ -2949,7 +2949,7 @@ message DescribeNexusOperationResponse { bytes long_poll_token = 6; } -message PollNexusOperationRequest { +message PollNexusOperationExecutionRequest { string namespace = 1; string operation_id = 2; // Operation run ID. If empty the request targets the latest run. @@ -2959,7 +2959,7 @@ message PollNexusOperationRequest { temporal.api.enums.v1.NexusOperationWaitStage wait_stage = 4; } -message PollNexusOperationResponse { +message PollNexusOperationExecutionResponse { // The run ID of the operation, useful when run_id was not specified in the request. string run_id = 1; @@ -2978,11 +2978,11 @@ message PollNexusOperationResponse { } } -message ListNexusOperationsRequest { +message ListNexusOperationExecutionsRequest { string namespace = 1; // Max number of operations to return per page. int32 page_size = 2; - // Token returned in ListNexusOperationsResponse. + // Token returned in ListNexusOperationExecutionsResponse. bytes next_page_token = 3; // Visibility query, see https://docs.temporal.io/list-filter for the syntax. // Search attributes that are avaialble for Nexus operations include: @@ -3001,8 +3001,8 @@ message ListNexusOperationsRequest { string query = 4; } -message ListNexusOperationsResponse { - repeated temporal.api.nexus.v1.NexusOperationListInfo operations = 1; +message ListNexusOperationExecutionsResponse { + repeated temporal.api.nexus.v1.NexusOperationExecutionListInfo operations = 1; // Token to use to fetch the next page. If empty, there is no next page. bytes next_page_token = 2; } @@ -3031,14 +3031,14 @@ message CountActivityExecutionsResponse { } } -message CountNexusOperationsRequest { +message CountNexusOperationExecutionsRequest { string namespace = 1; // Visibility query, see https://docs.temporal.io/list-filter for the syntax. - // See also ListNexusOperationsRequest for search attributes available for Nexus operations. + // See also ListNexusOperationExecutionsRequest for search attributes available for Nexus operations. string query = 2; } -message CountNexusOperationsResponse { +message CountNexusOperationExecutionsResponse { // If `query` is not grouping by any field, the count is an approximate number // of operations that match the query. // If `query` is grouping by a field, the count is simply the sum of the counts @@ -3099,7 +3099,7 @@ message DeleteActivityExecutionRequest { message DeleteActivityExecutionResponse { } -message RequestCancelNexusOperationRequest { +message RequestCancelNexusOperationExecutionRequest { string namespace = 1; string operation_id = 2; // Operation run ID, targets the latest run if empty. @@ -3108,14 +3108,14 @@ message RequestCancelNexusOperationRequest { string identity = 4; // Used to de-dupe cancellation requests. string request_id = 5; - // Reason for requesting the cancellation, recorded and available via the DescribeNexusOperation API. + // Reason for requesting the cancellation, recorded and available via the DescribeNexusOperationExecution API. string reason = 6; } -message RequestCancelNexusOperationResponse { +message RequestCancelNexusOperationExecutionResponse { } -message TerminateNexusOperationRequest { +message TerminateNexusOperationExecutionRequest { string namespace = 1; string operation_id = 2; // Operation run ID, targets the latest run if empty. @@ -3128,15 +3128,15 @@ message TerminateNexusOperationRequest { string reason = 6; } -message TerminateNexusOperationResponse { +message TerminateNexusOperationExecutionResponse { } -message DeleteNexusOperationRequest { +message DeleteNexusOperationExecutionRequest { string namespace = 1; string operation_id = 2; // Operation run ID, targets the latest run if empty. string run_id = 3; } -message DeleteNexusOperationResponse { +message DeleteNexusOperationExecutionResponse { } diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index e0f5a538e..4b3ed16a2 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1373,11 +1373,11 @@ service WorkflowService { }; } - // StartNexusOperation starts a new Nexus operation. + // StartNexusOperationExecution starts a new Nexus operation. // - // Returns a `NexusOperationAlreadyStarted` error if an instance already exists with same operation ID in this + // Returns a `NexusOperationExecutionAlreadyStarted` error if an instance already exists with same operation ID in this // namespace unless permitted by the specified ID conflict policy. - rpc StartNexusOperation (StartNexusOperationRequest) returns (StartNexusOperationResponse) { + rpc StartNexusOperationExecution (StartNexusOperationExecutionRequest) returns (StartNexusOperationExecutionResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/nexus-operations/{operation_id}" body: "*" @@ -1402,12 +1402,12 @@ service WorkflowService { }; } - // DescribeNexusOperation returns information about a Nexus operation. + // DescribeNexusOperationExecution returns information about a Nexus operation. // Supported use cases include: // - Get current operation info without waiting // - Long-poll for next state change and return new operation info // Response can optionally include operation input or outcome (if the operation has completed). - rpc DescribeNexusOperation (DescribeNexusOperationRequest) returns (DescribeNexusOperationResponse) { + rpc DescribeNexusOperationExecution (DescribeNexusOperationExecutionRequest) returns (DescribeNexusOperationExecutionResponse) { option (google.api.http) = { get: "/namespaces/{namespace}/nexus-operations/{operation_id}" additional_bindings { @@ -1427,9 +1427,9 @@ service WorkflowService { }; } - // PollNexusOperation long-polls for a Nexus operation for a given wait stage to complete and returns + // PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns // the outcome (result or failure). - rpc PollNexusOperation (PollNexusOperationRequest) returns (PollNexusOperationResponse) { + rpc PollNexusOperationExecution (PollNexusOperationExecutionRequest) returns (PollNexusOperationExecutionResponse) { option (google.api.http) = { get: "/namespaces/{namespace}/nexus-operations/{operation_id}/poll" additional_bindings { @@ -1448,8 +1448,8 @@ service WorkflowService { }; } - // ListNexusOperations is a visibility API to list Nexus operations in a specific namespace. - rpc ListNexusOperations (ListNexusOperationsRequest) returns (ListNexusOperationsResponse) { + // ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace. + rpc ListNexusOperationExecutions (ListNexusOperationExecutionsRequest) returns (ListNexusOperationExecutionsResponse) { option (google.api.http) = { get: "/namespaces/{namespace}/nexus-operations" additional_bindings { @@ -1468,8 +1468,8 @@ service WorkflowService { }; } - // CountNexusOperations is a visibility API to count Nexus operations in a specific namespace. - rpc CountNexusOperations (CountNexusOperationsRequest) returns (CountNexusOperationsResponse) { + // CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace. + rpc CountNexusOperationExecutions (CountNexusOperationExecutionsRequest) returns (CountNexusOperationExecutionsResponse) { option (google.api.http) = { get: "/namespaces/{namespace}/nexus-operation-count" additional_bindings { @@ -1495,12 +1495,12 @@ service WorkflowService { }; } - // RequestCancelNexusOperation requests cancellation of a Nexus operation. + // RequestCancelNexusOperationExecution requests cancellation of a Nexus operation. // // Requesting to cancel an operation does not automatically transition the operation to canceled status. // The operation will only transition to canceled status if it supports cancellation and the handler // processes the cancellation request. - rpc RequestCancelNexusOperation (RequestCancelNexusOperationRequest) returns (RequestCancelNexusOperationResponse) { + rpc RequestCancelNexusOperationExecution (RequestCancelNexusOperationExecutionRequest) returns (RequestCancelNexusOperationExecutionResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/nexus-operations/{operation_id}/cancel" body: "*" @@ -1535,11 +1535,11 @@ service WorkflowService { // aip.dev/not-precedent: Activity deletion not exposed to HTTP, users should use cancel or terminate. --) rpc DeleteActivityExecution (DeleteActivityExecutionRequest) returns (DeleteActivityExecutionResponse) {} - // TerminateNexusOperation terminates an existing Nexus operation immediately. + // TerminateNexusOperationExecution terminates an existing Nexus operation immediately. // // Termination happens immediately and the operation handler cannot react to it. A terminated operation will have // its outcome set to a failure with a termination reason. - rpc TerminateNexusOperation (TerminateNexusOperationRequest) returns (TerminateNexusOperationResponse) { + rpc TerminateNexusOperationExecution (TerminateNexusOperationExecutionRequest) returns (TerminateNexusOperationExecutionResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/nexus-operations/{operation_id}/terminate" body: "*" @@ -1550,11 +1550,11 @@ service WorkflowService { }; } - // DeleteNexusOperation asynchronously deletes a specific Nexus operation run (when + // DeleteNexusOperationExecution asynchronously deletes a specific Nexus operation run (when // run_id is provided) or the latest run (when run_id is not provided). If the operation // is running, it will be terminated before deletion. // // (-- api-linter: core::0127::http-annotation=disabled // aip.dev/not-precedent: Nexus operation deletion not exposed to HTTP, users should use cancel or terminate. --) - rpc DeleteNexusOperation (DeleteNexusOperationRequest) returns (DeleteNexusOperationResponse) {} + rpc DeleteNexusOperationExecution (DeleteNexusOperationExecutionRequest) returns (DeleteNexusOperationExecutionResponse) {} } From 1077802edace6e65e36a44d1028f8db8fb83964e Mon Sep 17 00:00:00 2001 From: Stephan Behnke Date: Wed, 25 Feb 2026 18:05:25 -0800 Subject: [PATCH 21/21] consistent comment --- openapi/openapiv2.json | 6 +++--- openapi/openapiv3.yaml | 8 ++++---- temporal/api/enums/v1/nexus.proto | 4 +++- temporal/api/nexus/v1/message.proto | 4 ++-- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 7f7421937..1729c1232 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -14907,7 +14907,7 @@ }, "status": { "$ref": "#/definitions/v1NexusOperationExecutionStatus", - "description": "A general status for this operation, indicates whether it is currently running or in one of the terminal statuses." + "description": "A general status for this operation, indicates whether it is currently running or in one of the terminal statuses.\nUpdated once when the operation is originally scheduled, and again when it reaches a terminal status." }, "state": { "$ref": "#/definitions/v1PendingNexusOperationState", @@ -15035,7 +15035,7 @@ }, "status": { "$ref": "#/definitions/v1NexusOperationExecutionStatus", - "description": "Set once when the operation is scheduled and updated once when it reaches a terminal status.\nUse DescribeNexusOperation for full current state." + "description": "The status is updated once, when the operation is originally scheduled, and again when the operation reaches a terminal status." }, "searchAttributes": { "$ref": "#/definitions/v1SearchAttributes", @@ -15070,7 +15070,7 @@ "NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT" ], "default": "NEXUS_OPERATION_EXECUTION_STATUS_UNSPECIFIED", - "description": "Status of a standalone Nexus operation.\n\n - NEXUS_OPERATION_EXECUTION_STATUS_RUNNING: The operation is not in a terminal status. The operation may be attempting to start,\nbacking off between attempts, or already started.\n - NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_EXECUTION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_EXECUTION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." + "description": "Status of a standalone Nexus operation execution.\nThe status is updated once, when the operation is originally scheduled, and again when the\noperation reaches a terminal status.\n\n - NEXUS_OPERATION_EXECUTION_STATUS_RUNNING: The operation is not in a terminal status. The operation may be attempting to start,\nbacking off between attempts, or already started.\n - NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED: The operation completed successfully.\n - NEXUS_OPERATION_EXECUTION_STATUS_FAILED: The operation completed with failure.\n - NEXUS_OPERATION_EXECUTION_STATUS_CANCELED: The operation completed as canceled.\nRequesting to cancel an operation does not automatically transition the operation to canceled status, depending\non the current operation status and the cancelation type used.\n - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED: The operation was terminated. Termination happens immediately without notifying the handler.\n - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT: The operation has timed out by reaching the specified schedule-to-close timeout." }, "v1NexusOperationFailedEventAttributes": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 468dfcf1e..bfe8775f2 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -11768,7 +11768,9 @@ components: - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT type: string - description: A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. + description: |- + A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. + Updated once when the operation is originally scheduled, and again when it reaches a terminal status. format: enum state: enum: @@ -11894,9 +11896,7 @@ components: - NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED - NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT type: string - description: |- - Set once when the operation is scheduled and updated once when it reaches a terminal status. - Use DescribeNexusOperation for full current state. + description: The status is updated once, when the operation is originally scheduled, and again when the operation reaches a terminal status. format: enum searchAttributes: allOf: diff --git a/temporal/api/enums/v1/nexus.proto b/temporal/api/enums/v1/nexus.proto index be5e44f13..e1d54abe8 100644 --- a/temporal/api/enums/v1/nexus.proto +++ b/temporal/api/enums/v1/nexus.proto @@ -20,7 +20,9 @@ enum NexusHandlerErrorRetryBehavior { NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE = 2; } -// Status of a standalone Nexus operation. +// Status of a standalone Nexus operation execution. +// The status is updated once, when the operation is originally scheduled, and again when the +// operation reaches a terminal status. // (-- api-linter: core::0216::synonyms=disabled // aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) enum NexusOperationExecutionStatus { diff --git a/temporal/api/nexus/v1/message.proto b/temporal/api/nexus/v1/message.proto index dfde46f09..fb6209cd8 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -256,6 +256,7 @@ message NexusOperationExecutionInfo { string operation = 5; // A general status for this operation, indicates whether it is currently running or in one of the terminal statuses. + // Updated once when the operation is originally scheduled, and again when it reaches a terminal status. temporal.api.enums.v1.NexusOperationExecutionStatus status = 6; // More detailed breakdown of NEXUS_OPERATION_EXECUTION_STATUS_RUNNING. temporal.api.enums.v1.PendingNexusOperationState state = 7; @@ -336,8 +337,7 @@ message NexusOperationExecutionListInfo { google.protobuf.Timestamp schedule_time = 6; // If the operation is in a terminal status, this field represents the time the operation transitioned to that status. google.protobuf.Timestamp close_time = 7; - // Set once when the operation is scheduled and updated once when it reaches a terminal status. - // Use DescribeNexusOperation for full current state. + // The status is updated once, when the operation is originally scheduled, and again when the operation reaches a terminal status. temporal.api.enums.v1.NexusOperationExecutionStatus status = 8; // Search attributes from the start request.