This is an automated email from the ASF dual-hosted git repository.
choo121600 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 2017b407666 AGENTS.md: require translating domain-layer exceptions to
`HTTPException` at FastAPI route boundaries (#67221)
2017b407666 is described below
commit 2017b407666ecec13dee23db83d3e773d9db8928
Author: Jason(Zhe-You) Liu <[email protected]>
AuthorDate: Wed May 20 14:32:18 2026 +0800
AGENTS.md: require translating domain-layer exceptions to `HTTPException`
at FastAPI route boundaries (#67221)
---
AGENTS.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/AGENTS.md b/AGENTS.md
index 629b2cbb7a3..92fab69a65b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -137,6 +137,7 @@ reported as such are described in "What is NOT considered a
security vulnerabili
- Imports at top of file. Valid exceptions: circular imports, lazy loading for
worker isolation, `TYPE_CHECKING` blocks.
- Guard heavy type-only imports (e.g., `kubernetes.client`) with
`TYPE_CHECKING` in multi-process code paths.
- Define dedicated exception classes or use existing exceptions such as
`ValueError` instead of raising the broad `AirflowException` directly. Each
error case should have a specific exception type that conveys what went wrong.
+- Translate domain-layer exceptions to `HTTPException` at FastAPI route
boundaries. In `airflow-core/src/airflow/core_api/` route handlers, catch
errors raised by domain code (e.g., `ValueError` from
`airflow.state.metastore.MetastoreStateBackend` for a missing row or invalid
input) and re-raise as `HTTPException` with the right status (`404` for
not-found, `400` for invalid input). Otherwise they propagate as `500 Internal
Server Error`, leaking internals and misleading clients.
- Bulk `DELETE`/`UPDATE` in the scheduler loop or any synchronous interval
task (e.g. `call_regular_interval` callbacks) must be batched with `LIMIT` and
committed between batches — never issue a single unbounded bulk write against a
user-driven table. Unbounded bulk writes hold row locks for the entire
transaction (blocking concurrent writers) and stall the scheduler main loop.
Filter columns used by the cleanup must be indexed. Follow the batching pattern
in `airflow-core/src/airflow/u [...]
- Name functions and methods with action verbs: `get_`, `extract_`, `find_`,
`compute_`, `build_`, etc. Avoid noun-only names like `_serialize_keys` or
`_base_names` — they read as attributes, not callables. Predicates (`is_`,
`has_`) are the one exception.
- Apache License header on all new files (prek enforces this).
