henry3260 commented on code in PR #71188: URL: https://github.com/apache/airflow/pull/71188#discussion_r4076472648
########## java-sdk/sdk/src/main/kotlin/org/apache/airflow/sdk/internal/ArgValues.kt: ########## @@ -0,0 +1,198 @@ +/* + * 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. + */ + +@file:Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN") + +package org.apache.airflow.sdk.internal + +import com.fasterxml.jackson.databind.ObjectMapper +import com.fasterxml.jackson.databind.json.JsonMapper +import org.apache.airflow.sdk.Client +import org.apache.airflow.sdk.MissingXComException +import org.apache.airflow.sdk.TaskInput +import org.apache.airflow.sdk.execution.ArgBinding +import java.lang.reflect.Field +import java.lang.reflect.Type + +/** + * @suppress + * + * Resolves a task's data parameters from the arg bindings the supervisor + * delivered, and decodes their raw wire values into the declared types. Public + * so that processor-generated task classes can call it; not user-facing API. + * + * The bindings come from the Python `@task.stub` call site, which is also the + * graph the scheduler ordered the run by. Flat data parameters resolve the + * binding at their position (through [TaskArgs]); [TaskInput] fields resolve + * bindings by name. + */ +object ArgValues { + private val mapper: ObjectMapper = JsonMapper.builder().build().findAndRegisterModules() + + /** + * Materializes a [TaskInput] with every field bound by the argument name it + * claims. + * + * The single populator behind both authoring APIs — the annotation processor + * emits a call to it for a `@Builder.Task` [TaskInput] parameter, and + * [org.apache.airflow.sdk.InputTask] calls it before handing the input to a + * task written against the interface. + * + * @throws IllegalArgumentException if the input cannot be populated. + * @throws MissingXComException if a primitive field's binding resolves to + * nothing. + */ + @JvmStatic + fun <I : TaskInput> bindInput( + client: Client, + type: Class<I>, + ): I { + val input = newInput(type) + val arguments = ArgIndex(client.argBindings) + bindableFields(type).forEach { field -> field.set(input, resolveField(client, arguments, field)) } Review Comment: This is the whole binding path: one pass over the fields, each looking for an argument of its own name. There is no fallback for a sole unclaimed argument. It is not consistent in Python and Go. Python and Go can take a single argument as a whole value Maybe we should add it? ########## java-sdk/sdk/src/main/kotlin/org/apache/airflow/sdk/internal/ArgValues.kt: ########## @@ -0,0 +1,198 @@ +/* + * 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. + */ + +@file:Suppress("PLATFORM_CLASS_MAPPED_TO_KOTLIN") + +package org.apache.airflow.sdk.internal + +import com.fasterxml.jackson.databind.ObjectMapper +import com.fasterxml.jackson.databind.json.JsonMapper +import org.apache.airflow.sdk.Client +import org.apache.airflow.sdk.MissingXComException +import org.apache.airflow.sdk.TaskInput +import org.apache.airflow.sdk.execution.ArgBinding +import java.lang.reflect.Field +import java.lang.reflect.Type + +/** + * @suppress + * + * Resolves a task's data parameters from the arg bindings the supervisor + * delivered, and decodes their raw wire values into the declared types. Public + * so that processor-generated task classes can call it; not user-facing API. + * + * The bindings come from the Python `@task.stub` call site, which is also the + * graph the scheduler ordered the run by. Flat data parameters resolve the + * binding at their position (through [TaskArgs]); [TaskInput] fields resolve + * bindings by name. + */ +object ArgValues { + private val mapper: ObjectMapper = JsonMapper.builder().build().findAndRegisterModules() + + /** + * Materializes a [TaskInput] with every field bound by the argument name it + * claims. + * + * The single populator behind both authoring APIs — the annotation processor + * emits a call to it for a `@Builder.Task` [TaskInput] parameter, and + * [org.apache.airflow.sdk.InputTask] calls it before handing the input to a + * task written against the interface. + * + * @throws IllegalArgumentException if the input cannot be populated. + * @throws MissingXComException if a primitive field's binding resolves to + * nothing. + */ + @JvmStatic + fun <I : TaskInput> bindInput( + client: Client, + type: Class<I>, + ): I { + val input = newInput(type) + val arguments = ArgIndex(client.argBindings) + bindableFields(type).forEach { field -> field.set(input, resolveField(client, arguments, field)) } + return input + } + + /** + * Resolves the data parameter at [position] into [type], passing null + * through. Backs [TaskArgs]; a parameter that cannot be null goes through + * [TaskArgs.require], which turns null into [missing]. [TaskArgs.of] has + * already matched the declared parameters against the bindings, so a + * position always names one. + * + * @param position Zero-based index among the task's data parameters, in + * declaration order. + */ + internal fun valueAt( + client: Client, + position: Int, + type: Type, + ): Any? = decode(client.resolveBinding(client.argBindings[position]), type) + + /** + * Builds the failure for a binding that resolved to nothing where a value is + * required, naming [target] — the stub argument, or the [TaskInput] field + * that claimed it. + */ + internal fun missing( + binding: ArgBinding, + taskId: String, + target: String = binding.name, + ): MissingXComException = + when (binding) { + is ArgBinding.XCom -> MissingXComException(binding.taskId, target) + is ArgBinding.Literal -> + MissingXComException( + "Task parameter '$target' of task '$taskId' is bound to a null literal, but has a primitive " + + "type that cannot be null; declare a boxed type (e.g. Integer instead of int) to receive null.", + ) + } + + /** + * Resolves one [TaskInput] field from the argument it claims. A primitive + * field cannot hold null, so it fails with a clear [MissingXComException] + * when the binding resolves to nothing; boxed and reference fields receive + * null instead. + */ + private fun resolveField( + client: Client, + arguments: ArgIndex, + field: Field, + ): Any? { + val argName = argNameOf(field) + val binding = arguments.find(argName, pinned = isPinned(field)) + if (!field.type.isPrimitive) return binding?.let { decode(client.resolveBinding(it), field.genericType) } + + checkNotNull(binding) { Review Comment: Is this divergence intended? Here a primitive field fails instead, while a boxed one returns null one line above. If that is intended, it is worth a line in ADR-0007 ########## java-sdk/sdk/src/main/kotlin/org/apache/airflow/sdk/execution/ArgBinding.kt: ########## @@ -0,0 +1,77 @@ +/* + * 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. + */ + +package org.apache.airflow.sdk.execution + +/** + * One stub-task argument bound at the `@task.stub` TaskFlow call site in the + * Python Dag file, delivered via `TIRunContext.arg_bindings`. + * + * The supervisor schema models this as a `kind`-discriminated union + * (`XComArgBinding` / `LiteralArgBinding`), which jsonSchema2Pojo cannot + * express as a typed field — the generated `TIRunContext.argBindings` is a + * plain `Object` holding the msgpack-decoded list of maps — so this hand- + * written decoder materializes the typed view. + */ +internal sealed class ArgBinding { + abstract val name: String + + internal data class XCom( + override val name: String, + val taskId: String, + val mapIndex: Int, + val elementIndex: Int?, + ) : ArgBinding() + + internal data class Literal( + override val name: String, + val value: Any?, + ) : ArgBinding() +} + +/** + * Decodes the raw `TIRunContext.argBindings` payload into a list of bindings + * preserving the stub signature's parameter order — flat task parameters + * bind by that position, input-bundle fields by [ArgBinding.name]. + * + * @throws IllegalStateException on a malformed payload, an unsupported + * binding kind, or a duplicate argument name; the task cannot bind its + * arguments correctly, so it must fail rather than run with wrong inputs. + */ +internal fun decodeArgBindings(raw: Any?): List<ArgBinding> { + if (raw == null) return emptyList() + check(raw is List<*>) { "arg_bindings payload is not a list: ${raw.javaClass.name}" } + val seen = mutableSetOf<String>() + return raw.map { entry -> + check(entry is Map<*, *>) { "arg_bindings entry is not a map: $entry" } + val name = checkNotNull(entry["name"] as? String) { "arg_bindings entry has no name: $entry" } + check(seen.add(name)) { "arg_bindings entries have duplicate name: '$name'" } + when (val kind = entry["kind"]) { + "literal" -> ArgBinding.Literal(name = name, value = entry["value"]) Review Comment: `from_default` is not read here, so a defaulted stub parameter still counts toward the binding list. Without it, `TaskArgs.of`'s `check(bound == declared)` sees one more argument than the method declares -- 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]
