src/sdk/task.tstypescript
/*!
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

// The task-handler call surface: what a task handler sees while it runs.
//
// Everything the SDK supplies comes from a getter rather than a parameter, so
// nothing it injects shares a namespace with an author's arguments.

import { AsyncLocalStorage } from "node:async_hooks";

import type { TaskClient } from "./client.js";

/** Runtime metadata for the current task invocation. */
export interface TaskContext {
  /** Identifier of the Dag containing this task. */
  readonly dagId: string;
  /** Task ID for this handler invocation, including any TaskGroup prefix. */
  readonly taskId: string;
  /** Dag run identifier for the current task attempt. */
  readonly runId: string;
  /** Airflow try number for the current task attempt. */
  readonly tryNumber: number;
  /** -1 for non-mapped tasks, 0..N-1 for mapped instances. */
  readonly mapIndex: number;
  /**
   * AbortSignal that fires when Airflow terminates the task subprocess
   * with SIGTERM or SIGINT.
   *
   * Pass this signal to `fetch()`, timers, or any other API that accepts an
   * abort signal for cooperative cancellation and cleanup.
   */
  readonly signal: AbortSignal;
}

/** What the runtime puts in scope for the duration of one handler call. */
export interface TaskScope {
  readonly ctx: TaskContext;
  readonly client: TaskClient;
}

// Keyed on a global symbol, as the serve latch is: two resolved copies of the
// package would otherwise hold one storage each, and a handler reaching for
// `getClient()` through the copy that is not running the task would find
// nothing in scope.
const SCOPE_STORAGE = Symbol.for("airflow.ts-sdk.task-scope");

function scopeStorage(): AsyncLocalStorage<TaskScope> {
  const holder = globalThis as unknown as Record<symbol, AsyncLocalStorage<TaskScope> | undefined>;
  return (holder[SCOPE_STORAGE] ??= new AsyncLocalStorage<TaskScope>());
}

/**
 * Internal: call `fn` with `scope` in place, as the runtime does per task.
 *
 * `AsyncLocalStorage` carries the store across every `await` and into every
 * promise created inside `fn`, so a handler's helpers see it without being
 * passed anything. Not re-exported from the package root: a handler reads the
 * scope, it does not install one.
 */
export function runInTaskScope<T>(scope: TaskScope, fn: () => T): T {
  return scopeStorage().run(scope, fn);
}

type ScopeAccessor = "getContext" | "getClient";

function currentScope(accessor: ScopeAccessor): TaskScope {
  const scope = scopeStorage().getStore();
  if (!scope) {
    throw new Error(
      `${accessor}() is only available inside a task handler. ` +
        "The scope is in place only for the duration of the handler call, so " +
        "this ran either at module top level or in work that outlived it.",
    );
  }
  return scope;
}

/**
 * Runtime metadata for the task currently running.
 *
 * ```ts
 * async function transform() {
 *   throw new Error(`task ${getContext().taskId} has nothing to transform`);
 * }
 * ```
 *
 * @throws when called outside a task handler.
 */
export function getContext(): TaskContext {
  return currentScope("getContext").ctx;
}

/**
 * Client for reading and writing Airflow task-time data for the task currently
 * running.
 *
 * ```ts
 * async function transform() {
 *   const client = getClient();
 *   return await client.getXCom<number>({ key: "return_value", taskId: "extract" });
 * }
 * ```
 *
 * Work that outlives the handler is the one gap. Async context propagates into
 * a promise created inside the handler, so one it never awaits still resolves,
 * but it runs after the task's terminal state has been reported and writes to
 * a finished task. Await everything a handler starts.
 *
 * @throws when called outside a task handler.
 */
export function getClient(): TaskClient {
  return currentScope("getClient").client;
}

/**
 * Function signature for a TypeScript task handler.
 *
 * `TArgs` describes what the Dag's call site passes. {@link getContext} and
 * {@link getClient} reach the runtime from inside the call, so neither is a
 * parameter.
 *
 * ```ts
 * interface TransformArgs {
 *   regionCode: string;
 *   threshold: number;
 * }
 *
 * async function transform({ regionCode, threshold }: TransformArgs) {
 *   // ...
 * }
 * ```
 *
 * A handler that takes no arguments declares no parameter.
 *
 * Non-`undefined` return values are automatically pushed to XCom under the
 * `"return_value"` key, matching Python `@task` behavior.
 */
export type TaskFunction<TArgs = void, TReturn = unknown> = (
  args: TArgs,
) => TReturn | Promise<TReturn>;