pierrejeambrun commented on code in PR #67908: URL: https://github.com/apache/airflow/pull/67908#discussion_r3414088225
########## ts-sdk/src/client-types.ts: ########## @@ -0,0 +1,68 @@ +/*! + * 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. + */ + +/** JSON-compatible value accepted by Airflow for XCom payloads. */ +export type JsonValue = + | string + | number + | boolean + | null + | JsonValue[] + | { [key: string]: 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. + */ +export interface GetXComOpts { + key: string; + dagId?: string; + runId?: string; + taskId?: string; + mapIndex?: number | null; + includePriorDates?: boolean; +} + +/** + * Options for pushing an XCom value. + * + * `dagId`, `taskId`, and `runId` default to the running task's context. + */ +export interface SetXComOpts { + key: string; + value: JsonValue; + dagId?: string; + runId?: string; + taskId?: string; + mapIndex?: number | null; +} + +/** Airflow Connection details returned by a task client. */ +export interface ConnectionResult { + connId: string; + connType: string; Review Comment: `connId`/`connType` diverge slightly from the sibling SDKs — Java's `Connection` uses `id`/`type`, Go's uses `ID`/`Type`. The camelCase-of-the-wire-name reads clearly on its own so I don't feel strongly, but since these public surfaces are meant to mirror each other, could we make it a conscious choice? Either align to `id`/`type`, or keep the `conn` prefix and note why it's preferred for TS. ########## ts-sdk/src/registry.ts: ########## @@ -0,0 +1,90 @@ +/*! + * 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 { TaskHandler } from "./task.js"; + +/** Identifies the Airflow task handled by a TypeScript function. */ +export interface TaskRegistration { + /** Identifier of the Dag containing this task. */ + dagId: string; + /** Airflow task ID, including any TaskGroup prefix. */ + taskId: string; Review Comment: Tiny nit: `TaskContext` and `TaskHandlerArgs` are `readonly`, but `TaskRegistration`'s fields aren't — could we make them `readonly` too for consistency? ```suggestion /** Identifier of the Dag containing this task. */ readonly dagId: string; /** Airflow task ID, including any TaskGroup prefix. */ readonly taskId: string; ``` ########## ts-sdk/src/task.ts: ########## @@ -0,0 +1,63 @@ +/*! + * 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 — types every user task handler sees. + +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; + /** Stable Airflow task instance identifier. */ + readonly taskInstanceId: string; Review Comment: Small consistency check: neither the Go SDK's `TaskInstance` (`DagID`/`RunID`/`TaskID`/`MapIndex`/`TryNumber`) nor the Java SDK's `Context.TaskInstance` exposes a raw task-instance id — they locate a TI by the dag/run/task/map tuple. Is `taskInstanceId` needed on the public context here (for coordinator XCom addressing, maybe?), or could it drop to stay aligned with the other SDKs? Fine either way — just want it to be an intentional divergence rather than drift. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
