Skip to content

Wire request_id through CallbackInfo for linking #851

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

Merged
chrsmith merged 4 commits into from
Aug 19, 2026
Merged

Wire request_id through CallbackInfo for linking #851

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e5678ad
Wire request_id through CallbackInfo for linking
chrsmith Aug 17, 2026
7f4fe7f
Rename request_id to callback_id
chrsmith Aug 17, 2026
54d5276
Address PR feedback; Worker callbacks scope
chrsmith Aug 18, 2026
52984c1
Rename to EXECUTION_TYPE_NEXUS_OPERATION
chrsmith Aug 18, 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
124 changes: 71 additions & 53 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11107,21 +11107,6 @@
},
"description": "A link to a standalone Nexus operation."
},
"LinkNexusOperationCallback": {
"type": "object",
"properties": {
"operationId": {
"type": "string"
},
"runId": {
"type": "string"
},
"requestId": {
"type": "string"
}
},
"description": "A link to a worker callback attached to a Nexus operation within the same namespace. e.g. the completion handler attached\nto a standalone Nexus operation, not the source Nexus operation itself. A standalone Nexus operation can have multiple\ncallbacks attached to them, and will be differentiated by the server-generated request_id used when the callback was invoked."
},
"LinkWorkflow": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -11549,7 +11534,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 @@ -12583,7 +12568,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 @@ -12745,7 +12730,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Completion callbacks to be invoked once the Nexus operation reaches a terminal state."
},
Expand Down Expand Up @@ -12836,7 +12821,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 @@ -13380,7 +13365,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 @@ -13480,7 +13465,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 @@ -13515,6 +13500,10 @@
"type": "string",
"description": "If the state is BLOCKED, blocked reason provides additional information."
},
"requestId": {
"type": "string",
"description": "The Request ID used when the Callback was delivered. Used as an idempotency key in case multiple deliveries\nare made. Typically, this matches the incomming request ID sent to Temporal which added the Callback to an\nexecution."
},
"success": {
"type": "object",
"properties": {},
Expand Down Expand Up @@ -13589,7 +13578,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 @@ -13626,6 +13615,19 @@
"blockedReason": {
"type": "string",
"description": "If the state is BLOCKED, blocked reason provides additional information."
},
"requestId": {
"type": "string",
"description": "The Request ID used when the Callback was delivered. Used as an idempotency key in case multiple deliveries\nare made. Typically, this matches the incomming request ID sent to Temporal which added the Callback to an\nexecution."
},
"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."
}
},
"description": "CallbackInfo contains the state of an attached workflow callback."
Expand Down Expand Up @@ -13659,6 +13661,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 @@ -14737,29 +14762,6 @@
},
"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": {
"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."
},
"v1CallbackState": {
"type": "string",
"enum": [
Expand Down Expand Up @@ -16123,17 +16125,19 @@
"type": "string"
}
},
"description": "Identifies a specific execution within a namespace. This is used for standalone activities\nexecutions in batch jobs currently."
"description": "Identifies a specific execution within a namespace."
},
"v1ExecutionType": {
"type": "string",
"enum": [
"EXECUTION_TYPE_UNSPECIFIED",
"EXECUTION_TYPE_WORKFLOW",
"EXECUTION_TYPE_ACTIVITY"
"EXECUTION_TYPE_ACTIVITY",
"EXECUTION_TYPE_NEXUS",
"EXECUTION_TYPE_UPDATE_WORKFLOW"
],
"default": "EXECUTION_TYPE_UNSPECIFIED",
"description": " - EXECUTION_TYPE_WORKFLOW: A workflow execution archetype.\n - EXECUTION_TYPE_ACTIVITY: An activity execution archetype. This is reserved for standalone activities."
"description": " - EXECUTION_TYPE_WORKFLOW: A workflow execution archetype.\n - EXECUTION_TYPE_ACTIVITY: An activity execution archetype. This is reserved for standalone activities.\n - EXECUTION_TYPE_NEXUS: A Nexus operation execution archetype. This is reserved for standalone Nexus operations.\n - EXECUTION_TYPE_UPDATE_WORKFLOW: An update workflow execution archtype."
},
"v1ExternalWorkflowExecutionCancelRequestedEventAttributes": {
"type": "object",
Expand Down Expand Up @@ -16866,12 +16870,26 @@
"workflow": {
"$ref": "#/definitions/LinkWorkflow"
},
"nexusOperationCallback": {
"$ref": "#/definitions/LinkNexusOperationCallback"
"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": {
"execution": {
"$ref": "#/definitions/v1Execution",
"description": "Source execution the callback was attached to."
},
"requestId": {
"type": "string",
"description": "Request ID used for the callback's delivery."
}
},
"description": "A link to a worker callback attached to an execution. An execution (e.g. workflow or standalone Nexus\noperation) can have multiple callbacks attached to them, and will be differentiated by the request_id used when the callback\nis invoked."
},
"v1ListActivityExecutionsResponse": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -18872,7 +18890,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 @@ -21777,7 +21795,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 @@ -21993,7 +22011,7 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
"$ref": "#/definitions/commonV1Callback"
},
"description": "Completion callbacks attached when this workflow was started."
},
Expand Down
43 changes: 25 additions & 18 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10905,6 +10905,12 @@ components:
blockedReason:
type: string
description: If the state is BLOCKED, blocked reason provides additional information.
requestId:
type: string
description: |-
The Request ID used when the Callback was delivered. Used as an idempotency key in case multiple deliveries
are made. Typically, this matches the incomming request ID sent to Temporal which added the Callback to an
execution.
failure:
allOf:
- $ref: '#/components/schemas/Failure'
Expand Down Expand Up @@ -12431,15 +12437,15 @@ components:
- EXECUTION_TYPE_UNSPECIFIED
- EXECUTION_TYPE_WORKFLOW
- EXECUTION_TYPE_ACTIVITY
- EXECUTION_TYPE_NEXUS
- EXECUTION_TYPE_UPDATE_WORKFLOW
type: string
format: enum
businessId:
type: string
runId:
type: string
description: |-
Identifies a specific execution within a namespace. This is used for standalone activities
executions in batch jobs currently.
description: Identifies a specific execution within a namespace.
ExternalWorkflowExecutionCancelRequestedEventAttributes:
type: object
properties:
Expand Down Expand Up @@ -13146,8 +13152,8 @@ components:
$ref: '#/components/schemas/Link_NexusOperation'
workflow:
$ref: '#/components/schemas/Link_Workflow'
nexusOperationCallback:
$ref: '#/components/schemas/Link_NexusOperationCallback'
callback:
$ref: '#/components/schemas/Link_Callback'
description: |-
Link can be associated with history events. It might contain information about an external entity
related to the history event. For example, workflow A makes a Nexus call that starts workflow B:
Expand All @@ -13172,6 +13178,20 @@ components:
A link to a built-in batch job.
Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).
This link can be put on workflow history events generated by actions taken by a batch job.
Link_Callback:
type: object
properties:
execution:
allOf:
- $ref: '#/components/schemas/Execution'
description: Source execution the callback was attached to.
requestId:
type: string
description: Request ID used for the callback's delivery.
description: |-
A link to a worker callback attached to an execution. An execution (e.g. workflow or standalone Nexus
operation) can have multiple callbacks attached to them, and will be differentiated by the request_id used when the callback
is invoked.
Link_NexusOperation:
type: object
properties:
Expand All @@ -13182,19 +13202,6 @@ components:
runId:
type: string
description: A link to a standalone Nexus operation.
Link_NexusOperationCallback:
type: object
properties:
operationId:
type: string
runId:
type: string
requestId:
type: string
description: |-
A link to a worker callback attached to a Nexus operation within the same namespace. e.g. the completion handler attached
to a standalone Nexus operation, not the source Nexus operation itself. A standalone Nexus operation can have multiple
callbacks attached to them, and will be differentiated by the server-generated request_id used when the callback was invoked.
Link_Workflow:
type: object
properties:
Expand Down
9 changes: 7 additions & 2 deletions temporal/api/callback/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,17 @@ message CallbackInfo {
// If the state is BLOCKED, blocked reason provides additional information.
string blocked_reason = 8;

// The Request ID used when the Callback was delivered. Used as an idempotency key in case multiple deliveries

@bergundy bergundy Aug 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would decouple the user provided request ID from the one the system generates. The start request is not the same as the callback delivery request and those should have different IDs. I would be confused if I saw the same request ID provided in a log for different purposes.

@bergundy bergundy Aug 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am concerned that this will be confused with the request ID of the start request used to attach this callback. Document the semantics as we did here:

api/temporal/api/nexus/v1/message.proto

Lines 308 to 311 in 7868510

// Server-generated request ID used as an idempotency token when submitting start requests to
// the handler. Distinct from the request_id in StartNexusOperationRequest, which is the
// caller-side idempotency key for the StartNexusOperation RPC itself.
string request_id = 21;

@chrsmith chrsmith Aug 17, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for linking to the comment, I agree that's exactly how we'd want to define it.

// are made. Typically, this matches the incomming request ID sent to Temporal which added the Callback to an
// execution.
string request_id = 9;

// Result of the callback's execution, only set when the callback reaches a terminal state.
oneof result {
// The callback completed successfully. (Which may include delivering a "failed" result successfully.)
google.protobuf.Empty success = 9;
google.protobuf.Empty success = 10;
// The failure if the callback was not able to complete successfully. e.g. timed out, received an
// unretriable error, etc.
temporal.api.failure.v1.Failure failure = 10;
temporal.api.failure.v1.Failure failure = 11;
}
}
20 changes: 10 additions & 10 deletions temporal/api/common/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,7 @@ message WorkflowExecution {
string run_id = 2;
}

// Identifies a specific execution within a namespace. This is used for standalone activities
// executions in batch jobs currently.
// Identifies a specific execution within a namespace.
message Execution {
temporal.api.enums.v1.ExecutionType type = 1;
string business_id = 2;
Expand Down Expand Up @@ -304,13 +303,14 @@ message Link {
string reason = 4;
}

// A link to a worker callback attached to a Nexus operation within the same namespace. e.g. the completion handler attached
// to a standalone Nexus operation, not the source Nexus operation itself. A standalone Nexus operation can have multiple
// callbacks attached to them, and will be differentiated by the server-generated request_id used when the callback was invoked.
message NexusOperationCallback {
string operation_id = 1;
string run_id = 2;
string request_id = 3;
// A link to a worker callback attached to an execution. An execution (e.g. workflow or standalone Nexus
// operation) can have multiple callbacks attached to them, and will be differentiated by the request_id used when the callback
// is invoked.
message Callback {
// Source execution the callback was attached to.
Execution execution = 1;
// Request ID used for the callback's delivery.
string request_id = 2;

@VegetarianOrc VegetarianOrc Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should consider creating a "callback ID" as fully supported thing. The ambiguity where the request ID can be shared across multiple callbacks feels a little awkward.

@chrsmith chrsmith Aug 17, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strong +1 to this. We just need a way to uniquely identify a worker callback within the scope of an execution, and having an entirely server-side generated ID removes any potential confusion.

Moreover, having it be an entirely Temporal-managed CallbackInfo::callback_id and not a user-editable Callback::id simplifies things even more.

@bergundy bergundy Aug 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no user-editable callback::id. I'd be more than okay using the request ID as the callback ID since it is a unique identifier as long as we document it.

}

oneof variant {
Expand All @@ -319,7 +319,7 @@ message Link {
Activity activity = 3;
NexusOperation nexus_operation = 4;
Workflow workflow = 5;
NexusOperationCallback nexus_operation_callback = 6;
Callback callback = 6;
}
}

Expand Down
Loading
Loading