Fairness Keys & Weights (#1768)

Author: Sushisource

packages/common/src/priority.ts

@@ -11,7 +11,8 @@ import type { temporal } from '@temporalio/proto';
  * calling workflow, then use the default (documented on the field).
  * The overall semantics of Priority are:
  * 1. First, consider "priority_key": lower number goes first.
- * (more will be added here later)
+ * 2. Then, consider fairness: the fairness mechanism attempts to dispatch tasks for a given key in
+ *    proportion to its weight.
  */
 export interface Priority {
   /**
@@ -26,13 +27,43 @@ export interface Priority {
    * The default priority is (min+max)/2. With the default max of 5 and min of 1, that comes out to 3.
    */
   priorityKey?: number;
+
+  /**
+   * FairnessKey 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.
+   *
+   * Fairness keys are limited to 64 bytes.
+   */
+  fairnessKey?: string;
+
+  /**
+   * FairnessWeight 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 in this field.
+   * 3. The default weight of 1.0 will be used.
+   *
+   * Weight values are clamped to the range [0.001, 1000].
+   */
+  fairnessWeight?: number;
 }
 
 /**
  * Turn a proto compatible Priority into a TS Priority
  */
 export function decodePriority(priority?: temporal.api.common.v1.IPriority | null): Priority {
-  return { priorityKey: priority?.priorityKey ?? undefined };
+  return {
+    priorityKey: priority?.priorityKey ?? undefined,
+    fairnessKey: priority?.fairnessKey ?? undefined,
+    fairnessWeight: priority?.fairnessWeight ?? undefined,
+  };
 }
 
 /**
@@ -50,5 +81,7 @@ export function compilePriority(priority: Priority): temporal.api.common.v1.IPri
 
   return {
     priorityKey: priority.priorityKey ?? 0,
+    fairnessKey: priority.fairnessKey ?? '',
+    fairnessWeight: priority.fairnessWeight ?? 0,
   };
 }