feat: comprehensive audit fixes and new modules (v0.2.0-M7)

P0 bug fixes:
- Add asyncio.Lock to InMemoryMessageBroker for concurrent-safe pub/sub
- Add asyncio.Lock to InMemoryPersistenceAdapter for concurrent-safe saga state

P1 improvements:
- Track background tasks during startup, cancel on stop()
- Add EventFailureStrategy (LOG/RAISE) to CommandBus event publishing
- Implement @controller_advice stereotype for global exception handling
- Wire @controller_advice handlers into ControllerRegistrar dispatch chain

P2 feature gaps:
- Add WebSocket support: @websocket_mapping, WebSocketSession, auto-discovery
- Add OAuth2 auto-configuration: resource server, auth server, client registration
- Add OAuth2ResourceServerFilter for JWKS-based Bearer token validation
- Add session management: HttpSession, SessionStore protocol, memory/Redis adapters
- Wire existing Value descriptor into Container field injection
- Implement @shell_method_availability for conditional command registration

P3 new modules:
- Add i18n module: MessageSource protocol, ResourceBundleMessageSource (YAML/JSON),
  AcceptHeaderLocaleResolver, FixedLocaleResolver, auto-configuration
- Add XML serialization: dict_to_xml/xml_to_dict converters, XMLResponse,
  Accept header content negotiation in controller dispatch
- Fix ASGI pathsend to use chunked 64KB reads instead of read_bytes()

Author: ancongui

pyproject.toml

@@ -143,12 +143,18 @@ server = "pyfly.server.auto_configuration:ServerAutoConfiguration"
 event-loop = "pyfly.server.auto_configuration:EventLoopAutoConfiguration"
 security-jwt = "pyfly.security.auto_configuration:JwtAutoConfiguration"
 security-password = "pyfly.security.auto_configuration:PasswordEncoderAutoConfiguration"
+oauth2-resource-server = "pyfly.security.auto_configuration:OAuth2ResourceServerAutoConfiguration"
+oauth2-authorization-server = "pyfly.security.auto_configuration:OAuth2AuthorizationServerAutoConfiguration"
+oauth2-client = "pyfly.security.auto_configuration:OAuth2ClientAutoConfiguration"
 scheduling = "pyfly.scheduling.auto_configuration:SchedulingAutoConfiguration"
 metrics = "pyfly.observability.auto_configuration:MetricsAutoConfiguration"
 tracing = "pyfly.observability.auto_configuration:TracingAutoConfiguration"
 actuator = "pyfly.actuator.auto_configuration:ActuatorAutoConfiguration"
 actuator-metrics = "pyfly.actuator.auto_configuration:MetricsActuatorAutoConfiguration"
 aop = "pyfly.aop.auto_configuration:AopAutoConfiguration"
+i18n = "pyfly.i18n.auto_configuration:I18nAutoConfiguration"
+session = "pyfly.session.auto_configuration:SessionStoreAutoConfiguration"
+session-filter = "pyfly.session.auto_configuration:SessionFilterAutoConfiguration"
 
 [project.scripts]
 pyfly = "pyfly.cli.main:cli"

src/pyfly/container/__init__.py

@@ -27,6 +27,7 @@
     component,
     configuration,
     controller,
+    controller_advice,
     repository,
     rest_controller,
     service,
@@ -48,6 +49,7 @@
     "component",
     "configuration",
     "controller",
+    "controller_advice",
     "order",
     "primary",
     "repository",

src/pyfly/container/container.py

@@ -248,14 +248,31 @@ def _resolve_param(self, param_type: type) -> Any:
         return self.resolve(param_type)
 
     def _inject_autowired_fields(self, instance: Any) -> None:
-        """Inject dependencies into fields marked with Autowired()."""
+        """Inject dependencies into fields marked with Autowired() or Value()."""
+        from pyfly.core.value import Value
+
         try:
             hints = typing.get_type_hints(type(instance), include_extras=True)
         except Exception:
             return
 
         for attr_name, attr_type in hints.items():
             default = getattr(type(instance), attr_name, None)
+
+            # Handle @Value("${key}") field descriptors
+            if isinstance(default, Value):
+                from pyfly.core.config import Config
+
+                config_reg = self._registrations.get(Config)
+                if config_reg is None or config_reg.instance is None:
+                    raise RuntimeError(
+                        f"Cannot resolve @Value for {type(instance).__qualname__}.{attr_name}: "
+                        f"Config bean not registered"
+                    )
+                resolved = default.resolve(config_reg.instance)
+                setattr(instance, attr_name, resolved)
+                continue
+
             if not isinstance(default, Autowired):
                 continue
 

src/pyfly/container/stereotypes.py

@@ -83,3 +83,4 @@ def decorator(cls: T) -> T:
 rest_controller = _make_stereotype("rest_controller")
 configuration = _make_stereotype("configuration")
 shell_component = _make_stereotype("shell_component")
+controller_advice = _make_stereotype("controller_advice")

src/pyfly/context/application_context.py

@@ -69,6 +69,7 @@ def __init__(self, config: Config) -> None:
         self._started = False
         self._infrastructure_adapters: list[Any] = []
         self._task_scheduler: Any | None = None
+        self._background_tasks: list[asyncio.Task[Any]] = []
         self._wiring_counts: dict[str, int] = {}
 
         # Register config and container as singleton beans (injectable like Spring's ApplicationContext)
@@ -236,6 +237,14 @@ async def stop(self) -> None:
         """
         shutdown_timeout = float(self._config.get("pyfly.context.shutdown-timeout", 30))
 
+        # Cancel tracked background tasks
+        for task in self._background_tasks:
+            if not task.done():
+                task.cancel()
+        if self._background_tasks:
+            await asyncio.gather(*self._background_tasks, return_exceptions=True)
+            self._background_tasks.clear()
+
         # Stop task scheduler
         if self._task_scheduler is not None:
             try:
@@ -594,7 +603,8 @@ def _wire_message_listeners(self) -> None:
                 topic = getattr(method, "__pyfly_listener_topic__", "")
                 group = getattr(method, "__pyfly_listener_group__", None)
                 # MessageBrokerPort.subscribe is async; defer via create_task
-                asyncio.get_event_loop().create_task(broker.subscribe(topic, method, group=group))
+                task = asyncio.get_event_loop().create_task(broker.subscribe(topic, method, group=group))
+                self._background_tasks.append(task)
                 count += 1
         self._wiring_counts["message_listeners"] = count
         if count:
@@ -652,7 +662,8 @@ def _wire_scheduled(self) -> None:
         self._wiring_counts["scheduled"] = count
         if count:
             self._task_scheduler = scheduler
-            asyncio.get_event_loop().create_task(scheduler.start())
+            task = asyncio.get_event_loop().create_task(scheduler.start())
+            self._background_tasks.append(task)
             logger.debug("Discovered %d @scheduled method(s)", count)
 
     def _wire_async_methods(self) -> None:
@@ -716,6 +727,20 @@ def _wire_shell_commands(self) -> None:
                 if not getattr(method, "__pyfly_shell_method__", False):
                     continue
 
+                # Check @shell_method_availability
+                availability_checker_name = getattr(method, "__pyfly_shell_availability__", None)
+                if availability_checker_name:
+                    checker = getattr(reg.instance, availability_checker_name, None)
+                    if checker is not None:
+                        reason = checker()
+                        if reason:
+                            logger.debug(
+                                "Shell command '%s' unavailable: %s",
+                                getattr(method, "__pyfly_shell_key__", attr_name),
+                                reason,
+                            )
+                            continue
+
                 from pyfly.shell.param_inference import infer_params
 
                 key = getattr(method, "__pyfly_shell_key__", attr_name)

src/pyfly/core/__init__.py

@@ -16,12 +16,14 @@
 from pyfly.core.application import PyFlyApplication, pyfly_application
 from pyfly.core.banner import BannerMode, BannerPrinter
 from pyfly.core.config import Config, config_properties
+from pyfly.core.value import Value
 
 __all__ = [
     "BannerMode",
     "BannerPrinter",
     "Config",
     "PyFlyApplication",
+    "Value",
     "config_properties",
     "pyfly_application",
 ]

src/pyfly/cqrs/command/bus.py

@@ -21,6 +21,7 @@
 
 from __future__ import annotations
 
+import enum
 import logging
 from typing import Any, Protocol, TypeVar, runtime_checkable
 
@@ -39,6 +40,16 @@
 _logger = logging.getLogger(__name__)
 
 
+class EventFailureStrategy(enum.Enum):
+    """Strategy for handling domain event publishing failures."""
+
+    LOG = "log"
+    """Log failures and continue (default). Command succeeds even if events fail."""
+
+    RAISE = "raise"
+    """Raise a CommandProcessingException if any event fails to publish."""
+
+
 @runtime_checkable
 class CommandBus(Protocol):
     """Port for sending commands through the CQRS pipeline."""
@@ -73,12 +84,14 @@ def __init__(
         authorization: AuthorizationService | None = None,
         metrics: CqrsMetricsService | None = None,
         event_publisher: Any | None = None,
+        event_failure_strategy: EventFailureStrategy = EventFailureStrategy.LOG,
     ) -> None:
         self._registry = registry
         self._validation = validation
         self._authorization = authorization
         self._metrics = metrics or CqrsMetricsService()
         self._event_publisher = event_publisher
+        self._event_failure_strategy = event_failure_strategy
 
     # ── CommandBus protocol ────────────────────────────────────
 
@@ -153,12 +166,22 @@ async def _try_publish_events(self, command: Any, result: Any) -> None:
             return
         events = getattr(result, "domain_events", None) or getattr(command, "domain_events", None)
         if events:
-            failed_events = []
+            failed_events: list[tuple[Any, Exception]] = []
             for event in events:
                 try:
                     await publisher.publish(event)
                 except Exception as exc:
                     _logger.error("Failed to publish domain event %s: %s", type(event).__name__, exc)
-                    failed_events.append(event)
-            if failed_events:
+                    failed_events.append((event, exc))
+            if failed_events and self._event_failure_strategy == EventFailureStrategy.RAISE:
+                first_event, first_exc = failed_events[0]
+                raise CommandProcessingException(
+                    message=(
+                        f"{len(failed_events)} domain event(s) failed to publish "
+                        f"for {type(command).__name__}; first failure: {first_exc}"
+                    ),
+                    command_type=type(command),
+                    cause=first_exc,
+                ) from first_exc
+            elif failed_events:
                 _logger.error("%d domain event(s) failed to publish", len(failed_events))

src/pyfly/i18n/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Firefly Software Solutions Inc.
+#
+# Licensed 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.
+"""PyFly I18n — Internationalisation with pluggable message sources.
+
+Import concrete adapter types from the adapter package::
+
+    from pyfly.i18n.adapters.resource_bundle import ResourceBundleMessageSource
+"""
+
+from pyfly.i18n.locale import (
+    AcceptHeaderLocaleResolver,
+    FixedLocaleResolver,
+    LocaleResolver,
+)
+from pyfly.i18n.ports.outbound import MessageSource
+
+__all__ = [
+    "AcceptHeaderLocaleResolver",
+    "FixedLocaleResolver",
+    "LocaleResolver",
+    "MessageSource",
+]

src/pyfly/i18n/adapters/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2026 Firefly Software Solutions Inc.
+#
+# Licensed 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.
+"""I18n adapters — concrete message-source implementations."""
+
+from pyfly.i18n.adapters.resource_bundle import ResourceBundleMessageSource
+
+__all__ = ["ResourceBundleMessageSource"]