This is an automated email from the ASF dual-hosted git repository.

jason810496 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/main by this push:
     new f5f7f2b838b TS SDK: Fix the XCom map index default and reject invalid 
XCom arguments (#76893)
f5f7f2b838b is described below

commit f5f7f2b838b95dc4b76d2ecb1069429a3c4af1c3
Author: Jason(Zhe-You) Liu <[email protected]>
AuthorDate: Tue Nov 17 19:35:19 2026 +0800

    TS SDK: Fix the XCom map index default and reject invalid XCom arguments 
(#76893)
    
    * TS SDK: Default XCom map index to unmapped when targeting another task
    
    A mapped task reading or writing another task's XCom used its own map 
index, so it missed the unmapped row. The index is now inherited only when the 
Dag, run and task all match the running task.
    
    This also changes how argument binding pulls an upstream return_value for a 
mapped downstream task: it now reads the unmapped row.
    
    * TS SDK: Reject invalid XCom arguments before sending
    
    The supervisor never replies to a frame that fails its validation, so a 
non-string key, dagId, taskId or runId, or a non-integer map index hung the 
task until its execution timeout. Throw before sending the frame instead, and 
reject empty strings too.
    
    * TS SDK: Document null XCom target ids as falling back to the current task
    
    Passing null for dagId, taskId or runId already targets the running task, 
but the docs said a non-string value throws TypeError.
    
    * TS SDK: Type XCom target ids as nullable
    
    The client already treats a null dagId, taskId or runId as the running 
task, so the option types now accept null like mapIndex does.
---
 .../language-sdks/typescript.rst                   |  7 ++-
 ts-sdk/src/coordinator/client.ts                   | 71 ++++++++++++++--------
 ts-sdk/src/sdk/client-types.ts                     | 27 +++++---
 ts-sdk/src/sdk/client.ts                           | 11 +++-
 ts-sdk/tests/coordinator/client.test.ts            | 70 ++++++++++++++++++++-
 ts-sdk/tests/public-api.test.ts                    | 12 ++--
 6 files changed, 152 insertions(+), 46 deletions(-)

diff --git 
a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst 
b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
index 5638ededd19..3662d0171e9 100644
--- a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
+++ b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
@@ -592,11 +592,12 @@ The ``TaskClient``
    * - ``getConnectionOrThrow(connId)``
      - Same, but throws ``ConnectionNotFoundError``, like Python's 
``BaseHook.get_connection``.
    * - ``getXCom<T>({ key, ... })``
-     - An XCom value, or ``null`` when it does not exist. ``dagId``, 
``runId``, ``taskId`` and ``mapIndex``
-       default to the current task; pass ``taskId`` to read an upstream task's 
XCom. See
+     - An XCom value, or ``null`` when it does not exist. ``dagId``, ``runId`` 
and ``taskId`` default to the
+       current task; pass ``taskId`` to read an upstream task's XCom. 
``mapIndex`` defaults to the current
+       task's own map index when the target is the current task, and to the 
unmapped value otherwise. See
        :ref:`typescript-sdk/types`.
    * - ``setXCom({ key, value, ... })``
-     - Publishes an XCom value.
+     - Publishes an XCom value. The target and ``mapIndex`` default the same 
way as for ``getXCom``.
    * - ``taskStateStore``
      - This task instance's key/value store, with ``get<T>(key)``, ``set(key, 
value, { retention? })``,
        ``delete(key)`` and ``clear()``. See 
:ref:`typescript-sdk/task-state-store`.
diff --git a/ts-sdk/src/coordinator/client.ts b/ts-sdk/src/coordinator/client.ts
index 7ae3ece5ef9..e16aa21531a 100644
--- a/ts-sdk/src/coordinator/client.ts
+++ b/ts-sdk/src/coordinator/client.ts
@@ -58,14 +58,35 @@ import type {
  */
 type AbsentRowPolicy = "throw" | { codes: readonly string[]; apiServer404: 
boolean };
 
-function resolveWireMapIndex(
-  requestedMapIndex: number | null | undefined,
-  contextMapIndex: number,
-): number | null {
-  // `mapIndex` is nullable, so only use the context value when the user did
-  // not provide one. If the user passes null, send null to the supervisor.
-  const mapIndex = requestedMapIndex === undefined ? contextMapIndex : 
requestedMapIndex;
-  return mapIndex == null || mapIndex < 0 ? null : mapIndex;
+type XComTargetOpts = Pick<GetXComOpts, "key" | "dagId" | "runId" | "taskId" | 
"mapIndex">;
+
+function resolveXComTarget(opts: XComTargetOpts, ctx: TaskContext) {
+  // The supervisor never replies to a frame with a wrongly typed field, so the
+  // task would hang instead of failing fast.
+  assertKey(opts.key, "XCom key");
+  for (const [label, id] of [
+    ["dagId", opts.dagId],
+    ["taskId", opts.taskId],
+    ["runId", opts.runId],
+  ] as const) {
+    if (id != null) assertKey(id, `XCom ${label}`);
+  }
+  assertMapIndex(opts.mapIndex);
+  const dag_id = opts.dagId ?? ctx.dagId;
+  const task_id = opts.taskId ?? ctx.taskId;
+  const run_id = opts.runId ?? ctx.runId;
+  // A map index only names a row of the task that owns it, so another task or
+  // run does not inherit it. `mapIndex` is nullable: an explicit null stays 
null.
+  const targetsSelf = dag_id === ctx.dagId && task_id === ctx.taskId && run_id 
=== ctx.runId;
+  const mapIndex =
+    opts.mapIndex === undefined ? (targetsSelf ? ctx.mapIndex : null) : 
opts.mapIndex;
+  return {
+    key: opts.key,
+    dag_id,
+    task_id,
+    run_id,
+    map_index: mapIndex === null || mapIndex < 0 ? null : mapIndex,
+  };
 }
 
 function fromWireConnection(body: WireConnectionResult): ConnectionResult {
@@ -145,12 +166,22 @@ const RETENTION_DAYS_ENV_VAR = 
"AIRFLOW__STATE_STORE__DEFAULT_RETENTION_DAYS";
 const MS_PER_SECOND = 1000;
 const SECONDS_PER_DAY = 24 * 60 * 60;
 
-function assertKey(key: string): void {
+function assertKey(key: string, label: string): void {
   if (typeof key !== "string") {
-    throw new TypeError(`task state store key must be a string, got ${typeof 
key}`);
+    throw new TypeError(`${label} must be a string, got ${typeof key}`);
   }
   if (key === "") {
-    throw new RangeError("task state store key must not be empty");
+    throw new RangeError(`${label} must not be empty`);
+  }
+}
+
+function assertMapIndex(mapIndex: number | null | undefined): void {
+  if (mapIndex === undefined || mapIndex === null) return;
+  if (typeof mapIndex !== "number") {
+    throw new TypeError(`XCom mapIndex must be an integer or null, got 
${typeof mapIndex}`);
+  }
+  if (!Number.isInteger(mapIndex)) {
+    throw new RangeError(`XCom mapIndex must be an integer, got ${mapIndex}`);
   }
 }
 
@@ -250,7 +281,7 @@ export function createCoordinatorClient(
 
   const taskStateStore: TaskStateStore = {
     async get<T = unknown>(key: string): Promise<T | null> {
-      assertKey(key);
+      assertKey(key, "task state store key");
       const msg: GetTaskStateStore = { type: "GetTaskStateStore", ti_id: tiId, 
key };
       return rpc(
         "GetTaskStateStore",
@@ -266,7 +297,7 @@ export function createCoordinatorClient(
       value: NonNullable<JsonValue>,
       opts: TaskStateStoreSetOpts = {},
     ): Promise<void> {
-      assertKey(key);
+      assertKey(key, "task state store key");
       if (
         value === null ||
         value === undefined ||
@@ -285,7 +316,7 @@ export function createCoordinatorClient(
     },
 
     async delete(key: string): Promise<void> {
-      assertKey(key);
+      assertKey(key, "task state store key");
       const msg: DeleteTaskStateStore = { type: "DeleteTaskStateStore", ti_id: 
tiId, key };
       await rpc("DeleteTaskStateStore", "OKResponse", msg, () => undefined, 
"throw");
     },
@@ -344,11 +375,7 @@ export function createCoordinatorClient(
     async getXComEntry(opts: GetXComOpts): Promise<XComEntry> {
       const msg: GetXCom = {
         type: "GetXCom",
-        key: opts.key,
-        dag_id: opts.dagId ?? ctx.dagId,
-        task_id: opts.taskId ?? ctx.taskId,
-        run_id: opts.runId ?? ctx.runId,
-        map_index: resolveWireMapIndex(opts.mapIndex, ctx.mapIndex),
+        ...resolveXComTarget(opts, ctx),
         include_prior_dates: opts.includePriorDates ?? false,
       };
       const entry = await rpc<XComEntry>(
@@ -375,12 +402,8 @@ export function createCoordinatorClient(
     async setXCom(opts: SetXComOpts): Promise<void> {
       const msg: SetXCom = {
         type: "SetXCom",
-        key: opts.key,
+        ...resolveXComTarget(opts, ctx),
         value: opts.value,
-        dag_id: opts.dagId ?? ctx.dagId,
-        task_id: opts.taskId ?? ctx.taskId,
-        run_id: opts.runId ?? ctx.runId,
-        map_index: resolveWireMapIndex(opts.mapIndex, ctx.mapIndex),
       };
       await rpc("SetXCom", null, msg, () => undefined, "throw");
     },
diff --git a/ts-sdk/src/sdk/client-types.ts b/ts-sdk/src/sdk/client-types.ts
index a76a1557c49..3fa3ad04913 100644
--- a/ts-sdk/src/sdk/client-types.ts
+++ b/ts-sdk/src/sdk/client-types.ts
@@ -24,14 +24,18 @@ export type JsonValue =
 /**
  * Options for pulling an XCom value.
  *
- * `dagId`, `taskId`, and `runId` default to the running task's context.
- * Pass them only when pulling an XCom value from another task or run.
+ * `dagId`, `taskId`, and `runId` default to the running task's context when
+ * omitted or `null`. Pass them only when pulling an XCom value from another 
task or run.
+ *
+ * `mapIndex` defaults to the running task's own map index when the target is
+ * the running task, and to the unmapped value for any other task or run. Pass
+ * a number to pick one mapped instance, or `null` for the unmapped one.
  */
 export interface GetXComOpts {
   key: string;
-  dagId?: string;
-  runId?: string;
-  taskId?: string;
+  dagId?: string | null;
+  runId?: string | null;
+  taskId?: string | null;
   mapIndex?: number | null;
   includePriorDates?: boolean;
 }
@@ -39,14 +43,19 @@ export interface GetXComOpts {
 /**
  * Options for pushing an XCom value.
  *
- * `dagId`, `taskId`, and `runId` default to the running task's context.
+ * `dagId`, `taskId`, and `runId` default to the running task's context when
+ * omitted or `null`.
+ *
+ * `mapIndex` defaults to the running task's own map index when the target is
+ * the running task, and to the unmapped value for any other task or run. Pass
+ * a number to pick one mapped instance, or `null` for the unmapped one.
  */
 export interface SetXComOpts {
   key: string;
   value: JsonValue;
-  dagId?: string;
-  runId?: string;
-  taskId?: string;
+  dagId?: string | null;
+  runId?: string | null;
+  taskId?: string | null;
   mapIndex?: number | null;
 }
 
diff --git a/ts-sdk/src/sdk/client.ts b/ts-sdk/src/sdk/client.ts
index d1e59a1091a..31c1f18da2d 100644
--- a/ts-sdk/src/sdk/client.ts
+++ b/ts-sdk/src/sdk/client.ts
@@ -75,7 +75,7 @@ export interface TaskClient {
    * Pull an XCom value.
    *
    * Returns `null` when the row is missing. Locator fields default to the
-   * current task's context.
+   * current task's context; see {@link GetXComOpts} for how `mapIndex` 
defaults.
    *
    * The generic `T` lets callers narrow the return type when the shape is
    * known:
@@ -84,13 +84,20 @@ export interface TaskClient {
    * const data = await client.getXCom<{ count: number }>({ key: "result" });
    * // data is { count: number } | null
    * ```
+   *
+   * @throws `TypeError` when `key` is not a string, `dagId`, `taskId` or 
`runId` is set to a non-string, or `mapIndex` is not a number or `null`.
+   * @throws `RangeError` when `key`, `dagId`, `taskId` or `runId` is an empty 
string, or `mapIndex` is not an integer.
    */
   getXCom<T = unknown>(opts: GetXComOpts): Promise<T | null>;
 
   /**
    * Push an XCom value.
    *
-   * Target fields default to the current task's context.
+   * Target fields default to the current task's context; see
+   * {@link SetXComOpts} for how `mapIndex` defaults.
+   *
+   * @throws `TypeError` when `key` is not a string, `dagId`, `taskId` or 
`runId` is set to a non-string, or `mapIndex` is not a number or `null`.
+   * @throws `RangeError` when `key`, `dagId`, `taskId` or `runId` is an empty 
string, or `mapIndex` is not an integer.
    */
   setXCom(opts: SetXComOpts): Promise<void>;
 
diff --git a/ts-sdk/tests/coordinator/client.test.ts 
b/ts-sdk/tests/coordinator/client.test.ts
index a2133f785f4..8c618539731 100644
--- a/ts-sdk/tests/coordinator/client.test.ts
+++ b/ts-sdk/tests/coordinator/client.test.ts
@@ -23,6 +23,7 @@ import { NEVER_EXPIRE } from "../../src/sdk/client-types.js";
 import { createCoordinatorClient } from "../../src/coordinator/client.js";
 import type { CommChannel } from "../../src/coordinator/comm-channel.js";
 import type { TaskClient } from "../../src/sdk/client.js";
+import type { GetXComOpts } from "../../src/sdk/client-types.js";
 import type { TaskContext } from "../../src/sdk/task.js";
 
 const RETENTION_ENV_VAR = "AIRFLOW__STATE_STORE__DEFAULT_RETENTION_DAYS";
@@ -50,8 +51,22 @@ function client(frames: { body: unknown; error?: unknown 
}[]) {
   return createCoordinatorClient(fakeComm(frames), FAKE_CTX, FAKE_TI_ID);
 }
 
+const MAPPED_CTX: TaskContext = { ...FAKE_CTX, mapIndex: 3 };
+
+type XComOpts = Pick<GetXComOpts, "key" | "dagId" | "runId" | "taskId" | 
"mapIndex">;
+
+/** Each XCom call that takes a target, with the reply the supervisor gives 
it. */
+const XCOM_CALLS = [
+  [
+    "getXCom",
+    { type: "XComResult", key: "k", value: null },
+    (c: TaskClient, o: XComOpts) => c.getXCom(o),
+  ],
+  ["setXCom", null, (c: TaskClient, o: XComOpts) => c.setXCom({ ...o, value: 1 
})],
+] as const;
+
 /** Captures the request bodies sent, answering each one with `reply`. */
-function recordingClient(reply: unknown = null) {
+function recordingClient(reply: unknown = null, ctx: TaskContext = FAKE_CTX) {
   const sent: Record<string, unknown>[] = [];
   const comm = {
     request: async (body: Record<string, unknown>) => {
@@ -59,7 +74,7 @@ function recordingClient(reply: unknown = null) {
       return { body: reply };
     },
   } as unknown as CommChannel;
-  return { client: createCoordinatorClient(comm, FAKE_CTX, FAKE_TI_ID), sent };
+  return { client: createCoordinatorClient(comm, ctx, FAKE_TI_ID), sent };
 }
 
 describe("getVariable not-found contract", () => {
@@ -323,6 +338,57 @@ describe("client is bound to TaskContext", () => {
   });
 });
 
+describe("XCom map index default", () => {
+  describe.each(XCOM_CALLS)("%s", (_name, reply, call) => {
+    it.each([
+      ["the running task", {}, 3],
+      ["the running task named explicitly", { dagId: "d", taskId: "t", runId: 
"r" }, 3],
+      ["another task", { taskId: "extract" }, null],
+      ["another Dag", { dagId: "other_dag" }, null],
+      ["another run", { runId: "manual__1" }, null],
+      ["another task with an explicit mapIndex", { taskId: "extract", 
mapIndex: 2 }, 2],
+      ["another task with mapIndex 0", { taskId: "extract", mapIndex: 0 }, 0],
+      ["the running task with mapIndex null", { mapIndex: null }, null],
+      ["the running task with null target ids", { dagId: null, taskId: null, 
runId: null }, 3],
+    ] as [string, Omit<XComOpts, "key">, number | null][])(
+      "from a mapped task targeting %s sends map_index %s",
+      async (_label, target, expected) => {
+        const { client: c, sent } = recordingClient(reply, MAPPED_CTX);
+
+        await call(c, { key: "k", ...target });
+
+        expect(sent[0]).toMatchObject({ map_index: expected });
+      },
+    );
+  });
+});
+
+describe("XCom key and map index guards", () => {
+  describe.each(XCOM_CALLS)("%s", (_name, reply, call) => {
+    it.each([
+      ["an empty key", { key: "" }, RangeError],
+      ["an undefined key", { key: undefined }, TypeError],
+      ["a numeric key", { key: 1 }, TypeError],
+      ["a fractional mapIndex", { key: "k", mapIndex: 1.5 }, RangeError],
+      ["a NaN mapIndex", { key: "k", mapIndex: Number.NaN }, RangeError],
+      ["an Infinity mapIndex", { key: "k", mapIndex: Number.POSITIVE_INFINITY 
}, RangeError],
+      ["a string mapIndex", { key: "k", mapIndex: "1" }, TypeError],
+      ["a numeric dagId", { key: "k", dagId: 1 }, TypeError],
+      ["a numeric taskId", { key: "k", taskId: 1 }, TypeError],
+      ["an empty runId", { key: "k", runId: "" }, RangeError],
+    ] as [string, unknown, ErrorConstructor][])(
+      "rejects %s without sending a request",
+      async (_label, opts, errorType) => {
+        const { client: c, sent } = recordingClient(reply);
+
+        await expect(call(c, opts as XComOpts)).rejects.toThrow(errorType);
+
+        expect(sent).toHaveLength(0);
+      },
+    );
+  });
+});
+
 describe("getConnection", () => {
   it("maps wire snake_case connection fields to public camelCase fields", 
async () => {
     const c = client([
diff --git a/ts-sdk/tests/public-api.test.ts b/ts-sdk/tests/public-api.test.ts
index 36efb39d266..980c4c3e205 100644
--- a/ts-sdk/tests/public-api.test.ts
+++ b/ts-sdk/tests/public-api.test.ts
@@ -414,18 +414,18 @@ describe("public API", () => {
     }>();
     expectTypeOf<GetXComOpts>().toEqualTypeOf<{
       key: string;
-      dagId?: string;
-      runId?: string;
-      taskId?: string;
+      dagId?: string | null;
+      runId?: string | null;
+      taskId?: string | null;
       mapIndex?: number | null;
       includePriorDates?: boolean;
     }>();
     expectTypeOf<SetXComOpts>().toEqualTypeOf<{
       key: string;
       value: SetXComOpts["value"];
-      dagId?: string;
-      runId?: string;
-      taskId?: string;
+      dagId?: string | null;
+      runId?: string | null;
+      taskId?: string | null;
       mapIndex?: number | null;
     }>();
     expectTypeOf<ConnectionResult>().toEqualTypeOf<{

Reply via email to