async-task-api-worker 0.1.0rc2__tar.gz → 0.1.0rc3__tar.gz

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.1.0-rc.3](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.2...async-task-api-worker-v0.1.0-rc.3) (2026-10-23)
+
+
+### Bug Fixes
+
+* **sdk:** close an already closed channel quietly and tie the close budgets together ([51e0281](https://github.com/IA-Generative/async-api/commit/51e0281dfe7ea22686f0967d4c8ce55efa470d0e))
+* **sdk:** name the invalid settings instead of quoting pydantic's text about them ([df6c747](https://github.com/IA-Generative/async-api/commit/df6c7475464600f31f767997269d3f86b1cf432e))
+* **sdk:** treat a pydantic validation error in a startup hook as a configuration error ([5e98af1](https://github.com/IA-Generative/async-api/commit/5e98af109a027fc2903a3f98d5d0028f936efbba))
+
 ## [0.1.0-rc.2](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.1...async-task-api-worker-v0.1.0-rc.2) (2026-10-23)
 
 

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: async-task-api-worker
-Version: 0.1.0-rc.2
+Version: 0.1.0-rc.3
 Summary: SDK to write workers for the AsyncTaskAPI platform: protocol models, runtime and conformance kit.
 Project-URL: Repository, https://github.com/IA-Generative/async-api
 License: MIT
@@ -77,6 +77,11 @@ process is stopped and `await worker.serve()` serves from an existing event loop
 - The settings are read and validated first: an invalid configuration, or a task timeout that does not fit under the
   broker's consumer timeout (`task timeout + WORKER_RETRY_BACKOFF_MAX_S + 60 s < WORKER_CONSUMER_TIMEOUT_S`), exits with
   code 2 before any connection. Exit codes: 0 clean stop, 1 failure, 2 configuration or usage error.
+- A pydantic `ValidationError` raised by a startup hook (a settings class of your own, say) is a configuration error too:
+  one line naming the invalid fields, never their values (and `<Model> (a model-level check failed)` for a check that
+  belongs to no field), exit code 2. In job mode that fails the Job without a retry. So a startup hook must only validate
+  **configuration**: a hook that validates external data (a downloaded document, a response) must catch its own errors and
+  raise a `FatalError` or `RetryableError` from the task, where the task-level error model applies.
 - The queues are declared durable and with no arguments (the broker decides their type and policies), and consumed with
   manual acknowledgements: a task is acked only after its result is published.
 - SIGTERM or SIGINT stops consuming, lets the in-flight tasks finish within `WORKER_SHUTDOWN_GRACE_S` (default 25 s),

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/README.md

@@ -56,6 +56,11 @@ process is stopped and `await worker.serve()` serves from an existing event loop
 - The settings are read and validated first: an invalid configuration, or a task timeout that does not fit under the
   broker's consumer timeout (`task timeout + WORKER_RETRY_BACKOFF_MAX_S + 60 s < WORKER_CONSUMER_TIMEOUT_S`), exits with
   code 2 before any connection. Exit codes: 0 clean stop, 1 failure, 2 configuration or usage error.
+- A pydantic `ValidationError` raised by a startup hook (a settings class of your own, say) is a configuration error too:
+  one line naming the invalid fields, never their values (and `<Model> (a model-level check failed)` for a check that
+  belongs to no field), exit code 2. In job mode that fails the Job without a retry. So a startup hook must only validate
+  **configuration**: a hook that validates external data (a downloaded document, a response) must catch its own errors and
+  raise a `FatalError` or `RetryableError` from the task, where the task-level error model applies.
 - The queues are declared durable and with no arguments (the broker decides their type and policies), and consumed with
   manual acknowledgements: a task is acked only after its result is published.
 - SIGTERM or SIGINT stops consuming, lets the in-flight tasks finish within `WORKER_SHUTDOWN_GRACE_S` (default 25 s),

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "async-task-api-worker"
-version = "0.1.0-rc.2"
+version = "0.1.0-rc.3"
 description = "SDK to write workers for the AsyncTaskAPI platform: protocol models, runtime and conformance kit."
 readme = "README.md"
 license = { text = "MIT" }

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/src/async_task_api_worker/_runtime/amqp_transport.py

@@ -217,6 +217,8 @@ class AmqpTransport:
         self._queue = None
         if connection is None:
             return
+        # ``close_timeout_s`` (the channels' share plus the connection's) is the whole budget of this method, and it
+        # must stay within the lifecycle's own bound on ``close()``: both default to ``CLOSE_TIMEOUT_S``.
         channels_timeout_s = self._close_timeout_s * _CHANNELS_SHARE
         try:
             async with asyncio.timeout(channels_timeout_s):
@@ -231,8 +233,14 @@ class AmqpTransport:
 
     @staticmethod
     async def _close_channel(channel: AbstractChannel) -> None:
+        if channel.is_closed:
+            # A robust channel reports itself closed while the connection reconnects: nothing to close or wait for.
+            _LOGGER.debug("A channel was already closed (an outage, most likely).")
+            return
         try:
             await channel.close()
+        except ChannelInvalidStateError:
+            _LOGGER.debug("A channel became invalid while closing (an outage, most likely).")
         except Exception:
             _LOGGER.warning("Closing a channel failed: closing the connection anyway.", exc_info=True)
 

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/src/async_task_api_worker/_runtime/lifecycle.py

@@ -28,9 +28,15 @@ from concurrent.futures import ThreadPoolExecutor
 from enum import Enum
 from typing import TYPE_CHECKING, Final, NoReturn
 
+from pydantic import ValidationError
+
 from async_task_api_worker._runtime.engine import Engine
 from async_task_api_worker._runtime.transport import CLOSE_TIMEOUT_S, Delivery, Transport, TransportUnavailableError
-from async_task_api_worker.errors import WorkerConfigurationError, WorkerDefinitionError
+from async_task_api_worker.errors import (
+    WorkerConfigurationError,
+    WorkerDefinitionError,
+    configuration_error_from_validation,
+)
 from async_task_api_worker.observability.health import HealthServer, RuntimeState
 from async_task_api_worker.observability.logging import configure_logging
 from async_task_api_worker.observability.loop_lag import EventLoopLagProbe
@@ -137,7 +143,7 @@ class Lifecycle:
                 await health.start()
                 loop_lag.start()
             for hook in self._worker._startup_hooks:
-                if not await self._until_stopped(hook()):
+                if not await self._run_startup_hook(hook):
                     break  # stopped during startup: nothing was consumed, drain and exit
                 started_hooks += 1
             if started_hooks == len(self._worker._startup_hooks) and await self._connect(settings):
@@ -226,6 +232,20 @@ class Lifecycle:
                 return True
         return False
 
+    async def _run_startup_hook(self, hook: Callable[[], Awaitable[None]]) -> bool:
+        """Run a startup hook. False when a stop came first.
+
+        A pydantic ``ValidationError`` from a hook (a settings class of its own, say) is a configuration error: one
+        line, exit code 2, and no value of the input in the message nor chained to it.
+        """
+        configuration_error: WorkerConfigurationError | None = None
+        try:
+            return await self._until_stopped(hook())
+        except ValidationError as error:
+            configuration_error = configuration_error_from_validation(error)
+        assert configuration_error is not None
+        raise configuration_error
+
     async def _until_stopped(self, work: Awaitable[object]) -> bool:
         """Run ``work``, cancelling it if a stop is requested first. False when it was cancelled by the stop.
 

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/src/async_task_api_worker/cli.py

@@ -8,8 +8,14 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import Final
 
+from pydantic import ValidationError
+
 from async_task_api_worker._runtime.lifecycle import EXIT_CONFIGURATION, EXIT_FAILURE, EXIT_OK, run_blocking
-from async_task_api_worker.errors import WorkerConfigurationError, WorkerDefinitionError
+from async_task_api_worker.errors import (
+    WorkerConfigurationError,
+    WorkerDefinitionError,
+    configuration_error_from_validation,
+)
 from async_task_api_worker.worker import Worker
 
 __all__ = ["EXIT_CONFIGURATION", "EXIT_FAILURE", "EXIT_OK", "load_worker", "main"]
@@ -31,6 +37,11 @@ def _working_directory_first() -> None:
         sys.path.insert(0, working_directory)
 
 
+def _configuration_target_error(where: str, error: ValidationError) -> TargetError:
+    """A pydantic ``ValidationError`` while loading is a configuration error: field names, never their values."""
+    return TargetError(f"Invalid worker configuration in {where}: {configuration_error_from_validation(error)}")
+
+
 def load_worker(target: str) -> Worker:
     """Import ``module:attr``: ``attr`` is a ``Worker`` or a zero-argument factory function returning one."""
     module_name, separator, attribute = target.partition(_TARGET_SEPARATOR)
@@ -46,6 +57,8 @@ def load_worker(target: str) -> Worker:
     except _DEFINITION_ERRORS as error:
         msg = f"Invalid worker definition in module {module_name!r}: {error}"
         raise TargetError(msg) from error
+    except ValidationError as error:
+        raise _configuration_target_error(f"module {module_name!r}", error) from None
     try:
         candidate = getattr(module, attribute)
     except AttributeError as error:
@@ -57,6 +70,8 @@ def load_worker(target: str) -> Worker:
         except _DEFINITION_ERRORS as error:
             msg = f"Invalid worker definition in {target!r}: {error}"
             raise TargetError(msg) from error
+        except ValidationError as error:
+            raise _configuration_target_error(repr(target), error) from None
         except TypeError as error:
             msg = f"{target!r} cannot be called without arguments: {error}"
             raise TargetError(msg) from error

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/src/async_task_api_worker/errors.py

@@ -6,6 +6,8 @@ from enum import StrEnum
 from types import MappingProxyType
 from typing import Final
 
+from pydantic import ValidationError
+
 _CODE_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[A-Z][A-Z0-9_]{2,63}$")
 _MIN_MESSAGE_LENGTH: Final[int] = 1
 MAX_MESSAGE_LENGTH: Final[int] = 500
@@ -114,3 +116,20 @@ class WorkerConfigurationError(Exception):
 
 class WorkerDefinitionError(Exception):
     """Invalid decorator usage, raised at import time."""
+
+
+def configuration_error_from_validation(error: ValidationError) -> WorkerConfigurationError:
+    """A configuration error for a pydantic ``ValidationError`` raised while setting the worker up (a hook, say).
+
+    The message names the invalid fields (``loc[0]``) and nothing else, never a value and never pydantic's ``msg``:
+    ``input`` can hold a whole settings dict, secrets included, and a validator written by the user can format the very
+    value it rejects. An issue with no location (a model-level check) is reported as a fixed text with the name of the
+    model (``error.title``). The caller adds the prefix. Build the error outside an ``except`` block and raise it
+    ``from None``, so that the original one, with its ``input``, is not chained to it.
+    """
+    issues = error.errors(include_input=False, include_url=False, include_context=False)
+    names = list(dict.fromkeys(str(issue["loc"][0]) for issue in issues if issue["loc"]))
+    parts = [", ".join(names)] if names else []
+    if any(not issue["loc"] for issue in issues):
+        parts.append(f"{error.title} (a model-level check failed)")
+    return WorkerConfigurationError("; ".join(parts))

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc3}/src/async_task_api_worker/settings.py

@@ -8,6 +8,7 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from async_task_api_worker.errors import WorkerConfigurationError
 
+_MISSING_TYPE: Final[str] = "missing"
 DEFAULT_WORKER_CONCURRENCY: Final[int] = 1
 DEFAULT_HEALTH_CHECK_HOST: Final[str] = "0.0.0.0"  # noqa: S104 - the probe must be reachable from the pod network
 DEFAULT_HEALTH_CHECK_PORT: Final[int] = 8083
@@ -116,12 +117,17 @@ class WorkerSettings(BaseSettings):
         try:
             return handler(data)
         except ValidationError as error:
-            # Never echo ``input`` or the raw error: BROKER_URL carries credentials.
+            # THE RULE: the message is built from field names, never from a value or from pydantic's text about one. A
+            # field-level ``msg`` can quote the input (a validator that formats it, BROKER_URL above all, which carries
+            # credentials), so for those only the setting name and whether it is missing are said. A model-level ``msg``
+            # (no location) is the text of one of OUR validators, written without a value. That is deliberate: the
+            # user's validators, handled by ``configuration_error_from_validation``, can format theirs, so that one
+            # never uses a ``msg``.
             problems = "; ".join(
-                f"{location}: {issue['msg']}"
+                f"{location} is {'missing' if issue['type'] == _MISSING_TYPE else 'invalid'}"
                 if (location := ".".join(map(str, issue["loc"])).upper())
                 else issue["msg"]
-                for issue in error.errors()
+                for issue in error.errors(include_input=False, include_url=False, include_context=False)
             )
             msg = f"Invalid worker settings: {problems}"
             raise WorkerConfigurationError(msg) from None