diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index ad6aae01b..4aa32a26b 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -157,6 +157,60 @@ ] } }, + "/api/v1/namespaces/{namespace}/activities": { + "get": { + "summary": "ListActivityExecutions is a visibility API to list activity executions in a specific namespace.", + "operationId": "ListActivityExecutions2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListActivityExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListActivityExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/activities/cancel": { "post": { "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", @@ -640,15 +694,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/archived-workflows": { - "get": { - "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", - "operationId": "ListArchivedWorkflowExecutions2", + "/api/v1/namespaces/{namespace}/activities/{activityId}": { + "post": { + "summary": "StartActivityExecution starts a new activity execution.", + "description": "Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", + "operationId": "StartActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + "$ref": "#/definitions/v1StartActivityExecutionResponse" } }, "default": { @@ -666,24 +721,18 @@ "type": "string" }, { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" - }, - { - "name": "nextPageToken", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "name": "activityId", + "in": "path", + "required": true, + "type": "string" }, { - "name": "query", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" + } } ], "tags": [ @@ -691,15 +740,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/batch-operations": { + "/api/v1/namespaces/{namespace}/activities/{execution.activityId}": { "get": { - "summary": "ListBatchOperations returns a list of batch operations", - "operationId": "ListBatchOperations2", + "summary": "DescribeActivityExecution returns information about the specified activity execution.", + "operationId": "DescribeActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListBatchOperationsResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -712,26 +761,21 @@ "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": "execution.activityId", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", - "description": "Next page token", + "name": "execution.runId", "in": "query", "required": false, - "type": "string", - "format": "byte" + "type": "string" } ], "tags": [ @@ -739,15 +783,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/batch-operations/{jobId}": { - "get": { - "summary": "DescribeBatchOperation returns the information about a batch operation", - "operationId": "DescribeBatchOperation2", + "/api/v1/namespaces/{namespace}/activities/{execution.activityId}/cancel": { + "post": { + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Requesting to cancel an activity does not automatically transition the activity to canceled status. If the\nactivity has a currently running attempt, the activity will only transition to canceled status if the current\nattempt is unsuccessful.\nTODO: Clarify what happens if there are no more allowed retries after the current attempt.\n\nIt returns success if the requested activity is already closed.\nTODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?", + "operationId": "RequestCancelActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeBatchOperationResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -760,31 +805,39 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "execution.activityId", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" + } } ], "tags": [ "WorkflowService" ] - }, - "post": { - "summary": "StartBatchOperation starts a new batch operation", - "operationId": "StartBatchOperation2", + } + }, + "/api/v1/namespaces/{namespace}/activities/{execution.activityId}/result": { + "get": { + "summary": "GetActivityResult returns the activity result if it is in a terminal status or (optionally) wait for it to reach\none.", + "operationId": "GetActivityResult2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartBatchOperationResponse" + "$ref": "#/definitions/v1GetActivityResultResponse" } }, "default": { @@ -797,25 +850,28 @@ "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", + "name": "execution.activityId", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" - } + "name": "execution.runId", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "wait", + "description": "If set, turns this request into a long poll that is unblocked when the activity reaches a terminal status.\nThe wait duration is capped by the request's context deadline or by the maximum enforced long poll interval\nallowed by the server.", + "in": "query", + "required": false, + "type": "boolean" } ], "tags": [ @@ -823,15 +879,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/batch-operations/{jobId}/stop": { + "/api/v1/namespaces/{namespace}/activities/{execution.activityId}/terminate": { "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation2", + "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 and will be requested to be canceled by the server when it heartbeats.", + "operationId": "TerminateActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -844,14 +901,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "execution.activityId", "in": "path", "required": true, "type": "string" @@ -861,7 +916,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -870,15 +925,15 @@ ] } }, - "/api/v1/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": "SetCurrentDeployment2", + "/api/v1/namespaces/{namespace}/activity-count": { + "get": { + "summary": "CountActivityExecutions is a visibility API to count of activity executions in a specific namespace.", + "operationId": "CountActivityExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetCurrentDeploymentResponse" + "$ref": "#/definitions/v1CountActivityExecutionsResponse" } }, "default": { @@ -896,19 +951,11 @@ "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, + "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/WorkflowServiceSetCurrentDeploymentBody" - } } ], "tags": [ @@ -916,15 +963,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/current-deployment/{seriesName}": { + "/api/v1/namespaces/{namespace}/archived-workflows": { "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": "GetCurrentDeployment2", + "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", + "operationId": "ListArchivedWorkflowExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetCurrentDeploymentResponse" + "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" } }, "default": { @@ -942,9 +989,23 @@ "type": "string" }, { - "name": "seriesName", - "in": "path", - "required": true, + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "in": "query", + "required": false, "type": "string" } ], @@ -953,15 +1014,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments": { + "/api/v1/namespaces/{namespace}/batch-operations": { "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": "ListDeployments2", + "summary": "ListBatchOperations returns a list of batch operations", + "operationId": "ListBatchOperations2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListDeploymentsResponse" + "$ref": "#/definitions/v1ListBatchOperationsResponse" } }, "default": { @@ -974,12 +1035,14 @@ "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", @@ -987,17 +1050,11 @@ }, { "name": "nextPageToken", + "description": "Next page token", "in": "query", "required": false, "type": "string", "format": "byte" - }, - { - "name": "seriesName", - "description": "Optional. Use to filter based on exact series name match.", - "in": "query", - "required": false, - "type": "string" } ], "tags": [ @@ -1005,15 +1062,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "/api/v1/namespaces/{namespace}/batch-operations/{jobId}": { "get": { - "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", - "operationId": "DescribeDeployment2", + "summary": "DescribeBatchOperation returns the information about a batch operation", + "operationId": "DescribeBatchOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeDeploymentResponse" + "$ref": "#/definitions/v1DescribeBatchOperationResponse" } }, "default": { @@ -1026,20 +1083,14 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "name": "jobId", + "description": "Batch job id", "in": "path", "required": true, "type": "string" @@ -1048,17 +1099,15 @@ "tags": [ "WorkflowService" ] - } - }, - "/api/v1/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": "GetDeploymentReachability2", + }, + "post": { + "summary": "StartBatchOperation starts a new batch operation", + "operationId": "StartBatchOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + "$ref": "#/definitions/v1StartBatchOperationResponse" } }, "default": { @@ -1071,21 +1120,295 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "name": "jobId", + "description": "Job ID defines the unique ID for the batch job", "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, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/batch-operations/{jobId}/stop": { + "post": { + "summary": "StopBatchOperation stops a batch operation", + "operationId": "StopBatchOperation2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StopBatchOperationResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "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": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/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": "SetCurrentDeployment2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/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": "GetCurrentDeployment2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "seriesName", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/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": "ListDeployments2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListDeploymentsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "get": { + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", + "operationId": "DescribeDeployment2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeDeploymentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "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": [ + "WorkflowService" + ] + } + }, + "/api/v1/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": "GetDeploymentReachability2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "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" } @@ -3721,18 +4044,266 @@ } ], "tags": [ - "WorkflowService" + "WorkflowService" + ] + }, + "post": { + "summary": "RegisterNamespace creates a new namespace which can be used as a container for all resources.", + "description": "A Namespace is a top level entity within Temporal, and is used as a container for resources\nlike workflow executions, task queues, etc. A Namespace acts as a sandbox and provides\nisolation for all resources within the namespace. All resources belongs to exactly one\nnamespace.", + "operationId": "RegisterNamespace", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1RegisterNamespaceResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/v1RegisterNamespaceRequest" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster/namespaces/{namespace}": { + "get": { + "summary": "DescribeNamespace returns the information and configuration for a registered namespace.", + "operationId": "DescribeNamespace", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeNamespaceResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "id", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster/namespaces/{namespace}/search-attributes": { + "get": { + "summary": "ListSearchAttributes returns comprehensive information about search attributes.", + "operationId": "ListSearchAttributes", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListSearchAttributesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/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" ] }, - "post": { - "summary": "RegisterNamespace creates a new namespace which can be used as a container for all resources.", - "description": "A Namespace is a top level entity within Temporal, and is used as a container for resources\nlike workflow executions, task queues, etc. A Namespace acts as a sandbox and provides\nisolation for all resources within the namespace. All resources belongs to exactly one\nnamespace.", - "operationId": "RegisterNamespace", + "delete": { + "summary": "Delete an incoming Nexus service by ID.", + "operationId": "DeleteNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RegisterNamespaceResponse" + "$ref": "#/definitions/v1DeleteNexusEndpointResponse" } }, "default": { @@ -3744,28 +4315,35 @@ }, "parameters": [ { - "name": "body", - "in": "body", + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/v1RegisterNamespaceRequest" - } + "type": "string" + }, + { + "name": "version", + "description": "Data version for this endpoint. Must match current version.", + "in": "query", + "required": false, + "type": "string", + "format": "int64" } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster/namespaces/{namespace}": { - "get": { - "summary": "DescribeNamespace returns the information and configuration for a registered namespace.", - "operationId": "DescribeNamespace", + "/cluster/nexus/endpoints/{id}/update": { + "post": { + "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", + "operationId": "UpdateNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeNamespaceResponse" + "$ref": "#/definitions/v1UpdateNexusEndpointResponse" } }, "default": { @@ -3777,32 +4355,35 @@ }, "parameters": [ { - "name": "namespace", + "name": "id", + "description": "Server-generated unique endpoint ID.", "in": "path", "required": true, "type": "string" }, { - "name": "id", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + } } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster/namespaces/{namespace}/search-attributes": { + "/namespaces/{namespace}/activities": { "get": { - "summary": "ListSearchAttributes returns comprehensive information about search attributes.", - "operationId": "ListSearchAttributes", + "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/v1ListSearchAttributesResponse" + "$ref": "#/definitions/v1ListActivityExecutionsResponse" } }, "default": { @@ -3818,22 +4399,46 @@ "in": "path", "required": true, "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListActivityExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/namespaces/{namespace}/update": { + "/namespaces/{namespace}/activities/cancel": { "post": { - "summary": "UpdateNamespace is used to update the information and configuration of a registered\nnamespace.", - "operationId": "UpdateNamespace", + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCanceled", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNamespaceResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" } }, "default": { @@ -3855,7 +4460,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" } } ], @@ -3864,15 +4469,15 @@ ] } }, - "/cluster/nexus/endpoints": { - "get": { - "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", - "operationId": "ListNexusEndpoints", + "/namespaces/{namespace}/activities/cancel-by-id": { + "post": { + "summary": "See `RecordActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCanceledById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNexusEndpointsResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" } }, "default": { @@ -3884,40 +4489,36 @@ }, "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": "namespace", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" }, { - "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" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, + } + }, + "/namespaces/{namespace}/activities/complete": { "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": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", + "description": "This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCompleted", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" } }, "default": { @@ -3928,29 +4529,35 @@ } }, "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointRequest" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" } } ], "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/complete-by-id": { + "post": { + "summary": "See `RecordActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCompletedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" } }, "default": { @@ -3962,25 +4569,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/WorkflowServiceRespondActivityTaskCompletedByIdBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, - "delete": { - "summary": "Delete an incoming Nexus service by ID.", - "operationId": "DeleteNexusEndpoint", + } + }, + "/namespaces/{namespace}/activities/fail": { + "post": { + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskFailed", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" } }, "default": { @@ -3992,35 +4610,34 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "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/WorkflowServiceRespondActivityTaskFailedBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/nexus/endpoints/{id}/update": { + "/namespaces/{namespace}/activities/fail-by-id": { "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": "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/v1UpdateNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" } }, "default": { @@ -4032,8 +4649,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" @@ -4043,25 +4660,25 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/namespaces/{namespace}/activities/cancel": { + "/namespaces/{namespace}/activities/heartbeat": { "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCanceled", + "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", + "description": "If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to\nthe workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in\nsuch situations, in that event, the SDK should request cancellation of the activity.", + "operationId": "RecordActivityTaskHeartbeat", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" } }, "default": { @@ -4083,7 +4700,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], @@ -4092,15 +4709,15 @@ ] } }, - "/namespaces/{namespace}/activities/cancel-by-id": { + "/namespaces/{namespace}/activities/heartbeat-by-id": { "post": { - "summary": "See `RecordActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCanceledById", + "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/v1RespondActivityTaskCanceledByIdResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" } }, "default": { @@ -4123,7 +4740,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" } } ], @@ -4132,16 +4749,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete": { + "/namespaces/{namespace}/activities/pause": { "post": { - "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", - "description": "This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCompleted", + "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", + "operationId": "PauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + "$ref": "#/definitions/v1PauseActivityResponse" } }, "default": { @@ -4154,6 +4771,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4163,7 +4781,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" + "$ref": "#/definitions/WorkflowServicePauseActivityBody" } } ], @@ -4172,15 +4790,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete-by-id": { + "/namespaces/{namespace}/activities/reset": { "post": { - "summary": "See `RecordActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById", + "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", + "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.", + "operationId": "ResetActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1ResetActivityResponse" } }, "default": { @@ -4193,7 +4812,7 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4203,7 +4822,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + "$ref": "#/definitions/WorkflowServiceResetActivityBody" } } ], @@ -4212,16 +4831,16 @@ ] } }, - "/namespaces/{namespace}/activities/fail": { + "/namespaces/{namespace}/activities/unpause": { "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": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", + "operationId": "UnpauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" + "$ref": "#/definitions/v1UnpauseActivityResponse" } }, "default": { @@ -4234,6 +4853,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4243,7 +4863,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" } } ], @@ -4252,15 +4872,15 @@ ] } }, - "/namespaces/{namespace}/activities/fail-by-id": { + "/namespaces/{namespace}/activities/update-options": { "post": { - "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskFailedById", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.", + "operationId": "UpdateActivityOptions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1UpdateActivityOptionsResponse" } }, "default": { @@ -4283,7 +4903,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" } } ], @@ -4292,16 +4912,16 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat": { + "/namespaces/{namespace}/activities/{activityId}": { "post": { - "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", - "description": "If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to\nthe workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in\nsuch situations, in that event, the SDK should request cancellation of the activity.", - "operationId": "RecordActivityTaskHeartbeat", + "summary": "StartActivityExecution starts a new activity execution.", + "description": "Returns an `ExecutionAlreadyStarted` 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/v1RecordActivityTaskHeartbeatResponse" + "$ref": "#/definitions/v1StartActivityExecutionResponse" } }, "default": { @@ -4318,12 +4938,18 @@ "required": true, "type": "string" }, + { + "name": "activityId", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" + "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" } } ], @@ -4332,15 +4958,15 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat-by-id": { - "post": { - "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RecordActivityTaskHeartbeatById", + "/namespaces/{namespace}/activities/{execution.activityId}": { + "get": { + "summary": "DescribeActivityExecution returns information about the specified activity execution.", + "operationId": "DescribeActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -4353,18 +4979,21 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "execution.activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" - } + "type": "string" + }, + { + "name": "execution.runId", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -4372,16 +5001,16 @@ ] } }, - "/namespaces/{namespace}/activities/pause": { + "/namespaces/{namespace}/activities/{execution.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", - "operationId": "PauseActivity", + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Requesting to cancel an activity does not automatically transition the activity to canceled status. If the\nactivity has a currently running attempt, the activity will only transition to canceled status if the current\nattempt is unsuccessful.\nTODO: Clarify what happens if there are no more allowed retries after the current attempt.\n\nIt returns success if the requested activity is already closed.\nTODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?", + "operationId": "RequestCancelActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PauseActivityResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -4394,7 +5023,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "execution.activityId", "in": "path", "required": true, "type": "string" @@ -4404,7 +5038,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -4413,16 +5047,15 @@ ] } }, - "/namespaces/{namespace}/activities/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.", - "operationId": "ResetActivity", + "/namespaces/{namespace}/activities/{execution.activityId}/result": { + "get": { + "summary": "GetActivityResult returns the activity result if it is in a terminal status or (optionally) wait for it to reach\none.", + "operationId": "GetActivityResult", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ResetActivityResponse" + "$ref": "#/definitions/v1GetActivityResultResponse" } }, "default": { @@ -4435,18 +5068,28 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "execution.activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" - } + "type": "string" + }, + { + "name": "execution.runId", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "wait", + "description": "If set, turns this request into a long poll that is unblocked when the activity reaches a terminal status.\nThe wait duration is capped by the request's context deadline or by the maximum enforced long poll interval\nallowed by the server.", + "in": "query", + "required": false, + "type": "boolean" } ], "tags": [ @@ -4454,16 +5097,16 @@ ] } }, - "/namespaces/{namespace}/activities/unpause": { + "/namespaces/{namespace}/activities/{execution.activityId}/terminate": { "post": { - "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", - "operationId": "UnpauseActivity", + "summary": "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 and will be requested to be canceled by the server when it heartbeats.", + "operationId": "TerminateActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UnpauseActivityResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -4476,7 +5119,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "execution.activityId", "in": "path", "required": true, "type": "string" @@ -4486,7 +5134,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -4495,15 +5143,15 @@ ] } }, - "/namespaces/{namespace}/activities/update-options": { - "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.", - "operationId": "UpdateActivityOptions", + "/namespaces/{namespace}/activity-count": { + "get": { + "summary": "CountActivityExecutions is a visibility API to count of activity executions in a specific namespace.", + "operationId": "CountActivityExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsResponse" + "$ref": "#/definitions/v1CountActivityExecutionsResponse" } }, "default": { @@ -4516,18 +5164,16 @@ "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/WorkflowServiceUpdateActivityOptionsBody" - } + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -7334,22 +7980,6 @@ } } }, - "CountWorkflowExecutionsResponseAggregationGroup": { - "type": "object", - "properties": { - "groupValues": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1Payload" - } - }, - "count": { - "type": "string", - "format": "int64" - } - } - }, "DeploymentInfoTaskQueueInfo": { "type": "object", "properties": { @@ -7439,6 +8069,21 @@ } } }, + "LinkActivity": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "activityId": { + "type": "string" + }, + "runId": { + "type": "string" + } + }, + "description": "A link to an activity." + }, "LinkBatchJob": { "type": "object", "properties": { @@ -7509,19 +8154,6 @@ } } }, - "PauseInfoManual": { - "type": "object", - "properties": { - "identity": { - "type": "string", - "description": "The identity of the actor that paused the activity." - }, - "reason": { - "type": "string", - "description": "Reason for pausing the activity." - } - } - }, "PauseInfoRule": { "type": "object", "properties": { @@ -7539,24 +8171,6 @@ } } }, - "PendingActivityInfoPauseInfo": { - "type": "object", - "properties": { - "pauseTime": { - "type": "string", - "format": "date-time", - "description": "The time when the activity was paused." - }, - "manual": { - "$ref": "#/definitions/PauseInfoManual", - "title": "activity was paused by the manual intervention" - }, - "rule": { - "$ref": "#/definitions/PauseInfoRule", - "title": "activity was paused by the rule" - } - } - }, "PostResetOperationSignalWorkflow": { "type": "object", "properties": { @@ -8092,7 +8706,7 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", @@ -8128,6 +8742,33 @@ } } }, + "WorkflowServiceRequestCancelActivityExecutionBody": { + "type": "object", + "properties": { + "execution": { + "type": "object", + "properties": { + "runId": { + "type": "string" + } + }, + "description": "Activity execution, targets the latest run if run_id is empty.", + "title": "Activity execution, targets the latest run if run_id is empty." + }, + "identity": { + "type": "string", + "description": "The identity of the worker/client." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe cancellation requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the cancellation, recorded and available via the DescribeActivityExecution API.\nNot propagated to a worker if an activity attempt is currently running." + } + } + }, "WorkflowServiceRequestCancelWorkflowExecutionBody": { "type": "object", "properties": { @@ -8293,7 +8934,7 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", @@ -8352,7 +8993,7 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", @@ -8411,7 +9052,7 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", @@ -8656,23 +9297,91 @@ }, "input": { "$ref": "#/definitions/v1Payloads", - "title": "Serialized value(s) to provide with the signal" + "title": "Serialized value(s) to provide with the signal" + }, + "identity": { + "type": "string", + "title": "The identity of the worker/client" + }, + "requestId": { + "type": "string", + "title": "Used to de-dupe sent signals" + }, + "control": { + "type": "string", + "description": "Deprecated." + }, + "header": { + "$ref": "#/definitions/v1Header", + "description": "Headers that are passed with the signal to the processing workflow.\nThese can include things like auth or tracing tokens." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apicommonv1Link" + }, + "description": "Links to be associated with the WorkflowExecutionSignaled event." + } + }, + "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationSignal.\n - temporal.api.workflow.v1.PostResetOperation.SignalWorkflow." + }, + "WorkflowServiceStartActivityExecutionBody": { + "type": "object", + "properties": { + "identity": { + "type": "string", + "title": "The identity of the client who initiated this request" + }, + "requestId": { + "type": "string", + "description": "A unique identifier for this start request. Typically UUIDv4." + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType" + }, + "options": { + "$ref": "#/definitions/v1ActivityOptions" + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "description": "Serialized arguments to the activity. These are passed as arguments to the activity function." }, - "identity": { - "type": "string", - "title": "The identity of the worker/client" + "idReusePolicy": { + "$ref": "#/definitions/v1IdReusePolicy", + "description": "Defines whether to allow re-using the activity id from a previously *closed* activity.\nThe default policy is ID_REUSE_POLICY_ALLOW_DUPLICATE." }, - "requestId": { - "type": "string", - "title": "Used to de-dupe sent signals" + "idConflictPolicy": { + "$ref": "#/definitions/v1IdConflictPolicy", + "description": "Defines how to resolve an activity id conflict with a *running* activity.\nThe default policy is ID_CONFLICT_POLICY_FAIL." }, - "control": { - "type": "string", - "description": "Deprecated." + "memo": { + "$ref": "#/definitions/v1Memo", + "description": "Arbitrary structured data that can be attached to the activity execution and made available via the list and\ndescribe APIs." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes for indexing." }, "header": { "$ref": "#/definitions/v1Header", - "description": "Headers that are passed with the signal to the processing workflow.\nThese can include things like auth or tracing tokens." + "description": "Header for context propagation and tracing purposes." + }, + "requestEagerExecution": { + "type": "boolean", + "description": "Request to get the first activity task inline in the response bypassing matching service and worker polling.\nIf set to `true` the caller is expected to have a worker available and capable of processing the task.\nThe returned task will be marked as started and is expected to be completed by the specified\n`schedule_to_close_timeout`." + }, + "completionCallbacks": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Callback" + }, + "description": "Callbacks to be called by the server when this activity reaches a terminal status.\nCallback addresses must be whitelisted in the server's dynamic configuration." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity." }, "links": { "type": "array", @@ -8680,10 +9389,17 @@ "type": "object", "$ref": "#/definitions/apicommonv1Link" }, - "description": "Links to be associated with the WorkflowExecutionSignaled event." + "description": "Links to be associated with the activity." + }, + "onConflictOptions": { + "$ref": "#/definitions/apiactivityv1OnConflictOptions", + "description": "Defines actions to be done to the existing running activity when ID_CONFLICT_POLICY_USE_EXISTING is used. If not\nset or empty, it won't do anything to the existing running activity." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "title": "Priority metadata" } - }, - "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationSignal.\n - temporal.api.workflow.v1.PostResetOperation.SignalWorkflow." + } }, "WorkflowServiceStartBatchOperationBody": { "type": "object", @@ -8836,7 +9552,7 @@ "description": "If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.\nTo unset the override after the workflow is running, use UpdateWorkflowExecutionOptions." }, "onConflictOptions": { - "$ref": "#/definitions/v1OnConflictOptions", + "$ref": "#/definitions/apiworkflowv1OnConflictOptions", "description": "Defines actions to be done to the existing running workflow when the conflict policy\nWORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING is used. If not set (ie., nil value) or set to a\nempty object (ie., all options with default value), it won't do anything to the existing\nrunning workflow. If set, it will add a history event to the running workflow." }, "priority": { @@ -8858,6 +9574,29 @@ } } }, + "WorkflowServiceTerminateActivityExecutionBody": { + "type": "object", + "properties": { + "execution": { + "type": "object", + "properties": { + "runId": { + "type": "string" + } + }, + "description": "Activity execution, targets the latest run if run_id is empty.", + "title": "Activity execution, targets the latest run if run_id is empty." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the termination, recorded in in the activity's result failure outcome." + }, + "identity": { + "type": "string", + "description": "The identity of the worker/client." + } + } + }, "WorkflowServiceTerminateWorkflowExecutionBody": { "type": "object", "properties": { @@ -9191,6 +9930,24 @@ }, "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationUpdateWorkflowExecutionOptions.\n - temporal.api.workflow.v1.PostResetOperation.UpdateWorkflowOptions." }, + "apiactivityv1OnConflictOptions": { + "type": "object", + "properties": { + "attachRequestId": { + "type": "boolean", + "description": "Attaches the request ID to the running workflow." + }, + "attachCompletionCallbacks": { + "type": "boolean", + "description": "Attaches the completion callbacks to the running workflow." + }, + "attachLinks": { + "type": "boolean", + "description": "Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event." + } + }, + "description": "When StartActivityExecution uses the ID_CONFLICT_POLICY_USE_EXISTING and there is already an existing running\nactivity, OnConflictOptions defines actions to be taken on the existing running activity, updating its state." + }, "apicommonv1Link": { "type": "object", "properties": { @@ -9199,6 +9956,9 @@ }, "batchJob": { "$ref": "#/definitions/LinkBatchJob" + }, + "activity": { + "$ref": "#/definitions/LinkActivity" } }, "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." @@ -9302,69 +10062,275 @@ "format": "date-time", "description": "The timestamp when the request was scheduled in the frontend." }, - "startOperation": { - "$ref": "#/definitions/v1StartOperationRequest" + "startOperation": { + "$ref": "#/definitions/v1StartOperationRequest" + }, + "cancelOperation": { + "$ref": "#/definitions/v1CancelOperationRequest" + } + }, + "description": "A Nexus request." + }, + "apinexusv1Response": { + "type": "object", + "properties": { + "startOperation": { + "$ref": "#/definitions/v1StartOperationResponse" + }, + "cancelOperation": { + "$ref": "#/definitions/v1CancelOperationResponse" + } + }, + "description": "A response indicating that the handler has successfully processed a request." + }, + "apiupdatev1Request": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/definitions/v1Meta" + }, + "input": { + "$ref": "#/definitions/v1Input" + } + }, + "description": "The client request that triggers a Workflow Update." + }, + "apiworkflowv1OnConflictOptions": { + "type": "object", + "properties": { + "attachRequestId": { + "type": "boolean", + "description": "Attaches the request ID to the running workflow." + }, + "attachCompletionCallbacks": { + "type": "boolean", + "description": "Attaches the completion callbacks to the running workflow." + }, + "attachLinks": { + "type": "boolean", + "description": "Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event." + } + }, + "description": "When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and\nthere is already an existing running workflow, OnConflictOptions defines actions to be taken on\nthe existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent\nhistory event in the running workflow with the changes requested in this object." + }, + "protobufAny": { + "type": "object", + "properties": { + "@type": { + "type": "string", + "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics." + } + }, + "additionalProperties": {}, + "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(&foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := &pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := &pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": ,\n \"lastName\": \n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" + }, + "rpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/protobufAny" + } + } + } + }, + "v1ActivityExecution": { + "type": "object", + "properties": { + "activityId": { + "type": "string" + }, + "runId": { + "type": "string" + } + }, + "title": "Identifies a specific activity within a namespace. Practically speaking, because run_id is a\nuuid, a workflow execution is globally unique. Note that many commands allow specifying an empty\nrun id as a way of saying \"target the latest run of the activity\".\nTODO: Make this a generic EntityExecution?" + }, + "v1ActivityExecutionInfo": { + "type": "object", + "properties": { + "activityExecution": { + "$ref": "#/definitions/v1ActivityExecution", + "description": "Unique identifier of this activity within its namespace." + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType", + "description": "The type of the activity, a string that maps to a registered activity on a worker." + }, + "status": { + "$ref": "#/definitions/v1ActivityExecutionStatus", + "description": "A general status for this activity, indicates whether it is currently running or in one of the terminal statuses." + }, + "runState": { + "$ref": "#/definitions/v1PendingActivityState", + "description": "More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING." + }, + "heartbeatDetails": { + "$ref": "#/definitions/v1Payloads", + "description": "Details provided in the last recorded activity heartbeat." + }, + "lastHeartbeatTime": { + "type": "string", + "format": "date-time", + "description": "Time the last heartbeat was recorded." + }, + "lastStartedTime": { + "type": "string", + "format": "date-time", + "description": "Time the last attempt was started." + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The attempt this activity is currently on.\nIncremented each time a new attempt is started.\nTODO: Confirm if this is on scheduled or started." + }, + "maximumAttempts": { + "type": "integer", + "format": "int32" + }, + "scheduledTime": { + "type": "string", + "format": "date-time", + "description": "Time the activity was originally scheduled via a StartActivityExecution request." + }, + "expirationTime": { + "type": "string", + "format": "date-time", + "description": "Scheduled time + schedule to close timeout." + }, + "lastFailure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "Failure details from the last failed attempt." + }, + "lastWorkerIdentity": { + "type": "string" + }, + "currentRetryInterval": { + "type": "string", + "description": "Time from the last attempt failure to the next activity retry.\nIf the activity is currently running, this represents the next retry interval in case the attempt fails.\nIf activity is currently backing off between attempt, this represents the current retry interval.\nIf there is no next retry allowed, this field will be null.\nThis interval is typically calculated from the specified retry policy, but may be modified if an activity fails\nwith a retryable application failure specifying a retry delay." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last activity attempt completed. If activity has not been completed yet, it will be null." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next activity attempt will be scheduled.\nIf activity is currently scheduled or started, this field will be null." + }, + "lastDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version this activity was dispatched to most recently.\nIf nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "description": "Priority metadata." + }, + "pauseInfo": { + "$ref": "#/definitions/v1ActivityExecutionInfoPauseInfo" + }, + "activityOptions": { + "$ref": "#/definitions/v1ActivityOptions", + "description": "Current activity options. May be different from the one used to start the activity." + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "description": "Serialized activity input, passed as arguments to the activity function." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Incremented each time the activity's state is mutated in persistence." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + }, + "header": { + "$ref": "#/definitions/v1Header" + }, + "eagerExecutionRequested": { + "type": "boolean", + "description": "Whether the activity was started with a request_eager_execution flag set to `true`, indicating that the first\ntask was delivered inline in the start response, bypassing matching." + }, + "completionCallbacks": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Callback" + }, + "description": "Callbacks to be called by the server when this activity reaches a terminal status.\nCallback addresses must be whitelisted in the server's dynamic configuration." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity." }, - "cancelOperation": { - "$ref": "#/definitions/v1CancelOperationRequest" - } - }, - "description": "A Nexus request." - }, - "apinexusv1Response": { - "type": "object", - "properties": { - "startOperation": { - "$ref": "#/definitions/v1StartOperationResponse" + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apicommonv1Link" + }, + "description": "Links to be associated with the activity." }, - "cancelOperation": { - "$ref": "#/definitions/v1CancelOperationResponse" + "canceledReason": { + "type": "string", + "description": "Set if activity cancelation was requested." } }, - "description": "A response indicating that the handler has successfully processed a request." + "description": "Info for a standalone activity." }, - "apiupdatev1Request": { + "v1ActivityExecutionInfoPauseInfo": { "type": "object", "properties": { - "meta": { - "$ref": "#/definitions/v1Meta" + "pauseTime": { + "type": "string", + "format": "date-time", + "description": "The time when the activity was paused." }, - "input": { - "$ref": "#/definitions/v1Input" + "manual": { + "$ref": "#/definitions/v1ActivityExecutionInfoPauseInfoManual", + "description": "The activity was paused by direct API invocation." } }, - "description": "The client request that triggers a Workflow Update." + "title": "TODO: Move this to a common package?" }, - "protobufAny": { + "v1ActivityExecutionInfoPauseInfoManual": { "type": "object", "properties": { - "@type": { + "identity": { "type": "string", - "description": "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics." - } - }, - "additionalProperties": {}, - "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(&foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := &pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := &pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": ,\n \"lastName\": \n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }" - }, - "rpcStatus": { - "type": "object", - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" + "description": "The identity of the actor that paused the activity." }, - "details": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/protobufAny" - } + "reason": { + "type": "string", + "description": "Reason for pausing the activity." } } }, + "v1ActivityExecutionStatus": { + "type": "string", + "enum": [ + "ACTIVITY_EXECUTION_STATUS_UNSPECIFIED", + "ACTIVITY_EXECUTION_STATUS_RUNNING", + "ACTIVITY_EXECUTION_STATUS_COMPLETED", + "ACTIVITY_EXECUTION_STATUS_FAILED", + "ACTIVITY_EXECUTION_STATUS_CANCELED", + "ACTIVITY_EXECUTION_STATUS_TERMINATED", + "ACTIVITY_EXECUTION_STATUS_TIMED_OUT" + ], + "default": "ACTIVITY_EXECUTION_STATUS_UNSPECIFIED", + "description": "Status of a standalone activity.\nThe status is updated once, when the activity is originally scheduled, and again when the activity reaches a terminal\nstatus.\nTODO: Should this be a common execution status? Seems like the other archetypes will share this status.\n\n - ACTIVITY_EXECUTION_STATUS_RUNNING: The activity is not in a terminal status. This does not necessarily mean that there is a currently running\nattempt. The activity may be backing off between attempts or waiting for a worker to pick it up.\n - ACTIVITY_EXECUTION_STATUS_COMPLETED: The activity completed successfully.\n - ACTIVITY_EXECUTION_STATUS_FAILED: The activity completed with failure.\n - ACTIVITY_EXECUTION_STATUS_CANCELED: The activity completed as canceled.\nRequesting to cancel an activity does not automatically transition the activity to canceled status. If the\nactivity has a currently running attempt, the activity will only transition to canceled status if the current\nattempt is unsuccessful.\nTODO: Clarify what happens if there are no more allowed retries after the current attempt.\n - ACTIVITY_EXECUTION_STATUS_TERMINATED: The activity was terminated. Termination does not reach the worker and the activity code cannot react to it.\nA terminated activity may have a running attempt and will be requested to be canceled by the server when it\nheartbeats.\n - ACTIVITY_EXECUTION_STATUS_TIMED_OUT: The activity has timed out by reaching the specified shedule-to-start or schedule-to-close timeouts.\nTODO: Clarify if there are other conditions where the activity can end up in timed out status." + }, "v1ActivityFailureInfo": { "type": "object", "properties": { @@ -9390,6 +10356,56 @@ } } }, + "v1ActivityListInfo": { + "type": "object", + "properties": { + "activityExecution": { + "$ref": "#/definitions/v1ActivityExecution", + "description": "Unique identifier of this activity within its namespace." + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType", + "description": "The type of the activity, a string that maps to a registered activity on a worker." + }, + "scheduledTime": { + "type": "string", + "format": "date-time", + "title": "Time the activity was originally scheduled via a StartActivityExecution request.\nTODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for\nconsistency?" + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "If the activity is in a terminal status, this field represents the time the activity transitioned to that status." + }, + "status": { + "$ref": "#/definitions/v1ActivityExecutionStatus", + "description": "Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not\navailable in the list response." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes from the start request." + }, + "taskQueue": { + "type": "string", + "description": "The task queue this activity was scheduled on when it was originally started, updated on activity options update." + }, + "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 activity is closed." + } + }, + "description": "Limited activity information returned in the list response." + }, "v1ActivityOptions": { "type": "object", "properties": { @@ -9413,7 +10429,8 @@ "description": "Maximum permitted time between successful worker heartbeats." }, "retryPolicy": { - "$ref": "#/definitions/v1RetryPolicy" + "$ref": "#/definitions/v1RetryPolicy", + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`." } } }, @@ -10680,6 +11697,40 @@ } } }, + "v1CountActivityExecutionsResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "int64", + "description": "If `query` is not grouping by any field, the count is an approximate number\nof activities 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 activities matching the query." + }, + "groups": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CountActivityExecutionsResponseAggregationGroup" + }, + "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." + } + } + }, + "v1CountActivityExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CountWorkflowExecutionsResponse": { "type": "object", "properties": { @@ -10692,12 +11743,28 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/CountWorkflowExecutionsResponseAggregationGroup" + "$ref": "#/definitions/v1CountWorkflowExecutionsResponseAggregationGroup" }, "description": "`groups` contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." } } }, + "v1CountWorkflowExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CreateNexusEndpointRequest": { "type": "object", "properties": { @@ -10750,6 +11817,9 @@ } } }, + "v1DeleteActivityExecutionResponse": { + "type": "object" + }, "v1DeleteNamespaceResponse": { "type": "object", "properties": { @@ -10878,6 +11948,14 @@ "type": "object", "description": "Deprecated." }, + "v1DescribeActivityExecutionResponse": { + "type": "object", + "properties": { + "info": { + "$ref": "#/definitions/v1ActivityExecutionInfo" + } + } + }, "v1DescribeBatchOperationResponse": { "type": "object", "properties": { @@ -11374,6 +12452,23 @@ } } }, + "v1GetActivityResultResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the completed activity, may be used in case a run ID was not specified in the request." + }, + "result": { + "$ref": "#/definitions/v1Payloads", + "description": "The result if the activity completed successfully." + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The failure if the activity completed unsuccessfully." + } + } + }, "v1GetClusterInfoResponse": { "type": "object", "properties": { @@ -11879,6 +12974,28 @@ ], "default": "HISTORY_EVENT_FILTER_TYPE_UNSPECIFIED" }, + "v1IdConflictPolicy": { + "type": "string", + "enum": [ + "ID_CONFLICT_POLICY_UNSPECIFIED", + "ID_CONFLICT_POLICY_FAIL", + "ID_CONFLICT_POLICY_USE_EXISTING", + "ID_CONFLICT_POLICY_TERMINATE_EXISTING" + ], + "default": "ID_CONFLICT_POLICY_UNSPECIFIED", + "description": "Defines what to do when trying to start an execution with the same ID as a *running* execution.\nNote that it is *never* valid to have two actively running instances of the same execution ID.\n\nSee `IdReusePolicy` for handling execution ID duplication with a *closed* execution.\n\n - ID_CONFLICT_POLICY_FAIL: Don't start a new execution; instead return `ExecutionAlreadyStarted` error.\n - ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new execution; instead return a handle for the running execution.\n - ID_CONFLICT_POLICY_TERMINATE_EXISTING: Terminate the running execution before starting a new one." + }, + "v1IdReusePolicy": { + "type": "string", + "enum": [ + "ID_REUSE_POLICY_UNSPECIFIED", + "ID_REUSE_POLICY_ALLOW_DUPLICATE", + "ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY", + "ID_REUSE_POLICY_REJECT_DUPLICATE" + ], + "default": "ID_REUSE_POLICY_UNSPECIFIED", + "description": "Defines whether to allow re-using an ID from a previously *closed* execution.\nIf the request is denied, the server returns an `ExecutionAlreadyStarted` error.\n\nSee `IdConflictPolicy` for handling ID duplication with a *running* execution.\n\n - ID_REUSE_POLICY_ALLOW_DUPLICATE: Always allow starting an execution using the same entity ID.\n - ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting an execution using the same ID, only when the last execution's final state is one of [terminated,\ncancelled, timed out, failed].\n - ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the ID for this execution. Future start requests could potentially change the policy,\nallowing re-use of the ID." + }, "v1IndexedValueType": { "type": "string", "enum": [ @@ -11922,6 +13039,23 @@ }, "description": "IntervalSpec matches times that can be expressed as:\nepoch + n * interval + phase\nwhere n is an integer.\nphase defaults to zero if missing. interval is required.\nBoth interval and phase must be non-negative and are truncated to the nearest\nsecond before any calculations.\nFor example, an interval of 1 hour with phase of zero would match every hour,\non the hour. The same interval but a phase of 19 minutes would match every\nxx:19:00. An interval of 28 days with phase zero would match\n2022-02-17T00:00:00Z (among other times). The same interval with a phase of 3\ndays, 5 hours, and 23 minutes would match 2022-02-20T05:23:00Z instead." }, + "v1ListActivityExecutionsResponse": { + "type": "object", + "properties": { + "executions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1ActivityListInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte", + "description": "Token to use to fetch the next page. If empty, there is no next page." + } + } + }, "v1ListArchivedWorkflowExecutionsResponse": { "type": "object", "properties": { @@ -12790,24 +13924,6 @@ }, "description": "Nexus operation timed out." }, - "v1OnConflictOptions": { - "type": "object", - "properties": { - "attachRequestId": { - "type": "boolean", - "description": "Attaches the request ID to the running workflow." - }, - "attachCompletionCallbacks": { - "type": "boolean", - "description": "Attaches the completion callbacks to the running workflow." - }, - "attachLinks": { - "type": "boolean", - "description": "Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event." - } - }, - "description": "When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and\nthere is already an existing running workflow, OnConflictOptions defines actions to be taken on\nthe existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent\nhistory event in the running workflow with the changes requested in this object." - }, "v1Outcome": { "type": "object", "properties": { @@ -12947,7 +14063,7 @@ "title": "Priority metadata" }, "pauseInfo": { - "$ref": "#/definitions/PendingActivityInfoPauseInfo" + "$ref": "#/definitions/v1PendingActivityInfoPauseInfo" }, "activityOptions": { "$ref": "#/definitions/v1ActivityOptions", @@ -12955,6 +14071,37 @@ } } }, + "v1PendingActivityInfoPauseInfo": { + "type": "object", + "properties": { + "pauseTime": { + "type": "string", + "format": "date-time", + "description": "The time when the activity was paused." + }, + "manual": { + "$ref": "#/definitions/v1PendingActivityInfoPauseInfoManual", + "title": "activity was paused by the manual intervention" + }, + "rule": { + "$ref": "#/definitions/PauseInfoRule", + "title": "activity was paused by the rule" + } + } + }, + "v1PendingActivityInfoPauseInfoManual": { + "type": "object", + "properties": { + "identity": { + "type": "string", + "description": "The identity of the actor that paused the activity." + }, + "reason": { + "type": "string", + "description": "Reason for pausing the activity." + } + } + }, "v1PendingActivityState": { "type": "string", "enum": [ @@ -13643,6 +14790,9 @@ ], "default": "REPLICATION_STATE_UNSPECIFIED" }, + "v1RequestCancelActivityExecutionResponse": { + "type": "object" + }, "v1RequestCancelActivityTaskCommandAttributes": { "type": "object", "properties": { @@ -14740,6 +15890,27 @@ "v1SignalWorkflowExecutionResponse": { "type": "object" }, + "v1StartActivityExecutionResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the activity that was started - or used (via ID_CONFLICT_POLICY_USE_EXISTING)." + }, + "started": { + "type": "boolean", + "description": "If true, a new activity was started." + }, + "eagerTask": { + "$ref": "#/definitions/v1PollActivityTaskQueueResponse", + "description": "When `request_eager_execution` is set on the `StartActivityExecutionRequest`, the server will return the first\nactivity task to be eagerly executed.\nThe caller is expected to have a worker available to process the task." + }, + "link": { + "$ref": "#/definitions/apicommonv1Link", + "description": "Link to the workflow event." + } + } + }, "v1StartBatchOperationResponse": { "type": "object" }, @@ -15118,7 +16289,7 @@ "description": "If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.\nTo unset the override after the workflow is running, use UpdateWorkflowExecutionOptions." }, "onConflictOptions": { - "$ref": "#/definitions/v1OnConflictOptions", + "$ref": "#/definitions/apiworkflowv1OnConflictOptions", "description": "Defines actions to be done to the existing running workflow when the conflict policy\nWORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING is used. If not set (ie., nil value) or set to a\nempty object (ie., all options with default value), it won't do anything to the existing\nrunning workflow. If set, it will add a history event to the running workflow." }, "priority": { @@ -15490,6 +16661,9 @@ "default": "TASK_REACHABILITY_UNSPECIFIED", "description": "Specifies which category of tasks may reach a worker on a versioned task queue.\nUsed both in a reachability query and its response.\nDeprecated.\n\n - TASK_REACHABILITY_NEW_WORKFLOWS: There's a possiblity for a worker to receive new workflow tasks. Workers should *not* be retired.\n - TASK_REACHABILITY_EXISTING_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from existing workflows. Workers\nshould *not* be retired.\nThis enum value does not distinguish between open and closed workflows.\n - TASK_REACHABILITY_OPEN_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from open workflows. Workers\nshould *not* be retired.\n - TASK_REACHABILITY_CLOSED_WORKFLOWS: There's a possiblity for a worker to receive existing workflow tasks from closed workflows. Workers may be\nretired dependending on application requirements. For example, if there's no need to query closed workflows." }, + "v1TerminateActivityExecutionResponse": { + "type": "object" + }, "v1TerminateWorkflowExecutionResponse": { "type": "object" }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index c81fcb4f8..3bd710b52 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -122,6 +122,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities: + get: + tags: + - WorkflowService + description: ListActivityExecutions is a visibility API to list activity executions in a specific namespace. + operationId: ListActivityExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of executions to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListActivityExecutionsResponse. + schema: + type: string + format: bytes + - 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/ListActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/activities/cancel: post: tags: @@ -592,6 +634,238 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{activityId}: + post: + tags: + - WorkflowService + description: |- + StartActivityExecution starts a new activity execution. + + Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace + unless permitted by the specified ID conflict policy. + operationId: StartActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{execution.activity_id}: + get: + tags: + - WorkflowService + description: DescribeActivityExecution returns information about the specified activity execution. + operationId: DescribeActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + - name: execution.activityId + in: query + schema: + type: string + - name: execution.runId + in: query + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{execution.activity_id}/cancel: + post: + tags: + - WorkflowService + description: "RequestCancelActivityExecution requests cancellation of an activity execution.\n\n Requesting to cancel an activity does not automatically transition the activity to canceled status. If the\n activity has a currently running attempt, the activity will only transition to canceled status if the current\n attempt is unsuccessful.\n TODO: Clarify what happens if there are no more allowed retries after the current attempt.\n \n It returns success if the requested activity is already closed.\n TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?" + operationId: RequestCancelActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{execution.activity_id}/result: + get: + tags: + - WorkflowService + description: |- + GetActivityResult returns the activity result if it is in a terminal status or (optionally) wait for it to reach + one. + operationId: GetActivityResult + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + - name: execution.activityId + in: query + schema: + type: string + - name: execution.runId + in: query + schema: + type: string + - name: wait + in: query + description: |- + If set, turns this request into a long poll that is unblocked when the activity reaches a terminal status. + The wait duration is capped by the request's context deadline or by the maximum enforced long poll interval + allowed by the server. + schema: + type: boolean + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetActivityResultResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{execution.activity_id}/terminate: + post: + tags: + - WorkflowService + description: |- + 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 + running attempt and will be requested to be canceled by the server when it heartbeats. + operationId: TerminateActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activity-count: + get: + tags: + - WorkflowService + description: CountActivityExecutions is a visibility API to count of activity executions in a specific namespace. + operationId: CountActivityExecutions + 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/CountActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/archived-workflows: get: tags: @@ -3601,43 +3875,85 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/cancel: - post: + /namespaces/{namespace}/activities: + get: tags: - WorkflowService - description: |- - RespondActivityTaskFailed is called by workers when processing an activity task fails. - - This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history - and a new workflow task created for the workflow. Fails with `NotFound` if the task token is - no longer valid due to activity timeout, already being completed, or never having existed. - operationId: RespondActivityTaskCanceled + description: ListActivityExecutions is a visibility API to list activity executions in a specific namespace. + operationId: ListActivityExecutions parameters: - name: namespace in: path required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RespondActivityTaskCanceledRequest' - required: true + - name: pageSize + in: query + description: Max number of executions to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListActivityExecutionsResponse. + schema: + type: string + format: bytes + - 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/RespondActivityTaskCanceledResponse' + $ref: '#/components/schemas/ListActivityExecutionsResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/cancel-by-id: + /namespaces/{namespace}/activities/cancel: + post: + tags: + - WorkflowService + description: |- + RespondActivityTaskFailed is called by workers when processing an activity task fails. + + This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history + and a new workflow task created for the workflow. Fails with `NotFound` if the task token is + no longer valid due to activity timeout, already being completed, or never having existed. + operationId: RespondActivityTaskCanceled + parameters: + - name: namespace + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskCanceledRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskCanceledResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/cancel-by-id: post: tags: - WorkflowService @@ -4071,6 +4387,238 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{activityId}: + post: + tags: + - WorkflowService + description: |- + StartActivityExecution starts a new activity execution. + + Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace + unless permitted by the specified ID conflict policy. + operationId: StartActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{execution.activity_id}: + get: + tags: + - WorkflowService + description: DescribeActivityExecution returns information about the specified activity execution. + operationId: DescribeActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + - name: execution.activityId + in: query + schema: + type: string + - name: execution.runId + in: query + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{execution.activity_id}/cancel: + post: + tags: + - WorkflowService + description: "RequestCancelActivityExecution requests cancellation of an activity execution.\n\n Requesting to cancel an activity does not automatically transition the activity to canceled status. If the\n activity has a currently running attempt, the activity will only transition to canceled status if the current\n attempt is unsuccessful.\n TODO: Clarify what happens if there are no more allowed retries after the current attempt.\n \n It returns success if the requested activity is already closed.\n TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?" + operationId: RequestCancelActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{execution.activity_id}/result: + get: + tags: + - WorkflowService + description: |- + GetActivityResult returns the activity result if it is in a terminal status or (optionally) wait for it to reach + one. + operationId: GetActivityResult + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + - name: execution.activityId + in: query + schema: + type: string + - name: execution.runId + in: query + schema: + type: string + - name: wait + in: query + description: |- + If set, turns this request into a long poll that is unblocked when the activity reaches a terminal status. + The wait duration is capped by the request's context deadline or by the maximum enforced long poll interval + allowed by the server. + schema: + type: boolean + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetActivityResultResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{execution.activity_id}/terminate: + post: + tags: + - WorkflowService + description: |- + 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 + running attempt and will be requested to be canceled by the server when it heartbeats. + operationId: TerminateActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.activity_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activity-count: + get: + tags: + - WorkflowService + description: CountActivityExecutions is a visibility API to count of activity executions in a specific namespace. + operationId: CountActivityExecutions + 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/CountActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/archived-workflows: get: tags: @@ -6518,6 +7066,172 @@ paths: $ref: '#/components/schemas/Status' components: schemas: + ActivityExecution: + type: object + properties: + activityId: + type: string + runId: + type: string + description: |- + Identifies a specific activity within a namespace. Practically speaking, because run_id is a + uuid, a workflow execution is globally unique. Note that many commands allow specifying an empty + run id as a way of saying "target the latest run of the activity". + TODO: Make this a generic EntityExecution? + ActivityExecutionInfo: + type: object + properties: + activityExecution: + allOf: + - $ref: '#/components/schemas/ActivityExecution' + description: Unique identifier of this activity within its namespace. + activityType: + allOf: + - $ref: '#/components/schemas/ActivityType' + description: The type of the activity, a string that maps to a registered activity on a worker. + status: + enum: + - ACTIVITY_EXECUTION_STATUS_UNSPECIFIED + - ACTIVITY_EXECUTION_STATUS_RUNNING + - ACTIVITY_EXECUTION_STATUS_COMPLETED + - ACTIVITY_EXECUTION_STATUS_FAILED + - ACTIVITY_EXECUTION_STATUS_CANCELED + - ACTIVITY_EXECUTION_STATUS_TERMINATED + - ACTIVITY_EXECUTION_STATUS_TIMED_OUT + type: string + description: A general status for this activity, indicates whether it is currently running or in one of the terminal statuses. + format: enum + runState: + enum: + - PENDING_ACTIVITY_STATE_UNSPECIFIED + - PENDING_ACTIVITY_STATE_SCHEDULED + - PENDING_ACTIVITY_STATE_STARTED + - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED + - PENDING_ACTIVITY_STATE_PAUSED + - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED + type: string + description: More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. + format: enum + heartbeatDetails: + allOf: + - $ref: '#/components/schemas/Payloads' + description: Details provided in the last recorded activity heartbeat. + lastHeartbeatTime: + type: string + description: Time the last heartbeat was recorded. + format: date-time + lastStartedTime: + type: string + description: Time the last attempt was started. + format: date-time + attempt: + type: integer + description: |- + The attempt this activity is currently on. + Incremented each time a new attempt is started. + TODO: Confirm if this is on scheduled or started. + format: int32 + maximumAttempts: + type: integer + format: int32 + scheduledTime: + type: string + description: Time the activity was originally scheduled via a StartActivityExecution request. + format: date-time + expirationTime: + type: string + description: Scheduled time + schedule to close timeout. + format: date-time + lastFailure: + allOf: + - $ref: '#/components/schemas/Failure' + description: Failure details from the last failed attempt. + lastWorkerIdentity: + type: string + currentRetryInterval: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Time from the last attempt failure to the next activity retry. + If the activity is currently running, this represents the next retry interval in case the attempt fails. + If activity is currently backing off between attempt, this represents the current retry interval. + If there is no next retry allowed, this field will be null. + This interval is typically calculated from the specified retry policy, but may be modified if an activity fails + with a retryable application failure specifying a retry delay. + lastAttemptCompleteTime: + type: string + description: The time when the last activity attempt completed. If activity has not been completed yet, it will be null. + format: date-time + nextAttemptScheduleTime: + type: string + description: |- + The time when the next activity attempt will be scheduled. + If activity is currently scheduled or started, this field will be null. + format: date-time + lastDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The Worker Deployment Version this activity was dispatched to most recently. + If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. + priority: + allOf: + - $ref: '#/components/schemas/Priority' + description: Priority metadata. + pauseInfo: + $ref: '#/components/schemas/ActivityExecutionInfo_PauseInfo' + activityOptions: + allOf: + - $ref: '#/components/schemas/ActivityOptions' + description: Current activity options. May be different from the one used to start the activity. + input: + allOf: + - $ref: '#/components/schemas/Payloads' + description: Serialized activity input, passed as arguments to the activity function. + stateTransitionCount: + type: string + description: Incremented each time the activity's state is mutated in persistence. + searchAttributes: + $ref: '#/components/schemas/SearchAttributes' + header: + $ref: '#/components/schemas/Header' + eagerExecutionRequested: + type: boolean + description: |- + Whether the activity was started with a request_eager_execution flag set to `true`, indicating that the first + task was delivered inline in the start response, bypassing matching. + completionCallbacks: + type: array + items: + $ref: '#/components/schemas/Callback' + description: |- + Callbacks to be called by the server when this activity reaches a terminal status. + Callback addresses must be whitelisted in the server's dynamic configuration. + 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 activity. + links: + type: array + items: + $ref: '#/components/schemas/Link' + description: Links to be associated with the activity. + canceledReason: + type: string + description: Set if activity cancelation was requested. + description: Info for a standalone activity. + ActivityExecutionInfo_PauseInfo: + type: object + properties: + pauseTime: + type: string + description: The time when the activity was paused. + format: date-time + manual: + allOf: + - $ref: '#/components/schemas/PauseInfo_Manual' + description: The activity was paused by direct API invocation. + description: 'TODO: Move this to a common package?' ActivityFailureInfo: type: object properties: @@ -6543,6 +7257,62 @@ components: - RETRY_STATE_CANCEL_REQUESTED type: string format: enum + ActivityListInfo: + type: object + properties: + activityExecution: + allOf: + - $ref: '#/components/schemas/ActivityExecution' + description: Unique identifier of this activity within its namespace. + activityType: + allOf: + - $ref: '#/components/schemas/ActivityType' + description: The type of the activity, a string that maps to a registered activity on a worker. + scheduledTime: + type: string + description: |- + Time the activity was originally scheduled via a StartActivityExecution request. + TODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for + consistency? + format: date-time + closeTime: + type: string + description: If the activity is in a terminal status, this field represents the time the activity transitioned to that status. + format: date-time + status: + enum: + - ACTIVITY_EXECUTION_STATUS_UNSPECIFIED + - ACTIVITY_EXECUTION_STATUS_RUNNING + - ACTIVITY_EXECUTION_STATUS_COMPLETED + - ACTIVITY_EXECUTION_STATUS_FAILED + - ACTIVITY_EXECUTION_STATUS_CANCELED + - ACTIVITY_EXECUTION_STATUS_TERMINATED + - ACTIVITY_EXECUTION_STATUS_TIMED_OUT + type: string + description: |- + Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not + available in the list response. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes from the start request. + taskQueue: + type: string + description: The task queue this activity was scheduled on when it was originally started, updated on activity options update. + 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 activity is closed. + description: Limited activity information returned in the list response. ActivityOptions: type: object properties: @@ -6583,7 +7353,9 @@ components: type: string description: Maximum permitted time between successful worker heartbeats. retryPolicy: - $ref: '#/components/schemas/RetryPolicy' + allOf: + - $ref: '#/components/schemas/RetryPolicy' + description: The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. ActivityPropertiesModifiedExternallyEventAttributes: type: object properties: @@ -7579,6 +8351,33 @@ components: type: string description: Time of the last update. format: date-time + CountActivityExecutionsResponse: + type: object + properties: + count: + type: string + description: |- + If `query` is not grouping by any field, the count is an approximate number + of activities 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 activities matching the query. + groups: + type: array + items: + $ref: '#/components/schemas/CountActivityExecutionsResponse_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. + CountActivityExecutionsResponse_AggregationGroup: + type: object + properties: + groupValues: + type: array + items: + $ref: '#/components/schemas/Payload' + count: + type: string CountWorkflowExecutionsResponse: type: object properties: @@ -7828,6 +8627,11 @@ components: Holds information about ongoing transition of a workflow execution from one worker deployment version to another. Experimental. Might change in the future. + DescribeActivityExecutionResponse: + type: object + properties: + info: + $ref: '#/components/schemas/ActivityExecutionInfo' DescribeBatchOperationResponse: type: object properties: @@ -8362,6 +9166,20 @@ components: allOf: - $ref: '#/components/schemas/WorkerConfig' description: The worker configuration. + GetActivityResultResponse: + type: object + properties: + runId: + type: string + description: The run ID of the completed activity, may be used in case a run ID was not specified in the request. + result: + allOf: + - $ref: '#/components/schemas/Payloads' + description: The result if the activity completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the activity completed unsuccessfully. GetClusterInfoResponse: type: object properties: @@ -8849,11 +9667,23 @@ components: $ref: '#/components/schemas/Link_WorkflowEvent' batchJob: $ref: '#/components/schemas/Link_BatchJob' + activity: + $ref: '#/components/schemas/Link_Activity' 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: in this case, a history event in workflow A could contain a Link to the workflow started event in workflow B, and vice-versa. + Link_Activity: + type: object + properties: + namespace: + type: string + activityId: + type: string + runId: + type: string + description: A link to an activity. Link_BatchJob: type: object properties: @@ -8876,6 +9706,17 @@ components: $ref: '#/components/schemas/WorkflowEvent_EventReference' requestIdRef: $ref: '#/components/schemas/WorkflowEvent_RequestIdReference' + ListActivityExecutionsResponse: + type: object + properties: + executions: + type: array + items: + $ref: '#/components/schemas/ActivityListInfo' + nextPageToken: + type: string + description: Token to use to fetch the next page. If empty, there is no next page. + format: bytes ListArchivedWorkflowExecutionsResponse: type: object properties: @@ -9563,10 +10404,8 @@ components: type: boolean description: Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event. description: |- - When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and - there is already an existing running workflow, OnConflictOptions defines actions to be taken on - the existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent - history event in the running workflow with the changes requested in this object. + When StartActivityExecution uses the ID_CONFLICT_POLICY_USE_EXISTING and there is already an existing running + activity, OnConflictOptions defines actions to be taken on the existing running activity, updating its state. Outcome: type: object properties: @@ -9901,6 +10740,99 @@ components: version: type: string description: The version of the plugin, may be empty. + PollActivityTaskQueueResponse: + type: object + properties: + taskToken: + type: string + description: A unique identifier for this task + format: bytes + workflowNamespace: + type: string + description: The namespace the workflow which requested this activity lives in + workflowType: + allOf: + - $ref: '#/components/schemas/WorkflowType' + description: Type of the requesting workflow + workflowExecution: + allOf: + - $ref: '#/components/schemas/WorkflowExecution' + description: Execution info of the requesting workflow + activityType: + $ref: '#/components/schemas/ActivityType' + activityId: + type: string + description: |- + The autogenerated or user specified identifier of this activity. Can be used to complete the + activity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage + has resolved, but unique IDs for every activity invocation is a good idea. + header: + allOf: + - $ref: '#/components/schemas/Header' + description: |- + Headers specified by the scheduling workflow. Commonly used to propagate contextual info + from the workflow to its activities. For example, tracing contexts. + input: + allOf: + - $ref: '#/components/schemas/Payloads' + description: Arguments to the activity invocation + heartbeatDetails: + allOf: + - $ref: '#/components/schemas/Payloads' + description: |- + Details of the last heartbeat that was recorded for this activity as of the time this task + was delivered. + scheduledTime: + type: string + description: When was this task first scheduled + format: date-time + currentAttemptScheduledTime: + type: string + description: When was this task attempt scheduled + format: date-time + startedTime: + type: string + description: When was this task started (this attempt) + format: date-time + attempt: + type: integer + description: Starting at 1, the number of attempts to perform this activity + format: int32 + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + First scheduled -> final result reported timeout + + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + startToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Current attempt start -> final result reported timeout + + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + heartbeatTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: Window within which the activity must report a heartbeat, or be timed out. + retryPolicy: + allOf: + - $ref: '#/components/schemas/RetryPolicy' + description: |- + This is the retry policy the service uses which may be different from the one provided + (or not) during activity scheduling. The service can override the provided one if some + values are not specified or exceed configured system limits. + pollerScalingDecision: + allOf: + - $ref: '#/components/schemas/PollerScalingDecision' + description: Server-advised information the SDK may use to adjust its poller count. + priority: + allOf: + - $ref: '#/components/schemas/Priority' + description: Priority metadata PollWorkflowTaskQueueResponse: type: object properties: @@ -10257,7 +11189,7 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string description: Run Id of the workflow which scheduled this activity @@ -10404,6 +11336,29 @@ components: input: $ref: '#/components/schemas/Input' description: The client request that triggers a Workflow Update. + RequestCancelActivityExecutionRequest: + type: object + properties: + namespace: + type: string + execution: + allOf: + - $ref: '#/components/schemas/ActivityExecution' + description: Activity execution, targets the latest run if run_id is empty. + identity: + type: string + description: The identity of the worker/client. + requestId: + type: string + description: Used to de-dupe cancellation requests. + reason: + type: string + description: |- + Reason for requesting the cancellation, recorded and available via the DescribeActivityExecution API. + Not propagated to a worker if an activity attempt is currently running. + RequestCancelActivityExecutionResponse: + type: object + properties: {} RequestCancelExternalWorkflowExecutionFailedEventAttributes: type: object properties: @@ -10775,7 +11730,7 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string description: Run Id of the workflow which scheduled this activity @@ -10842,7 +11797,7 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string description: Run Id of the workflow which scheduled this activity @@ -10905,7 +11860,7 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string description: Run Id of the workflow which scheduled this activity @@ -11868,6 +12823,116 @@ components: SignalWorkflowExecutionResponse: type: object properties: {} + StartActivityExecutionRequest: + type: object + properties: + namespace: + type: string + identity: + type: string + description: The identity of the client who initiated this request + requestId: + type: string + description: A unique identifier for this start request. Typically UUIDv4. + activityId: + type: string + activityType: + $ref: '#/components/schemas/ActivityType' + options: + $ref: '#/components/schemas/ActivityOptions' + input: + allOf: + - $ref: '#/components/schemas/Payloads' + description: Serialized arguments to the activity. These are passed as arguments to the activity function. + idReusePolicy: + enum: + - ID_REUSE_POLICY_UNSPECIFIED + - ID_REUSE_POLICY_ALLOW_DUPLICATE + - ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY + - ID_REUSE_POLICY_REJECT_DUPLICATE + type: string + description: |- + Defines whether to allow re-using the activity id from a previously *closed* activity. + The default policy is ID_REUSE_POLICY_ALLOW_DUPLICATE. + format: enum + idConflictPolicy: + enum: + - ID_CONFLICT_POLICY_UNSPECIFIED + - ID_CONFLICT_POLICY_FAIL + - ID_CONFLICT_POLICY_USE_EXISTING + - ID_CONFLICT_POLICY_TERMINATE_EXISTING + type: string + description: |- + Defines how to resolve an activity id conflict with a *running* activity. + The default policy is ID_CONFLICT_POLICY_FAIL. + format: enum + memo: + allOf: + - $ref: '#/components/schemas/Memo' + description: |- + Arbitrary structured data that can be attached to the activity execution and made available via the list and + describe APIs. + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes for indexing. + header: + allOf: + - $ref: '#/components/schemas/Header' + description: Header for context propagation and tracing purposes. + requestEagerExecution: + type: boolean + description: |- + Request to get the first activity task inline in the response bypassing matching service and worker polling. + If set to `true` the caller is expected to have a worker available and capable of processing the task. + The returned task will be marked as started and is expected to be completed by the specified + `schedule_to_close_timeout`. + completionCallbacks: + type: array + items: + $ref: '#/components/schemas/Callback' + description: |- + Callbacks to be called by the server when this activity reaches a terminal status. + Callback addresses must be whitelisted in the server's dynamic configuration. + 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 activity. + links: + type: array + items: + $ref: '#/components/schemas/Link' + description: Links to be associated with the activity. + onConflictOptions: + allOf: + - $ref: '#/components/schemas/OnConflictOptions' + description: |- + Defines actions to be done to the existing running activity when ID_CONFLICT_POLICY_USE_EXISTING is used. If not + set or empty, it won't do anything to the existing running activity. + priority: + allOf: + - $ref: '#/components/schemas/Priority' + description: Priority metadata + StartActivityExecutionResponse: + type: object + properties: + runId: + type: string + description: The run ID of the activity that was started - or used (via ID_CONFLICT_POLICY_USE_EXISTING). + started: + type: boolean + description: If true, a new activity was started. + eagerTask: + allOf: + - $ref: '#/components/schemas/PollActivityTaskQueueResponse' + description: |- + When `request_eager_execution` is set on the `StartActivityExecutionRequest`, the server will return the first + activity task to be eagerly executed. + The caller is expected to have a worker available to process the task. + link: + allOf: + - $ref: '#/components/schemas/Link' + description: Link to the workflow event. StartBatchOperationRequest: type: object properties: @@ -12499,6 +13564,24 @@ components: description: Last time versioning information of this Task Queue changed. format: date-time description: Experimental. Worker Deployments are experimental and might significantly change in the future. + TerminateActivityExecutionRequest: + type: object + properties: + namespace: + type: string + execution: + allOf: + - $ref: '#/components/schemas/ActivityExecution' + description: Activity execution, targets the latest run if run_id is empty. + reason: + type: string + description: Reason for requesting the termination, recorded in in the activity's result failure outcome. + identity: + type: string + description: The identity of the worker/client. + TerminateActivityExecutionResponse: + type: object + properties: {} TerminateWorkflowExecutionRequest: type: object properties: diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index e70e814b4..108b665b5 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -9,10 +9,36 @@ option java_outer_classname = "MessageProto"; option ruby_package = "Temporalio::Api::Activity::V1"; option csharp_namespace = "Temporalio.Api.Activity.V1"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + import "temporal/api/common/v1/message.proto"; +import "temporal/api/deployment/v1/message.proto"; +import "temporal/api/enums/v1/activity.proto"; +import "temporal/api/enums/v1/workflow.proto"; +import "temporal/api/failure/v1/message.proto"; import "temporal/api/taskqueue/v1/message.proto"; +import "temporal/api/sdk/v1/user_metadata.proto"; -import "google/protobuf/duration.proto"; +// Identifies a specific activity within a namespace. Practically speaking, because run_id is a +// uuid, a workflow execution is globally unique. Note that many commands allow specifying an empty +// run id as a way of saying "target the latest run of the activity". +// TODO: Make this a generic EntityExecution? +message ActivityExecution { + string activity_id = 1; + string run_id = 2; +} + +// When StartActivityExecution uses the ID_CONFLICT_POLICY_USE_EXISTING and there is already an existing running +// activity, OnConflictOptions defines actions to be taken on the existing running activity, updating its state. +message OnConflictOptions { + // Attaches the request ID to the running workflow. + bool attach_request_id = 1; + // Attaches the completion callbacks to the running workflow. + bool attach_completion_callbacks = 2; + // Attaches the links to the WorkflowExecutionOptionsUpdatedEvent history event. + bool attach_links = 3; +} message ActivityOptions { temporal.api.taskqueue.v1.TaskQueue task_queue = 1; @@ -40,6 +66,135 @@ message ActivityOptions { google.protobuf.Duration start_to_close_timeout = 4; // Maximum permitted time between successful worker heartbeats. google.protobuf.Duration heartbeat_timeout = 5; - + // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. temporal.api.common.v1.RetryPolicy retry_policy = 6; -} \ No newline at end of file +} + +// Info for a standalone activity. +message ActivityExecutionInfo { + // Unique identifier of this activity within its namespace. + ActivityExecution activity_execution = 1; + + // The type of the activity, a string that maps to a registered activity on a worker. + temporal.api.common.v1.ActivityType activity_type = 2; + // A general status for this activity, indicates whether it is currently running or in one of the terminal statuses. + temporal.api.enums.v1.ActivityExecutionStatus status = 3; + // More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. + temporal.api.enums.v1.PendingActivityState run_state = 4; + // Details provided in the last recorded activity heartbeat. + temporal.api.common.v1.Payloads heartbeat_details = 5; + // Time the last heartbeat was recorded. + google.protobuf.Timestamp last_heartbeat_time = 6; + // Time the last attempt was started. + google.protobuf.Timestamp last_started_time = 7; + // The attempt this activity is currently on. + // Incremented each time a new attempt is started. + // TODO: Confirm if this is on scheduled or started. + int32 attempt = 8; + int32 maximum_attempts = 9; + // Time the activity was originally scheduled via a StartActivityExecution request. + google.protobuf.Timestamp scheduled_time = 10; + // Scheduled time + schedule to close timeout. + google.protobuf.Timestamp expiration_time = 11; + // Failure details from the last failed attempt. + temporal.api.failure.v1.Failure last_failure = 12; + string last_worker_identity = 13; + + // Time from the last attempt failure to the next activity retry. + // If the activity is currently running, this represents the next retry interval in case the attempt fails. + // If activity is currently backing off between attempt, this represents the current retry interval. + // If there is no next retry allowed, this field will be null. + // This interval is typically calculated from the specified retry policy, but may be modified if an activity fails + // with a retryable application failure specifying a retry delay. + google.protobuf.Duration current_retry_interval = 14; + + // The time when the last activity attempt completed. If activity has not been completed yet, it will be null. + google.protobuf.Timestamp last_attempt_complete_time = 15; + + // The time when the next activity attempt will be scheduled. + // If activity is currently scheduled or started, this field will be null. + google.protobuf.Timestamp next_attempt_schedule_time = 16; + + // The Worker Deployment Version this activity was dispatched to most recently. + // If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. + temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 17; + + // Priority metadata. + temporal.api.common.v1.Priority priority = 18; + + // TODO: Move this to a common package? + message PauseInfo { + // The time when the activity was paused. + google.protobuf.Timestamp pause_time = 1; + + message Manual { + // The identity of the actor that paused the activity. + string identity = 1; + // Reason for pausing the activity. + string reason = 2; + } + + oneof paused_by { + // The activity was paused by direct API invocation. + Manual manual = 2; + } + } + + PauseInfo pause_info = 19; + + // Current activity options. May be different from the one used to start the activity. + temporal.api.activity.v1.ActivityOptions activity_options = 20; + + // Serialized activity input, passed as arguments to the activity function. + temporal.api.common.v1.Payloads input = 21; + + // Incremented each time the activity's state is mutated in persistence. + int64 state_transition_count = 22; + + temporal.api.common.v1.SearchAttributes search_attributes = 23; + temporal.api.common.v1.Header header = 24; + // Whether the activity was started with a request_eager_execution flag set to `true`, indicating that the first + // task was delivered inline in the start response, bypassing matching. + bool eager_execution_requested = 25; + + // Callbacks to be called by the server when this activity reaches a terminal status. + // Callback addresses must be whitelisted in the server's dynamic configuration. + repeated temporal.api.common.v1.Callback completion_callbacks = 26; + // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity. + temporal.api.sdk.v1.UserMetadata user_metadata = 27; + // Links to be associated with the activity. + repeated temporal.api.common.v1.Link links = 28; + + // Set if activity cancelation was requested. + string canceled_reason = 31; +} + +// Limited activity information returned in the list response. +message ActivityListInfo { + // Unique identifier of this activity within its namespace. + ActivityExecution activity_execution = 1; + // The type of the activity, a string that maps to a registered activity on a worker. + temporal.api.common.v1.ActivityType activity_type = 2; + // Time the activity was originally scheduled via a StartActivityExecution request. + // TODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for + // consistency? + google.protobuf.Timestamp scheduled_time = 3; + // If the activity is in a terminal status, this field represents the time the activity transitioned to that status. + google.protobuf.Timestamp close_time = 4; + // Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not + // available in the list response. + temporal.api.enums.v1.ActivityExecutionStatus status = 5; + + // Search attributes from the start request. + temporal.api.common.v1.SearchAttributes search_attributes = 6; + + // The task queue this activity was scheduled on when it was originally started, updated on activity options update. + string task_queue = 7; + // Updated on terminal status. + int64 state_transition_count = 8; + // Updated once on scheduled and once on terminal status. + int64 state_size_bytes = 9; + // The difference between close time and scheduled time. + // This field is only populated if the activity is closed. + google.protobuf.Duration execution_duration = 10; +} diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 838f5fefc..a07693e9a 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -232,9 +232,17 @@ message Link { string job_id = 1; } + // A link to an activity. + message Activity { + string namespace = 1; + string activity_id = 2; + string run_id = 3; + } + oneof variant { WorkflowEvent workflow_event = 1; BatchJob batch_job = 2; + Activity activity = 3; } } diff --git a/temporal/api/enums/v1/activity.proto b/temporal/api/enums/v1/activity.proto new file mode 100644 index 000000000..5061f3162 --- /dev/null +++ b/temporal/api/enums/v1/activity.proto @@ -0,0 +1,40 @@ +syntax = "proto3"; + +package temporal.api.enums.v1; + +option go_package = "go.temporal.io/api/enums/v1;enums"; +option java_package = "io.temporal.api.enums.v1"; +option java_multiple_files = true; +option java_outer_classname = "ActivityProto"; +option ruby_package = "Temporalio::Api::Enums::V1"; +option csharp_namespace = "Temporalio.Api.Enums.V1"; + +// Status of a standalone activity. +// The status is updated once, when the activity is originally scheduled, and again when the activity reaches a terminal +// status. +// TODO: Should this be a common execution status? Seems like the other archetypes will share this status. +// (-- api-linter: core::0216::synonyms=disabled +// aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) +enum ActivityExecutionStatus { + ACTIVITY_EXECUTION_STATUS_UNSPECIFIED = 0; + // The activity is not in a terminal status. This does not necessarily mean that there is a currently running + // attempt. The activity may be backing off between attempts or waiting for a worker to pick it up. + ACTIVITY_EXECUTION_STATUS_RUNNING = 1; + // The activity completed successfully. + ACTIVITY_EXECUTION_STATUS_COMPLETED = 2; + // The activity completed with failure. + ACTIVITY_EXECUTION_STATUS_FAILED = 3; + // The activity completed as canceled. + // Requesting to cancel an activity does not automatically transition the activity to canceled status. If the + // activity has a currently running attempt, the activity will only transition to canceled status if the current + // attempt is unsuccessful. + // TODO: Clarify what happens if there are no more allowed retries after the current attempt. + ACTIVITY_EXECUTION_STATUS_CANCELED = 4; + // The activity was terminated. Termination does not reach the worker and the activity code cannot react to it. + // A terminated activity may have a running attempt and will be requested to be canceled by the server when it + // heartbeats. + ACTIVITY_EXECUTION_STATUS_TERMINATED = 5; + // The activity has timed out by reaching the specified shedule-to-start or schedule-to-close timeouts. + // TODO: Clarify if there are other conditions where the activity can end up in timed out status. + ACTIVITY_EXECUTION_STATUS_TIMED_OUT = 6; +} diff --git a/temporal/api/enums/v1/id.proto b/temporal/api/enums/v1/id.proto new file mode 100644 index 000000000..cc25502ea --- /dev/null +++ b/temporal/api/enums/v1/id.proto @@ -0,0 +1,40 @@ +syntax = "proto3"; + +package temporal.api.enums.v1; + +option go_package = "go.temporal.io/api/enums/v1;enums"; +option java_package = "io.temporal.api.enums.v1"; +option java_multiple_files = true; +option java_outer_classname = "IdProto"; +option ruby_package = "Temporalio::Api::Enums::V1"; +option csharp_namespace = "Temporalio.Api.Enums.V1"; + +// Defines whether to allow re-using an ID from a previously *closed* execution. +// If the request is denied, the server returns an `ExecutionAlreadyStarted` error. +// +// See `IdConflictPolicy` for handling ID duplication with a *running* execution. +enum IdReusePolicy { + ID_REUSE_POLICY_UNSPECIFIED = 0; + // Always allow starting an execution using the same entity ID. + ID_REUSE_POLICY_ALLOW_DUPLICATE = 1; + // Allow starting an execution using the same ID, only when the last execution's final state is one of [terminated, + // cancelled, timed out, failed]. + ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2; + // Do not permit re-use of the ID for this execution. Future start requests could potentially change the policy, + // allowing re-use of the ID. + ID_REUSE_POLICY_REJECT_DUPLICATE = 3; +} + +// Defines what to do when trying to start an execution with the same ID as a *running* execution. +// Note that it is *never* valid to have two actively running instances of the same execution ID. +// +// See `IdReusePolicy` for handling execution ID duplication with a *closed* execution. +enum IdConflictPolicy { + ID_CONFLICT_POLICY_UNSPECIFIED = 0; + // Don't start a new execution; instead return `ExecutionAlreadyStarted` error. + ID_CONFLICT_POLICY_FAIL = 1; + // Don't start a new execution; instead return a handle for the running execution. + ID_CONFLICT_POLICY_USE_EXISTING = 2; + // Terminate the running execution before starting a new one. + ID_CONFLICT_POLICY_TERMINATE_EXISTING = 3; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 4636c20a0..fabd8f42d 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -19,6 +19,7 @@ import "temporal/api/enums/v1/reset.proto"; import "temporal/api/enums/v1/task_queue.proto"; import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/update.proto"; +import "temporal/api/enums/v1/id.proto"; import "temporal/api/activity/v1/message.proto"; import "temporal/api/common/v1/message.proto"; import "temporal/api/history/v1/message.proto"; @@ -525,7 +526,7 @@ message RecordActivityTaskHeartbeatResponse { message RecordActivityTaskHeartbeatByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; // Run Id of the workflow which scheduled this activity string run_id = 3; @@ -577,7 +578,7 @@ message RespondActivityTaskCompletedResponse { message RespondActivityTaskCompletedByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; // Run Id of the workflow which scheduled this activity string run_id = 3; @@ -624,7 +625,7 @@ message RespondActivityTaskFailedResponse { message RespondActivityTaskFailedByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; // Run Id of the workflow which scheduled this activity string run_id = 3; @@ -671,7 +672,7 @@ message RespondActivityTaskCanceledResponse { message RespondActivityTaskCanceledByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; // Run Id of the workflow which scheduled this activity string run_id = 3; @@ -2591,4 +2592,173 @@ message DescribeWorkerRequest { message DescribeWorkerResponse { temporal.api.worker.v1.WorkerInfo worker_info = 1; -} \ No newline at end of file +} + +message StartActivityExecutionRequest { + string namespace = 1; + // The identity of the client who initiated this request + string identity = 2; + // A unique identifier for this start request. Typically UUIDv4. + string request_id = 3; + + string activity_id = 4; + temporal.api.common.v1.ActivityType activity_type = 5; + temporal.api.activity.v1.ActivityOptions options = 6; + // Serialized arguments to the activity. These are passed as arguments to the activity function. + temporal.api.common.v1.Payloads input = 7; + + // Defines whether to allow re-using the activity id from a previously *closed* activity. + // The default policy is ID_REUSE_POLICY_ALLOW_DUPLICATE. + temporal.api.enums.v1.IdReusePolicy id_reuse_policy = 8; + // Defines how to resolve an activity id conflict with a *running* activity. + // The default policy is ID_CONFLICT_POLICY_FAIL. + temporal.api.enums.v1.IdConflictPolicy id_conflict_policy = 9; + + // Arbitrary structured data that can be attached to the activity execution and made available via the list and + // describe APIs. + temporal.api.common.v1.Memo memo = 10; + // Search attributes for indexing. + temporal.api.common.v1.SearchAttributes search_attributes = 11; + // Header for context propagation and tracing purposes. + temporal.api.common.v1.Header header = 12; + // Request to get the first activity task inline in the response bypassing matching service and worker polling. + // If set to `true` the caller is expected to have a worker available and capable of processing the task. + // The returned task will be marked as started and is expected to be completed by the specified + // `schedule_to_close_timeout`. + bool request_eager_execution = 13; + // Callbacks to be called by the server when this activity reaches a terminal status. + // Callback addresses must be whitelisted in the server's dynamic configuration. + repeated temporal.api.common.v1.Callback completion_callbacks = 14; + // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity. + temporal.api.sdk.v1.UserMetadata user_metadata = 15; + // Links to be associated with the activity. + repeated temporal.api.common.v1.Link links = 16; + // Defines actions to be done to the existing running activity when ID_CONFLICT_POLICY_USE_EXISTING is used. If not + // set or empty, it won't do anything to the existing running activity. + temporal.api.activity.v1.OnConflictOptions on_conflict_options = 17; + // Priority metadata + temporal.api.common.v1.Priority priority = 18; +} + +message StartActivityExecutionResponse { + // The run ID of the activity that was started - or used (via ID_CONFLICT_POLICY_USE_EXISTING). + string run_id = 1; + // If true, a new activity was started. + bool started = 2; + // When `request_eager_execution` is set on the `StartActivityExecutionRequest`, the server will return the first + // activity task to be eagerly executed. + // The caller is expected to have a worker available to process the task. + PollActivityTaskQueueResponse eager_task = 3; + // Link to the workflow event. + temporal.api.common.v1.Link link = 4; +} + +message DescribeActivityExecutionRequest { + string namespace = 1; + // Activity execution, targets the latest run if run_id is empty. + temporal.api.activity.v1.ActivityExecution execution = 2; +} + +message DescribeActivityExecutionResponse { + temporal.api.activity.v1.ActivityExecutionInfo info = 1; +} + +message ListActivityExecutionsRequest { + string namespace = 1; + // Max number of executions to return per page. + int32 page_size = 2; + // Token returned in ListActivityExecutionsResponse. + bytes next_page_token = 3; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + string query = 4; +} + +message ListActivityExecutionsResponse { + repeated temporal.api.activity.v1.ActivityListInfo executions = 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. + string query = 2; +} + +message CountActivityExecutionsResponse { + // If `query` is not grouping by any field, the count is an approximate number + // of activities 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 activities 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 GetActivityResultRequest { + string namespace = 1; + // Activity execution, targets the latest run if run_id is empty. + temporal.api.activity.v1.ActivityExecution execution = 2; + // If set, turns this request into a long poll that is unblocked when the activity reaches a terminal status. + // The wait duration is capped by the request's context deadline or by the maximum enforced long poll interval + // allowed by the server. + bool wait = 3; +} + +message GetActivityResultResponse { + // The run ID of the completed activity, may be used in case a run ID was not specified in the request. + string run_id = 1; + + oneof outcome { + // The result if the activity completed successfully. + temporal.api.common.v1.Payloads result = 2; + // The failure if the activity completed unsuccessfully. + temporal.api.failure.v1.Failure failure = 3; + } +} + +message RequestCancelActivityExecutionRequest { + string namespace = 1; + // Activity execution, targets the latest run if run_id is empty. + temporal.api.activity.v1.ActivityExecution execution = 2; + // The identity of the worker/client. + string identity = 3; + // Used to de-dupe cancellation requests. + string request_id = 4; + // Reason for requesting the cancellation, recorded and available via the DescribeActivityExecution API. + // Not propagated to a worker if an activity attempt is currently running. + string reason = 5; +} + +message RequestCancelActivityExecutionResponse { +} + +message TerminateActivityExecutionRequest { + string namespace = 1; + // Activity execution, targets the latest run if run_id is empty. + temporal.api.activity.v1.ActivityExecution execution = 2; + // Reason for requesting the termination, recorded in in the activity's result failure outcome. + string reason = 3; + // The identity of the worker/client. + string identity = 4; +} + +message TerminateActivityExecutionResponse { +} + +message DeleteActivityExecutionRequest { + string namespace = 1; + // Activity execution, targets the latest run if run_id is empty. + temporal.api.activity.v1.ActivityExecution execution = 2; +} + +message DeleteActivityExecutionResponse { +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 8b45c9a1b..8456ce107 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1259,4 +1259,104 @@ service WorkflowService { } }; } + + // StartActivityExecution starts a new activity execution. + // + // Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace + // unless permitted by the specified ID conflict policy. + rpc StartActivityExecution (StartActivityExecutionRequest) returns (StartActivityExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activities/{activity_id}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activities/{activity_id}" + body: "*" + } + }; + } + + // DescribeActivityExecution returns information about the specified activity execution. + rpc DescribeActivityExecution (DescribeActivityExecutionRequest) returns (DescribeActivityExecutionResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activities/{execution.activity_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activities/{execution.activity_id}" + } + }; + } + + // ListActivityExecutions is a visibility API to list activity executions in a specific namespace. + rpc ListActivityExecutions (ListActivityExecutionsRequest) returns (ListActivityExecutionsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activities" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activities" + } + }; + } + + // CountActivityExecutions is a visibility API to count of activity executions in a specific namespace. + rpc CountActivityExecutions (CountActivityExecutionsRequest) returns (CountActivityExecutionsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activity-count" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activity-count" + } + }; + } + + // GetActivityResult returns the activity result if it is in a terminal status or (optionally) wait for it to reach + // one. + rpc GetActivityResult (GetActivityResultRequest) returns (GetActivityResultResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activities/{execution.activity_id}/result" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activities/{execution.activity_id}/result" + } + }; + } + + // RequestCancelActivityExecution requests cancellation of an activity execution. + // + // Requesting to cancel an activity does not automatically transition the activity to canceled status. If the + // activity has a currently running attempt, the activity will only transition to canceled status if the current + // attempt is unsuccessful. + // TODO: Clarify what happens if there are no more allowed retries after the current attempt. + // + // It returns success if the requested activity is already closed. + // TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior? + rpc RequestCancelActivityExecution (RequestCancelActivityExecutionRequest) returns (RequestCancelActivityExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activities/{execution.activity_id}/cancel" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activities/{execution.activity_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 + // running attempt and will be requested to be canceled by the server when it heartbeats. + rpc TerminateActivityExecution (TerminateActivityExecutionRequest) returns (TerminateActivityExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activities/{execution.activity_id}/terminate" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activities/{execution.activity_id}/terminate" + body: "*" + } + }; + } + + // DeleteActivityExecution asynchronously deletes a specific activity execution (when + // ActivityExecution.run_id is provided) or the latest activity execution (when + // ActivityExecution.run_id is not provided). If the activity EXecution is running, it will be + // terminated before deletion. + // + // (-- 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) {} }