src/sdk/client.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.
 */

import type {
  ConnectionResult,
  GetXComOpts,
  JsonValue,
  SetXComOpts,
  TaskStateStoreSetOpts,
} from "./client-types.js";

/**
 * Client for reading and writing Airflow task-time data from a task handler.
 *
 * The active runtime selects the concrete transport and implements this
 * interface for the current task attempt.
 */
export interface TaskClient {
  /**
   * Look up an Airflow Variable.
   *
   * Returns `null` when the key is missing or stored with a null value.
   * Throws on any other error.
   *
   * This is intentionally JS-friendly behavior. Use
   * {@link getVariableOrThrow} when missing variables should raise.
   */
  getVariable(key: string): Promise<string | null>;

  /**
   * Look up an Airflow Variable and raise when it is missing.
   *
   * This matches Python `Variable.get` behavior when no default value is
   * supplied.
   *
   * @throws {@link Exceptions!VariableNotFoundError | VariableNotFoundError} when the key is missing.
   */
  getVariableOrThrow(key: string): Promise<string>;

  /**
   * Store an Airflow Variable, replacing any existing value.
   *
   * The value is stored as a string. Serialize structured data (for example
   * with `JSON.stringify`) before storing it.
   *
   * Omitting `description` clears the description the Variable had.
   */
  setVariable(key: string, value: string, description?: string | null): Promise<void>;

  /**
   * Delete an Airflow Variable.
   *
   * Resolves even when the key does not exist — the Execution API's delete
   * route is idempotent and does not report a missing key as an error.
   */
  deleteVariable(key: string): Promise<void>;

  /**
   * Pull an XCom value.
   *
   * Returns `null` when the row is missing. Locator fields default to the
   * current task's context.
   *
   * The generic `T` lets callers narrow the return type when the shape is
   * known:
   *
   * ```ts
   * const data = await client.getXCom<{ count: number }>({ key: "result" });
   * // data is { count: number } | null
   * ```
   */
  getXCom<T = unknown>(opts: GetXComOpts): Promise<T | null>;

  /**
   * Push an XCom value.
   *
   * Target fields default to the current task's context.
   */
  setXCom(opts: SetXComOpts): Promise<void>;

  /**
   * Key/value state private to this task instance.
   *
   * See {@link TaskStateStore}.
   */
  readonly taskStateStore: TaskStateStore;

  /**
   * Look up an Airflow Connection by ID.
   *
   * Returns `null` when the connection does not exist. Throws on any other
   * error.
   *
   * This is intentionally JS-friendly behavior. Use
   * {@link getConnectionOrThrow} when missing connections should raise.
   */
  getConnection(connId: string): Promise<ConnectionResult | null>;

  /**
   * Look up an Airflow Connection by ID and raise when it is missing.
   *
   * This matches Python `BaseHook.get_connection` behavior.
   *
   * @throws {@link Exceptions!ConnectionNotFoundError | ConnectionNotFoundError} when the connection does not exist.
   */
  getConnectionOrThrow(connId: string): Promise<ConnectionResult>;
}

/**
 * Key/value state private to one task instance, kept across its retries within
 * the same Dag run.
 *
 * Reach it through {@link TaskClient.taskStateStore}:
 *
 * ```ts
 * const store = getClient().taskStateStore;
 * let jobId = await store.get<string>("job_id");
 * if (jobId == null) {
 *   jobId = await submit();
 *   await store.set("job_id", jobId, { retention: NEVER_EXPIRE });
 * }
 * ```
 *
 * Values are stored in the metadata database as-is; the `[workers]
 * state_store_backend` that Python tasks can configure is not applied here.
 */
export interface TaskStateStore {
  /**
   * Look up a value.
   *
   * Returns `null` when the key is missing. Throws on any other error.
   *
   * The generic `T` lets callers narrow the return type when the shape is
   * known.
   *
   * @throws `TypeError` when `key` is not a string.
   * @throws `RangeError` when `key` is empty.
   */
  get<T = unknown>(key: string): Promise<T | null>;

  /**
   * Store a value, replacing any existing value for the key.
   *
   * `opts.retention` is how long to keep the key, in seconds.
   *
   * @throws `TypeError` when `key` is not a string, or `value` is null,
   * undefined, NaN, or Infinity.
   * @throws `RangeError` when `key` is empty; when `retention` is
   * negative, NaN, or Infinity; when the deployment's
   * `[state_store] default_retention_days` is invalid; or when the resolved
   * expiry would overflow the wire timestamp (year 9999).
   */
  set(key: string, value: NonNullable<JsonValue>, opts?: TaskStateStoreSetOpts): Promise<void>;

  /**
   * Delete a key.
   *
   * Resolves even when the key does not exist — the Execution API's delete
   * route is idempotent and does not report a missing key as an error.
   *
   * @throws `TypeError` when `key` is not a string.
   * @throws `RangeError` when `key` is empty.
   */
  delete(key: string): Promise<void>;

  /** Delete every key stored for this task instance. */
  clear(): Promise<void>;
}

/** Error thrown by {@link TaskClient.getVariableOrThrow}. */
export class VariableNotFoundError extends Error {
  constructor(public readonly key: string) {
    super(`Variable not found: ${key}`);
    this.name = "VariableNotFoundError";
  }
}

/** Error thrown by {@link TaskClient.getConnectionOrThrow}. */
export class ConnectionNotFoundError extends Error {
  constructor(public readonly connId: string) {
    super(`Connection not found: ${connId}`);
    this.name = "ConnectionNotFoundError";
  }
}