diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 2f21bedcc..1729c1232 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": "CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace.", + "operationId": "CountNexusOperationExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CountSchedulesResponse" + "$ref": "#/definitions/v1CountNexusOperationExecutionsResponse" } }, "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 ListNexusOperationExecutionsRequest 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": "ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace.", + "operationId": "ListNexusOperationExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSchedulesResponse" + "$ref": "#/definitions/v1ListNexusOperationExecutionsResponse" } }, "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 ListNexusOperationExecutionsResponse.", "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": "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/v1DescribeScheduleResponse" + "$ref": "#/definitions/v1DescribeNexusOperationExecutionResponse" } }, "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 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", + "format": "byte" } ], "tags": [ "WorkflowService" ] }, - "delete": { - "summary": "Deletes a schedule, removing it from the system.", - "operationId": "DeleteSchedule2", + "post": { + "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/v1DeleteScheduleResponse" + "$ref": "#/definitions/v1StartNexusOperationExecutionResponse" } }, "default": { @@ -1613,38 +1640,41 @@ "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", + "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" }, { - "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/WorkflowServiceStartNexusOperationExecutionBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/api/v1/namespaces/{namespace}/nexus-operations/{operationId}/cancel": { "post": { - "summary": "Creates a new schedule.", - "operationId": "CreateSchedule2", + "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": "RequestCancelNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateScheduleResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationExecutionResponse" } }, "default": { @@ -1657,14 +1687,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 +1702,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelNexusOperationExecutionBody" } } ], @@ -1683,15 +1711,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": "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/v1ListScheduleMatchingTimesResponse" + "$ref": "#/definitions/v1PollNexusOperationExecutionResponse" } }, "default": { @@ -1704,32 +1732,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 +1768,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": "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": "TerminateNexusOperationExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PatchScheduleResponse" + "$ref": "#/definitions/v1TerminateNexusOperationExecutionResponse" } }, "default": { @@ -1758,14 +1790,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 +1805,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePatchScheduleBody" + "$ref": "#/definitions/WorkflowServiceTerminateNexusOperationExecutionBody" } } ], @@ -1784,15 +1814,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 +1835,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 +1852,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 +1873,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 +1928,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", @@ -4500,15 +4852,202 @@ ] } }, - "/cluster/namespaces/{namespace}/update": { + "/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/v1UpdateNamespaceResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/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", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListNexusEndpointsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "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": "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": "string" + } + ], + "tags": [ + "OperatorService" + ] + }, + "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", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CreateNexusEndpointResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/v1CreateNexusEndpointRequest" + } + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/cluster/nexus/endpoints/{id}": { + "get": { + "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/v1GetNexusEndpointResponse" + } + }, + "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" + } + ], + "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", + "format": "int64" + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/cluster/nexus/endpoints/{id}/update": { "post": { - "summary": "UpdateNamespace is used to update the information and configuration of a registered\nnamespace.", - "operationId": "UpdateNamespace", + "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/v1UpdateNamespaceResponse" + "$ref": "#/definitions/v1UpdateNexusEndpointResponse" } }, "default": { @@ -4520,7 +5059,8 @@ }, "parameters": [ { - "name": "namespace", + "name": "id", + "description": "Server-generated unique endpoint ID.", "in": "path", "required": true, "type": "string" @@ -4530,24 +5070,24 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" + "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" } } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster/nexus/endpoints": { + "/namespaces/{namespace}/activities": { "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", + "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/v1ListNexusEndpointsResponse" + "$ref": "#/definitions/v1ListActivityExecutionsResponse" } }, "default": { @@ -4558,8 +5098,15 @@ } }, "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", @@ -4567,32 +5114,35 @@ }, { "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.", + "description": "Token returned in ListActivityExecutionsResponse.", "in": "query", "required": false, "type": "string", "format": "byte" }, { - "name": "name", - "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", "in": "query", "required": false, "type": "string" } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, + } + }, + "/namespaces/{namespace}/activities-deprecated/pause": { "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": "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/v1CreateNexusEndpointResponse" + "$ref": "#/definitions/v1PauseActivityResponse" } }, "default": { @@ -4603,29 +5153,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/WorkflowServicePauseActivityBody" } } ], "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-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/v1GetNexusEndpointResponse" + "$ref": "#/definitions/v1ResetActivityResponse" } }, "default": { @@ -4637,25 +5195,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": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceResetActivityBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, - "delete": { - "summary": "Delete an incoming Nexus service by ID.", - "operationId": "DeleteNexusEndpoint", + } + }, + "/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/v1DeleteNexusEndpointResponse" + "$ref": "#/definitions/v1UnpauseActivityResponse" } }, "default": { @@ -4667,35 +5236,35 @@ }, "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/WorkflowServiceUnpauseActivityBody" + } } ], "tags": [ - "OperatorService" + "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 +5276,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 +5287,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 +5322,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 +5407,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 +5429,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 +5444,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -4822,16 +5453,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 +5474,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 +5491,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" } } ], @@ -4863,16 +5500,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 +5521,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 +5538,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" } } ], @@ -4904,15 +5547,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 +5573,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 +5594,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 +5631,22 @@ "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 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" ] - }, + } + }, + "/namespaces/{namespace}/activities/{activityId}/resolve-as-canceled": { "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": "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/v1StartActivityExecutionResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" } }, "default": { @@ -5030,13 +5659,14 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "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.", + "description": "Id of the activity to confirm is cancelled", "in": "path", "required": true, "type": "string" @@ -5046,7 +5676,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" } } ], @@ -5055,16 +5685,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/cancel": { + "/namespaces/{namespace}/activities/{activityId}/terminate": { "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": "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/v1RequestCancelActivityExecutionResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -5092,7 +5722,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -5101,15 +5731,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/complete": { + "/namespaces/{namespace}/activity-complete": { "post": { - "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById", + "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/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" } }, "default": { @@ -5122,14 +5753,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 complete", "in": "path", "required": true, "type": "string" @@ -5139,7 +5762,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" } } ], @@ -5148,15 +5771,15 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/fail": { - "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}/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/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1CountActivityExecutionsResponse" } }, "default": { @@ -5169,14 +5792,45 @@ "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", + "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}/activity-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/v1RespondActivityTaskFailedResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", "in": "path", "required": true, "type": "string" @@ -5186,7 +5840,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" } } ], @@ -5195,15 +5849,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 +5871,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 +5880,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], @@ -5242,15 +5889,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 +5916,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 +5929,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 +5950,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 +5980,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 +6001,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 +6028,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 +6049,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 +6086,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 +6112,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 +6133,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 +6150,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" } } ], @@ -5497,16 +6159,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 +6184,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 +6205,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 +6231,10 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "seriesName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" - } + "type": "string" } ], "tags": [ @@ -5577,15 +6242,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 +6282,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 +6294,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 +6315,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 +6339,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 +6360,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 +6382,17 @@ "tags": [ "WorkflowService" ] - }, - "post": { - "summary": "StartBatchOperation starts a new batch operation", - "operationId": "StartBatchOperation", + } + }, + "/namespaces/{namespace}/nexus-operation-count": { + "get": { + "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/v1StartBatchOperationResponse" + "$ref": "#/definitions/v1CountNexusOperationExecutionsResponse" } }, "default": { @@ -5734,25 +6405,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 ListNexusOperationExecutionsRequest 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 +6422,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}/stop": { - "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation", + "/namespaces/{namespace}/nexus-operations": { + "get": { + "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/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1ListNexusOperationExecutionsResponse" } }, "default": { @@ -5781,25 +6443,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 ListNexusOperationExecutionsResponse.", + "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 +6476,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": "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/v1SetCurrentDeploymentResponse" + "$ref": "#/definitions/v1DescribeNexusOperationExecutionResponse" } }, "default": { @@ -5833,35 +6502,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 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", + "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": "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/v1GetCurrentDeploymentResponse" + "$ref": "#/definitions/v1StartNexusOperationExecutionResponse" } }, "default": { @@ -5879,10 +6567,19 @@ "type": "string" }, { - "name": "seriesName", + "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" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartNexusOperationExecutionBody" + } } ], "tags": [ @@ -5890,15 +6587,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": "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": "RequestCancelNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListDeploymentsResponse" + "$ref": "#/definitions/v1RequestCancelNexusOperationExecutionResponse" } }, "default": { @@ -5916,25 +6614,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/WorkflowServiceRequestCancelNexusOperationExecutionBody" + } } ], "tags": [ @@ -5942,15 +6633,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": "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/v1DescribeDeploymentResponse" + "$ref": "#/definitions/v1PollNexusOperationExecutionResponse" } }, "default": { @@ -5968,18 +6659,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": [ @@ -5987,15 +6690,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": "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": "TerminateNexusOperationExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + "$ref": "#/definitions/v1TerminateNexusOperationExecutionResponse" } }, "default": { @@ -6013,18 +6717,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/WorkflowServiceTerminateNexusOperationExecutionBody" + } } ], "tags": [ @@ -8769,6 +9473,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." }, + "LinkNexusOperationExecution": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "operationId": { + "type": "string" + }, + "runId": { + "type": "string" + } + }, + "description": "A link to a standalone Nexus operation execution." + }, "LinkWorkflowEvent": { "type": "object", "properties": { @@ -9353,6 +10072,27 @@ } } }, + "WorkflowServiceRequestCancelNexusOperationExecutionBody": { + "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 DescribeNexusOperationExecution API." + } + } + }, "WorkflowServiceRequestCancelWorkflowExecutionBody": { "type": "object", "properties": { @@ -10007,6 +10747,62 @@ } } }, + "WorkflowServiceStartNexusOperationExecutionBody": { + "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 caller-side start request. Typically UUIDv4.\nStartOperation requests sent to the handler will use a server-generated request ID." + }, + "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 +10948,27 @@ } } }, + "WorkflowServiceTerminateNexusOperationExecutionBody": { + "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": { @@ -11920,6 +12737,40 @@ } } }, + "v1CountNexusOperationExecutionsResponse": { + "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/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." + } + } + }, + "v1CountNexusOperationExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CountSchedulesResponse": { "type": "object", "properties": { @@ -12266,6 +13117,36 @@ } } }, + "v1DescribeNexusOperationExecutionResponse": { + "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/v1NexusOperationExecutionInfo", + "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." + } + } + }, "v1DescribeScheduleResponse": { "type": "object", "properties": { @@ -13246,6 +14127,9 @@ }, "batchJob": { "$ref": "#/definitions/LinkBatchJob" + }, + "nexusOperation": { + "$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." @@ -13350,6 +14234,23 @@ } } }, + "v1ListNexusOperationExecutionsResponse": { + "type": "object", + "properties": { + "operations": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1NexusOperationExecutionListInfo" + } + }, + "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": { @@ -13941,6 +14842,236 @@ }, "description": "Nexus operation completed successfully." }, + "v1NexusOperationExecutionCancellationInfo": { + "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": "NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation." + }, + "v1NexusOperationExecutionInfo": { + "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/v1NexusOperationExecutionStatus", + "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", + "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": "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/v1NexusOperationExecutionCancellationInfo" + }, + "blockedReason": { + "type": "string", + "description": "If the state is BLOCKED, blocked reason provides additional information." + }, + "requestId": { + "type": "string", + "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", + "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": "Full current state of a standalone Nexus operation, as of the time of the request." + }, + "v1NexusOperationExecutionListInfo": { + "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/v1NexusOperationExecutionStatus", + "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", + "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 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 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", "properties": { @@ -13991,6 +15122,27 @@ }, "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", "properties": { @@ -14087,6 +15239,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": { @@ -14439,6 +15601,31 @@ } } }, + "v1PollNexusOperationExecutionResponse": { + "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": "The current stage of the operation. May be more advanced than the stage requested in the poll." + }, + "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 +16066,9 @@ } } }, + "v1RequestCancelNexusOperationExecutionResponse": { + "type": "object" + }, "v1RequestCancelWorkflowExecutionResponse": { "type": "object" }, @@ -15836,6 +17026,19 @@ } } }, + "v1StartNexusOperationExecutionResponse": { + "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 +17382,9 @@ "v1TerminateActivityExecutionResponse": { "type": "object" }, + "v1TerminateNexusOperationExecutionResponse": { + "type": "object" + }, "v1TerminateWorkflowExecutionResponse": { "type": "object" }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index c220f6773..bfe8775f2 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1343,6 +1343,327 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operation-count: + get: + tags: + - WorkflowService + description: CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace. + operationId: CountNexusOperationExecutions + 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 ListNexusOperationExecutionsRequest for search attributes available for Nexus operations. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountNexusOperationExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations: + get: + tags: + - WorkflowService + description: ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperationExecutions + 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 ListNexusOperationExecutionsResponse. + 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/ListNexusOperationExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/nexus-operations/{operationId}: + get: + tags: + - WorkflowService + description: |- + 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: DescribeNexusOperationExecution + 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 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 + 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/DescribeNexusOperationExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartNexusOperationExecution starts a new Nexus operation. + + 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: StartNexusOperationExecution + parameters: + - name: namespace + in: path + required: true + schema: + 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 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationExecutionResponse' + 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: |- + 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: RequestCancelNexusOperationExecution + 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/RequestCancelNexusOperationExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationExecutionResponse' + 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: |- + PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns + the outcome (result or failure). + operationId: PollNexusOperationExecution + 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/PollNexusOperationExecutionResponse' + 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: |- + 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: TerminateNexusOperationExecution + 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/TerminateNexusOperationExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/schedule-count: get: tags: @@ -5436,12 +5757,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: CountNexusOperationExecutions is a visibility API to count Nexus operations in a specific namespace. + operationId: CountNexusOperationExecutions parameters: - name: namespace in: path @@ -5450,7 +5771,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 ListNexusOperationExecutionsRequest for search attributes available for Nexus operations. schema: type: string responses: @@ -5459,27 +5782,346 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CountSchedulesResponse' + $ref: '#/components/schemas/CountNexusOperationExecutionsResponse' 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: ListNexusOperationExecutions is a visibility API to list Nexus operations in a specific namespace. + operationId: ListNexusOperationExecutions 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 ListNexusOperationExecutionsResponse. + 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/ListNexusOperationExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}: + get: + tags: + - WorkflowService + description: |- + 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: DescribeNexusOperationExecution + 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 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 + 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/DescribeNexusOperationExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartNexusOperationExecution starts a new Nexus operation. + + 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: StartNexusOperationExecution + parameters: + - name: namespace + in: path + required: true + schema: + 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 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartNexusOperationExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/cancel: + post: + tags: + - WorkflowService + description: |- + 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: RequestCancelNexusOperationExecution + 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/RequestCancelNexusOperationExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelNexusOperationExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/poll: + get: + tags: + - WorkflowService + description: |- + PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns + the outcome (result or failure). + operationId: PollNexusOperationExecution + 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/PollNexusOperationExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/nexus-operations/{operationId}/terminate: + post: + tags: + - WorkflowService + description: |- + 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: TerminateNexusOperationExecution + 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/TerminateNexusOperationExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateNexusOperationExecutionResponse' + 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,14 +9719,41 @@ components: $ref: '#/components/schemas/Payload' count: type: string - CountSchedulesResponse: + CountNexusOperationExecutionsResponse: type: object properties: count: type: string description: |- If `query` is not grouping by any field, the count is an approximate number - of schedules that match the query. + 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/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. + CountNexusOperationExecutionsResponse_AggregationGroup: + type: object + properties: + groupValues: + type: array + items: + $ref: '#/components/schemas/Payload' + count: + type: string + CountSchedulesResponse: + type: object + properties: + count: + type: string + description: |- + If `query` is not grouping by any field, the count is an approximate number + of schedules 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 schedules matching the query. @@ -9456,6 +10125,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. + DescribeNexusOperationExecutionResponse: + 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/NexusOperationExecutionInfo' + 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 +11059,8 @@ components: $ref: '#/components/schemas/Link_WorkflowEvent' batchJob: $ref: '#/components/schemas/Link_BatchJob' + 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: @@ -10376,6 +11075,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_NexusOperationExecution: + type: object + properties: + namespace: + type: string + operationId: + type: string + runId: + type: string + description: A link to a standalone Nexus operation execution. Link_WorkflowEvent: type: object properties: @@ -10453,6 +11162,17 @@ components: type: array items: $ref: '#/components/schemas/Endpoint' + ListNexusOperationExecutionsResponse: + type: object + properties: + operations: + type: array + items: + $ref: '#/components/schemas/NexusOperationExecutionListInfo' + 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: @@ -10978,6 +11698,226 @@ components: type: string description: The request ID allocated at schedule time. description: Nexus operation completed successfully. + NexusOperationExecutionCancellationInfo: + type: object + properties: + requestedTime: + type: string + 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 + 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: 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 + 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: NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation. + NexusOperationExecutionInfo: + 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_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. + Updated once when the operation is originally scheduled, and again when it reaches a terminal status. + 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: |- + 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/NexusOperationExecutionCancellationInfo' + blockedReason: + type: string + description: If the state is BLOCKED, blocked reason provides additional information. + requestId: + type: string + description: |- + 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. + 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: Full current state of a standalone Nexus operation, as of the time of the request. + NexusOperationExecutionListInfo: + 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_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: The status is updated once, when the operation is originally scheduled, and again when the operation reaches a terminal status. + 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 NexusOperationExecutionInfo (note that it may already be present in + NexusOperationExecutionInfo but not at the top-level). NexusOperationFailedEventAttributes: type: object properties: @@ -11534,6 +12474,31 @@ components: description: The run ID of the activity, useful when run_id was not specified in the request. outcome: $ref: '#/components/schemas/ActivityExecutionOutcome' + PollNexusOperationExecutionResponse: + 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: The current stage of the operation. May be more advanced than the stage requested in the poll. + 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 +13085,28 @@ components: reason: type: string description: Reason for requesting the cancellation + RequestCancelNexusOperationExecutionRequest: + 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 DescribeNexusOperationExecution API. + RequestCancelNexusOperationExecutionResponse: + type: object + properties: {} RequestCancelWorkflowExecutionRequest: type: object properties: @@ -13833,6 +14820,95 @@ components: allOf: - $ref: '#/components/schemas/Priority' description: Priority metadata + StartNexusOperationExecutionRequest: + 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 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. + 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. + StartNexusOperationExecutionResponse: + 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 +15412,28 @@ components: TerminateActivityExecutionResponse: type: object properties: {} + TerminateNexusOperationExecutionRequest: + 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. + TerminateNexusOperationExecutionResponse: + type: object + properties: {} TerminateWorkflowExecutionRequest: type: object properties: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index aa5b3f370..63fa31aae 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 execution. + message NexusOperationExecution { + string namespace = 1; + string operation_id = 2; + string run_id = 3; + } + oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; + NexusOperationExecution nexus_operation = 3; } } diff --git a/temporal/api/enums/v1/nexus.proto b/temporal/api/enums/v1/nexus.proto index 3a3087716..e1d54abe8 100644 --- a/temporal/api/enums/v1/nexus.proto +++ b/temporal/api/enums/v1/nexus.proto @@ -20,3 +20,63 @@ enum NexusHandlerErrorRetryBehavior { NEXUS_HANDLER_ERROR_RETRY_BEHAVIOR_NON_RETRYABLE = 2; } +// 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 { + 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_EXECUTION_STATUS_RUNNING = 1; + // The operation completed successfully. + NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED = 2; + // The operation completed with failure. + 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_EXECUTION_STATUS_CANCELED = 4; + // The operation was terminated. Termination happens immediately without notifying the handler. + NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED = 5; + // The operation has timed out by reaching the specified schedule-to-close timeout. + NEXUS_OPERATION_EXECUTION_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 c01e90e2c..2abb60db6 100644 --- a/temporal/api/errordetails/v1/message.proto +++ b/temporal/api/errordetails/v1/message.proto @@ -129,3 +129,11 @@ message ActivityExecutionAlreadyStartedFailure { string start_request_id = 1; string run_id = 2; } + +// 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 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 552b75c26..fb6209cd8 100644 --- a/temporal/api/nexus/v1/message.proto +++ b/temporal/api/nexus/v1/message.proto @@ -9,10 +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 @@ -199,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. @@ -213,3 +216,138 @@ message EndpointTarget { External external = 2; } } + +// NexusOperationExecutionCancellationInfo contains the state of a Nexus operation cancellation. +message NexusOperationExecutionCancellationInfo { + // 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 CancelNexusOperationRequest. + string reason = 8; +} + +// Full current state of a standalone Nexus operation, as of the time of the request. +message NexusOperationExecutionInfo { + // 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. + // 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; + + // 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; + + // 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; + + NexusOperationExecutionCancellationInfo cancellation_info = 17; + + // If the state is BLOCKED, blocked reason provides additional information. + string blocked_reason = 18; + + // 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. + 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 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. + 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; + // 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. + 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 4bf3272c6..64e7ba39b 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -20,6 +20,7 @@ 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/activity.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"; @@ -275,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"; } @@ -453,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"; } @@ -2853,6 +2854,159 @@ message ListActivityExecutionsResponse { bytes next_page_token = 2; } +message StartNexusOperationExecutionRequest { + string namespace = 1; + // The identity of the client who initiated this request. + string identity = 2; + // 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 + // 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; + // 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 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 DescribeNexusOperationExecutionRequest { + 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 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 + // 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 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.NexusOperationExecutionInfo 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 PollNexusOperationExecutionRequest { + 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 PollNexusOperationExecutionResponse { + // The run ID of the operation, useful when run_id was not specified in the request. + string run_id = 1; + + // 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. + 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 ListNexusOperationExecutionsRequest { + string namespace = 1; + // Max number of operations to return per page. + int32 page_size = 2; + // 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: + // - OperationId + // - RunId + // - Endpoint + // - Service + // - Operation + // - RequestId + // - StartTime + // - ExecutionTime + // - CloseTime + // - ExecutionStatus + // - ExecutionDuration + // - StateTransitionCount + string query = 4; +} + +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; +} + message CountActivityExecutionsRequest { string namespace = 1; // Visibility query, see https://docs.temporal.io/list-filter for the syntax. @@ -2877,6 +3031,31 @@ message CountActivityExecutionsResponse { } } +message CountNexusOperationExecutionsRequest { + string namespace = 1; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + // See also ListNexusOperationExecutionsRequest for search attributes available for Nexus operations. + string query = 2; +} + +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 + // 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 RequestCancelActivityExecutionRequest { string namespace = 1; string activity_id = 2; @@ -2919,3 +3098,45 @@ message DeleteActivityExecutionRequest { message DeleteActivityExecutionResponse { } + +message RequestCancelNexusOperationExecutionRequest { + 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 DescribeNexusOperationExecution API. + string reason = 6; +} + +message RequestCancelNexusOperationExecutionResponse { +} + +message TerminateNexusOperationExecutionRequest { + 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 TerminateNexusOperationExecutionResponse { +} + +message DeleteNexusOperationExecutionRequest { + string namespace = 1; + string operation_id = 2; + // Operation run ID, targets the latest run if empty. + string run_id = 3; +} + +message DeleteNexusOperationExecutionResponse { +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index c67a2717b..4b3ed16a2 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1373,6 +1373,21 @@ service WorkflowService { }; } + // StartNexusOperationExecution starts a new Nexus operation. + // + // 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 StartNexusOperationExecution (StartNexusOperationExecutionRequest) returns (StartNexusOperationExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/nexus-operations/{operation_id}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}" + body: "*" + } + }; + } + // DescribeActivityExecution returns information about an activity execution. // It can be used to: // - Get current activity info without waiting @@ -1387,6 +1402,20 @@ service WorkflowService { }; } + // 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 DescribeNexusOperationExecution (DescribeNexusOperationExecutionRequest) returns (DescribeNexusOperationExecutionResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/nexus-operations/{operation_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}" + } + }; + } + // PollActivityExecution long-polls for an activity execution to complete and returns the // outcome (result or failure). rpc PollActivityExecution (PollActivityExecutionRequest) returns (PollActivityExecutionResponse) { @@ -1398,6 +1427,17 @@ service WorkflowService { }; } + // PollNexusOperationExecution long-polls for a Nexus operation for a given wait stage to complete and returns + // the outcome (result or failure). + rpc PollNexusOperationExecution (PollNexusOperationExecutionRequest) returns (PollNexusOperationExecutionResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/nexus-operations/{operation_id}/poll" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/nexus-operations/{operation_id}/poll" + } + }; + } + // ListActivityExecutions is a visibility API to list activity executions in a specific namespace. rpc ListActivityExecutions (ListActivityExecutionsRequest) returns (ListActivityExecutionsResponse) { option (google.api.http) = { @@ -1408,6 +1448,16 @@ service WorkflowService { }; } + // 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 { + get: "/api/v1/namespaces/{namespace}/nexus-operations" + } + }; + } + // CountActivityExecutions is a visibility API to count activity executions in a specific namespace. rpc CountActivityExecutions (CountActivityExecutionsRequest) returns (CountActivityExecutionsResponse) { option (google.api.http) = { @@ -1418,6 +1468,16 @@ service WorkflowService { }; } + // 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 { + get: "/api/v1/namespaces/{namespace}/nexus-operation-count" + } + }; + } + // RequestCancelActivityExecution requests cancellation of an activity execution. // // Cancellation is cooperative: this call records the request, but the activity must detect and @@ -1435,6 +1495,22 @@ service WorkflowService { }; } + // 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 RequestCancelNexusOperationExecution (RequestCancelNexusOperationExecutionRequest) returns (RequestCancelNexusOperationExecutionResponse) { + 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: "*" + } + }; + } + // TerminateActivityExecution terminates an existing activity execution immediately. // // Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a @@ -1458,4 +1534,27 @@ service WorkflowService { // (-- api-linter: core::0127::http-annotation=disabled // aip.dev/not-precedent: Activity deletion not exposed to HTTP, users should use cancel or terminate. --) rpc DeleteActivityExecution (DeleteActivityExecutionRequest) returns (DeleteActivityExecutionResponse) {} + + // 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 TerminateNexusOperationExecution (TerminateNexusOperationExecutionRequest) returns (TerminateNexusOperationExecutionResponse) { + 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: "*" + } + }; + } + + // 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 DeleteNexusOperationExecution (DeleteNexusOperationExecutionRequest) returns (DeleteNexusOperationExecutionResponse) {} }