diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 997b568b6..086c18179 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,6 +15,7 @@ jobs: - uses: arduino/setup-protoc@v2 - name: 'Setup jq' uses: dcarbone/install-jq-action@v2 + - uses: astral-sh/setup-uv@v7 - run: make ci-build - name: Fail if the repo is dirty run: | diff --git a/.gitignore b/.gitignore index 8655883e5..6ecb261fb 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ /.gen /.vscode /.stamp -*~ \ No newline at end of file +*~ +__pycache__/ \ No newline at end of file diff --git a/Makefile b/Makefile index b4b33bdb5..dad5beb3b 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ SHELL=bash -o pipefail $(VERBOSE).SILENT: ############################# Main targets ############################# -ci-build: install proto http-api-docs +ci-build: install proto http-api-docs test # Install dependencies. install: grpc-install api-linter-install buf-install @@ -73,6 +73,10 @@ http-api-docs: yq e -i '(.paths[] | .[] | .operationId) |= sub("\w+_(.*)", "$$1")' $(OAPI_OUT)/openapi.yaml mv -f $(OAPI_OUT)/openapi.yaml $(OAPI_OUT)/openapiv3.yaml +test: + ./test-http-api-ambiguity + + ##### Plugins & tools ##### grpc-install: @printf $(COLOR) "Install/update protoc and plugins..." @@ -113,7 +117,7 @@ buf-lint: $(STAMPDIR)/buf-mod-prune (cd $(PROTO_ROOT) && buf lint) buf-breaking: - @printf $(COLOR) "Run buf breaking changes check against master branch..." + @printf $(COLOR) "Run buf breaking changes check against master branch..." @(cd $(PROTO_ROOT) && buf breaking --against 'https://github.com/temporalio/api.git#branch=master') ##### Clean ##### diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 85e0f95b4..c41a2ba28 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -291,16 +291,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/complete": { + "/api/v1/namespaces/{namespace}/activities/cancel/{activityId}": { "post": { - "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", - "description": "For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCompleted2", + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Cancellation is cooperative: this call records the request, but the activity must detect and\nacknowledge it for the activity to reach CANCELED status. The cancellation signal is\ndelivered via `cancel_requested` in the heartbeat response; SDKs surface this via\nlanguage-idiomatic mechanisms (context cancellation, exceptions, abort signals).", + "operationId": "RequestCancelActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -317,12 +317,18 @@ "required": true, "type": "string" }, + { + "name": "activityId", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -331,15 +337,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/complete-by-id": { + "/api/v1/namespaces/{namespace}/activities/complete": { "post": { - "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById2", + "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", + "description": "For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCompleted2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" } }, "default": { @@ -352,7 +359,6 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -362,7 +368,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" } } ], @@ -371,16 +377,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/fail": { + "/api/v1/namespaces/{namespace}/activities/complete-by-id": { "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": "RespondActivityTaskFailed2", + "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCompletedById2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" } }, "default": { @@ -393,6 +398,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -402,7 +408,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" } } ], @@ -411,15 +417,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/fail-by-id": { - "post": { - "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskFailedById2", + "/api/v1/namespaces/{namespace}/activities/describe/{activityId}": { + "get": { + "summary": "DescribeActivityExecution returns information about an activity execution.\nIt can be used to:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", + "operationId": "DescribeActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -432,18 +438,44 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" - } + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the activity has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ @@ -451,16 +483,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/heartbeat": { + "/api/v1/namespaces/{namespace}/activities/fail": { "post": { - "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", - "description": "If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen the current attempt times out. Depending on RetryPolicy, this may trigger a retry or\ntime out the activity.\n\nFor workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow\nhistory. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,\nin that event, the SDK should request cancellation of the activity.\n\nThe request may contain response `details` which will be persisted by the server and may be\nused by the activity to checkpoint progress. The `cancel_requested` field in the response\nindicates whether cancellation has been requested for the activity.", - "operationId": "RecordActivityTaskHeartbeat2", + "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": "RespondActivityTaskFailed2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" } }, "default": { @@ -482,7 +514,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" } } ], @@ -491,15 +523,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/heartbeat-by-id": { + "/api/v1/namespaces/{namespace}/activities/fail-by-id": { "post": { - "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RecordActivityTaskHeartbeatById2", + "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskFailedById2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" } }, "default": { @@ -522,7 +554,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" } } ], @@ -531,16 +563,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/pause": { + "/api/v1/namespaces/{namespace}/activities/heartbeat": { "post": { - "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", - "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "PauseActivity2", + "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", + "description": "If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen the current attempt times out. Depending on RetryPolicy, this may trigger a retry or\ntime out the activity.\n\nFor workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow\nhistory. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,\nin that event, the SDK should request cancellation of the activity.\n\nThe request may contain response `details` which will be persisted by the server and may be\nused by the activity to checkpoint progress. The `cancel_requested` field in the response\nindicates whether cancellation has been requested for the activity.", + "operationId": "RecordActivityTaskHeartbeat2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PauseActivityResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" } }, "default": { @@ -553,7 +585,6 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -563,7 +594,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], @@ -572,16 +603,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/reset": { + "/api/v1/namespaces/{namespace}/activities/heartbeat-by-id": { "post": { - "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", - "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "ResetActivity2", + "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RecordActivityTaskHeartbeatById2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ResetActivityResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" } }, "default": { @@ -594,7 +624,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" @@ -604,7 +634,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" } } ], @@ -613,16 +643,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/unpause": { - "post": { - "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "UnpauseActivity2", + "/api/v1/namespaces/{namespace}/activities/outcome/{activityId}": { + "get": { + "summary": "PollActivityExecution long-polls for an activity execution to complete and returns the\noutcome (result or failure).", + "operationId": "PollActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UnpauseActivityResponse" + "$ref": "#/definitions/v1PollActivityExecutionResponse" } }, "default": { @@ -635,18 +664,22 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" - } + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -654,15 +687,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/update-options": { + "/api/v1/namespaces/{namespace}/activities/pause": { "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", - "operationId": "UpdateActivityOptions2", + "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "PauseActivity2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsResponse" + "$ref": "#/definitions/v1PauseActivityResponse" } }, "default": { @@ -675,7 +709,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" @@ -685,7 +719,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" + "$ref": "#/definitions/WorkflowServicePauseActivityBody" } } ], @@ -694,15 +728,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/{activityId}": { - "get": { - "summary": "DescribeActivityExecution returns information about an activity execution.\nIt can be used to:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", - "operationId": "DescribeActivityExecution2", + "/api/v1/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.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "ResetActivity2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeActivityExecutionResponse" + "$ref": "#/definitions/v1ResetActivityResponse" } }, "default": { @@ -715,50 +750,26 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "runId", - "description": "Activity run ID. If empty the request targets the latest run.", - "in": "query", - "required": false, - "type": "string" - }, - { - "name": "includeInput", - "description": "Include the input field in the response.", - "in": "query", - "required": false, - "type": "boolean" - }, - { - "name": "includeOutcome", - "description": "Include the outcome (result/failure) in the response if the activity has completed.", - "in": "query", - "required": false, - "type": "boolean" - }, - { - "name": "longPollToken", - "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "schema": { + "$ref": "#/definitions/WorkflowServiceResetActivityBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/api/v1/namespaces/{namespace}/activities/start/{activityId}": { "post": { "summary": "StartActivityExecution starts a new activity execution.", "description": "Returns an `ActivityExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", @@ -805,16 +816,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/{activityId}/cancel": { + "/api/v1/namespaces/{namespace}/activities/terminate/{activityId}": { "post": { - "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", - "description": "Cancellation is cooperative: this call records the request, but the activity must detect and\nacknowledge it for the activity to reach CANCELED status. The cancellation signal is\ndelivered via `cancel_requested` in the heartbeat response; SDKs surface this via\nlanguage-idiomatic mechanisms (context cancellation, exceptions, abort signals).", - "operationId": "RequestCancelActivityExecution2", + "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", + "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt.", + "operationId": "TerminateActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -842,7 +853,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -851,15 +862,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/{activityId}/outcome": { - "get": { - "summary": "PollActivityExecution long-polls for an activity execution to complete and returns the\noutcome (result or failure).", - "operationId": "PollActivityExecution2", + "/api/v1/namespaces/{namespace}/activities/unpause": { + "post": { + "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "UnpauseActivity2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PollActivityExecutionResponse" + "$ref": "#/definitions/v1UnpauseActivityResponse" } }, "default": { @@ -872,22 +884,18 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "runId", - "description": "Activity run ID. If empty the request targets the latest run.", - "in": "query", - "required": false, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + } } ], "tags": [ @@ -895,16 +903,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/activities/{activityId}/terminate": { + "/api/v1/namespaces/{namespace}/activities/update-options": { "post": { - "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", - "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt.", - "operationId": "TerminateActivityExecution2", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", + "operationId": "UpdateActivityOptions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1TerminateActivityExecutionResponse" + "$ref": "#/definitions/v1UpdateActivityOptionsResponse" } }, "default": { @@ -917,12 +924,7 @@ "parameters": [ { "name": "namespace", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "activityId", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -932,7 +934,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" } } ], @@ -4657,16 +4659,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete": { + "/namespaces/{namespace}/activities/cancel/{activityId}": { "post": { - "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", - "description": "For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCompleted", + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Cancellation is cooperative: this call records the request, but the activity must detect and\nacknowledge it for the activity to reach CANCELED status. The cancellation signal is\ndelivered via `cancel_requested` in the heartbeat response; SDKs surface this via\nlanguage-idiomatic mechanisms (context cancellation, exceptions, abort signals).", + "operationId": "RequestCancelActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -4683,12 +4685,18 @@ "required": true, "type": "string" }, + { + "name": "activityId", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -4697,15 +4705,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete-by-id": { + "/namespaces/{namespace}/activities/complete": { "post": { - "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById", + "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", + "description": "For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCompleted", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" } }, "default": { @@ -4718,7 +4727,6 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -4728,7 +4736,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" } } ], @@ -4737,16 +4745,15 @@ ] } }, - "/namespaces/{namespace}/activities/fail": { + "/namespaces/{namespace}/activities/complete-by-id": { "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": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCompletedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" } }, "default": { @@ -4759,6 +4766,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -4768,7 +4776,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" } } ], @@ -4777,15 +4785,15 @@ ] } }, - "/namespaces/{namespace}/activities/fail-by-id": { - "post": { - "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskFailedById", + "/namespaces/{namespace}/activities/describe/{activityId}": { + "get": { + "summary": "DescribeActivityExecution returns information about an activity execution.\nIt can be used to:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", + "operationId": "DescribeActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -4798,18 +4806,44 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" - } + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the activity has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ @@ -4817,16 +4851,16 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat": { + "/namespaces/{namespace}/activities/fail": { "post": { - "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", - "description": "If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen the current attempt times out. Depending on RetryPolicy, this may trigger a retry or\ntime out the activity.\n\nFor workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow\nhistory. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,\nin that event, the SDK should request cancellation of the activity.\n\nThe request may contain response `details` which will be persisted by the server and may be\nused by the activity to checkpoint progress. The `cancel_requested` field in the response\nindicates whether cancellation has been requested for the activity.", - "operationId": "RecordActivityTaskHeartbeat", + "summary": "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/v1RecordActivityTaskHeartbeatResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" } }, "default": { @@ -4848,7 +4882,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" } } ], @@ -4857,15 +4891,15 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat-by-id": { + "/namespaces/{namespace}/activities/fail-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", + "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/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" } }, "default": { @@ -4888,7 +4922,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" } } ], @@ -4897,16 +4931,16 @@ ] } }, - "/namespaces/{namespace}/activities/pause": { + "/namespaces/{namespace}/activities/heartbeat": { "post": { - "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", - "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "PauseActivity", + "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", + "description": "If a worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen the current attempt times out. Depending on RetryPolicy, this may trigger a retry or\ntime out the activity.\n\nFor workflow activities, an `ACTIVITY_TASK_TIMED_OUT` event will be written to the workflow\nhistory. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in such situations,\nin that event, the SDK should request cancellation of the activity.\n\nThe request may contain response `details` which will be persisted by the server and may be\nused by the activity to checkpoint progress. The `cancel_requested` field in the response\nindicates whether cancellation has been requested for the activity.", + "operationId": "RecordActivityTaskHeartbeat", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PauseActivityResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" } }, "default": { @@ -4919,7 +4953,6 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4929,7 +4962,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], @@ -4938,16 +4971,15 @@ ] } }, - "/namespaces/{namespace}/activities/reset": { + "/namespaces/{namespace}/activities/heartbeat-by-id": { "post": { - "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", - "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "ResetActivity", + "summary": "See `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/v1ResetActivityResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" } }, "default": { @@ -4960,7 +4992,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" @@ -4970,7 +5002,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" } } ], @@ -4979,16 +5011,15 @@ ] } }, - "/namespaces/{namespace}/activities/unpause": { - "post": { - "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", - "operationId": "UnpauseActivity", + "/namespaces/{namespace}/activities/outcome/{activityId}": { + "get": { + "summary": "PollActivityExecution long-polls for an activity execution to complete and returns the\noutcome (result or failure).", + "operationId": "PollActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UnpauseActivityResponse" + "$ref": "#/definitions/v1PollActivityExecutionResponse" } }, "default": { @@ -5001,18 +5032,22 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" - } + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5020,15 +5055,16 @@ ] } }, - "/namespaces/{namespace}/activities/update-options": { + "/namespaces/{namespace}/activities/pause": { "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", - "operationId": "UpdateActivityOptions", + "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "PauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsResponse" + "$ref": "#/definitions/v1PauseActivityResponse" } }, "default": { @@ -5041,7 +5077,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" @@ -5051,7 +5087,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" + "$ref": "#/definitions/WorkflowServicePauseActivityBody" } } ], @@ -5060,15 +5096,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}": { - "get": { - "summary": "DescribeActivityExecution returns information about an activity execution.\nIt can be used to:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", - "operationId": "DescribeActivityExecution", + "/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.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "ResetActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeActivityExecutionResponse" + "$ref": "#/definitions/v1ResetActivityResponse" } }, "default": { @@ -5081,50 +5118,26 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "runId", - "description": "Activity run ID. If empty the request targets the latest run.", - "in": "query", - "required": false, - "type": "string" - }, - { - "name": "includeInput", - "description": "Include the input field in the response.", - "in": "query", - "required": false, - "type": "boolean" - }, - { - "name": "includeOutcome", - "description": "Include the outcome (result/failure) in the response if the activity has completed.", - "in": "query", - "required": false, - "type": "boolean" - }, - { - "name": "longPollToken", - "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", - "in": "query", - "required": false, - "type": "string", - "format": "byte" + "schema": { + "$ref": "#/definitions/WorkflowServiceResetActivityBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/namespaces/{namespace}/activities/start/{activityId}": { "post": { "summary": "StartActivityExecution starts a new activity execution.", "description": "Returns an `ActivityExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", @@ -5171,16 +5184,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/cancel": { + "/namespaces/{namespace}/activities/terminate/{activityId}": { "post": { - "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", - "description": "Cancellation is cooperative: this call records the request, but the activity must detect and\nacknowledge it for the activity to reach CANCELED status. The cancellation signal is\ndelivered via `cancel_requested` in the heartbeat response; SDKs surface this via\nlanguage-idiomatic mechanisms (context cancellation, exceptions, abort signals).", - "operationId": "RequestCancelActivityExecution", + "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", + "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt.", + "operationId": "TerminateActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -5208,7 +5221,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -5217,15 +5230,16 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/outcome": { - "get": { - "summary": "PollActivityExecution long-polls for an activity execution to complete and returns the\noutcome (result or failure).", - "operationId": "PollActivityExecution", + "/namespaces/{namespace}/activities/unpause": { + "post": { + "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "UnpauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PollActivityExecutionResponse" + "$ref": "#/definitions/v1UnpauseActivityResponse" } }, "default": { @@ -5238,22 +5252,18 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "activityId", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "runId", - "description": "Activity run ID. If empty the request targets the latest run.", - "in": "query", - "required": false, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + } } ], "tags": [ @@ -5261,16 +5271,15 @@ ] } }, - "/namespaces/{namespace}/activities/{activityId}/terminate": { + "/namespaces/{namespace}/activities/update-options": { "post": { - "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", - "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt.", - "operationId": "TerminateActivityExecution", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", + "operationId": "UpdateActivityOptions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1TerminateActivityExecutionResponse" + "$ref": "#/definitions/v1UpdateActivityOptionsResponse" } }, "default": { @@ -5283,12 +5292,7 @@ "parameters": [ { "name": "namespace", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "activityId", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -5298,7 +5302,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" } } ], @@ -8365,17 +8369,6 @@ } } }, - "ExecuteMultiOperationResponseResponse": { - "type": "object", - "properties": { - "startWorkflow": { - "$ref": "#/definitions/v1StartWorkflowExecutionResponse" - }, - "updateWorkflow": { - "$ref": "#/definitions/v1UpdateWorkflowExecutionResponse" - } - } - }, "LinkBatchJob": { "type": "object", "properties": { @@ -8483,95 +8476,244 @@ }, "identity": { "type": "string", - "description": "The identity of the actor that created the rule." + "description": "The identity of the actor that created the rule." + }, + "reason": { + "type": "string", + "description": "Reason why rule was created. Populated from rule description." + } + } + }, + "PayloadExternalPayloadDetails": { + "type": "object", + "properties": { + "sizeBytes": { + "type": "string", + "format": "int64", + "title": "Size in bytes of the externally stored payload" + } + }, + "description": "Describes an externally stored object referenced by this payload." + }, + "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": { + "signalName": { + "type": "string", + "description": "The workflow author-defined name of the signal to send to the workflow." + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "description": "Serialized value(s) to provide with the signal." + }, + "header": { + "$ref": "#/definitions/v1Header", + "description": "Headers that are passed with the signal to the processing workflow." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apicommonv1Link" + }, + "description": "Links to be associated with the WorkflowExecutionSignaled event." + } + }, + "description": "SignalWorkflow represents sending a signal after a workflow reset.\nKeep the parameter in sync with temporal.api.workflowservice.v1.SignalWorkflowExecutionRequest." + }, + "PostResetOperationUpdateWorkflowOptions": { + "type": "object", + "properties": { + "workflowExecutionOptions": { + "$ref": "#/definitions/v1WorkflowExecutionOptions", + "description": "Update Workflow options that were originally specified via StartWorkflowExecution. Partial updates are accepted and controlled by update_mask." + }, + "updateMask": { + "type": "string", + "description": "Controls which fields from `workflow_execution_options` will be applied.\nTo unset a field, set it to null and use the update mask to indicate that it should be mutated." + } + }, + "description": "UpdateWorkflowOptions represents updating workflow execution options after a workflow reset.\nKeep the parameters in sync with temporal.api.workflowservice.v1.UpdateWorkflowExecutionOptionsRequest." + }, + "StartOperationResponseAsync": { + "type": "object", + "properties": { + "operationId": { + "type": "string", + "description": "Deprecated. Renamed to operation_token." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apinexusv1Link" + } + }, + "operationToken": { + "type": "string" + } + }, + "description": "The operation will complete asynchronously.\nThe returned ID can be used to reference this operation." + }, + "StartOperationResponseSync": { + "type": "object", + "properties": { + "payload": { + "$ref": "#/definitions/v1Payload" + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apinexusv1Link" + } + } + }, + "description": "An operation completed successfully." + }, + "UpdateTaskQueueConfigRequestRateLimitUpdate": { + "type": "object", + "properties": { + "rateLimit": { + "$ref": "#/definitions/v1RateLimit", + "title": "Rate Limit to be updated" + }, + "reason": { + "type": "string", + "description": "Reason for why the rate limit was set." + } + } + }, + "UpdateWorkerBuildIdCompatibilityRequestAddNewCompatibleVersion": { + "type": "object", + "properties": { + "newBuildId": { + "type": "string", + "description": "A new id to be added to an existing compatible set." + }, + "existingCompatibleBuildId": { + "type": "string", + "description": "A build id which must already exist in the version sets known by the task queue. The new\nid will be stored in the set containing this id, marking it as compatible with\nthe versions within." + }, + "makeSetDefault": { + "type": "boolean", + "description": "When set, establishes the compatible set being targeted as the overall default for the\nqueue. If a different set was the current default, the targeted set will replace it as\nthe new default." + } + } + }, + "UpdateWorkerBuildIdCompatibilityRequestMergeSets": { + "type": "object", + "properties": { + "primarySetBuildId": { + "type": "string", + "title": "A build ID in the set whose default will become the merged set default" }, - "reason": { + "secondarySetBuildId": { "type": "string", - "description": "Reason why rule was created. Populated from rule description." + "title": "A build ID in the set which will be merged into the primary set" } } }, - "PayloadExternalPayloadDetails": { + "UpdateWorkerVersioningRulesRequestAddCompatibleBuildIdRedirectRule": { "type": "object", "properties": { - "sizeBytes": { - "type": "string", - "format": "int64", - "title": "Size in bytes of the externally stored payload" + "rule": { + "$ref": "#/definitions/v1CompatibleBuildIdRedirectRule" } }, - "description": "Describes an externally stored object referenced by this payload." + "description": "Adds the rule to the list of redirect rules for this Task Queue. There\ncan be at most one redirect rule for each distinct Source Build ID." }, - "PendingActivityInfoPauseInfo": { + "UpdateWorkerVersioningRulesRequestCommitBuildId": { "type": "object", "properties": { - "pauseTime": { - "type": "string", - "format": "date-time", - "description": "The time when the activity was paused." + "targetBuildId": { + "type": "string" }, - "manual": { - "$ref": "#/definitions/PauseInfoManual", - "title": "activity was paused by the manual intervention" + "force": { + "type": "boolean", + "description": "To prevent committing invalid Build IDs, we reject the request if no\npollers has been seen recently for this Build ID. Use the `force`\noption to disable this validation." + } + }, + "description": "This command is intended to be used to complete the rollout of a Build\nID and cleanup unnecessary rules possibly created during a gradual\nrollout. Specifically, this command will make the following changes\natomically:\n 1. Adds an assignment rule (with full ramp) for the target Build ID at\n the end of the list.\n 2. Removes all previously added assignment rules to the given target\n Build ID (if any).\n 3. Removes any fully-ramped assignment rule for other Build IDs." + }, + "UpdateWorkerVersioningRulesRequestDeleteBuildIdAssignmentRule": { + "type": "object", + "properties": { + "ruleIndex": { + "type": "integer", + "format": "int32" }, - "rule": { - "$ref": "#/definitions/PauseInfoRule", - "title": "activity was paused by the rule" + "force": { + "type": "boolean", + "title": "By default presence of one unconditional rule is enforced, otherwise\nthe delete operation will be rejected. Set `force` to true to\nbypass this validation. An unconditional assignment rule:\n - Has no hint filter\n - Has no ramp" } } }, - "PostResetOperationSignalWorkflow": { + "UpdateWorkerVersioningRulesRequestDeleteCompatibleBuildIdRedirectRule": { "type": "object", "properties": { - "signalName": { - "type": "string", - "description": "The workflow author-defined name of the signal to send to the workflow." - }, - "input": { - "$ref": "#/definitions/v1Payloads", - "description": "Serialized value(s) to provide with the signal." - }, - "header": { - "$ref": "#/definitions/v1Header", - "description": "Headers that are passed with the signal to the processing workflow." + "sourceBuildId": { + "type": "string" + } + } + }, + "UpdateWorkerVersioningRulesRequestInsertBuildIdAssignmentRule": { + "type": "object", + "properties": { + "ruleIndex": { + "type": "integer", + "format": "int32", + "description": "Use this option to insert the rule in a particular index. By\ndefault, the new rule is inserted at the beginning of the list\n(index 0). If the given index is too larger the rule will be\ninserted at the end of the list." }, - "links": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1Link" - }, - "description": "Links to be associated with the WorkflowExecutionSignaled event." + "rule": { + "$ref": "#/definitions/v1BuildIdAssignmentRule" } }, - "description": "SignalWorkflow represents sending a signal after a workflow reset.\nKeep the parameter in sync with temporal.api.workflowservice.v1.SignalWorkflowExecutionRequest." + "description": "Inserts the rule to the list of assignment rules for this Task Queue.\nThe rules are evaluated in order, starting from index 0. The first\napplicable rule will be applied and the rest will be ignored." }, - "PostResetOperationUpdateWorkflowOptions": { + "UpdateWorkerVersioningRulesRequestReplaceBuildIdAssignmentRule": { "type": "object", "properties": { - "workflowExecutionOptions": { - "$ref": "#/definitions/v1WorkflowExecutionOptions", - "description": "Update Workflow options that were originally specified via StartWorkflowExecution. Partial updates are accepted and controlled by update_mask." + "ruleIndex": { + "type": "integer", + "format": "int32" }, - "updateMask": { - "type": "string", - "description": "Controls which fields from `workflow_execution_options` will be applied.\nTo unset a field, set it to null and use the update mask to indicate that it should be mutated." + "rule": { + "$ref": "#/definitions/v1BuildIdAssignmentRule" + }, + "force": { + "type": "boolean", + "title": "By default presence of one unconditional rule is enforced, otherwise\nthe replace operation will be rejected. Set `force` to true to\nbypass this validation. An unconditional assignment rule:\n - Has no hint filter\n - Has no ramp" } }, - "description": "UpdateWorkflowOptions represents updating workflow execution options after a workflow reset.\nKeep the parameters in sync with temporal.api.workflowservice.v1.UpdateWorkflowExecutionOptionsRequest." + "description": "Replaces the assignment rule at a given index." }, - "UpdateTaskQueueConfigRequestRateLimitUpdate": { + "UpdateWorkerVersioningRulesRequestReplaceCompatibleBuildIdRedirectRule": { "type": "object", "properties": { - "rateLimit": { - "$ref": "#/definitions/v1RateLimit", - "title": "Rate Limit to be updated" - }, - "reason": { - "type": "string", - "description": "Reason for why the rate limit was set." + "rule": { + "$ref": "#/definitions/v1CompatibleBuildIdRedirectRule" } - } + }, + "description": "Replaces the routing rule with the given source Build ID." }, "VersioningOverridePinnedOverride": { "type": "object", @@ -9022,7 +9164,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/apiCommonV1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links to be associated with the WorkflowExecutionCanceled event." } @@ -9080,7 +9222,8 @@ "type": "string" } }, - "description": "The workflow to reset. If this contains a run ID then the workflow will be reset back to the\nprovided event ID in that run. Otherwise it will be reset to the provided event ID in the\ncurrent run. In all cases the current run will be terminated and a new run started." + "description": "The workflow to reset. If this contains a run ID then the workflow will be reset back to the\nprovided event ID in that run. Otherwise it will be reset to the provided event ID in the\ncurrent run. In all cases the current run will be terminated and a new run started.", + "title": "The workflow to reset. If this contains a run ID then the workflow will be reset back to the\nprovided event ID in that run. Otherwise it will be reset to the provided event ID in the\ncurrent run. In all cases the current run will be terminated and a new run started." }, "reason": { "type": "string" @@ -9242,7 +9385,7 @@ "title": "The task token as received in `PollActivityTaskQueueResponse`" }, "failure": { - "$ref": "#/definitions/apiFailureV1Failure", + "$ref": "#/definitions/apifailurev1Failure", "title": "Detailed failure information" }, "identity": { @@ -9283,7 +9426,7 @@ "title": "Id of the activity to fail" }, "failure": { - "$ref": "#/definitions/apiFailureV1Failure", + "$ref": "#/definitions/apifailurev1Failure", "title": "Detailed failure information" }, "identity": { @@ -9489,7 +9632,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/apiCommonV1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links to be associated with the WorkflowExecutionStarted and WorkflowExecutionSignaled events." }, @@ -9539,7 +9682,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/apiCommonV1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links to be associated with the WorkflowExecutionSignaled event." } @@ -9731,7 +9874,7 @@ "description": "Request to get the first workflow 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`workflow_task_timeout`." }, "continuedFailure": { - "$ref": "#/definitions/apiFailureV1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "These values will be available as ContinuedFailure and LastCompletionResult in the\nWorkflowExecutionStarted event and through SDKs. The are currently only used by the\nserver itself (for the schedules feature) and are not intended to be exposed in\nStartWorkflowExecution." }, "lastCompletionResult": { @@ -9757,7 +9900,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/apiCommonV1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links to be associated with the workflow." }, @@ -9844,7 +9987,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/apiCommonV1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links to be associated with the WorkflowExecutionTerminated event." } @@ -10112,78 +10255,236 @@ }, "description": "Used to update the user-defined metadata of a Worker Deployment Version." }, - "WorkflowServiceUpdateWorkflowExecutionBody": { + "WorkflowServiceUpdateWorkflowExecutionBody": { + "type": "object", + "properties": { + "workflowExecution": { + "type": "object", + "properties": { + "runId": { + "type": "string" + } + }, + "description": "The target Workflow Id and (optionally) a specific Run Id thereof.", + "title": "The target Workflow Id and (optionally) a specific Run Id thereof." + }, + "firstExecutionRunId": { + "type": "string", + "description": "If set, this call will error if the most recent (if no Run Id is set on\n`workflow_execution`), or specified (if it is) Workflow Execution is not\npart of the same execution chain as this Id." + }, + "waitPolicy": { + "$ref": "#/definitions/v1WaitPolicy", + "description": "Specifies client's intent to wait for Update results.\nNOTE: This field works together with API call timeout which is limited by\nserver timeout (maximum wait time). If server timeout is expired before\nuser specified timeout, API call returns even if specified stage is not reached.\nActual reached stage will be included in the response." + }, + "request": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/definitions/v1Meta" + }, + "input": { + "type": "object", + "properties": { + "header": { + "$ref": "#/definitions/v1Header", + "description": "Headers that are passed with the Update from the requesting entity.\nThese can include things like auth or tracing tokens." + }, + "args": { + "$ref": "#/definitions/v1Payloads", + "description": "The arguments to pass to the named Update handler." + } + } + } + }, + "description": "The request information that will be delivered all the way down to the\nWorkflow Execution.", + "title": "The request information that will be delivered all the way down to the\nWorkflow Execution." + } + } + }, + "WorkflowServiceUpdateWorkflowExecutionOptionsBody": { + "type": "object", + "properties": { + "workflowExecution": { + "type": "object", + "properties": { + "runId": { + "type": "string" + } + }, + "description": "The target Workflow Id and (optionally) a specific Run Id thereof.", + "title": "The target Workflow Id and (optionally) a specific Run Id thereof." + }, + "workflowExecutionOptions": { + "$ref": "#/definitions/v1WorkflowExecutionOptions", + "description": "Workflow Execution options. Partial updates are accepted and controlled by update_mask." + }, + "updateMask": { + "type": "string", + "description": "Controls which fields from `workflow_execution_options` will be applied.\nTo unset a field, set it to null and use the update mask to indicate that it should be mutated." + }, + "identity": { + "type": "string", + "description": "Optional. The identity of the client who initiated this request." + } + }, + "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationUpdateWorkflowExecutionOptions.\n - temporal.api.workflow.v1.PostResetOperation.UpdateWorkflowOptions." + }, + "apicommonv1Link": { + "type": "object", + "properties": { + "workflowEvent": { + "$ref": "#/definitions/LinkWorkflowEvent" + }, + "batchJob": { + "$ref": "#/definitions/LinkBatchJob" + } + }, + "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." + }, + "apifailurev1Failure": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "source": { + "type": "string", + "description": "The source this Failure originated in, e.g. TypeScriptSDK / JavaSDK\nIn some SDKs this is used to rehydrate the stack trace into an exception object." + }, + "stackTrace": { + "type": "string" + }, + "encodedAttributes": { + "$ref": "#/definitions/v1Payload", + "description": "Alternative way to supply `message` and `stack_trace` and possibly other attributes, used for encryption of\nerrors originating in user code which might contain sensitive information.\nThe `encoded_attributes` Payload could represent any serializable object, e.g. JSON object or a `Failure` proto\nmessage.\n\nSDK authors:\n- The SDK should provide a default `encodeFailureAttributes` and `decodeFailureAttributes` implementation that:\n - Uses a JSON object to represent `{ message, stack_trace }`.\n - Overwrites the original message with \"Encoded failure\" to indicate that more information could be extracted.\n - Overwrites the original stack_trace with an empty string.\n - The resulting JSON object is converted to Payload using the default PayloadConverter and should be processed\n by the user-provided PayloadCodec\n\n- If there's demand, we could allow overriding the default SDK implementation to encode other opaque Failure attributes." + }, + "cause": { + "$ref": "#/definitions/apifailurev1Failure" + }, + "applicationFailureInfo": { + "$ref": "#/definitions/v1ApplicationFailureInfo" + }, + "timeoutFailureInfo": { + "$ref": "#/definitions/v1TimeoutFailureInfo" + }, + "canceledFailureInfo": { + "$ref": "#/definitions/v1CanceledFailureInfo" + }, + "terminatedFailureInfo": { + "$ref": "#/definitions/v1TerminatedFailureInfo" + }, + "serverFailureInfo": { + "$ref": "#/definitions/v1ServerFailureInfo" + }, + "resetWorkflowFailureInfo": { + "$ref": "#/definitions/v1ResetWorkflowFailureInfo" + }, + "activityFailureInfo": { + "$ref": "#/definitions/v1ActivityFailureInfo" + }, + "childWorkflowExecutionFailureInfo": { + "$ref": "#/definitions/v1ChildWorkflowExecutionFailureInfo" + }, + "nexusOperationExecutionFailureInfo": { + "$ref": "#/definitions/v1NexusOperationFailureInfo" + }, + "nexusHandlerFailureInfo": { + "$ref": "#/definitions/v1NexusHandlerFailureInfo" + } + } + }, + "apinexusv1Failure": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "stackTrace": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "details": { + "type": "string", + "format": "byte", + "description": "UTF-8 encoded JSON serializable details." + }, + "cause": { + "$ref": "#/definitions/apinexusv1Failure" + } + }, + "title": "A general purpose failure message.\nSee: https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure" + }, + "apinexusv1Link": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "See https://github.com/nexus-rpc/api/blob/main/SPEC.md#links." + }, + "type": { + "type": "string" + } + } + }, + "apinexusv1Request": { "type": "object", "properties": { - "workflowExecution": { + "header": { "type": "object", - "properties": { - "runId": { - "type": "string" - } + "additionalProperties": { + "type": "string" }, - "description": "The target Workflow Id and (optionally) a specific Run Id thereof.", - "title": "The target Workflow Id and (optionally) a specific Run Id thereof." + "description": "Headers extracted from the original request in the Temporal frontend.\nWhen using Nexus over HTTP, this includes the request's HTTP headers ignoring multiple values." }, - "firstExecutionRunId": { + "scheduledTime": { "type": "string", - "description": "If set, this call will error if the most recent (if no Run Id is set on\n`workflow_execution`), or specified (if it is) Workflow Execution is not\npart of the same execution chain as this Id." + "format": "date-time", + "description": "The timestamp when the request was scheduled in the frontend." }, - "waitPolicy": { - "$ref": "#/definitions/v1WaitPolicy", - "description": "Specifies client's intent to wait for Update results.\nNOTE: This field works together with API call timeout which is limited by\nserver timeout (maximum wait time). If server timeout is expired before\nuser specified timeout, API call returns even if specified stage is not reached.\nActual reached stage will be included in the response." + "capabilities": { + "$ref": "#/definitions/v1RequestCapabilities" }, - "request": { - "type": "object", - "properties": { - "meta": { - "$ref": "#/definitions/v1Meta" - }, - "input": { - "type": "object", - "properties": { - "header": { - "$ref": "#/definitions/v1Header", - "description": "Headers that are passed with the Update from the requesting entity.\nThese can include things like auth or tracing tokens." - }, - "args": { - "$ref": "#/definitions/v1Payloads", - "description": "The arguments to pass to the named Update handler." - } - } - } - }, - "description": "The request information that will be delivered all the way down to the\nWorkflow Execution." + "startOperation": { + "$ref": "#/definitions/v1StartOperationRequest" + }, + "cancelOperation": { + "$ref": "#/definitions/v1CancelOperationRequest" + }, + "endpoint": { + "type": "string", + "description": "The endpoint this request was addressed to before forwarding to the worker.\nSupported from server version 1.30.0." } - } + }, + "description": "A Nexus request." }, - "WorkflowServiceUpdateWorkflowExecutionOptionsBody": { + "apinexusv1Response": { "type": "object", "properties": { - "workflowExecution": { - "type": "object", - "properties": { - "runId": { - "type": "string" - } - }, - "description": "The target Workflow Id and (optionally) a specific Run Id thereof.", - "title": "The target Workflow Id and (optionally) a specific Run Id thereof." - }, - "workflowExecutionOptions": { - "$ref": "#/definitions/v1WorkflowExecutionOptions", - "description": "Workflow Execution options. Partial updates are accepted and controlled by update_mask." + "startOperation": { + "$ref": "#/definitions/v1StartOperationResponse" }, - "updateMask": { - "type": "string", - "description": "Controls which fields from `workflow_execution_options` will be applied.\nTo unset a field, set it to null and use the update mask to indicate that it should be mutated." + "cancelOperation": { + "$ref": "#/definitions/v1CancelOperationResponse" + } + }, + "description": "A response indicating that the handler has successfully processed a request." + }, + "apiupdatev1Request": { + "type": "object", + "properties": { + "meta": { + "$ref": "#/definitions/v1Meta" }, - "identity": { - "type": "string", - "description": "Optional. The identity of the client who initiated this request." + "input": { + "$ref": "#/definitions/v1Input" } }, - "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationUpdateWorkflowExecutionOptions.\n - temporal.api.workflow.v1.PostResetOperation.UpdateWorkflowOptions." + "description": "The client request that triggers a Workflow Update." }, "protobufAny": { "type": "object", @@ -10299,7 +10600,7 @@ "description": "Time when the activity transitioned to a closed state." }, "lastFailure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Failure details from the last failed attempt." }, "lastWorkerIdentity": { @@ -10416,7 +10717,7 @@ "description": "The result if the activity completed successfully." }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "The failure if the activity completed unsuccessfully." } }, @@ -10606,7 +10907,7 @@ "type": "object", "properties": { "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "title": "Failure details" }, "scheduledEventId": { @@ -10708,7 +11009,7 @@ "title": "Starting at 1, the number of times this task has been attempted" }, "lastFailure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Will be set to the most recent failure details, if this task has previously failed and then\nbeen retried." }, "workerVersion": { @@ -10726,7 +11027,7 @@ "type": "object", "properties": { "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "If this activity had failed, was retried, and then timed out, that failure is stored as the\n`cause` in here." }, "scheduledEventId": { @@ -10753,6 +11054,12 @@ }, "title": "Represents the identifier used by a activity author to define the activity. Typically, the\nname of a function. This is sometimes referred to as the activity's \"name\"" }, + "v1AddOrUpdateRemoteClusterResponse": { + "type": "object" + }, + "v1AddSearchAttributesResponse": { + "type": "object" + }, "v1Alert": { "type": "object", "properties": { @@ -11186,7 +11493,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback." } @@ -11223,7 +11530,7 @@ "description": "The time when the last attempt completed." }, "lastAttemptFailure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "The last attempt's failure, if any." }, "nextAttemptScheduleTime": { @@ -11261,6 +11568,49 @@ ], "default": "CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED_CAUSE_UNSPECIFIED" }, + "v1CancelOperationRequest": { + "type": "object", + "properties": { + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Type of operation to cancel." + }, + "operationId": { + "type": "string", + "description": "Operation ID as originally generated by a Handler.\n\nDeprecated. Renamed to operation_token." + }, + "operationToken": { + "type": "string", + "description": "Operation token as originally generated by a Handler." + } + }, + "description": "A request to cancel an operation." + }, + "v1CancelOperationResponse": { + "type": "object", + "description": "Response variant for CancelOperationRequest." + }, + "v1CancelTimerCommandAttributes": { + "type": "object", + "properties": { + "timerId": { + "type": "string", + "title": "The same timer id from the start timer command" + } + } + }, + "v1CancelWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "details": { + "$ref": "#/definitions/v1Payloads" + } + } + }, "v1CanceledFailureInfo": { "type": "object", "properties": { @@ -11335,7 +11685,7 @@ "type": "object", "properties": { "failure": { - "$ref": "#/definitions/v1Failure" + "$ref": "#/definitions/apifailurev1Failure" }, "namespace": { "type": "string", @@ -11475,6 +11825,45 @@ } } }, + "v1ClusterMetadata": { + "type": "object", + "properties": { + "clusterName": { + "type": "string", + "description": "Name of the cluster name." + }, + "clusterId": { + "type": "string", + "description": "Id of the cluster." + }, + "address": { + "type": "string", + "description": "gRPC address." + }, + "httpAddress": { + "type": "string", + "description": "HTTP address, if one exists." + }, + "initialFailoverVersion": { + "type": "string", + "format": "int64", + "description": "A unique failover version across all connected clusters." + }, + "historyShardCount": { + "type": "integer", + "format": "int32", + "description": "History service shard number." + }, + "isConnectionEnabled": { + "type": "boolean", + "description": "A flag to indicate if a connection is active." + }, + "isReplicationEnabled": { + "type": "boolean", + "description": "A flag to indicate if replication is enabled." + } + } + }, "v1ClusterReplicationConfig": { "type": "object", "properties": { @@ -11483,6 +11872,95 @@ } } }, + "v1Command": { + "type": "object", + "properties": { + "commandType": { + "$ref": "#/definitions/v1CommandType" + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata on the command. This is sometimes carried over to the history event if one is\ncreated as a result of the command. Most commands won't have this information, and how this\ninformation is used is dependent upon the interface that reads it.\n\nCurrent well-known uses:\n * start_child_workflow_execution_command_attributes - populates\n temporal.api.workflow.v1.WorkflowExecutionInfo.user_metadata where the summary and details\n are used by user interfaces to show fixed as-of-start workflow summary and details.\n * start_timer_command_attributes - populates temporal.api.history.v1.HistoryEvent for timer\n started where the summary is used to identify the timer." + }, + "scheduleActivityTaskCommandAttributes": { + "$ref": "#/definitions/v1ScheduleActivityTaskCommandAttributes" + }, + "startTimerCommandAttributes": { + "$ref": "#/definitions/v1StartTimerCommandAttributes" + }, + "completeWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1CompleteWorkflowExecutionCommandAttributes" + }, + "failWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1FailWorkflowExecutionCommandAttributes" + }, + "requestCancelActivityTaskCommandAttributes": { + "$ref": "#/definitions/v1RequestCancelActivityTaskCommandAttributes" + }, + "cancelTimerCommandAttributes": { + "$ref": "#/definitions/v1CancelTimerCommandAttributes" + }, + "cancelWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1CancelWorkflowExecutionCommandAttributes" + }, + "requestCancelExternalWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1RequestCancelExternalWorkflowExecutionCommandAttributes" + }, + "recordMarkerCommandAttributes": { + "$ref": "#/definitions/v1RecordMarkerCommandAttributes" + }, + "continueAsNewWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1ContinueAsNewWorkflowExecutionCommandAttributes" + }, + "startChildWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1StartChildWorkflowExecutionCommandAttributes" + }, + "signalExternalWorkflowExecutionCommandAttributes": { + "$ref": "#/definitions/v1SignalExternalWorkflowExecutionCommandAttributes" + }, + "upsertWorkflowSearchAttributesCommandAttributes": { + "$ref": "#/definitions/v1UpsertWorkflowSearchAttributesCommandAttributes" + }, + "protocolMessageCommandAttributes": { + "$ref": "#/definitions/v1ProtocolMessageCommandAttributes" + }, + "modifyWorkflowPropertiesCommandAttributes": { + "$ref": "#/definitions/v1ModifyWorkflowPropertiesCommandAttributes", + "title": "16 is available for use - it was used as part of a prototype that never made it into a release" + }, + "scheduleNexusOperationCommandAttributes": { + "$ref": "#/definitions/v1ScheduleNexusOperationCommandAttributes" + }, + "requestCancelNexusOperationCommandAttributes": { + "$ref": "#/definitions/v1RequestCancelNexusOperationCommandAttributes" + } + } + }, + "v1CommandType": { + "type": "string", + "enum": [ + "COMMAND_TYPE_UNSPECIFIED", + "COMMAND_TYPE_SCHEDULE_ACTIVITY_TASK", + "COMMAND_TYPE_REQUEST_CANCEL_ACTIVITY_TASK", + "COMMAND_TYPE_START_TIMER", + "COMMAND_TYPE_COMPLETE_WORKFLOW_EXECUTION", + "COMMAND_TYPE_FAIL_WORKFLOW_EXECUTION", + "COMMAND_TYPE_CANCEL_TIMER", + "COMMAND_TYPE_CANCEL_WORKFLOW_EXECUTION", + "COMMAND_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION", + "COMMAND_TYPE_RECORD_MARKER", + "COMMAND_TYPE_CONTINUE_AS_NEW_WORKFLOW_EXECUTION", + "COMMAND_TYPE_START_CHILD_WORKFLOW_EXECUTION", + "COMMAND_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION", + "COMMAND_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES", + "COMMAND_TYPE_PROTOCOL_MESSAGE", + "COMMAND_TYPE_MODIFY_WORKFLOW_PROPERTIES", + "COMMAND_TYPE_SCHEDULE_NEXUS_OPERATION", + "COMMAND_TYPE_REQUEST_CANCEL_NEXUS_OPERATION" + ], + "default": "COMMAND_TYPE_UNSPECIFIED", + "description": "Whenever this list of command types is changed do change the function shouldBufferEvent in mutableStateBuilder.go to make sure to do the correct event ordering." + }, "v1CompatibleBuildIdRedirectRule": { "type": "object", "properties": { @@ -11509,6 +11987,14 @@ }, "description": "Used by the worker versioning APIs, represents an unordered set of one or more versions which are\nconsidered to be compatible with each other. Currently the versions are always worker build IDs." }, + "v1CompleteWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/v1Payloads" + } + } + }, "v1ConfigMetadata": { "type": "object", "properties": { @@ -11547,6 +12033,68 @@ "default": "CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_UNSPECIFIED", "description": "Experimental. Defines the versioning behavior to be used by the first task of a new workflow run in a continue-as-new chain.\n\n - CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_AUTO_UPGRADE: Start the new run with AutoUpgrade behavior. Use the Target Version of the workflow's task queue at\nstart-time, as AutoUpgrade workflows do. After the first workflow task completes, use whatever\nVersioning Behavior the workflow is annotated with in the workflow code.\n\nNote that if the previous workflow had a Pinned override, that override will be inherited by the\nnew workflow run regardless of the ContinueAsNewVersioningBehavior specified in the continue-as-new\ncommand. If a Pinned override is inherited by the new run, and the new run starts with AutoUpgrade\nbehavior, the base version of the new run will be the Target Version as described above, but the\neffective version will be whatever is specified by the Versioning Override until the override is removed." }, + "v1ContinueAsNewWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "workflowType": { + "$ref": "#/definitions/v1WorkflowType" + }, + "taskQueue": { + "$ref": "#/definitions/v1TaskQueue" + }, + "input": { + "$ref": "#/definitions/v1Payloads" + }, + "workflowRunTimeout": { + "type": "string", + "description": "Timeout of a single workflow run." + }, + "workflowTaskTimeout": { + "type": "string", + "description": "Timeout of a single workflow task." + }, + "backoffStartInterval": { + "type": "string", + "description": "How long the workflow start will be delayed - not really a \"backoff\" in the traditional sense." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy" + }, + "initiator": { + "$ref": "#/definitions/v1ContinueAsNewInitiator", + "title": "Should be removed" + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "title": "Should be removed" + }, + "lastCompletionResult": { + "$ref": "#/definitions/v1Payloads", + "title": "Should be removed" + }, + "cronSchedule": { + "type": "string", + "description": "Should be removed. Not necessarily unused but unclear and not exposed by SDKs." + }, + "header": { + "$ref": "#/definitions/v1Header" + }, + "memo": { + "$ref": "#/definitions/v1Memo" + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + }, + "inheritBuildId": { + "type": "boolean", + "description": "If this is set, the new execution inherits the Build ID of the current execution. Otherwise,\nthe assignment rules will be used to independently assign a Build ID to the new execution.\nDeprecated. Only considered for versioning v0.2." + }, + "initialVersioningBehavior": { + "$ref": "#/definitions/v1ContinueAsNewVersioningBehavior", + "description": "Experimental. Optionally decide the versioning behavior that the first task of the new run should use.\nFor example, choose to AutoUpgrade on continue-as-new instead of inheriting the pinned version\nof the previous run." + } + } + }, "v1CountActivityExecutionsResponse": { "type": "object", "properties": { @@ -11701,6 +12249,18 @@ } } }, + "v1DeleteActivityExecutionResponse": { + "type": "object" + }, + "v1DeleteNamespaceResponse": { + "type": "object", + "properties": { + "deletedNamespace": { + "type": "string", + "description": "Temporary namespace name that is used during reclaim resources step." + } + } + }, "v1DeleteNexusEndpointResponse": { "type": "object" }, @@ -11713,6 +12273,9 @@ "v1DeleteWorkerDeploymentVersionResponse": { "type": "object" }, + "v1DeleteWorkflowExecutionResponse": { + "type": "object" + }, "v1DeleteWorkflowRuleResponse": { "type": "object" }, @@ -11813,6 +12376,10 @@ }, "description": "Holds information about ongoing transition of a workflow execution from one worker\ndeployment version to another.\nExperimental. Might change in the future." }, + "v1DeprecateNamespaceResponse": { + "type": "object", + "description": "Deprecated." + }, "v1DescribeActivityExecutionResponse": { "type": "object", "properties": { @@ -12244,12 +12811,23 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/ExecuteMultiOperationResponseResponse" + "$ref": "#/definitions/v1ExecuteMultiOperationResponseResponse" } } }, "description": "IMPORTANT: For [StartWorkflow, UpdateWorkflow] combination (\"Update-with-Start\") when both\n 1. the workflow update for the requested update ID has already completed, and\n 2. the workflow for the requested workflow ID has already been closed,\nthen you'll receive\n - an update response containing the update's outcome, and\n - a start response with a `status` field that reflects the workflow's current state." }, + "v1ExecuteMultiOperationResponseResponse": { + "type": "object", + "properties": { + "startWorkflow": { + "$ref": "#/definitions/v1StartWorkflowExecutionResponse" + }, + "updateWorkflow": { + "$ref": "#/definitions/v1UpdateWorkflowExecutionResponse" + } + } + }, "v1ExternalWorkflowExecutionCancelRequestedEventAttributes": { "type": "object", "properties": { @@ -12294,6 +12872,14 @@ } } }, + "v1FailWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "failure": { + "$ref": "#/definitions/apifailurev1Failure" + } + } + }, "v1FailoverStatus": { "type": "object", "properties": { @@ -12309,58 +12895,6 @@ }, "title": "Represents a historical replication status of a Namespace" }, - "v1Failure": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "source": { - "type": "string", - "description": "The source this Failure originated in, e.g. TypeScriptSDK / JavaSDK\nIn some SDKs this is used to rehydrate the stack trace into an exception object." - }, - "stackTrace": { - "type": "string" - }, - "encodedAttributes": { - "$ref": "#/definitions/v1Payload", - "description": "Alternative way to supply `message` and `stack_trace` and possibly other attributes, used for encryption of\nerrors originating in user code which might contain sensitive information.\nThe `encoded_attributes` Payload could represent any serializable object, e.g. JSON object or a `Failure` proto\nmessage.\n\nSDK authors:\n- The SDK should provide a default `encodeFailureAttributes` and `decodeFailureAttributes` implementation that:\n - Uses a JSON object to represent `{ message, stack_trace }`.\n - Overwrites the original message with \"Encoded failure\" to indicate that more information could be extracted.\n - Overwrites the original stack_trace with an empty string.\n - The resulting JSON object is converted to Payload using the default PayloadConverter and should be processed\n by the user-provided PayloadCodec\n\n- If there's demand, we could allow overriding the default SDK implementation to encode other opaque Failure attributes." - }, - "cause": { - "$ref": "#/definitions/v1Failure" - }, - "applicationFailureInfo": { - "$ref": "#/definitions/v1ApplicationFailureInfo" - }, - "timeoutFailureInfo": { - "$ref": "#/definitions/v1TimeoutFailureInfo" - }, - "canceledFailureInfo": { - "$ref": "#/definitions/v1CanceledFailureInfo" - }, - "terminatedFailureInfo": { - "$ref": "#/definitions/v1TerminatedFailureInfo" - }, - "serverFailureInfo": { - "$ref": "#/definitions/v1ServerFailureInfo" - }, - "resetWorkflowFailureInfo": { - "$ref": "#/definitions/v1ResetWorkflowFailureInfo" - }, - "activityFailureInfo": { - "$ref": "#/definitions/v1ActivityFailureInfo" - }, - "childWorkflowExecutionFailureInfo": { - "$ref": "#/definitions/v1ChildWorkflowExecutionFailureInfo" - }, - "nexusOperationExecutionFailureInfo": { - "$ref": "#/definitions/v1NexusOperationFailureInfo" - }, - "nexusHandlerFailureInfo": { - "$ref": "#/definitions/v1NexusHandlerFailureInfo" - } - } - }, "v1FetchWorkerConfigResponse": { "type": "object", "properties": { @@ -12447,6 +12981,17 @@ } } }, + "v1GetSearchAttributesResponse": { + "type": "object", + "properties": { + "keys": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/v1IndexedValueType" + } + } + } + }, "v1GetSystemInfoResponse": { "type": "object", "properties": { @@ -12600,6 +13145,22 @@ } } }, + "v1HandlerError": { + "type": "object", + "properties": { + "errorType": { + "type": "string", + "description": "See https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors." + }, + "failure": { + "$ref": "#/definitions/apinexusv1Failure" + }, + "retryBehavior": { + "$ref": "#/definitions/v1NexusHandlerErrorRetryBehavior", + "description": "Retry behavior, defaults to the retry behavior of the error type as defined in the spec." + } + } + }, "v1Header": { "type": "object", "properties": { @@ -12661,7 +13222,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links associated with the event." }, @@ -12912,18 +13473,6 @@ }, "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." }, - "v1Link": { - "type": "object", - "properties": { - "workflowEvent": { - "$ref": "#/definitions/LinkWorkflowEvent" - }, - "batchJob": { - "$ref": "#/definitions/LinkBatchJob" - } - }, - "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." - }, "v1ListActivityExecutionsResponse": { "type": "object", "properties": { @@ -12974,6 +13523,39 @@ } } }, + "v1ListClosedWorkflowExecutionsResponse": { + "type": "object", + "properties": { + "executions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1WorkflowExecutionInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte" + } + } + }, + "v1ListClustersResponse": { + "type": "object", + "properties": { + "clusters": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1ClusterMetadata" + }, + "title": "List of all cluster information" + }, + "nextPageToken": { + "type": "string", + "format": "byte" + } + } + }, "v1ListDeploymentsResponse": { "type": "object", "properties": { @@ -13024,6 +13606,22 @@ } } }, + "v1ListOpenWorkflowExecutionsResponse": { + "type": "object", + "properties": { + "executions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1WorkflowExecutionInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte" + } + } + }, "v1ListScheduleMatchingTimesResponse": { "type": "object", "properties": { @@ -13078,6 +13676,25 @@ } } }, + "v1ListTaskQueuePartitionsResponse": { + "type": "object", + "properties": { + "activityTaskQueuePartitions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1TaskQueuePartitionMetadata" + } + }, + "workflowTaskQueuePartitions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1TaskQueuePartitionMetadata" + } + } + } + }, "v1ListWorkerDeploymentsResponse": { "type": "object", "properties": { @@ -13167,7 +13784,7 @@ "$ref": "#/definitions/v1Header" }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Some uses of markers, like a local activity, could \"fail\". If they did that is recorded here." } } @@ -13234,6 +13851,15 @@ }, "title": "Metadata relevant for metering purposes" }, + "v1ModifyWorkflowPropertiesCommandAttributes": { + "type": "object", + "properties": { + "upsertedMemo": { + "$ref": "#/definitions/v1Memo", + "description": "If set, update the workflow memo with the provided values. The values will be merged with\nthe existing memo. If the user wants to delete values, a default/empty Payload should be\nused as the value for the key being deleted." + } + } + }, "v1NamespaceConfig": { "type": "object", "properties": { @@ -13497,7 +14123,7 @@ "description": "The `WORKFLOW_TASK_COMPLETED` event that the corresponding RequestCancelNexusOperation command was reported\nwith." }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Failure details. A NexusOperationFailureInfo wrapping a CanceledFailureInfo." }, "scheduledEventId": { @@ -13531,7 +14157,7 @@ "description": "The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation." }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Cancellation details." }, "requestId": { @@ -13563,7 +14189,7 @@ "description": "The time when the last attempt completed." }, "lastAttemptFailure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "The last attempt's failure, if any." }, "nextAttemptScheduleTime": { @@ -13620,7 +14246,7 @@ "description": "The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation." }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Failure details. A NexusOperationFailureInfo wrapping an ApplicationFailureInfo." }, "requestId": { @@ -13747,7 +14373,7 @@ "description": "The ID of the `NEXUS_OPERATION_SCHEDULED` event. Uniquely identifies this operation." }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Failure details. A NexusOperationFailureInfo wrapping a CanceledFailureInfo." }, "requestId": { @@ -13782,7 +14408,7 @@ "$ref": "#/definitions/v1Payloads" }, "failure": { - "$ref": "#/definitions/v1Failure" + "$ref": "#/definitions/apifailurev1Failure" } }, "description": "The outcome of a Workflow Update: success or failure." @@ -13865,7 +14491,7 @@ "format": "date-time" }, "lastFailure": { - "$ref": "#/definitions/v1Failure" + "$ref": "#/definitions/apifailurev1Failure" }, "lastWorkerIdentity": { "type": "string" @@ -14003,7 +14629,7 @@ "description": "The time when the last attempt completed." }, "lastAttemptFailure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "The last attempt's failure, if any." }, "nextAttemptScheduleTime": { @@ -14065,47 +14691,171 @@ "format": "date-time", "description": "original_scheduled_time is the scheduled time of the first workflow task during workflow task heartbeat.\nHeartbeat workflow task is done by RespondWorkflowTaskComplete with ForceCreateNewWorkflowTask == true and no command\nIn this case, OriginalScheduledTime won't change. Then when current time - original_scheduled_time exceeds\nsome threshold, the workflow task will be forced timeout." }, - "startedTime": { - "type": "string", - "format": "date-time" + "startedTime": { + "type": "string", + "format": "date-time" + }, + "attempt": { + "type": "integer", + "format": "int32" + } + } + }, + "v1PendingWorkflowTaskState": { + "type": "string", + "enum": [ + "PENDING_WORKFLOW_TASK_STATE_UNSPECIFIED", + "PENDING_WORKFLOW_TASK_STATE_SCHEDULED", + "PENDING_WORKFLOW_TASK_STATE_STARTED" + ], + "default": "PENDING_WORKFLOW_TASK_STATE_UNSPECIFIED" + }, + "v1PluginInfo": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the plugin, required." + }, + "version": { + "type": "string", + "description": "The version of the plugin, may be empty." + } + } + }, + "v1PollActivityExecutionResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the activity, useful when run_id was not specified in the request." + }, + "outcome": { + "$ref": "#/definitions/v1ActivityExecutionOutcome" + } + } + }, + "v1PollActivityTaskQueueResponse": { + "type": "object", + "properties": { + "taskToken": { + "type": "string", + "format": "byte", + "title": "A unique identifier for this task" + }, + "workflowNamespace": { + "type": "string", + "description": "The namespace of the activity. If this is a workflow activity then this is the namespace of\nthe workflow also. If this is a standalone activity then the name of this field is\nmisleading, but retained for compatibility with workflow activities." + }, + "workflowType": { + "$ref": "#/definitions/v1WorkflowType", + "description": "Type of the requesting workflow (if this is a workflow activity)." + }, + "workflowExecution": { + "$ref": "#/definitions/v1WorkflowExecution", + "title": "Execution info of the requesting workflow (if this is a workflow activity)" + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType" + }, + "activityId": { + "type": "string", + "description": "The autogenerated or user specified identifier of this activity. Can be used to complete the\nactivity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage\nhas resolved, but unique IDs for every activity invocation is a good idea.\nNote that only a workflow activity ID may be autogenerated." + }, + "header": { + "$ref": "#/definitions/v1Header", + "description": "Headers specified by the scheduling workflow. Commonly used to propagate contextual info\nfrom the workflow to its activities. For example, tracing contexts." + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "title": "Arguments to the activity invocation" + }, + "heartbeatDetails": { + "$ref": "#/definitions/v1Payloads", + "description": "Details of the last heartbeat that was recorded for this activity as of the time this task\nwas delivered." + }, + "scheduledTime": { + "type": "string", + "format": "date-time", + "title": "When was this task first scheduled" + }, + "currentAttemptScheduledTime": { + "type": "string", + "format": "date-time", + "title": "When was this task attempt scheduled" + }, + "startedTime": { + "type": "string", + "format": "date-time", + "title": "When was this task started (this attempt)" + }, + "attempt": { + "type": "integer", + "format": "int32", + "title": "Starting at 1, the number of attempts to perform this activity" + }, + "scheduleToCloseTimeout": { + "type": "string", + "title": "First scheduled -> final result reported timeout" + }, + "startToCloseTimeout": { + "type": "string", + "title": "Current attempt start -> final result reported timeout" + }, + "heartbeatTimeout": { + "type": "string", + "description": "Window within which the activity must report a heartbeat, or be timed out." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy", + "description": "This is the retry policy the service uses which may be different from the one provided\n(or not) during activity scheduling. The service can override the provided one if some\nvalues are not specified or exceed configured system limits." + }, + "pollerScalingDecision": { + "$ref": "#/definitions/v1PollerScalingDecision", + "description": "Server-advised information the SDK may use to adjust its poller count." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "title": "Priority metadata" }, - "attempt": { - "type": "integer", - "format": "int32" + "activityRunId": { + "type": "string", + "description": "The run ID of the activity execution, only set for standalone activities." } } }, - "v1PendingWorkflowTaskState": { - "type": "string", - "enum": [ - "PENDING_WORKFLOW_TASK_STATE_UNSPECIFIED", - "PENDING_WORKFLOW_TASK_STATE_SCHEDULED", - "PENDING_WORKFLOW_TASK_STATE_STARTED" - ], - "default": "PENDING_WORKFLOW_TASK_STATE_UNSPECIFIED" - }, - "v1PluginInfo": { + "v1PollNexusTaskQueueResponse": { "type": "object", "properties": { - "name": { + "taskToken": { "type": "string", - "description": "The name of the plugin, required." + "format": "byte", + "description": "An opaque unique identifier for this task for correlating a completion request the embedded request." }, - "version": { - "type": "string", - "description": "The version of the plugin, may be empty." + "request": { + "$ref": "#/definitions/apinexusv1Request", + "description": "Embedded request as translated from the incoming frontend request." + }, + "pollerScalingDecision": { + "$ref": "#/definitions/v1PollerScalingDecision", + "description": "Server-advised information the SDK may use to adjust its poller count." } } }, - "v1PollActivityExecutionResponse": { + "v1PollWorkflowExecutionUpdateResponse": { "type": "object", "properties": { - "runId": { - "type": "string", - "description": "The run ID of the activity, useful when run_id was not specified in the request." - }, "outcome": { - "$ref": "#/definitions/v1ActivityExecutionOutcome" + "$ref": "#/definitions/v1Outcome", + "description": "The outcome of the update if and only if the update has completed. If\nthis response is being returned before the update has completed (e.g. due\nto the specification of a wait policy that only waits on\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED) then this field will\nnot be set." + }, + "stage": { + "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage", + "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed." + }, + "updateRef": { + "$ref": "#/definitions/v1UpdateRef", + "description": "Sufficient information to address this Update." } } }, @@ -14258,6 +15008,15 @@ }, "description": "Priority contains metadata that controls relative ordering of task processing\nwhen tasks are backed up in a queue. Initially, Priority will be used in\nmatching (workflow and activity) task queues. Later it may be used in history\ntask queues and in rate limiting decisions.\n\nPriority is attached to workflows and activities. By default, activities\ninherit Priority from the workflow that created them, but may override fields\nwhen an activity is started or modified.\n\nDespite being named \"Priority\", this message also contains fields that\ncontrol \"fairness\" mechanisms.\n\nFor all fields, the field not present or equal to zero/empty string means to\ninherit the value from the calling workflow, or if there is no calling\nworkflow, then use the default value.\n\nFor all fields other than fairness_key, the zero value isn't meaningful so\nthere's no confusion between inherit/default and a meaningful value. For\nfairness_key, the empty string will be interpreted as \"inherit\". This means\nthat if a workflow has a non-empty fairness key, you can't override the\nfairness key of its activity to the empty string.\n\nThe overall semantics of Priority are:\n1. First, consider \"priority\": higher priority (lower number) goes first.\n2. Then, consider fairness: try to dispatch tasks for different fairness keys\n in proportion to their weight.\n\nApplications may use any subset of mechanisms that are useful to them and\nleave the other fields to use default values.\n\nNot all queues in the system may support the \"full\" semantics of all priority\nfields. (Currently only support in matching task queues is planned.)" }, + "v1ProtocolMessageCommandAttributes": { + "type": "object", + "properties": { + "messageId": { + "type": "string", + "description": "The message ID of the message to which this command is a pointer." + } + } + }, "v1QueryRejectCondition": { "type": "string", "enum": [ @@ -14277,6 +15036,15 @@ } } }, + "v1QueryResultType": { + "type": "string", + "enum": [ + "QUERY_RESULT_TYPE_UNSPECIFIED", + "QUERY_RESULT_TYPE_ANSWERED", + "QUERY_RESULT_TYPE_FAILED" + ], + "default": "QUERY_RESULT_TYPE_UNSPECIFIED" + }, "v1QueryWorkflowResponse": { "type": "object", "properties": { @@ -14385,6 +15153,26 @@ } } }, + "v1RecordMarkerCommandAttributes": { + "type": "object", + "properties": { + "markerName": { + "type": "string" + }, + "details": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/v1Payloads" + } + }, + "header": { + "$ref": "#/definitions/v1Header" + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure" + } + } + }, "v1RecordWorkerHeartbeatResponse": { "type": "object" }, @@ -14461,6 +15249,12 @@ }, "description": "ReleaseInfo contains information about specific version of temporal." }, + "v1RemoveRemoteClusterResponse": { + "type": "object" + }, + "v1RemoveSearchAttributesResponse": { + "type": "object" + }, "v1ReplicationState": { "type": "string", "enum": [ @@ -14470,20 +15264,44 @@ ], "default": "REPLICATION_STATE_UNSPECIFIED" }, - "v1Request": { + "v1RequestCancelActivityExecutionResponse": { + "type": "object" + }, + "v1RequestCancelActivityTaskCommandAttributes": { "type": "object", "properties": { - "meta": { - "$ref": "#/definitions/v1Meta" - }, - "input": { - "$ref": "#/definitions/v1Input" + "scheduledEventId": { + "type": "string", + "format": "int64", + "description": "The `ACTIVITY_TASK_SCHEDULED` event id for the activity being cancelled." } - }, - "description": "The client request that triggers a Workflow Update." + } }, - "v1RequestCancelActivityExecutionResponse": { - "type": "object" + "v1RequestCancelExternalWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "workflowId": { + "type": "string" + }, + "runId": { + "type": "string" + }, + "control": { + "type": "string", + "description": "Deprecated." + }, + "childWorkflowOnly": { + "type": "boolean", + "description": "Set this to true if the workflow being cancelled is a child of the workflow originating this\ncommand. The request will be rejected if it is set to true and the target workflow is *not*\na child of the requesting workflow." + }, + "reason": { + "type": "string", + "title": "Reason for requesting the cancellation" + } + } }, "v1RequestCancelExternalWorkflowExecutionFailedEventAttributes": { "type": "object", @@ -14549,9 +15367,28 @@ } } }, + "v1RequestCancelNexusOperationCommandAttributes": { + "type": "object", + "properties": { + "scheduledEventId": { + "type": "string", + "format": "int64", + "description": "The `NEXUS_OPERATION_SCHEDULED` event ID (a unique identifier) for the operation to be canceled.\nThe operation may ignore cancellation and end up with any completion state." + } + } + }, "v1RequestCancelWorkflowExecutionResponse": { "type": "object" }, + "v1RequestCapabilities": { + "type": "object", + "properties": { + "temporalFailureResponses": { + "type": "boolean", + "description": "If set, handlers may use temporal.api.failure.v1.Failure instances to return failures to the server.\nThis also allows handler and operation errors to have their own messages and stack traces." + } + } + }, "v1RequestIdInfo": { "type": "object", "properties": { @@ -14685,6 +15522,9 @@ "default": "RESET_REAPPLY_TYPE_UNSPECIFIED", "description": "Deprecated: applications should use ResetReapplyExcludeType to specify\nexclusions from this set, and new event types should be added to ResetReapplyExcludeType\ninstead of here.\n\n - RESET_REAPPLY_TYPE_SIGNAL: Signals are reapplied when workflow is reset.\n - RESET_REAPPLY_TYPE_NONE: No events are reapplied when workflow is reset.\n - RESET_REAPPLY_TYPE_ALL_ELIGIBLE: All eligible events are reapplied when workflow is reset." }, + "v1ResetStickyTaskQueueResponse": { + "type": "object" + }, "v1ResetType": { "type": "string", "enum": [ @@ -14730,7 +15570,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Failure" + "$ref": "#/definitions/apifailurev1Failure" }, "title": "Server validation failures could include\nlast_heartbeat_details payload is too large, request failure is too large" } @@ -14743,12 +15583,56 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Failure" + "$ref": "#/definitions/apifailurev1Failure" }, "title": "Server validation failures could include\nlast_heartbeat_details payload is too large, request failure is too large" } } }, + "v1RespondNexusTaskCompletedResponse": { + "type": "object" + }, + "v1RespondNexusTaskFailedResponse": { + "type": "object" + }, + "v1RespondQueryTaskCompletedResponse": { + "type": "object" + }, + "v1RespondWorkflowTaskCompletedRequestCapabilities": { + "type": "object", + "properties": { + "discardSpeculativeWorkflowTaskWithEvents": { + "type": "boolean", + "description": "True if the SDK can handle speculative workflow task with command events. If true, the\nserver may choose, at its discretion, to discard a speculative workflow task even if that\nspeculative task included command events the SDK had not previously processed.\n" + } + }, + "description": "SDK capability details." + }, + "v1RespondWorkflowTaskCompletedResponse": { + "type": "object", + "properties": { + "workflowTask": { + "$ref": "#/definitions/v1PollWorkflowTaskQueueResponse", + "title": "See `RespondWorkflowTaskCompletedResponse::return_new_workflow_task`" + }, + "activityTasks": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1PollActivityTaskQueueResponse" + }, + "title": "See `ScheduleActivityTaskCommandAttributes::request_eager_execution`" + }, + "resetHistoryEventId": { + "type": "string", + "format": "int64", + "description": "If non zero, indicates the server has discarded the workflow task that was being responded to.\nWill be the event ID of the last workflow task started event in the history before the new workflow task.\nServer is only expected to discard a workflow task if it could not have modified the workflow state." + } + } + }, + "v1RespondWorkflowTaskFailedResponse": { + "type": "object" + }, "v1RetryPolicy": { "type": "object", "properties": { @@ -14850,6 +15734,23 @@ "default": "ROUTING_CONFIG_UPDATE_STATE_UNSPECIFIED", "description": "Indicates whether a change to the Routing Config has been\npropagated to all relevant Task Queues and their partitions.\n\n - ROUTING_CONFIG_UPDATE_STATE_IN_PROGRESS: Update to the RoutingConfig is currently in progress.\n - ROUTING_CONFIG_UPDATE_STATE_COMPLETED: Update to the RoutingConfig has completed successfully." }, + "v1ScanWorkflowExecutionsResponse": { + "type": "object", + "properties": { + "executions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1WorkflowExecutionInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte" + } + }, + "description": "Deprecated: Use with `ListWorkflowExecutions`." + }, "v1Schedule": { "type": "object", "properties": { @@ -14899,6 +15800,58 @@ } } }, + "v1ScheduleActivityTaskCommandAttributes": { + "type": "object", + "properties": { + "activityId": { + "type": "string" + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType" + }, + "taskQueue": { + "$ref": "#/definitions/v1TaskQueue" + }, + "header": { + "$ref": "#/definitions/v1Header" + }, + "input": { + "$ref": "#/definitions/v1Payloads" + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Indicates how long the caller is willing to wait for activity completion. The \"schedule\" time\nis when the activity is initially scheduled, not when the most recent retry is scheduled.\nLimits how long retries will be attempted. Either this or `start_to_close_timeout` must be\nspecified. When not specified, defaults to the workflow execution timeout.\n" + }, + "scheduleToStartTimeout": { + "type": "string", + "title": "Limits the time an activity task can stay in a task queue before a worker picks it up. The\n\"schedule\" time is when the most recent retry is scheduled. This timeout should usually not\nbe set: it's useful in specific scenarios like worker-specific task queues. This timeout is\nalways non retryable, as all a retry would achieve is to put it back into the same queue.\nDefaults to `schedule_to_close_timeout` or workflow execution timeout if that is not\nspecified. More info:\nhttps://docs.temporal.io/docs/content/what-is-a-schedule-to-start-timeout/" + }, + "startToCloseTimeout": { + "type": "string", + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be specified.\n" + }, + "heartbeatTimeout": { + "type": "string", + "description": "Maximum permitted time between successful worker heartbeats." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy", + "description": "Activities are provided by a default retry policy which is controlled through the service's\ndynamic configuration. Retries will be attempted until `schedule_to_close_timeout` has\nelapsed. To disable retries set retry_policy.maximum_attempts to 1." + }, + "requestEagerExecution": { + "type": "boolean", + "description": "Request to start the activity directly bypassing matching service and worker polling\nThe slot for executing the activity should be reserved when setting this field to true." + }, + "useWorkflowBuildId": { + "type": "boolean", + "description": "If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,\nAssignment rules of the activity's Task Queue will be used to determine the Build ID." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "description": "Priority metadata. If this message is not present, or any fields are not\npresent, they inherit the values from the workflow." + } + } + }, "v1ScheduleInfo": { "type": "object", "properties": { @@ -15017,8 +15970,48 @@ "format": "date-time" } } - }, - "description": "ScheduleListInfo is an abbreviated set of values from Schedule and ScheduleInfo\nthat's returned in ListSchedules." + }, + "description": "ScheduleListInfo is an abbreviated set of values from Schedule and ScheduleInfo\nthat's returned in ListSchedules." + }, + "v1ScheduleNexusOperationCommandAttributes": { + "type": "object", + "properties": { + "endpoint": { + "type": "string", + "description": "Endpoint name, must exist in the endpoint registry or this command will fail." + }, + "service": { + "type": "string", + "description": "Service name." + }, + "operation": { + "type": "string", + "description": "Operation name." + }, + "input": { + "$ref": "#/definitions/v1Payload", + "description": "Input for the operation. The server converts this into Nexus request content and the appropriate content headers\ninternally when sending the StartOperation request. On the handler side, if it is also backed by Temporal, the\ncontent is transformed back to the original Payload sent in this command." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Schedule-to-close timeout for this operation.\nIndicates how long the caller is willing to wait for operation completion.\nCalls are retried internally by the server." + }, + "nexusHeader": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Header to attach to the Nexus request.\nUsers are responsible for encrypting sensitive data in this header as it is stored in workflow history and\ntransmitted to external services as-is.\nThis is useful for propagating tracing information.\nNote these headers are not the same as Temporal headers on internal activities and child workflows, these are\ntransmitted to Nexus operations that may be external and are not traditional payloads." + }, + "scheduleToStartTimeout": { + "type": "string", + "description": "Schedule-to-start timeout for this operation.\nIndicates how long the caller is willing to wait for the operation to be started (or completed if synchronous)\nby the handler. If the operation is not started within this timeout, it will fail with\nTIMEOUT_TYPE_SCHEDULE_TO_START.\nIf not set or zero, no schedule-to-start timeout is enforced.\nRequires server version 1.31.0 or later." + }, + "startToCloseTimeout": { + "type": "string", + "description": "Start-to-close timeout for this operation.\nIndicates how long the caller is willing to wait for an asynchronous operation to complete after it has been\nstarted. If the operation does not complete within this timeout after starting, it will fail with\nTIMEOUT_TYPE_START_TO_CLOSE.\nOnly applies to asynchronous operations. Synchronous operations ignore this timeout.\nIf not set or zero, no start-to-close timeout is enforced.\nRequires server version 1.31.0 or later." + } + } }, "v1ScheduleOverlapPolicy": { "type": "string", @@ -15272,6 +16265,40 @@ ], "default": "SEVERITY_UNSPECIFIED" }, + "v1ShutdownWorkerResponse": { + "type": "object" + }, + "v1SignalExternalWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "execution": { + "$ref": "#/definitions/v1WorkflowExecution" + }, + "signalName": { + "type": "string", + "description": "The workflow author-defined name of the signal to send to the workflow." + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "description": "Serialized value(s) to provide with the signal." + }, + "control": { + "type": "string", + "title": "Deprecated" + }, + "childWorkflowOnly": { + "type": "boolean", + "description": "Set this to true if the workflow being cancelled is a child of the workflow originating this\ncommand. The request will be rejected if it is set to true and the target workflow is *not*\na child of the requesting workflow." + }, + "header": { + "$ref": "#/definitions/v1Header", + "description": "Headers that are passed by the workflow that is sending a signal to the external \nworkflow that is receiving this signal." + } + } + }, "v1SignalExternalWorkflowExecutionFailedCause": { "type": "string", "enum": [ @@ -15385,6 +16412,73 @@ "v1StartBatchOperationResponse": { "type": "object" }, + "v1StartChildWorkflowExecutionCommandAttributes": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "workflowId": { + "type": "string" + }, + "workflowType": { + "$ref": "#/definitions/v1WorkflowType" + }, + "taskQueue": { + "$ref": "#/definitions/v1TaskQueue" + }, + "input": { + "$ref": "#/definitions/v1Payloads" + }, + "workflowExecutionTimeout": { + "type": "string", + "description": "Total workflow execution timeout including retries and continue as new." + }, + "workflowRunTimeout": { + "type": "string", + "description": "Timeout of a single workflow run." + }, + "workflowTaskTimeout": { + "type": "string", + "description": "Timeout of a single workflow task." + }, + "parentClosePolicy": { + "$ref": "#/definitions/v1ParentClosePolicy", + "description": "Default: PARENT_CLOSE_POLICY_TERMINATE." + }, + "control": { + "type": "string" + }, + "workflowIdReusePolicy": { + "$ref": "#/definitions/v1WorkflowIdReusePolicy", + "description": "Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy" + }, + "cronSchedule": { + "type": "string", + "description": "Establish a cron schedule for the child workflow." + }, + "header": { + "$ref": "#/definitions/v1Header" + }, + "memo": { + "$ref": "#/definitions/v1Memo" + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + }, + "inheritBuildId": { + "type": "boolean", + "description": "If this is set, the child workflow inherits the Build ID of the parent. Otherwise, the assignment\nrules of the child's Task Queue will be used to independently assign a Build ID to it.\nDeprecated. Only considered for versioning v0.2." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "description": "Priority metadata. If this message is not present, or any fields are not\npresent, they inherit the values from the workflow." + } + } + }, "v1StartChildWorkflowExecutionFailedCause": { "type": "string", "enum": [ @@ -15506,6 +16600,93 @@ } } }, + "v1StartOperationRequest": { + "type": "object", + "properties": { + "service": { + "type": "string", + "description": "Name of service to start the operation in." + }, + "operation": { + "type": "string", + "description": "Type of operation to start." + }, + "requestId": { + "type": "string", + "description": "A request ID that can be used as an idempotentency key." + }, + "callback": { + "type": "string", + "description": "Callback URL to call upon completion if the started operation is async." + }, + "payload": { + "$ref": "#/definitions/v1Payload", + "description": "Full request body from the incoming HTTP request." + }, + "callbackHeader": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Header that is expected to be attached to the callback request when the operation completes." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apinexusv1Link" + }, + "description": "Links contain caller information and can be attached to the operations started by the handler." + } + }, + "description": "A request to start an operation." + }, + "v1StartOperationResponse": { + "type": "object", + "properties": { + "syncSuccess": { + "$ref": "#/definitions/StartOperationResponseSync" + }, + "asyncSuccess": { + "$ref": "#/definitions/StartOperationResponseAsync" + }, + "operationError": { + "$ref": "#/definitions/v1UnsuccessfulOperationError", + "description": "The operation completed unsuccessfully (failed or canceled).\nDeprecated. Use the failure variant instead." + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The operation completed unsuccessfully (failed or canceled).\nFailure object must contain an ApplicationFailureInfo or CanceledFailureInfo object." + } + }, + "description": "Response variant for StartOperationRequest." + }, + "v1StartTimeFilter": { + "type": "object", + "properties": { + "earliestTime": { + "type": "string", + "format": "date-time" + }, + "latestTime": { + "type": "string", + "format": "date-time" + } + } + }, + "v1StartTimerCommandAttributes": { + "type": "object", + "properties": { + "timerId": { + "type": "string", + "description": "An id for the timer, currently live timers must have different ids. Typically autogenerated\nby the SDK." + }, + "startToFireTimeout": { + "type": "string", + "description": "How long until the timer fires, producing a `TIMER_FIRED` event.\n" + } + } + }, "v1StartWorkflowExecutionRequest": { "type": "object", "properties": { @@ -15575,7 +16756,7 @@ "description": "Request to get the first workflow 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`workflow_task_timeout`." }, "continuedFailure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "These values will be available as ContinuedFailure and LastCompletionResult in the\nWorkflowExecutionStarted event and through SDKs. The are currently only used by the\nserver itself (for the schedules feature) and are not intended to be exposed in\nStartWorkflowExecution." }, "lastCompletionResult": { @@ -15601,7 +16782,7 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1Link" + "$ref": "#/definitions/apicommonv1Link" }, "description": "Links to be associated with the workflow." }, @@ -15643,11 +16824,30 @@ "description": "When `request_eager_execution` is set on the `StartWorkflowExecutionRequest`, the server - if supported - will\nreturn the first workflow task to be eagerly executed.\nThe caller is expected to have a worker available to process the task." }, "link": { - "$ref": "#/definitions/v1Link", + "$ref": "#/definitions/apicommonv1Link", "description": "Link to the workflow event." } } }, + "v1StatusFilter": { + "type": "object", + "properties": { + "status": { + "$ref": "#/definitions/v1WorkflowExecutionStatus" + } + } + }, + "v1StickyExecutionAttributes": { + "type": "object", + "properties": { + "workerTaskQueue": { + "$ref": "#/definitions/v1TaskQueue" + }, + "scheduleToStartTimeout": { + "type": "string" + } + } + }, "v1StopBatchOperationResponse": { "type": "object" }, @@ -15790,6 +16990,28 @@ "default": "TASK_QUEUE_KIND_UNSPECIFIED", "description": " - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities." }, + "v1TaskQueueMetadata": { + "type": "object", + "properties": { + "maxTasksPerSecond": { + "type": "number", + "format": "double", + "title": "Allows throttling dispatch of tasks from this queue" + } + }, + "title": "Only applies to activity task queues" + }, + "v1TaskQueuePartitionMetadata": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "ownerHostName": { + "type": "string" + } + } + }, "v1TaskQueueReachability": { "type": "object", "properties": { @@ -16104,6 +17326,18 @@ "type": "object", "description": "Response to a successful UnpauseWorkflowExecution request." }, + "v1UnsuccessfulOperationError": { + "type": "object", + "properties": { + "operationState": { + "type": "string", + "description": "See https://github.com/nexus-rpc/api/blob/main/SPEC.md#operationinfo." + }, + "failure": { + "$ref": "#/definitions/apinexusv1Failure" + } + } + }, "v1UpdateActivityOptionsResponse": { "type": "object", "properties": { @@ -16216,6 +17450,10 @@ } } }, + "v1UpdateWorkerBuildIdCompatibilityResponse": { + "type": "object", + "title": "[cleanup-wv-pre-release]" + }, "v1UpdateWorkerConfigResponse": { "type": "object", "properties": { @@ -16234,6 +17472,31 @@ } } }, + "v1UpdateWorkerVersioningRulesResponse": { + "type": "object", + "properties": { + "assignmentRules": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1TimestampedBuildIdAssignmentRule" + } + }, + "compatibleRedirectRules": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1TimestampedCompatibleBuildIdRedirectRule" + } + }, + "conflictToken": { + "type": "string", + "format": "byte", + "description": "This value can be passed back to UpdateWorkerVersioningRulesRequest to\nensure that the rules were not modified between the two updates, which\ncould lead to lost updates and other confusion." + } + }, + "title": "[cleanup-wv-pre-release]" + }, "v1UpdateWorkflowExecutionLifecycleStage": { "type": "string", "enum": [ @@ -16274,7 +17537,7 @@ "description": "Specifies client's intent to wait for Update results.\nNOTE: This field works together with API call timeout which is limited by\nserver timeout (maximum wait time). If server timeout is expired before\nuser specified timeout, API call returns even if specified stage is not reached.\nActual reached stage will be included in the response." }, "request": { - "$ref": "#/definitions/v1Request", + "$ref": "#/definitions/apiupdatev1Request", "description": "The request information that will be delivered all the way down to the\nWorkflow Execution." } } @@ -16296,6 +17559,14 @@ } } }, + "v1UpsertWorkflowSearchAttributesCommandAttributes": { + "type": "object", + "properties": { + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + } + } + }, "v1UpsertWorkflowSearchAttributesEventAttributes": { "type": "object", "properties": { @@ -16983,7 +18254,7 @@ "$ref": "#/definitions/v1ContinueAsNewInitiator" }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "Deprecated. If a workflow's retry policy would cause a new run to start when the current one\nhas failed, this field would be populated with that failure. Now (when supported by server\nand sdk) the final event will be `WORKFLOW_EXECUTION_FAILED` with `new_execution_run_id` set." }, "lastCompletionResult": { @@ -17058,7 +18329,7 @@ "type": "object", "properties": { "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "title": "Serialized result of workflow failure (ex: An exception thrown, or error returned)" }, "retryState": { @@ -17075,6 +18346,17 @@ } } }, + "v1WorkflowExecutionFilter": { + "type": "object", + "properties": { + "workflowId": { + "type": "string" + }, + "runId": { + "type": "string" + } + } + }, "v1WorkflowExecutionInfo": { "type": "object", "properties": { @@ -17339,7 +18621,7 @@ "$ref": "#/definitions/v1ContinueAsNewInitiator" }, "continuedFailure": { - "$ref": "#/definitions/v1Failure" + "$ref": "#/definitions/apifailurev1Failure" }, "lastCompletionResult": { "$ref": "#/definitions/v1Payloads" @@ -17524,7 +18806,7 @@ "description": "The event ID used to sequence the original request message." }, "acceptedRequest": { - "$ref": "#/definitions/v1Request", + "$ref": "#/definitions/apiupdatev1Request", "description": "The message payload of the original request message that initiated this\nupdate." } } @@ -17533,7 +18815,7 @@ "type": "object", "properties": { "request": { - "$ref": "#/definitions/v1Request", + "$ref": "#/definitions/apiupdatev1Request", "description": "The update request associated with this event." }, "origin": { @@ -17577,11 +18859,11 @@ "description": "The event ID used to sequence the original request message." }, "rejectedRequest": { - "$ref": "#/definitions/v1Request", + "$ref": "#/definitions/apiupdatev1Request", "description": "The message payload of the original request message that initiated this\nupdate." }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "description": "The cause of rejection." } } @@ -17706,6 +18988,28 @@ }, "title": "See https://docs.temporal.io/docs/concepts/queries/" }, + "v1WorkflowQueryResult": { + "type": "object", + "properties": { + "resultType": { + "$ref": "#/definitions/v1QueryResultType", + "title": "Did the query succeed or fail?" + }, + "answer": { + "$ref": "#/definitions/v1Payloads", + "description": "Set when the query succeeds with the results.\nMutually exclusive with `error_message` and `failure`." + }, + "errorMessage": { + "type": "string", + "description": "Mutually exclusive with `answer`. Set when the query fails.\nSee also the newer `failure` field." + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The full reason for this query failure. This field is newer than `error_message` and can be encoded by the SDK's\nfailure converter to support E2E encryption of messages and stack traces.\nMutually exclusive with `answer`. Set when the query fails." + } + }, + "title": "Answer to a `WorkflowQuery`" + }, "v1WorkflowRule": { "type": "object", "properties": { @@ -17913,7 +19217,7 @@ "$ref": "#/definitions/v1WorkflowTaskFailedCause" }, "failure": { - "$ref": "#/definitions/v1Failure", + "$ref": "#/definitions/apifailurev1Failure", "title": "The failure details" }, "identity": { @@ -18030,6 +19334,14 @@ } }, "title": "Represents the identifier used by a workflow author to define the workflow. Typically, the\nname of a function. This is sometimes referred to as the workflow's \"name\"" + }, + "v1WorkflowTypeFilter": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + } } } } diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 580d68a73..da70a0b6a 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -237,6 +237,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/cancel/{activityId}: + post: + tags: + - WorkflowService + description: |- + RequestCancelActivityExecution requests cancellation of an activity execution. + + Cancellation is cooperative: this call records the request, but the activity must detect and + acknowledge it for the activity to reach CANCELED status. The cancellation signal is + delivered via `cancel_requested` in the heartbeat response; SDKs surface this via + language-idiomatic mechanisms (context cancellation, exceptions, abort signals). + operationId: RequestCancelActivityExecution + 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/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/complete: post: tags: @@ -311,6 +353,68 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/describe/{activityId}: + get: + tags: + - WorkflowService + description: |- + DescribeActivityExecution returns information about an activity execution. + It can be used to: + - Get current activity info without waiting + - Long-poll for next state change and return new activity info + Response can optionally include activity input or outcome (if the activity has completed). + operationId: DescribeActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the activity has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that activity state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/activities/fail: post: tags: @@ -465,6 +569,43 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/outcome/{activityId}: + get: + tags: + - WorkflowService + description: |- + PollActivityExecution long-polls for an activity execution to complete and returns the + outcome (result or failure). + operationId: PollActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/activities/pause: post: tags: @@ -566,6 +707,90 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/start/{activityId}: + post: + tags: + - WorkflowService + description: |- + StartActivityExecution starts a new activity execution. + + Returns an `ActivityExecutionAlreadyStarted` 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 + description: |- + Identifier for this activity. Required. This identifier should be meaningful in the user's + own system. It must be unique among activities in the same namespace, subject to the rules + imposed by id_reuse_policy and id_conflict_policy. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/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/terminate/{activityId}: + 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. + operationId: TerminateActivityExecution + 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/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}/activities/unpause: post: tags: @@ -649,245 +874,21 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/activities/{activityId}: + /api/v1/namespaces/{namespace}/activity-count: get: tags: - WorkflowService - description: |- - DescribeActivityExecution returns information about an activity execution. - It can be used to: - - Get current activity info without waiting - - Long-poll for next state change and return new activity info - Response can optionally include activity input or outcome (if the activity has completed). - operationId: DescribeActivityExecution + description: CountActivityExecutions is a visibility API to count activity executions in a specific namespace. + operationId: CountActivityExecutions parameters: - name: namespace in: path required: true schema: type: string - - name: activityId - in: path - required: true - schema: - type: string - - name: runId + - name: query in: query - description: Activity run ID. If empty the request targets the latest run. - schema: - type: string - - name: includeInput - in: query - description: Include the input field in the response. - schema: - type: boolean - - name: includeOutcome - in: query - description: Include the outcome (result/failure) in the response if the activity has completed. - schema: - type: boolean - - name: longPollToken - in: query - description: |- - Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity - state changes from the state encoded in this token. If absent, return current state immediately. - If present, run_id must also be present. - Note that activity state may change multiple times between requests, therefore it is not - guaranteed that a client making a sequence of long-poll requests will see a complete - sequence of state changes. - schema: - type: string - format: bytes - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DescribeActivityExecutionResponse' - default: - description: Default error response - content: - application/json: - schema: - $ref: '#/components/schemas/Status' - post: - tags: - - WorkflowService - description: |- - StartActivityExecution starts a new activity execution. - - Returns an `ActivityExecutionAlreadyStarted` 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 - description: |- - Identifier for this activity. Required. This identifier should be meaningful in the user's - own system. It must be unique among activities in the same namespace, subject to the rules - imposed by id_reuse_policy and id_conflict_policy. - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/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/{activityId}/cancel: - post: - tags: - - WorkflowService - description: |- - RequestCancelActivityExecution requests cancellation of an activity execution. - - Cancellation is cooperative: this call records the request, but the activity must detect and - acknowledge it for the activity to reach CANCELED status. The cancellation signal is - delivered via `cancel_requested` in the heartbeat response; SDKs surface this via - language-idiomatic mechanisms (context cancellation, exceptions, abort signals). - operationId: RequestCancelActivityExecution - 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/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/{activityId}/outcome: - get: - tags: - - WorkflowService - description: |- - PollActivityExecution long-polls for an activity execution to complete and returns the - outcome (result or failure). - operationId: PollActivityExecution - parameters: - - name: namespace - in: path - required: true - schema: - type: string - - name: activityId - in: path - required: true - schema: - type: string - - name: runId - in: query - description: Activity run ID. If empty the request targets the latest run. - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/PollActivityExecutionResponse' - default: - description: Default error response - content: - application/json: - schema: - $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/activities/{activityId}/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. - operationId: TerminateActivityExecution - 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/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 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. + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. schema: type: string responses: @@ -4150,29 +4151,34 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/complete: + /namespaces/{namespace}/activities/cancel/{activityId}: post: tags: - WorkflowService description: |- - RespondActivityTaskCompleted is called by workers when they successfully complete an activity - task. + RequestCancelActivityExecution requests cancellation of an activity execution. - For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` 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: RespondActivityTaskCompleted + Cancellation is cooperative: this call records the request, but the activity must detect and + acknowledge it for the activity to reach CANCELED status. The cancellation signal is + delivered via `cancel_requested` in the heartbeat response; SDKs surface this via + language-idiomatic mechanisms (context cancellation, exceptions, abort signals). + operationId: RequestCancelActivityExecution 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/RespondActivityTaskCompletedRequest' + $ref: '#/components/schemas/RequestCancelActivityExecutionRequest' required: true responses: "200": @@ -4180,28 +4186,28 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RespondActivityTaskCompletedResponse' + $ref: '#/components/schemas/RequestCancelActivityExecutionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/complete-by-id: + /namespaces/{namespace}/activities/complete: post: tags: - WorkflowService description: |- - See `RespondActivityTaskCompleted`. This version allows clients to record completions by - namespace/workflow id/activity id instead of task token. + RespondActivityTaskCompleted is called by workers when they successfully complete an activity + task. - (-- api-linter: core::0136::prepositions=disabled - aip.dev/not-precedent: "By" is used to indicate request type. --) - operationId: RespondActivityTaskCompletedById + For workflow activities, this results in a new `ACTIVITY_TASK_COMPLETED` 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: RespondActivityTaskCompleted parameters: - name: namespace in: path - description: Namespace of the workflow which scheduled this activity required: true schema: type: string @@ -4209,7 +4215,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RespondActivityTaskCompletedByIdRequest' + $ref: '#/components/schemas/RespondActivityTaskCompletedRequest' required: true responses: "200": @@ -4217,27 +4223,28 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RespondActivityTaskCompletedByIdResponse' + $ref: '#/components/schemas/RespondActivityTaskCompletedResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/fail: + /namespaces/{namespace}/activities/complete-by-id: post: tags: - WorkflowService description: |- - RespondActivityTaskFailed is called by workers when processing an activity task fails. + See `RespondActivityTaskCompleted`. This version allows clients to record completions by + namespace/workflow id/activity id instead of task token. - This results in a new `ACTIVITY_TASK_FAILED` 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: RespondActivityTaskFailed + (-- api-linter: core::0136::prepositions=disabled + aip.dev/not-precedent: "By" is used to indicate request type. --) + operationId: RespondActivityTaskCompletedById parameters: - name: namespace in: path + description: Namespace of the workflow which scheduled this activity required: true schema: type: string @@ -4245,7 +4252,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RespondActivityTaskFailedRequest' + $ref: '#/components/schemas/RespondActivityTaskCompletedByIdRequest' required: true responses: "200": @@ -4253,20 +4260,118 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RespondActivityTaskFailedResponse' + $ref: '#/components/schemas/RespondActivityTaskCompletedByIdResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/fail-by-id: - post: + /namespaces/{namespace}/activities/describe/{activityId}: + get: tags: - WorkflowService description: |- - See `RecordActivityTaskFailed`. This version allows clients to record failures by - namespace/workflow id/activity id instead of task token. + DescribeActivityExecution returns information about an activity execution. + It can be used to: + - Get current activity info without waiting + - Long-poll for next state change and return new activity info + Response can optionally include activity input or outcome (if the activity has completed). + operationId: DescribeActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the activity has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that activity state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/fail: + post: + tags: + - WorkflowService + description: |- + RespondActivityTaskFailed is called by workers when processing an activity task fails. + + This results in a new `ACTIVITY_TASK_FAILED` 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: RespondActivityTaskFailed + parameters: + - name: namespace + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskFailedRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RespondActivityTaskFailedResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/fail-by-id: + post: + tags: + - WorkflowService + description: |- + See `RecordActivityTaskFailed`. This version allows clients to record failures by + namespace/workflow id/activity id instead of task token. (-- api-linter: core::0136::prepositions=disabled aip.dev/not-precedent: "By" is used to indicate request type. --) @@ -4378,6 +4483,43 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/outcome/{activityId}: + get: + tags: + - WorkflowService + description: |- + PollActivityExecution long-polls for an activity execution to complete and returns the + outcome (result or failure). + operationId: PollActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PollActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/activities/pause: post: tags: @@ -4479,151 +4621,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/unpause: - post: - tags: - - WorkflowService - description: |- - UnpauseActivity unpauses the execution of an activity specified by its ID or type. - If there are multiple pending activities of the provided type - all of them will be unpaused. - - If activity is not paused, this call will have no effect. - If the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag). - Once the activity is unpaused, all timeout timers will be regenerated. - - Flags: - 'jitter': the activity will be scheduled at a random time within the jitter duration. - 'reset_attempts': the number of attempts will be reset. - 'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset. - - Returns a `NotFound` error if there is no pending activity with the provided ID or type - This API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and - structured to work well for standalone activities. - operationId: UnpauseActivity - parameters: - - name: namespace - in: path - description: Namespace of the workflow which scheduled this activity. - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UnpauseActivityRequest' - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UnpauseActivityResponse' - default: - description: Default error response - content: - application/json: - schema: - $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/update-options: - post: - tags: - - WorkflowService - description: |- - UpdateActivityOptions is called by the client to update the options of an activity by its ID or type. - If there are multiple pending activities of the provided type - all of them will be updated. - This API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and - structured to work well for standalone activities. - operationId: UpdateActivityOptions - parameters: - - name: namespace - in: path - description: Namespace of the workflow which scheduled this activity - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateActivityOptionsRequest' - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateActivityOptionsResponse' - default: - description: Default error response - content: - application/json: - schema: - $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/{activityId}: - get: - tags: - - WorkflowService - description: |- - DescribeActivityExecution returns information about an activity execution. - It can be used to: - - Get current activity info without waiting - - Long-poll for next state change and return new activity info - Response can optionally include activity input or outcome (if the activity has completed). - operationId: DescribeActivityExecution - parameters: - - name: namespace - in: path - required: true - schema: - type: string - - name: activityId - in: path - required: true - schema: - type: string - - name: runId - in: query - description: Activity run ID. If empty the request targets the latest run. - schema: - type: string - - name: includeInput - in: query - description: Include the input field in the response. - schema: - type: boolean - - name: includeOutcome - in: query - description: Include the outcome (result/failure) in the response if the activity has completed. - schema: - type: boolean - - name: longPollToken - in: query - description: |- - Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity - state changes from the state encoded in this token. If absent, return current state immediately. - If present, run_id must also be present. - Note that activity state may change multiple times between requests, therefore it is not - guaranteed that a client making a sequence of long-poll requests will see a complete - sequence of state changes. - schema: - type: string - format: bytes - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DescribeActivityExecutionResponse' - default: - description: Default error response - content: - application/json: - schema: - $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/start/{activityId}: post: tags: - WorkflowService @@ -4667,18 +4665,16 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/{activityId}/cancel: + /namespaces/{namespace}/activities/terminate/{activityId}: post: tags: - WorkflowService description: |- - RequestCancelActivityExecution requests cancellation of an activity execution. + TerminateActivityExecution terminates an existing activity execution immediately. - Cancellation is cooperative: this call records the request, but the activity must detect and - acknowledge it for the activity to reach CANCELED status. The cancellation signal is - delivered via `cancel_requested` in the heartbeat response; SDKs surface this via - language-idiomatic mechanisms (context cancellation, exceptions, abort signals). - operationId: RequestCancelActivityExecution + Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a + running attempt. + operationId: TerminateActivityExecution parameters: - name: namespace in: path @@ -4694,7 +4690,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RequestCancelActivityExecutionRequest' + $ref: '#/components/schemas/TerminateActivityExecutionRequest' required: true responses: "200": @@ -4702,68 +4698,74 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/RequestCancelActivityExecutionResponse' + $ref: '#/components/schemas/TerminateActivityExecutionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/{activityId}/outcome: - get: + /namespaces/{namespace}/activities/unpause: + post: tags: - WorkflowService description: |- - PollActivityExecution long-polls for an activity execution to complete and returns the - outcome (result or failure). - operationId: PollActivityExecution + UnpauseActivity unpauses the execution of an activity specified by its ID or type. + If there are multiple pending activities of the provided type - all of them will be unpaused. + + If activity is not paused, this call will have no effect. + If the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag). + Once the activity is unpaused, all timeout timers will be regenerated. + + Flags: + 'jitter': the activity will be scheduled at a random time within the jitter duration. + 'reset_attempts': the number of attempts will be reset. + 'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset. + + Returns a `NotFound` error if there is no pending activity with the provided ID or type + This API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and + structured to work well for standalone activities. + operationId: UnpauseActivity parameters: - name: namespace in: path + description: Namespace of the workflow which scheduled this activity. required: true schema: type: string - - name: activityId - in: path - required: true - schema: - type: string - - name: runId - in: query - description: Activity run ID. If empty the request targets the latest run. - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UnpauseActivityRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/PollActivityExecutionResponse' + $ref: '#/components/schemas/UnpauseActivityResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/activities/{activityId}/terminate: + /namespaces/{namespace}/activities/update-options: 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. - operationId: TerminateActivityExecution + UpdateActivityOptions is called by the client to update the options of an activity by its ID or type. + If there are multiple pending activities of the provided type - all of them will be updated. + This API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and + structured to work well for standalone activities. + operationId: UpdateActivityOptions parameters: - name: namespace in: path - required: true - schema: - type: string - - name: activityId - in: path + description: Namespace of the workflow which scheduled this activity required: true schema: type: string @@ -4771,7 +4773,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TerminateActivityExecutionRequest' + $ref: '#/components/schemas/UpdateActivityOptionsRequest' required: true responses: "200": @@ -4779,7 +4781,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TerminateActivityExecutionResponse' + $ref: '#/components/schemas/UpdateActivityOptionsResponse' default: description: Default error response content: diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 8b0eb2ce6..01605b4a2 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -1327,10 +1327,10 @@ service WorkflowService { // unless permitted by the specified ID conflict policy. rpc StartActivityExecution (StartActivityExecutionRequest) returns (StartActivityExecutionResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/activities/{activity_id}" + post: "/namespaces/{namespace}/activities/start/{activity_id}" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/activities/{activity_id}" + post: "/api/v1/namespaces/{namespace}/activities/start/{activity_id}" body: "*" } }; @@ -1343,9 +1343,9 @@ service WorkflowService { // Response can optionally include activity input or outcome (if the activity has completed). rpc DescribeActivityExecution (DescribeActivityExecutionRequest) returns (DescribeActivityExecutionResponse) { option (google.api.http) = { - get: "/namespaces/{namespace}/activities/{activity_id}" + get: "/namespaces/{namespace}/activities/describe/{activity_id}" additional_bindings { - get: "/api/v1/namespaces/{namespace}/activities/{activity_id}" + get: "/api/v1/namespaces/{namespace}/activities/describe/{activity_id}" } }; } @@ -1354,9 +1354,9 @@ service WorkflowService { // outcome (result or failure). rpc PollActivityExecution (PollActivityExecutionRequest) returns (PollActivityExecutionResponse) { option (google.api.http) = { - get: "/namespaces/{namespace}/activities/{activity_id}/outcome" + get: "/namespaces/{namespace}/activities/outcome/{activity_id}" additional_bindings { - get: "/api/v1/namespaces/{namespace}/activities/{activity_id}/outcome" + get: "/api/v1/namespaces/{namespace}/activities/outcome/{activity_id}" } }; } @@ -1389,10 +1389,10 @@ service WorkflowService { // language-idiomatic mechanisms (context cancellation, exceptions, abort signals). rpc RequestCancelActivityExecution (RequestCancelActivityExecutionRequest) returns (RequestCancelActivityExecutionResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/activities/{activity_id}/cancel" + post: "/namespaces/{namespace}/activities/cancel/{activity_id}" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/activities/{activity_id}/cancel" + post: "/api/v1/namespaces/{namespace}/activities/cancel/{activity_id}" body: "*" } }; @@ -1404,10 +1404,10 @@ service WorkflowService { // running attempt. rpc TerminateActivityExecution (TerminateActivityExecutionRequest) returns (TerminateActivityExecutionResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/activities/{activity_id}/terminate" + post: "/namespaces/{namespace}/activities/terminate/{activity_id}" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/activities/{activity_id}/terminate" + post: "/api/v1/namespaces/{namespace}/activities/terminate/{activity_id}" body: "*" } }; diff --git a/test-http-api-ambiguity b/test-http-api-ambiguity new file mode 100755 index 000000000..4ba4ac6de --- /dev/null +++ b/test-http-api-ambiguity @@ -0,0 +1,115 @@ +#!/usr/bin/env -S uv run --script +# +# /// script +# requires-python = ">=3.12" +# dependencies = ["pytest", "networkx"] +# /// +# +# Checks that every possible URL matches at most one HTTP API handler. +# Parses openapi/openapiv2.json and reports any pair of routes (same HTTP +# method) where a concrete URL could match both patterns. + +import json +import sys +from collections import defaultdict +from itertools import combinations +from pathlib import Path + +import networkx as nx +import pytest + +SPEC_PATH = Path(__file__).parent / "openapi" / "openapiv2.json" +HTTP_METHODS = {"get", "put", "post", "delete", "patch"} + +# Known ambiguities that have not yet been resolved. +KNOWN_CONFLICTS = { + ("post", "/namespaces/{namespace}/workflows/{workflowId}"), + ("post", "/api/v1/namespaces/{namespace}/workflows/{workflowId}"), +} + + +def test_no_ambiguous_routes() -> None: + g = find_conflicts(load_routes()) + unknown = nx.Graph( + (u, v) + for u, v in g.edges() + if u[:2] not in KNOWN_CONFLICTS and v[:2] not in KNOWN_CONFLICTS + ) + if unknown.number_of_edges(): + pytest.fail( + f"Found {len(list(nx.connected_components(unknown)))} conflict group(s):\n\n" + + format_conflicts(unknown) + ) + + +# --- helpers --- + + +def load_routes() -> defaultdict[str, list[tuple[str, str]]]: + spec = json.loads(SPEC_PATH.read_text()) + routes: defaultdict[str, list[tuple[str, str]]] = defaultdict(list) + for path, methods in spec["paths"].items(): + segments = path.strip("/").split("/") + validate_segments(path, segments) + for method in methods: + if method not in HTTP_METHODS: + continue + op_id = methods[method].get("operationId", "?") + routes[method].append((path, op_id)) + return routes + + +def find_conflicts(routes: defaultdict[str, list[tuple[str, str]]]) -> nx.Graph: + g: nx.Graph = nx.Graph() + for method, entries in sorted(routes.items()): + for (path_a, op_a), (path_b, op_b) in combinations(entries, 2): + if ambiguous(path_a, path_b): + g.add_edge((method, path_a, op_a), (method, path_b, op_b)) + return g + + +def format_conflicts(g: nx.Graph) -> str: + groups: list[str] = [] + for comp in nx.connected_components(g): + hub = max(comp, key=lambda n: g.degree(n)) # type: ignore[type-var] + others = sorted(comp - {hub}) + method, path, op = hub + lines = f"{method.upper()} {path} ({op}) ambiguous with:" + for _, p, o in others: + lines += f"\n {p} ({o})" + groups.append(lines) + return "\n\n".join(sorted(groups)) + + +def ambiguous(a: str, b: str) -> bool: + sa = a.strip("/").split("/") + sb = b.strip("/").split("/") + if len(sa) != len(sb): + return False + return all(x == y or is_variable(x) or is_variable(y) for x, y in zip(sa, sb)) + + +def is_variable(segment: str) -> bool: + return segment.startswith("{") and segment.endswith("}") + + +def validate_segments(path: str, segments: list[str]) -> None: + """Fail loudly if any segment uses multi-segment wildcards.""" + for seg in segments: + if seg in ("*", "**"): + raise ValueError( + f"Unsupported wildcard segment '{seg}' in {path}; extend this check." + ) + if seg.startswith("{") and "=" in seg: + raise ValueError( + f"Unsupported pattern variable '{seg}' in {path}; extend this check." + ) + + +if __name__ == "__main__": + try: + test_no_ambiguous_routes() + except pytest.fail.Exception as e: + print(f"FAILED: {e}", file=sys.stderr) + sys.exit(1) + print("PASSED: test_no_ambiguous_routes")