Initial protos for priority

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

@@ -246,3 +246,114 @@ message Link {
         BatchJob batch_job = 2;
     }
 }
+
+// Priority contains metadata that controls relative ordering of task processing
+// when tasks are backed up in a queue. Initially, Priority will be used in
+// matching (workflow and activity) task queues. Later it may be used in history
+// task queues and in rate limiting decisions.
+//
+// Priority is attached to workflows, activities, and Nexus tasks. By default,
+// activities inherit Priority from the workflow that created them, but may
+// override a subset of fields when an activity is started or modified.
+//
+// Despite being named "Priority", this message also contains fields that
+// control "fairness" mechanisms.
+//
+// For all fields, the field not present or equal to zero/empty string means to
+// inherit the value from the calling workflow. If there is no calling workflow,
+// then use the default value.
+//
+// Note that for all fields other than fairness_key, the not-present/zero value
+// is invalid, but for fairness_key, the empty string is a valid key. This means
+// that a workflow with a non-empty-string fairness key can't override the
+// fairness key of an activity to the empty string, it will be interpreted as
+// "inherit the workflow's key".
+//
+// The overall semantics of Priority are:
+// 1. First, consider "priority": higher priority (lower number) goes first.
+// 2. Next, consider fairness: try to dispatch tasks for different fairness keys
+//    in proportion to their weight.
+// 3. Finally, tasks may be ordered by an additional ordering key.
+//
+// Applications may use any subset of mechanisms that are useful to them and
+// leave the other fields to use default values.
+//
+// Not all queues in the system may support the "full" semantics of all priority
+// fields. (Currently only support in matching task queues is planned.)
+message Priority {
+    // Priority 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.
+    //
+    // If priority is not present (or zero), then the effective priority will be
+    // the default priority, which is is calculated by (min+max)/2. With the
+    // default max of 5, and min of 1, that comes out to 3.
+    int32 priority = 1;
+
+    // Fairness key is a short string that's used as a key for a fairness
+    // balancing mechanism. It may correspond to a tenant id, or to a fixed
+    // string like "high" or "low". The default is the empty string.
+    //
+    // The fairness mechanism attempts to dispatch tasks for a given key in
+    // proportion to its weight. For example, using a thousand distinct tenant
+    // ids, each with a weight of 1.0 (the default) will result in each tenant
+    // getting a roughly equal share of task dispatch throughput.
+    //
+    // (Note: this does not imply equal share of worker capacity! Fairness
+    // decisions are made only at dispatch time based on queue statistics, not
+    // current worker load.)
+    //
+    // As another example, using keys "high" and "low" with weight 9.0 and 1.0
+    // respectively will prefer dispatching "high" tasks over "low" tasks at a
+    // 9:1 ratio, while allowing either key to use all worker capacity if the
+    // other is not present.
+    //
+    // All fairness mechanisms, including rate limits, are best-effort and
+    // probabilistic. The results may not match what a "perfect" algorithm with
+    // infinite resources would produce. The more unique keys are used, the less
+    // accurate the results will be.
+    //
+    // Fairness keys are limited to 64 bytes.
+    string fairness_key = 2;
+
+    // Fairness weight for a task can come from multiple sources for
+    // flexibility. From highest to lowest precedence:
+    // 1. Weights for a small set of keys can be overridden in task queue
+    //    configuration with an API.
+    // 2. It can be attached to the workflow/activity/task in this field.
+    // 3. The default weight of 1.0 will be used.
+    // Note that if the weight for a key is attached in this field, for best
+    // results, the same weight should be used for the same key for a reasonable
+    // amount of time (minutes). It may change, but it may take some time for
+    // the change to be reflected.
+    //
+    // The recommended range of usable weights is [1e-3, 1e3].
+    float fairness_weight = 3;
+
+    // The fairness mechanism can also enforce rate limits per fairness key.
+    // Rate limits are specified in tasks dispatched per second.
+    // As with weights, rate limits can come from different sources:
+    // 1. Rate limits for a small set of keys can be overridden in task queue
+    //    configuration with an API.
+    // 2. It can be attached to the workflow/activity/task in this field.
+    // 3. The "default" rate limit for keys that are not overridden can be set
+    //    in task queue configuration also.
+    // 4. Otherwise, a very high rate limit will be applied.
+    float fairness_rate_limit = 4;
+
+    // Ordering key is a positive integer from 1 to MaxInt64. After priority and
+    // fairness mechanisms are applied, tasks will be finally ordered by
+    // ordering_key. Note that fine-grained values are allowed here, as opposed
+    // to priority.
+    //
+    // For example, applications might use the start time of a workflow (in
+    // seconds since the unix epoch) as ordering key for the workflow and all
+    // activities in it. This will have the effect of prioritizing activities of
+    // workflows that were started earlier, encouring completing older workflows
+    // over making progress in newer ones.
+    int64 ordering_key = 5;
+}

temporal/api/history/v1/message.proto

@@ -133,6 +133,8 @@ message WorkflowExecutionStartedEventAttributes {
     string inherited_build_id = 32;
     // Versioning override applied to this workflow when it was started.
     temporal.api.workflow.v1.VersioningOverride versioning_override = 33;
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 34;
 }
 
 message WorkflowExecutionCompletedEventAttributes {
@@ -333,6 +335,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 {
@@ -640,6 +645,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 {

temporal/api/workflow/v1/message.proto

@@ -110,6 +110,9 @@ message WorkflowExecutionInfo {
     // be versioned or unversioned, depending on `versioning_info.behavior` and `versioning_info.versioning_override`.
     // Experimental. Versioning info is experimental and might change in the future.
     WorkflowExecutionVersioningInfo versioning_info = 22;
+
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 23;
 }
 
 // Holds all the extra information about workflow execution that is not part of Visibility.
@@ -242,6 +245,9 @@ message PendingActivityInfo {
     // The deployment this activity was dispatched to most recently. Present only if the activity
     // was dispatched to a versioned worker.
     temporal.api.deployment.v1.Deployment last_deployment = 20;
+
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 21;
 }
 
 message PendingChildExecutionInfo {
@@ -320,6 +326,8 @@ message NewWorkflowExecutionInfo {
     // 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.
     VersioningOverride versioning_override = 15;
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 16;
 }
 
 // CallbackInfo contains the state of an attached workflow callback.

temporal/api/workflowservice/v1/request_response.proto

@@ -206,6 +206,8 @@ message StartWorkflowExecutionRequest {
     // 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.
     temporal.api.workflow.v1.VersioningOverride versioning_override = 25;
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 26;
 }
 
 message StartWorkflowExecutionResponse {
@@ -478,6 +480,8 @@ message PollActivityTaskQueueResponse {
     // (or not) during activity scheduling. The service can override the provided one if some
     // values are not specified or exceed configured system limits.
     temporal.api.common.v1.RetryPolicy retry_policy = 17;
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 18;
 }
 
 message RecordActivityTaskHeartbeatRequest {
@@ -751,6 +755,8 @@ message SignalWithStartWorkflowExecutionRequest {
     // 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.
     temporal.api.workflow.v1.VersioningOverride versioning_override = 25;
+    // Priority metadata
+    temporal.api.common.v1.Priority priority = 26;
 }
 
 message SignalWithStartWorkflowExecutionResponse {