src/sdk/trigger-dag-run.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 { JsonValue } from "./client-types.js";
import { isPlainRecord } from "./dag.js";
import { getBooleanEnv } from "./env.js";
import { brandOperator, type Operator } from "./operator.js";
import { toPlainJson } from "./plain-json.js";
import { executeTriggerDagRun, resumeTriggerDagRun } from "./trigger-dag-run-execute.js";
/** A Dag run state, as `allowedStates` and `failedStates` name one. */
export type DagRunState = "queued" | "running" | "success" | "failed";
const DAG_RUN_STATES: ReadonlySet<string> = new Set<DagRunState>([
"queued",
"running",
"success",
"failed",
]);
/** The `TriggerDagRunOperator` options, named as TypeScript spells them. */
export interface TriggerDagRunSpec {
/** Identifier of the Dag to trigger. */
readonly dagId: string;
/** Run ID for the triggered run; generated from the trigger time when unset. */
readonly runId?: string;
/** Configuration the triggered run is started with. */
readonly conf?: Readonly<Record<string, JsonValue>>;
/** Clear an existing run with the same ID instead of failing. */
readonly resetDagRun?: boolean;
/** Hold this task open until the triggered run finishes. */
readonly waitForCompletion?: boolean;
/** Seconds between checks while waiting. Defaults to 60. */
readonly pokeInterval?: number;
/** Run states that count as success when waiting. Defaults to `["success"]`. */
readonly allowedStates?: readonly DagRunState[];
/** Run states that count as failure when waiting. Defaults to `["failed"]`. */
readonly failedStates?: readonly DagRunState[];
/** Skip rather than fail when the run already exists. */
readonly skipWhenAlreadyExists?: boolean;
/** Fail rather than trigger when the target Dag is paused. */
readonly failWhenDagIsPaused?: boolean;
/** Note recorded against the triggered run. */
readonly note?: string;
/**
* While waiting, free the worker slot and defer to `DagStateTrigger`, which
* the Python triggerer runs. Defaults to `[operators] default_deferrable`, or
* to false when that is unset.
*/
readonly deferrable?: boolean;
}
/** Internal: a trigger task's options with `TriggerDagRunOperator`'s defaults applied. */
export interface TriggerDagRunTask extends Operator<void, void> {
readonly dagId: string;
readonly runId: string | undefined;
readonly conf: Readonly<Record<string, JsonValue>> | undefined;
readonly resetDagRun: boolean;
readonly waitForCompletion: boolean;
readonly pokeInterval: number;
readonly allowedStates: readonly DagRunState[];
readonly failedStates: readonly DagRunState[];
readonly skipWhenAlreadyExists: boolean;
readonly failWhenDagIsPaused: boolean;
readonly note: string | undefined;
readonly deferrable: boolean;
}
const OPTION_NAMES: ReadonlySet<string> = new Set<keyof TriggerDagRunSpec>([
"dagId",
"runId",
"conf",
"resetDagRun",
"waitForCompletion",
"pokeInterval",
"allowedStates",
"failedStates",
"skipWhenAlreadyExists",
"failWhenDagIsPaused",
"note",
"deferrable",
]);
function checkStates(name: string, states: unknown): DagRunState[] | undefined {
if (states === undefined) return undefined;
if (!Array.isArray(states)) {
throw new Error(`triggerDagRun(...) option "${name}" must be an array of Dag run states`);
}
for (const state of states) {
if (typeof state !== "string" || !DAG_RUN_STATES.has(state)) {
throw new Error(
`triggerDagRun(...) option "${name}" holds ${JSON.stringify(state)}, which is not a Dag ` +
`run state; use one of ${[...DAG_RUN_STATES].join(", ")}`,
);
}
}
return [...(states as DagRunState[])];
}
function checkType(name: string, value: unknown, type: "string" | "boolean"): void {
if (value !== undefined && typeof value !== type) {
throw new Error(`triggerDagRun(...) option "${name}" must be a ${type}`);
}
}
/**
* A task that triggers another Dag's run, passed to `dag.task` in place of a handler.
*
* ```ts
* dag.task(triggerDagRun({ dagId: "downstream_etl" }), { taskId: "trigger_downstream" })();
* ```
*/
export function triggerDagRun(spec: TriggerDagRunSpec): TriggerDagRunTask {
const options: unknown = spec;
if (!isPlainRecord(options)) {
throw new Error("triggerDagRun(...) takes an options object");
}
for (const name of Object.keys(options)) {
if (!OPTION_NAMES.has(name)) throw new Error(`Unknown option "${name}" for triggerDagRun(...)`);
}
if (typeof options["dagId"] !== "string" || options["dagId"].length === 0) {
throw new Error("triggerDagRun(...) needs the dagId of the Dag to trigger");
}
const conf = options["conf"];
if (conf !== undefined && (typeof conf !== "object" || conf === null || Array.isArray(conf))) {
throw new Error('triggerDagRun(...) option "conf" must be an object');
}
checkType("runId", options["runId"], "string");
checkType("note", options["note"], "string");
for (const flag of [
"resetDagRun",
"waitForCompletion",
"skipWhenAlreadyExists",
"failWhenDagIsPaused",
"deferrable",
]) {
checkType(flag, options[flag], "boolean");
}
const pokeInterval = options["pokeInterval"] ?? 60;
if (typeof pokeInterval !== "number" || !Number.isFinite(pokeInterval) || pokeInterval < 0) {
throw new Error('triggerDagRun(...) option "pokeInterval" must be a non-negative number');
}
const allowedStates = checkStates("allowedStates", options["allowedStates"]);
const failedStates = checkStates("failedStates", options["failedStates"]);
const task: TriggerDagRunTask = {
dagId: options["dagId"],
runId: (options["runId"] as string | undefined) || undefined,
conf: conf as TriggerDagRunTask["conf"],
resetDagRun: options["resetDagRun"] === true,
waitForCompletion: options["waitForCompletion"] === true,
pokeInterval,
// An empty `failedStates` is kept, as Python keeps it.
allowedStates: allowedStates?.length ? allowedStates : ["success"],
failedStates: failedStates ?? ["failed"],
skipWhenAlreadyExists: options["skipWhenAlreadyExists"] === true,
failWhenDagIsPaused: options["failWhenDagIsPaused"] === true,
note: (options["note"] as string | undefined) || undefined,
deferrable:
(options["deferrable"] as boolean | undefined) ??
getBooleanEnv("AIRFLOW__OPERATORS__DEFAULT_DEFERRABLE", false),
operatorName: "TriggerDagRunOperator",
requiresTaskId: true,
label: "triggerDagRun",
taskIdExample: 'dag.task(triggerDagRun({ dagId: "..." }), { taskId: "trigger_downstream" })',
takesNoInputs: true,
serialize: (label) => {
if (task.conf !== undefined) toPlainJson(task.conf, `conf of ${label}`);
// Makes the UI draw the task as `TriggerDagRunOperator` with its link.
return {
ui_color: "#ffefeb",
_operator_extra_links: { "Triggered DAG": "_link_TriggerDagRunLink" },
};
},
getDagDependencies: () => [{ target: task.dagId, dependencyType: "trigger" }],
execute: (op) => executeTriggerDagRun(task, op),
executeComplete: (op, event) => resumeTriggerDagRun(task, op, event),
};
return brandOperator(task);
}