Skip to content

API surface area for worker callbacks #836

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Draft
chrsmith wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

API surface area for worker callbacks #836

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1af88d7
API surface area for worker callbacks
chrsmith Jul 20, 2026
c074ae0
Expose CallbackExecutionInfo from DescribeNexusOperationExecutionResp…
chrsmith Jul 21, 2026
f6b3d1c
Add new Callback variant of Link
chrsmith Jul 22, 2026
c176d77
Address PR feedback
chrsmith Jul 24, 2026
7278236
Apply suggestions from code review
chrsmith Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 140 additions & 39 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10757,6 +10757,20 @@
}
}
},
"CallbackNexusOperationCompletion": {
"type": "object",
"properties": {
"operationId": {
"type": "string"
},
"runId": {
"type": "string"
},
"requestId": {
"type": "string"
}
}
},
"ComputeStatusProviderValidationStatus": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -10834,20 +10848,6 @@
},
"description": "Target an external server by URL.\nAt a later point, this will support providing credentials, in the meantime, an http.RoundTripper can be injected\ninto the server to modify the request."
},
"EndpointTargetWorker": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"description": "Namespace to route requests to."
},
"taskQueue": {
"type": "string",
"description": "Nexus task queue to route requests to."
}
},
"description": "Target a worker polling on a Nexus task queue in a specific namespace."
},
"EventGroupMarkerInboundEvent": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -11290,7 +11290,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Completion callbacks attached to the running workflow update."
}
Expand Down Expand Up @@ -12316,7 +12316,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Callbacks to be called by the server when this activity reaches a terminal state.\nCallback addresses must be whitelisted in the server's dynamic configuration."
},
Expand Down Expand Up @@ -12469,6 +12469,14 @@
"userMetadata": {
"$ref": "#/definitions/v1UserMetadata",
"description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the operation."
},
"completionCallbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/commonV1Callback"
},
"description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state."
}
}
},
Expand Down Expand Up @@ -12549,7 +12557,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Callbacks to be called by the server when this workflow reaches a terminal state.\nIf the workflow continues-as-new, these callbacks will be carried over to the new execution.\nCallback addresses must be whitelisted in the server's dynamic configuration."
},
Expand Down Expand Up @@ -13093,7 +13101,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Callbacks to be called by the server when this update reaches a terminal state."
},
Expand Down Expand Up @@ -13193,7 +13201,7 @@
"type": "object",
"properties": {
"callback": {
"$ref": "#/definitions/v1Callback",
"$ref": "#/definitions/commonV1Callback",
"description": "Information on how this callback should be invoked (e.g. its URL and type)."
},
"registrationTime": {
Expand Down Expand Up @@ -13253,7 +13261,7 @@
"type": "object",
"properties": {
"callback": {
"$ref": "#/definitions/v1Callback",
"$ref": "#/definitions/commonV1Callback",
"description": "Information on how this callback should be invoked (e.g. its URL and type)."
},
"trigger": {
Expand Down Expand Up @@ -13323,6 +13331,29 @@
},
"description": "When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and\nthere is already an existing running workflow, OnConflictOptions defines actions to be taken on\nthe existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent\nhistory event in the running workflow with the changes requested in this object."
},
"commonV1Callback": {
"type": "object",
"properties": {
"nexus": {
"$ref": "#/definitions/CallbackNexus"
},
"internal": {
"$ref": "#/definitions/CallbackInternal"
},
"worker": {
"$ref": "#/definitions/v1CallbackWorker"
},
"links": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Link"
},
"description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback."
}
},
"description": "Callback to attach to various events in the system, e.g. workflow run completion."
},
"protobufAny": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -14397,25 +14428,34 @@
},
"description": "CalendarSpec describes an event specification relative to the calendar,\nsimilar to a traditional cron specification, but with labeled fields. Each\nfield can be one of:\n *: matches always\n x: matches when the field equals x\n x/y : matches when the field equals x+n*y where n is an integer\n x-z: matches when the field is between x and z inclusive\n w,x,y,...: matches when the field is one of the listed values\nEach x, y, z, ... is either a decimal integer, or a month or day of week name\nor abbreviation (in the appropriate fields).\nA timestamp matches if all fields match.\nNote that fields have different default values, for convenience.\nNote that the special case that some cron implementations have for treating\nday_of_month and day_of_week as \"or\" instead of \"and\" when both are set is\nnot implemented.\nday_of_week can accept 0 or 7 as Sunday\nCalendarSpec gets compiled into StructuredCalendarSpec, which is what will be\nreturned if you describe the schedule."
},
"v1Callback": {
"v1CallbackExecutionInfo": {
"type": "object",
"properties": {
"nexus": {
"$ref": "#/definitions/CallbackNexus"
"callbackId": {
"type": "string",
"description": "Identifier of the callback's execution. Unique within the containing namespace."
},
"internal": {
"$ref": "#/definitions/CallbackInternal"
"info": {
"$ref": "#/definitions/apiCallbackV1CallbackInfo"
},
"links": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Link"
},
"description": "Links associated with the callback. It can be used to link to underlying resources of the\ncallback."
"outcome": {
"$ref": "#/definitions/v1CallbackExecutionOutcome"
}
},
"description": "Callback to attach to various events in the system, e.g. workflow run completion."
}
},
"v1CallbackExecutionOutcome": {
"type": "object",
"properties": {
"success": {
"type": "object",
"properties": {},
"title": "The callback completed successfully. (Which may include delivering a \"failed\" result successfully.)"
},
"failure": {
"$ref": "#/definitions/v1Failure",
"description": "The failure if the callback was not able to complete successfully. e.g. timed out, received an\nunretriable error, etc."
}
}
},
"v1CallbackState": {
"type": "string",
Expand All @@ -14429,7 +14469,31 @@
"CALLBACK_STATE_BLOCKED"
],
"default": "CALLBACK_STATE_UNSPECIFIED",
"description": "State of a callback.\n\n - CALLBACK_STATE_UNSPECIFIED: Default value, unspecified state.\n - CALLBACK_STATE_STANDBY: Callback is standing by, waiting to be triggered.\n - CALLBACK_STATE_SCHEDULED: Callback is in the queue waiting to be executed or is currently executing.\n - CALLBACK_STATE_BACKING_OFF: Callback has failed with a retryable error and is backing off before the next attempt.\n - CALLBACK_STATE_FAILED: Callback has failed.\n - CALLBACK_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_STATE_BLOCKED: Callback is blocked (eg: by circuit breaker)."
"description": "State of a callback.\n\n - CALLBACK_STATE_UNSPECIFIED: Default value, unspecified state.\n - CALLBACK_STATE_STANDBY: Callback is standing by, waiting to be triggered.\n - CALLBACK_STATE_SCHEDULED: Callback is in the queue waiting to be executed or is currently executing.\n - CALLBACK_STATE_BACKING_OFF: Callback has failed with a retryable error and is backing off before the next attempt.\n - CALLBACK_STATE_FAILED: Callback has failed.\n - CALLBACK_STATE_SUCCEEDED: Callback has succeeded.\n - CALLBACK_STATE_BLOCKED: Callback is blocked, e.g. by circuit breaker."
},
"v1CallbackWorker": {
"type": "object",
"properties": {
"taskQueueName": {
"type": "string",
"description": "Nexus task queue the Temporal worker is listening on.\n\nNOTE: This is not a temporal.api.taskqueue.v1.TaskQueue to avoid a circular dependency."
},
"service": {
"type": "string",
"description": "Target Nexus service, e.g. \"HTTPAdaptor\"."
},
"operation": {
"type": "string",
"description": "Target operation, e.g. \"DeliverAsWebhook\"."
},
"sourceContext": {
"$ref": "#/definitions/v1Payload",
"description": "There is a relatively small maximum size the source context can be, e.g. 32KiB.",
"title": "Arbitrary user-supplied data from the source operation's callsite. (As applicable, not all operations\nsupport attaching context data.)"
}
},
"description": "The targeted Nexus service must be registered within the same namespace as the source operation\nthe callback is attached to. (While Nexus allows for cross-namespace operations, worker callbacks\nare purely \"caller-side\".)\n\nWorker callbacks are only supported for certain types of operations, e.g. standalone Nexus operations.\nAttempting to attach a Worker callback for an unsupported operation will result in an INVALID_ARGUMENT\nerror from the server.",
"title": "Worker callbacks are requests to invoke a specific shape of Nexus operation on a Temporal worker.\nThe specified Nexus operation must have the following:\n- Input: temporal.api.notificationservice.v1.OnCompleteRequest\n- Output: temporal.api.notificationservice.v1.OnCompleteResponse"
},
"v1CancelExternalWorkflowExecutionFailedCause": {
"type": "string",
Expand Down Expand Up @@ -15354,6 +15418,14 @@
"type": "string",
"format": "byte",
"description": "Token for follow-on long-poll requests. Absent only if the operation is complete."
},
"completionCallbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1CallbackExecutionInfo"
},
"description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state.\nThey will remain in the CALLBACK_STATE_STANDBY state until the Nexus operation is finished."
}
}
},
Expand Down Expand Up @@ -15591,14 +15663,28 @@
"type": "object",
"properties": {
"worker": {
"$ref": "#/definitions/EndpointTargetWorker"
"$ref": "#/definitions/v1EndpointTargetWorker"
},
"external": {
"$ref": "#/definitions/EndpointTargetExternal"
}
},
"description": "Target to route requests to."
},
"v1EndpointTargetWorker": {
"type": "object",
"properties": {
"namespace": {
"type": "string",
"description": "Namespace to route requests to."
},
"taskQueue": {
"type": "string",
"description": "Nexus task queue to route requests to."
}
},
"description": "Target a worker polling on a Nexus task queue in a specific namespace."
},
"v1EventGroupMarker": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -16427,10 +16513,25 @@
},
"workflow": {
"$ref": "#/definitions/LinkWorkflow"
},
"callback": {
"$ref": "#/definitions/v1LinkCallback"
}
},
"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."
},
"v1LinkCallback": {
"type": "object",
"properties": {
"callbackId": {
"type": "string"
},
"nexusOperationCompletion": {
"$ref": "#/definitions/CallbackNexusOperationCompletion"
}
},
"description": "A link to a callback or completion handler for an operation. e.g. not a link to a standalone Nexus operation,\nbut the callback that was executed once that operation finished."
},
"v1ListActivityExecutionsResponse": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -18410,7 +18511,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Callbacks to be called by the server when this update reaches a terminal state."
},
Expand Down Expand Up @@ -21250,7 +21351,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Completion callbacks attached to the running workflow execution."
},
Expand Down Expand Up @@ -21466,7 +21567,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Completion callbacks attached when this workflow was started."
},
Expand Down
Loading
Loading