Merge initial protos for priority (#561)

**What changed?**
Add initial protos for priority, enough to attach simple priority
metadata to workflows and activities.

See #513 for the full future plans, only the first field (priority_key)
is included so far.

**Why?**
Control task ordering.

**Server PR**
Implementation on `priority` branch:
temporalio/temporal@main...priority

---------

Co-authored-by: Spencer Judge <[email protected]>
Co-authored-by: Yuri <[email protected]>
Co-authored-by: Rodrigo Zhou <[email protected]>
Co-authored-by: Carly de Frondeville <[email protected]>
Co-authored-by: Spencer Judge <[email protected]>

Author: 5 people

Makefile

@@ -1,4 +1,4 @@
-SHELL=/bin/bash -o pipefail
+SHELL=bash -o pipefail
 
 $(VERBOSE).SILENT:
 ############################# Main targets #############################

openapi/openapiv2.json

@@ -7152,6 +7152,10 @@
         "versioningOverride": {
           "$ref": "#/definitions/v1VersioningOverride",
           "description": "If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.\nTo unset the override after the workflow is running, use UpdateWorkflowExecutionOptions."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       }
     },
@@ -7344,6 +7348,10 @@
         "onConflictOptions": {
           "$ref": "#/definitions/v1OnConflictOptions",
           "description": "Defines actions to be done to the existing running workflow when the conflict policy\nWORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING is used. If not set (ie., nil value) or set to a\nempty object (ie., all options with default value), it won't do anything to the existing\nrunning workflow. If set, it will add a history event to the running workflow."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       }
     },
@@ -7992,6 +8000,10 @@
         "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."
         }
       }
     },
@@ -10642,6 +10654,10 @@
         "versioningOverride": {
           "$ref": "#/definitions/v1VersioningOverride",
           "description": "If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.\nTo unset the override after the workflow is running, use UpdateWorkflowExecutionOptions."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       },
       "description": "NewWorkflowExecutionInfo is a shared message that encapsulates all the\nrequired arguments to starting a workflow in different contexts."
@@ -11057,6 +11073,10 @@
         "lastWorkerDeploymentVersion": {
           "type": "string",
           "description": "The Worker Deployment Version this activity was dispatched to most recently."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       }
     },
@@ -11285,6 +11305,10 @@
         "pollerScalingDecision": {
           "$ref": "#/definitions/v1PollerScalingDecision",
           "description": "Server-advised information the SDK may use to adjust its poller count."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       }
     },
@@ -11440,6 +11464,17 @@
       },
       "description": "Attached to task responses to give hints to the SDK about how it may adjust its number of\npollers."
     },
+    "v1Priority": {
+      "type": "object",
+      "properties": {
+        "priorityKey": {
+          "type": "integer",
+          "format": "int32",
+          "description": "Priority key is a positive integer from 1 to n, where smaller integers\ncorrespond to higher priorities (tasks run sooner). In general, tasks in\na queue should be processed in close to priority order, although small\ndeviations are possible.\n\nThe maximum priority value (minimum priority) is determined by server\nconfiguration, and defaults to 5.\n\nThe default priority is (min+max)/2. With the default max of 5 and min of\n1, that comes out to 3."
+        }
+      },
+      "description": "Priority contains metadata that controls relative ordering of task processing\nwhen tasks are backlogged in a queue. Initially, Priority will be used in\nactivity and workflow task queues, which are typically where backlogs exist.\nOther queues in the server (such as transfer and timer queues) and rate\nlimiting decisions do not use Priority, but may in the future.\n\nPriority is attached to workflows and activities. Activities and child\nworkflows inherit Priority from the workflow that created them, but may\noverride fields when they are started or modified. For each field of a\nPriority on an activity/workflow, not present or equal to zero/empty string\nmeans to inherit the value from the calling workflow, or if there is no\ncalling workflow, then use the default (documented below).\n\nDespite being named \"Priority\", this message will also contains fields that\ncontrol \"fairness\" mechanisms.\n\nThe overall semantics of Priority are:\n1. First, consider \"priority_key\": lower number goes first.\n(more will be added here later)"
+    },
     "v1ProtocolMessageCommandAttributes": {
       "type": "object",
       "properties": {
@@ -12180,6 +12215,10 @@
         "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."
         }
       }
     },
@@ -12759,6 +12798,10 @@
         "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."
+        },
+        "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."
         }
       }
     },
@@ -12876,6 +12919,10 @@
         "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."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       }
     },
@@ -13068,6 +13115,10 @@
         "onConflictOptions": {
           "$ref": "#/definitions/v1OnConflictOptions",
           "description": "Defines actions to be done to the existing running workflow when the conflict policy\nWORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING is used. If not set (ie., nil value) or set to a\nempty object (ie., all options with default value), it won't do anything to the existing\nrunning workflow. If set, it will add a history event to the running workflow."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       }
     },
@@ -14314,6 +14365,10 @@
         "workerDeploymentName": {
           "type": "string",
           "description": "The name of Worker Deployment that completed the most recent workflow task.\nExperimental. Worker Deployments are experimental and might change in the future."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       },
       "description": "Hold basic information about a workflow execution.\nThis structure is a part of visibility, and thus contain a limited subset of information."
@@ -14516,6 +14571,10 @@
         "parentPinnedWorkerDeploymentVersion": {
           "type": "string",
           "description": "When present, it means this is a child workflow of a parent that is Pinned to this Worker\nDeployment Version. In this case, child workflow will start as Pinned to this Version instead\nof starting on the Current Version of its Task Queue.\nThis is set only if the child workflow is starting on a Task Queue belonging to the same\nWorker Deployment Version."
+        },
+        "priority": {
+          "$ref": "#/definitions/v1Priority",
+          "title": "Priority metadata"
         }
       },
       "title": "Always the first event in workflow history"

openapi/openapiv3.yaml

@@ -5747,6 +5747,12 @@ components:
           description: |-
             If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,
              Assignment rules of the activity's Task Queue will be used to determine the Build ID.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: |-
+            Priority metadata. If this message is not present, or any fields are not
+             present, they inherit the values from the workflow.
     ActivityTaskStartedEventAttributes:
       type: object
       properties:
@@ -7967,6 +7973,10 @@ components:
           description: |-
             If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.
              To unset the override after the workflow is running, use UpdateWorkflowExecutionOptions.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
       description: |-
         NewWorkflowExecutionInfo is a shared message that encapsulates all the
          required arguments to starting a workflow in different contexts.
@@ -8359,6 +8369,10 @@ components:
         lastWorkerDeploymentVersion:
           type: string
           description: The Worker Deployment Version this activity was dispatched to most recently.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
     PendingChildExecutionInfo:
       type: object
       properties:
@@ -8608,6 +8622,43 @@ components:
       description: |-
         Attached to task responses to give hints to the SDK about how it may adjust its number of
          pollers.
+    Priority:
+      type: object
+      properties:
+        priorityKey:
+          type: integer
+          description: |-
+            Priority key is a positive integer from 1 to n, where smaller integers
+             correspond to higher priorities (tasks run sooner). In general, tasks in
+             a queue should be processed in close to priority order, although small
+             deviations are possible.
+
+             The maximum priority value (minimum priority) is determined by server
+             configuration, and defaults to 5.
+
+             The default priority is (min+max)/2. With the default max of 5 and min of
+             1, that comes out to 3.
+          format: int32
+      description: |-
+        Priority contains metadata that controls relative ordering of task processing
+         when tasks are backlogged in a queue. Initially, Priority will be used in
+         activity and workflow task queues, which are typically where backlogs exist.
+         Other queues in the server (such as transfer and timer queues) and rate
+         limiting decisions do not use Priority, but may in the future.
+
+         Priority is attached to workflows and activities. Activities and child
+         workflows inherit Priority from the workflow that created them, but may
+         override fields when they are started or modified. For each field of a
+         Priority on an activity/workflow, not present or equal to zero/empty string
+         means to inherit the value from the calling workflow, or if there is no
+         calling workflow, then use the default (documented below).
+
+         Despite being named "Priority", this message will also contains fields that
+         control "fairness" mechanisms.
+
+         The overall semantics of Priority are:
+         1. First, consider "priority_key": lower number goes first.
+         (more will be added here later)
     QueryRejected:
       type: object
       properties:
@@ -10053,6 +10104,10 @@ components:
           description: |-
             If set, takes precedence over the Versioning Behavior sent by the SDK on Workflow Task completion.
              To unset the override after the workflow is running, use UpdateWorkflowExecutionOptions.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
     SignalWithStartWorkflowExecutionResponse:
       type: object
       properties:
@@ -10251,6 +10306,10 @@ components:
           description: |-
             If this is set, the child workflow inherits the Build ID of the parent. Otherwise, the assignment
              rules of the child's Task Queue will be used to independently assign a Build ID to it.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
     StartWorkflowExecutionRequest:
       type: object
       properties:
@@ -10382,6 +10441,10 @@ components:
              WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING is used. If not set (ie., nil value) or set to a
              empty object (ie., all options with default value), it won't do anything to the existing
              running workflow. If set, it will add a history event to the running workflow.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
     StartWorkflowExecutionResponse:
       type: object
       properties:
@@ -11791,6 +11854,10 @@ components:
           description: |-
             The name of Worker Deployment that completed the most recent workflow task.
              Experimental. Worker Deployments are experimental and might change in the future.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
       description: |-
         Hold basic information about a workflow execution.
          This structure is a part of visibility, and thus contain a limited subset of information.
@@ -12004,6 +12071,10 @@ components:
              of starting on the Current Version of its Task Queue.
              This is set only if the child workflow is starting on a Task Queue belonging to the same
              Worker Deployment Version.
+        priority:
+          allOf:
+            - $ref: '#/components/schemas/Priority'
+          description: Priority metadata
       description: Always the first event in workflow history
     WorkflowExecutionTerminatedEventAttributes:
       type: object

temporal/api/command/v1/message.proto

@@ -85,6 +85,9 @@ message ScheduleActivityTaskCommandAttributes {
     // If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,
     // Assignment rules of the activity's Task Queue will be used to determine the Build ID.
     bool use_workflow_build_id = 13;
+    // Priority metadata. If this message is not present, or any fields are not
+    // present, they inherit the values from the workflow.
+    temporal.api.common.v1.Priority priority = 14;
 }
 
 message RequestCancelActivityTaskCommandAttributes {
@@ -226,6 +229,9 @@ message StartChildWorkflowExecutionCommandAttributes {
     // If this is set, the child workflow inherits the Build ID of the parent. Otherwise, the assignment
     // rules of the child's Task Queue will be used to independently assign a Build ID to it.
     bool inherit_build_id = 17;
+    // Priority metadata. If this message is not present, or any fields are not
+    // present, they inherit the values from the workflow.
+    temporal.api.common.v1.Priority priority = 18;
 }
 
 message ProtocolMessageCommandAttributes {

temporal/api/common/v1/message.proto

@@ -247,3 +247,36 @@ message Link {
         BatchJob batch_job = 2;
     }
 }
+
+// Priority contains metadata that controls relative ordering of task processing
+// when tasks are backlogged in a queue. Initially, Priority will be used in
+// activity and workflow task queues, which are typically where backlogs exist.
+// Other queues in the server (such as transfer and timer queues) and rate
+// limiting decisions do not use Priority, but may in the future.
+//
+// Priority is attached to workflows and activities. Activities and child
+// workflows inherit Priority from the workflow that created them, but may
+// override fields when they are started or modified. For each field of a
+// Priority on an activity/workflow, not present or equal to zero/empty string
+// means to inherit the value from the calling workflow, or if there is no
+// calling workflow, then use the default (documented below).
+//
+// Despite being named "Priority", this message will also contains fields that
+// control "fairness" mechanisms.
+//
+// The overall semantics of Priority are:
+// 1. First, consider "priority_key": lower number goes first.
+// (more will be added here later)
+message Priority {
+    // Priority key is a positive integer from 1 to n, where smaller integers
+    // correspond to higher priorities (tasks run sooner). In general, tasks in
+    // a queue should be processed in close to priority order, although small
+    // deviations are possible.
+    //
+    // The maximum priority value (minimum priority) is determined by server
+    // configuration, and defaults to 5.
+    //
+    // The default priority is (min+max)/2. With the default max of 5 and min of
+    // 1, that comes out to 3.
+    int32 priority_key = 1;
+}

temporal/api/history/v1/message.proto

@@ -139,6 +139,9 @@ message WorkflowExecutionStartedEventAttributes {
     // This is set only if the child workflow is starting on a Task Queue belonging to the same
     // Worker Deployment Version.
     string parent_pinned_worker_deployment_version = 34;
+
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 35;
 }
 
 message WorkflowExecutionCompletedEventAttributes {
@@ -348,6 +351,9 @@ message ActivityTaskScheduledEventAttributes {
     // If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,
     // Assignment rules of the activity's Task Queue will be used to determine the Build ID.
     bool use_workflow_build_id = 13;
+    // Priority metadata. If this message is not present, or any fields are not
+    // present, they inherit the values from the workflow.
+    temporal.api.common.v1.Priority priority = 14;
 }
 
 message ActivityTaskStartedEventAttributes {
@@ -655,6 +661,8 @@ message StartChildWorkflowExecutionInitiatedEventAttributes {
     // If this is set, the child workflow inherits the Build ID of the parent. Otherwise, the assignment
     // rules of the child's Task Queue will be used to independently assign a Build ID to it.
     bool inherit_build_id = 19;
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 20;
 }
 
 message StartChildWorkflowExecutionFailedEventAttributes {