src/hitl/spec.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.
 */

// Human-in-the-loop tasks: `hitl(...)` and `approval(...)`, which mirror `HITLOperator` and
// `ApprovalOperator` in the standard provider. A factory is the Python operator's name without
// "Operator", and an option is the Python keyword argument in camelCase.

import { getArgNames } from "../sdk/arg-names.js";
import type { JsonValue } from "../sdk/client-types.js";
import { isPlainRecord } from "../sdk/dag.js";
import type { Operator } from "../sdk/operator.js";
import { toPlainJson } from "../sdk/plain-json.js";
import { APPROVE, createHITLTask, REJECT } from "./operator.js";

/** A user allowed to respond, as Airflow's auth manager identifies them. */
export type HITLUser = {
  readonly id: string;
  readonly name: string;
};

/** Text shown to the responder: fixed, or computed from the task's inputs on its first run. */
export type HITLText<TArgs, TText extends string | null = string> =
  TText | ((args: TArgs) => TText | Promise<TText>);

/** One form field on the Required Actions page, as Python's `Param` serializes. */
export interface HITLParam {
  /**
   * Pre-filled value. When `responseTimeout` passes and `defaults` is set, the scheduler records
   * each param's `value` as the response, so it is also the value used on timeout.
   */
  readonly value: JsonValue;
  readonly description?: string;
  /**
   * JSON Schema. The form renders `type`, `enum`, `format`, `items`, `minimum`, `maximum`,
   * `minLength`, `maxLength` and `values_display`.
   */
  readonly schema?: Readonly<Record<string, JsonValue>>;
}

/**
 * The options both HITL tasks take.
 *
 * `TSubjectArgs` and `TBodyArgs` are the inputs `subject` and `body` read when they are
 * functions; the task takes both.
 */
interface HITLBaseSpec<TSubjectArgs extends object | void, TBodyArgs extends object | void> {
  /** Headline of the request. */
  readonly subject: HITLText<TSubjectArgs>;
  /** Markdown shown below the headline. */
  readonly body?: HITLText<TBodyArgs, string | null>;
  /** Users allowed to respond. Anyone who can act on the task may respond when unset. */
  readonly assignedUsers?: readonly HITLUser[];
  /** Form fields the responder fills in, by name. Their answers are the result's `paramsInput`. */
  readonly params?: Readonly<Record<string, HITLParam>>;
  /**
   * Whole seconds to wait for a response, since TypeScript has no timedelta. Waits indefinitely
   * when unset. Use this rather than `executionTimeout`, which a HITL task does not enforce.
   */
  readonly responseTimeout?: number;
}

/** The `HITLOperator` options, named as TypeScript spells them. */
export interface HITLSpec<
  TSubjectArgs extends object | void = void,
  TBodyArgs extends object | void = TSubjectArgs,
> extends HITLBaseSpec<TSubjectArgs, TBodyArgs> {
  /** What the responder chooses from. */
  readonly options: readonly string[];
  /** Options chosen for the responder when `responseTimeout` passes without a response. */
  readonly defaults?: readonly string[];
  /** Whether more than one option may be chosen. */
  readonly multiple?: boolean;
}

/** The `ApprovalOperator` options, named as TypeScript spells them. */
export interface ApprovalSpec<
  TSubjectArgs extends object | void = void,
  TBodyArgs extends object | void = TSubjectArgs,
> extends HITLBaseSpec<TSubjectArgs, TBodyArgs> {
  /** The answer given for the responder when `responseTimeout` passes without a response. */
  readonly defaults?: "Approve" | "Reject";
  /**
   * On "Reject", skip every task downstream rather than only the tasks directly downstream.
   * Defaults to false.
   */
  readonly ignoreDownstreamTriggerRules?: boolean;
  /**
   * On "Reject", fail this task rather than skip what follows it. Defaults to false, so a
   * rejection succeeds. A retry asks the reviewer again, so `retries` with this option repeats
   * the request on each attempt.
   */
  readonly failOnReject?: boolean;
}

/**
 * The response a HITL task pushes to XCom and passes downstream.
 *
 * The keys are those of Python's `HITLTriggerEventSuccessPayload` in camelCase, and `respondedAt`
 * is an ISO-8601 string where Python's is a datetime. Airflow's own records of the request and
 * the response keep their snake_case keys.
 */
export type HITLResult = {
  readonly chosenOptions: string[];
  readonly paramsInput: Record<string, JsonValue>;
  /** ISO-8601 UTC instant of the response, to the millisecond. */
  readonly respondedAt: string;
  /** `null` when the defaults were applied on timeout. */
  readonly respondedByUser: HITLUser | null;
  /** Whether the defaults were applied because the response timeout passed. */
  readonly timedout: boolean;
};

/**
 * What `hitl(...)` and `approval(...)` return, to pass to `dag.task(...)`: the options, checked
 * and with their defaults applied.
 */
export interface HITLTask<TArgs extends object | void = void> extends Operator<TArgs, HITLResult> {
  readonly kind: "choice" | "approval";
  readonly subject: HITLText<TArgs>;
  readonly body: HITLText<TArgs, string | null> | undefined;
  /** @internal The `withArgNames` renames of `subject` and `body`, merged. */
  readonly argNames: ReadonlyMap<string, string>;
  readonly options: readonly string[];
  readonly defaults: readonly string[] | undefined;
  readonly multiple: boolean;
  readonly assignedUsers: readonly HITLUser[];
  readonly params: Readonly<Record<string, HITLParam>>;
  readonly responseTimeout: number | undefined;
  /** Only an approval acts on this. */
  readonly ignoreDownstreamTriggerRules: boolean;
  /** Only an approval acts on this. */
  readonly failOnReject: boolean;
}

/** What {@link createHITLTask} builds a task from: a task without its operator members. */
export type HITLTaskFields = Omit<HITLTask<never>, keyof Operator<never, HITLResult>>;

/**
 * The inputs a task takes when its subject reads `TSubject` and its body reads `TBody`: both, or
 * whichever is read. Bracketed, so that `void` is not distributed over.
 */
export type HITLTextArgs<TSubject, TBody> = [TSubject, TBody] extends [void, void]
  ? void
  : [TSubject] extends [void]
    ? TBody
    : [TBody] extends [void]
      ? TSubject
      : TSubject & TBody;

const SHARED_OPTION_NAMES = ["subject", "body", "assignedUsers", "params", "responseTimeout"];
const HITL_OPTION_NAMES: ReadonlySet<string> = new Set([
  ...SHARED_OPTION_NAMES,
  "options",
  "defaults",
  "multiple",
]);
const APPROVAL_OPTION_NAMES: ReadonlySet<string> = new Set([
  ...SHARED_OPTION_NAMES,
  "defaults",
  "ignoreDownstreamTriggerRules",
  "failOnReject",
]);
const PARAM_KEYS: ReadonlySet<string> = new Set(["value", "description", "schema"]);

/**
 * A task that asks a human to choose, passed to `dag.task` in place of a handler.
 *
 * Its first run creates the request and parks the task in `awaiting_input`, freeing the worker;
 * a later run resumes with the response, pushes it to XCom as a {@link HITLResult}, and
 * succeeds. The choice never skips or fails anything by itself.
 *
 * ```ts
 * dag.task("choose_region", hitl({
 *   subject: ({ report }: { report: Report }) => `Pick a region for ${report.version}`,
 *   options: ["us", "eu"],
 * }))({ report });
 * ```
 */
export function hitl<
  TSubjectArgs extends object | void = void,
  TBodyArgs extends object | void = TSubjectArgs,
>(spec: HITLSpec<TSubjectArgs, TBodyArgs>): HITLTask<HITLTextArgs<TSubjectArgs, TBodyArgs>> {
  const given = checkSpec("hitl", spec, HITL_OPTION_NAMES);
  const subject = checkSubject("hitl", given["subject"]);
  const body = checkBody("hitl", given["body"]);
  const options = checkOptions(given["options"]);
  const multiple = checkMultiple(given["multiple"]);
  const defaults = checkDefaults(given["defaults"], options, multiple);

  return createHITLTask({
    kind: "choice",
    subject,
    body,
    argNames: mergeArgNames("hitl", subject, body),
    options,
    defaults,
    multiple,
    assignedUsers: checkAssignedUsers("hitl", given["assignedUsers"]),
    params: checkParams("hitl", given["params"]),
    responseTimeout: checkResponseTimeout("hitl", given["responseTimeout"]),
    ignoreDownstreamTriggerRules: false,
    failOnReject: false,
  });
}

/**
 * A task that asks a human to approve or reject, passed to `dag.task` in place of a handler.
 *
 * Offers exactly "Approve" and "Reject", which is what the Airflow UI shows as an approval. On
 * "Reject" it skips what follows, or fails when {@link ApprovalSpec.failOnReject} is set.
 *
 * ```ts
 * dag.task("sign_off", approval({ subject: "Ship it?" }))().before(publish());
 * ```
 */
export function approval<
  TSubjectArgs extends object | void = void,
  TBodyArgs extends object | void = TSubjectArgs,
>(spec: ApprovalSpec<TSubjectArgs, TBodyArgs>): HITLTask<HITLTextArgs<TSubjectArgs, TBodyArgs>> {
  const given = checkSpec("approval", spec, APPROVAL_OPTION_NAMES);
  const subject = checkSubject("approval", given["subject"]);
  const body = checkBody("approval", given["body"]);

  return createHITLTask({
    kind: "approval",
    subject,
    body,
    argNames: mergeArgNames("approval", subject, body),
    options: [APPROVE, REJECT],
    defaults: checkApprovalDefault(given["defaults"]),
    multiple: false,
    assignedUsers: checkAssignedUsers("approval", given["assignedUsers"]),
    params: checkParams("approval", given["params"]),
    responseTimeout: checkResponseTimeout("approval", given["responseTimeout"]),
    ignoreDownstreamTriggerRules: checkFlag("approval", "ignoreDownstreamTriggerRules", given),
    failOnReject: checkFlag("approval", "failOnReject", given),
  });
}

// One checker per option. Each returns the option's value, or throws naming what is wrong.

function checkSpec(
  factory: string,
  spec: unknown,
  names: ReadonlySet<string>,
): Record<string, unknown> {
  if (!isPlainRecord(spec)) throw new Error(`${factory}(...) takes an options object`);
  for (const name of Object.keys(spec)) {
    if (!names.has(name)) throw new Error(`Unknown option "${name}" for ${factory}(...)`);
  }
  return spec;
}

function checkSubject(factory: string, value: unknown): HITLText<never> {
  if (typeof value === "function") return value as HITLText<never>;
  if (typeof value !== "string") {
    throw new Error(`${factory}(...) needs a "subject": a string, or a function returning one`);
  }
  if (value.length === 0) throw new Error(`${factory}(...) option "subject" cannot be empty`);
  return value;
}

function checkBody(factory: string, value: unknown): HITLText<never, string | null> | undefined {
  if (value === undefined || value === null) return undefined;
  if (typeof value === "string" || typeof value === "function") {
    return value as HITLText<never, string | null>;
  }
  throw new Error(`${factory}(...) option "body" must be a string, or a function returning one`);
}

/**
 * The `withArgNames` renames of the subject and the body, merged. Both texts read the one set of
 * inputs, so a name mapped to two different wire names has no single answer.
 */
function mergeArgNames(
  factory: string,
  subject: HITLText<never>,
  body: HITLText<never, string | null> | undefined,
): ReadonlyMap<string, string> {
  const subjectNames = typeof subject === "function" ? getArgNames(subject as never) : undefined;
  const bodyNames = typeof body === "function" ? getArgNames(body as never) : undefined;
  const merged = new Map(subjectNames);
  for (const [name, wireName] of bodyNames ?? []) {
    const existing = merged.get(name);
    if (existing !== undefined && existing !== wireName) {
      throw new Error(
        `${factory}(...) maps the input "${name}" to "${existing}" in its subject and to ` +
          `"${wireName}" in its body; use one name for it`,
      );
    }
    merged.set(name, wireName);
  }
  return merged;
}

function checkOptions(value: unknown): readonly string[] {
  if (!Array.isArray(value) || value.length === 0) {
    throw new Error('hitl(...) needs "options": a non-empty array of strings');
  }
  const seen = new Set<string>();
  for (const option of value) {
    if (typeof option !== "string" || option.length === 0) {
      throw new Error('hitl(...) option "options" holds a value that is not a non-empty string');
    }
    if (seen.has(option)) {
      throw new Error(`hitl(...) option "options" lists ${JSON.stringify(option)} twice`);
    }
    seen.add(option);
  }
  return Object.freeze([...seen]);
}

function checkMultiple(value: unknown): boolean {
  if (value === undefined) return false;
  if (typeof value === "boolean") return value;
  throw new Error('hitl(...) option "multiple" must be a boolean');
}

function checkDefaults(
  value: unknown,
  options: readonly string[],
  multiple: boolean,
): readonly string[] | undefined {
  if (value === undefined) return undefined;
  if (!Array.isArray(value) || value.length === 0) {
    throw new Error('hitl(...) option "defaults" must be a non-empty array of options');
  }
  const unknown = value.find((option) => !options.includes(option as string));
  if (unknown !== undefined) {
    throw new Error(
      `hitl(...) option "defaults" holds ${JSON.stringify(unknown)}, which is not one ` +
        `of the options ${JSON.stringify(options)}`,
    );
  }
  if (!multiple && value.length > 1) {
    throw new Error(`hitl(...) gives ${value.length} defaults, but "multiple" is not set`);
  }
  return Object.freeze([...(value as string[])]);
}

function checkApprovalDefault(value: unknown): readonly string[] | undefined {
  if (value === undefined) return undefined;
  if (value === APPROVE || value === REJECT) return Object.freeze([value]);
  throw new Error('approval(...) option "defaults" must be "Approve" or "Reject"');
}

function checkFlag(
  factory: string,
  name: "ignoreDownstreamTriggerRules" | "failOnReject",
  given: Record<string, unknown>,
): boolean {
  const value = given[name];
  if (value === undefined) return false;
  if (typeof value === "boolean") return value;
  throw new Error(`${factory}(...) option "${name}" must be a boolean`);
}

function checkResponseTimeout(factory: string, value: unknown): number | undefined {
  if (value === undefined) return undefined;
  if (Number.isInteger(value) && (value as number) > 0) return value as number;
  throw new Error(
    `${factory}(...) option "responseTimeout" must be a positive whole number of seconds`,
  );
}

function checkAssignedUsers(factory: string, value: unknown): readonly HITLUser[] {
  if (value === undefined) return Object.freeze([]);
  if (!Array.isArray(value)) {
    throw new Error(`${factory}(...) option "assignedUsers" must be an array of { id, name }`);
  }
  return Object.freeze(value.map((user: unknown) => checkAssignedUser(factory, user)));
}

function checkAssignedUser(factory: string, user: unknown): HITLUser {
  if (isAssignedUser(user)) return Object.freeze({ id: user.id, name: user.name });
  throw new Error(
    `${factory}(...) option "assignedUsers" holds ${JSON.stringify(user)}; each user is ` +
      "{ id, name } with a non-empty string id",
  );
}

/** `{ id, name }` with a non-empty string id, and nothing else. */
function isAssignedUser(user: unknown): user is HITLUser {
  if (!isPlainRecord(user)) return false;
  const { id, name, ...rest } = user;
  return (
    typeof id === "string" &&
    id.length > 0 &&
    typeof name === "string" &&
    Object.keys(rest).length === 0
  );
}

/** `HITLOperator.validate_params`, and a check that each param is one the form can carry. */
function checkParams(factory: string, value: unknown): Readonly<Record<string, HITLParam>> {
  if (value === undefined) return Object.freeze({});
  if (!isPlainRecord(value)) {
    throw new Error(`${factory}(...) option "params" must be an object of { value, ... } by name`);
  }
  if (Object.hasOwn(value, "_options")) {
    throw new Error(`${factory}(...) option "params": "_options" is not allowed in params`);
  }
  const params: Record<string, HITLParam> = {};
  for (const [name, param] of Object.entries(value)) {
    params[name] = checkParam(factory, name, param);
  }
  return Object.freeze(params);
}

function checkParam(factory: string, name: string, param: unknown): HITLParam {
  const label = `${factory}(...) param "${name}"`;
  if (!isPlainRecord(param)) throw new Error(`${label} must be an object of { value, ... }`);
  for (const key of Object.keys(param)) {
    if (!PARAM_KEYS.has(key)) throw new Error(`${label} has an unknown key "${key}"`);
  }
  if (param["value"] === undefined) throw new Error(`${label} needs a "value"`);
  const { description, schema } = param;
  if (description !== undefined && typeof description !== "string") {
    throw new Error(`${label} key "description" must be a string`);
  }
  if (schema !== undefined && !isPlainRecord(schema)) {
    throw new Error(`${label} key "schema" must be a JSON Schema object`);
  }
  return Object.freeze({
    value: toPlainJson(param["value"], `${label} key "value"`),
    ...(description !== undefined && { description }),
    ...(schema !== undefined && {
      schema: toPlainJson(schema, `${label} key "schema"`) as Record<string, JsonValue>,
    }),
  });
}