обеспечение возможности приложения выдавать команды и получать ответы по ctrl_iface wpa_supplicant. спланируй реализацию. для адаптера d-bus реализовано помещение в meta блок полей sender, path и др.

This commit is contained in:
Ilgiz Kamelyev 2026-04-21 12:07:08 +05:00
parent cf228a0d64
commit 2e4cae8a97
45 changed files with 1285 additions and 139 deletions

View File

@ -1,11 +1,11 @@
project_id: wf-agent3
focus: wpa-ctrl-socket-backend
focus: dbus-structured-meta-roundtrip
status: in_progress
updated_at: "2026-04-19"
updated_at: "2026-04-21"
scope:
- live ctrl_iface backend
- ctrl_event subscription path
- wpa backend factory threading
- config/docs/examples/tests
- nested dbus metadata in canonical messages
- protobuf Value map round-trip
- parser merge of RawMessage.details
- cache/export compatibility for protobuf meta
notes:
- "Keep file-backed WPA channels unchanged while adding live socket support."
- "Keep D-Bus transport details structured end-to-end without flattening."

View File

@ -2,32 +2,36 @@
## Scope
Live wpa_supplicant ctrl_iface support is being added through a UNIX datagram
backend, with ctrl_event split into a separate attach/receive path.
Structured D-Bus metadata is now preserved end-to-end as nested
`CanonicalMessage.meta["dbus"]` data, using protobuf `Value` entries instead of
flattened string maps.
## Current Structural Snapshot
- `app.adapters.wpa_supplicant_adapter.backend` now owns the live UNIX socket
client logic for ctrl requests and ctrl_event subscriptions.
- `app.adapters.wpa_supplicant_adapter.connection` now distinguishes
ctrl_iface and ctrl_event paths in the connection driver lifecycle.
- `app.adapters.wpa_supplicant_adapter.model` and the acquisition/parsing
registries now recognize `ctrl_event` as a first-class source channel.
- `app.application.supervisor` now threads a WPA backend factory into the
runtime build path, similar to the existing D-Bus backend factory hook.
- `app.application.config` and `app.application.models` now expose
`wpa_source.ctrl_socket_dir` with a default of `/var/run/wpa_supplicant`.
- `app.adapters.skeleton.model` now freezes nested mapping values and accepts
`RawMessage.details` as a transport metadata channel.
- `app.adapters.skeleton.parsing` merges `RawMessage.details` into canonical
message metadata for JSON and text parsers.
- `app.adapters.dbus_adapter.model` builds a nested `dbus` metadata block for
scan snapshots and canonical D-Bus messages.
- `app.adapters.dbus_adapter.connection` and wrapper layers now attach D-Bus
transport details to raw messages.
- `app.shared.contracts.proto.v1` now serializes `CanonicalMessage.meta` as a
`map<string, google.protobuf.Value>` so nested blocks survive round-trip.
- `app.application.broker` now injects adapter identity into protobuf meta via
`google.protobuf.Value` fields.
- `app.cache.store` now reads protobuf `adapter_id` metadata from `Value`
entries instead of assuming a string map.
## Observed Effects
- ctrl_iface can be backed by live socket requests instead of the smoke stub.
- ctrl_event receives unsolicited `CTRL-EVENT-*` messages through a separate
monitor socket.
- File-backed WPA status/config/event behavior remains unchanged.
- D-Bus scan snapshots now survive export/cache round-trip with nested
transport metadata intact.
- Cache listing and filtering still work with protobuf canonical messages after
the meta type change.
- Existing canonical dataclass consumers keep using plain Python mappings.
## Validation Notes
- Targeted backend, driver, factory, config, source-model, and supervisor tests
still need to be run after the code edits settle.
- Docs and example annotations were updated to describe ctrl_iface and
ctrl_event usage.
- Focused pytest run passed for the canonical model, protobuf contract, parser,
D-Bus adapter, and cache suites after the compatibility fixes.

View File

@ -1,29 +1,33 @@
project_id: wf-agent3
generated_at: "2026-04-19"
purpose: "Scope for live wpa_supplicant ctrl_iface backend and ctrl_event support."
generated_at: "2026-04-21"
purpose: "Structured D-Bus metadata round-trip through canonical messages and protobuf wire contract."
primary_files:
- src/app/adapters/wpa_supplicant_adapter/backend.py
- src/app/adapters/wpa_supplicant_adapter/connection/__init__.py
- src/app/adapters/wpa_supplicant_adapter/model/__init__.py
- src/app/application/config.py
- src/app/application/models.py
- src/app/application/supervisor.py
- src/app/adapters/skeleton/model/models.py
- src/app/adapters/skeleton/parsing/base.py
- src/app/adapters/skeleton/parsing/json.py
- src/app/adapters/skeleton/parsing/text.py
- src/app/adapters/dbus_adapter/model/__init__.py
- src/app/adapters/dbus_adapter/connection/__init__.py
- src/app/adapters/dbus_adapter/wrappers/operations.py
- src/app/application/broker.py
- src/app/cache/store.py
- src/app/shared/contracts/proto/v1/adapter_wire.proto
- src/app/shared/contracts/proto/v1/adapter_wire_pb2.py
- src/app/shared/contracts/proto/v1/converters.py
secondary_files:
- src/app/adapters/wpa_supplicant_adapter/acquisition/__init__.py
- src/app/adapters/wpa_supplicant_adapter/acquisition/registry.py
- src/app/adapters/wpa_supplicant_adapter/parsing/registry.py
- src/app/adapters/wpa_supplicant_adapter/wrappers/contracts.py
- src/app/adapters/wpa_supplicant_adapter/wrappers/__init__.py
- src/app/adapters/wpa_supplicant_adapter/README.md
- docs/usage_guide.md
- README.md
- src/app/application/examples/daemon_multi_adapter.yaml
- tests/test_canonical_models.py
- tests/test_proto_wire_contract.py
- tests/test_json_parser.py
- tests/test_text_parser.py
- tests/test_dbus_wrappers.py
- tests/test_dbus_connection_driver.py
- tests/test_dbus_adapter_cache_export.py
- tests/test_cache_store.py
- tests/test_cache_wire_contract.py
- tests/test_application_broker_cache.py
- tests/test_cache_control.py
validation_files:
- tests/test_wpa_supplicant_backend.py
- tests/test_wpa_supplicant_connection_driver.py
- tests/test_wpa_supplicant_factory.py
- tests/test_wpa_supplicant_acquisition.py
- tests/test_wpa_supplicant_parsers.py
- tests/test_wpa_supplicant_source_model.py
- tests/test_application_config.py
- tests/test_application_supervisor.py
- tests/test_dbus_adapter_cache_export.py
- tests/test_cache_control.py
- tests/test_proto_wire_contract.py
- tests/test_cache_store.py

View File

@ -183,8 +183,12 @@ Concrete adapter package для wpa_supplicant.
runtime и factory;
- использует wrapper layer для взаимодействия с backend и file-backed test
scenarios;
- поддерживает live `ctrl_iface` commands, separate `ctrl_event`
subscriptions, and file-backed `status`/`config`/`event` snapshots.
- поддерживает live `ctrl_iface` command/reply path, separate `ctrl_event`
subscriptions, and file-backed `status`/`config`/`event` snapshots;
- application-level commands идут через `runtime.execute_command(...)` и
используют тот же `ctrl_iface` backend, что и live control socket path;
- `ctrl_event` остаётся отдельным async stream и не используется как reply
channel для команд.
### `src/app/adapters/base/`

View File

@ -31,6 +31,13 @@ def _signal_name_for(message: RawMessage) -> str | None:
value = message.data.get(key)
if isinstance(value, str) and value.strip():
return value.strip()
if isinstance(message.details, Mapping):
dbus_details = message.details.get("dbus")
if isinstance(dbus_details, Mapping):
for key in ("signal_name", "signal", "member"):
value = dbus_details.get(key)
if isinstance(value, str) and value.strip():
return value.strip()
return None

View File

@ -49,6 +49,7 @@ from app.adapters.skeleton.model import RawMessage
from app.adapters.dbus_adapter.model import (
DbusScanMode,
DbusSourceDescriptor,
build_dbus_metadata_block,
snapshot_from_mapping,
)
@ -261,11 +262,27 @@ class DBusConnectionDriver(BaseConnectionDriver[RawMessage]):
payload = result.payload
if isinstance(payload, Mapping):
payload = dict(payload)
dbus_details = dict(result.details.get("dbus", {}))
if not dbus_details:
dbus_details = build_dbus_metadata_block(
bus_name=self.config.bus_name,
object_path=self.config.object_path,
interface=self.config.interface,
member=self.config.member,
signal_name=result.signal_name or self.config.member,
)
dbus_details.setdefault("bus_name", self.config.bus_name)
dbus_details.setdefault("object_path", self.config.object_path)
dbus_details.setdefault("interface", self.config.interface)
dbus_details.setdefault("member", self.config.member)
dbus_details.setdefault("signal_name", result.signal_name or self.config.member)
dbus_details.setdefault("source_uri", self._message_source())
return RawMessage(
data=payload,
source=self._message_source(),
transport="d-bus",
received_at=result.received_at or datetime.now(UTC),
details={"dbus": dbus_details},
)
def send(self, message: RawMessage) -> None:
@ -537,7 +554,23 @@ class DBusConnectionDriver(BaseConnectionDriver[RawMessage]):
len(raw_records),
self._message_source(),
)
return snapshot.to_raw_message()
return snapshot.to_raw_message(
details={
"dbus": build_dbus_metadata_block(
bus_name=self.config.bus_name,
object_path=interface_path,
interface=_WPA_INTERFACE_INTERFACE,
member="ScanDone",
signal_name="ScanDone",
source_uri=self.scan_source.source_uri,
interface_name=self.scan_source.interface_name,
monitored_ssid=self.scan_source.monitored_ssid,
filter_by_monitored_ssid=self.scan_source.filter_by_monitored_ssid,
resolved_interface_path=interface_path,
scan_profile=self.scan_source.scan_profile,
)
}
)
def _wait_for_scan_idle(
self,

View File

@ -131,16 +131,20 @@ class DbusScanSnapshot:
"frequency_mhz": record.frequency_mhz,
"signal_dbm": record.signal_dbm,
"age_seconds": record.age_seconds,
"details": dict(record.details),
"details": _plain_value(record.details),
}
for record in self.bss_records
],
"fingerprint": self.fingerprint,
"scanned_at": self.scanned_at.astimezone(UTC).isoformat(),
"details": dict(self.details),
"details": _plain_value(self.details),
}
def to_raw_message(self) -> RawMessage:
def to_raw_message(
self,
*,
details: Mapping[str, Any] | None = None,
) -> RawMessage:
payload = self.to_mapping()
envelope = {
"source": self.descriptor.source_uri,
@ -154,9 +158,57 @@ class DbusScanSnapshot:
transport="d-bus",
received_at=self.scanned_at,
encoding="utf-8",
details={} if details is None else details,
)
def build_dbus_metadata_block(
*,
bus_name: str,
object_path: str,
interface: str,
member: str | None = None,
signal_name: str | None = None,
source_uri: str | None = None,
sender: str | None = None,
destination: str | None = None,
unique_name: str | None = None,
interface_name: str | None = None,
monitored_ssid: str | None = None,
filter_by_monitored_ssid: bool | None = None,
resolved_interface_path: str | None = None,
scan_profile: DbusScanProfile | None = None,
) -> dict[str, Any]:
dbus: dict[str, Any] = {
"bus_name": bus_name,
"object_path": object_path,
"interface": interface,
}
if member is not None:
dbus["member"] = member
if signal_name is not None:
dbus["signal_name"] = signal_name
if source_uri is not None:
dbus["source_uri"] = source_uri
if sender is not None:
dbus["sender"] = sender
if destination is not None:
dbus["destination"] = destination
if unique_name is not None:
dbus["unique_name"] = unique_name
if interface_name is not None:
dbus["interface_name"] = interface_name
if monitored_ssid is not None:
dbus["monitored_ssid"] = monitored_ssid
if filter_by_monitored_ssid is not None:
dbus["filter_by_monitored_ssid"] = filter_by_monitored_ssid
if resolved_interface_path is not None:
dbus["resolved_interface_path"] = resolved_interface_path
if scan_profile is not None:
dbus["scan_profile"] = _scan_profile_mapping(scan_profile)
return dbus
def build_dbus_scan_snapshot(
descriptor: DbusSourceDescriptor,
interface_path: str,
@ -167,14 +219,19 @@ def build_dbus_scan_snapshot(
) -> DbusScanSnapshot:
scanned_at = scanned_at or datetime.now(UTC)
source_details = {
"dbus_source": {
"source_uri": descriptor.source_uri,
"identifier": descriptor.identifier,
"interface_name": descriptor.interface_name,
"interface_path": interface_path,
"monitored_ssid": descriptor.monitored_ssid,
"filter_by_monitored_ssid": descriptor.filter_by_monitored_ssid,
}
"dbus": build_dbus_metadata_block(
bus_name="fi.w1.wpa_supplicant1",
object_path=interface_path,
interface="fi.w1.wpa_supplicant1.Interface",
member="ScanDone",
signal_name="ScanDone",
source_uri=descriptor.source_uri,
interface_name=descriptor.interface_name,
monitored_ssid=descriptor.monitored_ssid,
filter_by_monitored_ssid=descriptor.filter_by_monitored_ssid,
resolved_interface_path=interface_path,
scan_profile=descriptor.scan_profile,
)
}
fingerprint = _fingerprint(
{
@ -269,6 +326,7 @@ def build_canonical_message(
"identifier": snapshot.descriptor.identifier,
"monitored_ssid": snapshot.descriptor.monitored_ssid,
"source_uri": snapshot.descriptor.source_uri,
"dbus": dict(snapshot.details.get("dbus", {})),
},
)
@ -305,7 +363,31 @@ def _normalize_identifier(value: str) -> str:
def _freeze_mapping(value: Mapping[str, Any]) -> Mapping[str, Any]:
return MappingProxyType(dict(value))
return MappingProxyType({key: _freeze_value(item) for key, item in value.items()})
def _freeze_value(value: Any) -> Any:
if isinstance(value, Mapping):
return _freeze_mapping(value)
if isinstance(value, list):
return tuple(_freeze_value(item) for item in value)
if isinstance(value, tuple):
return tuple(_freeze_value(item) for item in value)
if isinstance(value, set):
return frozenset(_freeze_value(item) for item in value)
return value
def _plain_value(value: Any) -> Any:
if isinstance(value, Mapping):
return {key: _plain_value(item) for key, item in value.items()}
if isinstance(value, list):
return [_plain_value(item) for item in value]
if isinstance(value, tuple):
return [_plain_value(item) for item in value]
if isinstance(value, set):
return [_plain_value(item) for item in value]
return value
def _optional_text(value: object) -> str | None:
@ -342,6 +424,7 @@ __all__ = [
"DbusScanSnapshot",
"DbusSourceDescriptor",
"build_canonical_message",
"build_dbus_metadata_block",
"build_dbus_scan_snapshot",
"snapshot_from_mapping",
]

View File

@ -3,11 +3,13 @@
from __future__ import annotations
import logging
from collections.abc import Mapping
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Any
from app.adapters.skeleton.wrappers import BaseExternalWrapper
from app.adapters.dbus_adapter.model import build_dbus_metadata_block
from .contracts import (
DbusBusConnectionRequest,
@ -42,6 +44,99 @@ from .contracts import (
logger = logging.getLogger(__name__)
def _text_or_none(value: Any) -> str | None:
if value is None:
return None
text = str(value).strip()
return text or None
def _header_mapping(value: Any) -> Mapping[str, Any]:
if not isinstance(value, Mapping):
return {}
for key in ("dbus", "headers"):
nested = value.get(key)
if isinstance(nested, Mapping):
return nested
return value
def _unwrap_backend_result(value: Any) -> tuple[Any, dict[str, Any]]:
if not isinstance(value, Mapping):
return value, {}
header_source = _header_mapping(value)
headers: dict[str, Any] = {}
for key in (
"sender",
"destination",
"unique_name",
"bus_name",
"object_path",
"interface",
"member",
"signal_name",
"signal",
"source_uri",
):
text = _text_or_none(header_source.get(key))
if text is not None:
headers[key] = text
payload: Any
if "envelope" in value and "payload" in value:
payload = dict(value)
elif "payload" in value:
payload = value["payload"]
elif "return_value" in value:
payload = value["return_value"]
elif "value" in value and len(value) == 1:
payload = value["value"]
else:
payload = value
return payload, headers
def _dbus_result_details(
*,
bus_name: str,
object_path: str,
interface: str,
member: str | None = None,
signal_name: str | None = None,
source_uri: str | None = None,
sender: str | None = None,
destination: str | None = None,
unique_name: str | None = None,
interface_name: str | None = None,
monitored_ssid: str | None = None,
resolved_interface_path: str | None = None,
scan_profile: Any | None = None,
timeout_seconds: float | None = None,
backend: str | None = None,
) -> dict[str, Any]:
details: dict[str, Any] = {
"dbus": build_dbus_metadata_block(
bus_name=bus_name,
object_path=object_path,
interface=interface,
member=member,
signal_name=signal_name,
source_uri=source_uri,
sender=sender,
destination=destination,
unique_name=unique_name,
interface_name=interface_name,
monitored_ssid=monitored_ssid,
resolved_interface_path=resolved_interface_path,
scan_profile=scan_profile,
)
}
if timeout_seconds is not None:
details["timeout_seconds"] = timeout_seconds
if backend is not None:
details["backend"] = backend
return details
@dataclass(slots=True)
class DbusBusConnectionWrapper(
BaseExternalWrapper[DbusBusConnectionRequest, DbusBusConnectionResult]
@ -125,7 +220,8 @@ class DbusInterfaceLookupWrapper(
{},
request.timeout_seconds,
)
interface_path = _coerce_text(result)
payload, headers = _unwrap_backend_result(result)
interface_path = _coerce_text(payload)
if not interface_path.strip():
raise DbusWrapperTransportError("GetInterface returned an empty path")
return DbusInterfaceLookupResult(
@ -134,8 +230,18 @@ class DbusInterfaceLookupWrapper(
interface_path=interface_path.strip(),
details={
"member": request.member,
"timeout_seconds": request.timeout_seconds,
"backend": type(self.backend).__name__,
**_dbus_result_details(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
interface_name=request.interface_name,
sender=headers.get("sender"),
destination=headers.get("destination"),
unique_name=headers.get("unique_name"),
timeout_seconds=request.timeout_seconds,
backend=type(self.backend).__name__,
),
**_context_details(request.context),
},
)
@ -173,17 +279,27 @@ class DbusMethodCallWrapper(
dict(request.keyword_arguments),
request.timeout_seconds,
)
payload, headers = _unwrap_backend_result(value)
return DbusMethodCallResult(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
return_value=value,
return_value=payload,
details={
"arguments": request.arguments,
"keyword_arguments": dict(request.keyword_arguments),
"timeout_seconds": request.timeout_seconds,
"backend": type(self.backend).__name__,
**_dbus_result_details(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
sender=headers.get("sender"),
destination=headers.get("destination"),
unique_name=headers.get("unique_name"),
timeout_seconds=request.timeout_seconds,
backend=type(self.backend).__name__,
),
**_context_details(request.context),
},
)
@ -235,17 +351,27 @@ class DbusInterfaceScanWrapper(
request.object_path,
type(response).__name__,
)
payload, headers = _unwrap_backend_result(response)
return DbusInterfaceScanResult(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
accepted=True,
response=response,
response=payload,
details={
"options": dict(request.options),
"timeout_seconds": request.timeout_seconds,
"backend": type(self.backend).__name__,
**_dbus_result_details(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
sender=headers.get("sender"),
destination=headers.get("destination"),
unique_name=headers.get("unique_name"),
timeout_seconds=request.timeout_seconds,
backend=type(self.backend).__name__,
),
**_context_details(request.context),
},
)
@ -272,16 +398,33 @@ class DbusSignalReceiveWrapper(
request.member,
request.timeout_seconds,
)
payload, headers = _unwrap_backend_result(payload)
signal_name = (
headers.get("signal_name")
or headers.get("member")
or headers.get("signal")
or request.member
)
return DbusSignalReceiveResult(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
signal_name=request.member,
signal_name=signal_name,
payload=payload,
received_at=datetime.now(UTC),
details={
"timeout_seconds": request.timeout_seconds,
"backend": type(self.backend).__name__,
**_dbus_result_details(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
signal_name=signal_name,
sender=headers.get("sender"),
destination=headers.get("destination"),
unique_name=headers.get("unique_name"),
timeout_seconds=request.timeout_seconds,
backend=type(self.backend).__name__,
),
**_context_details(request.context),
},
)
@ -307,6 +450,7 @@ class DbusScanDoneWrapper(BaseExternalWrapper[DbusScanDoneRequest, DbusScanDoneR
request.member,
request.timeout_seconds,
)
payload, headers = _unwrap_backend_result(payload)
return DbusScanDoneResult(
bus_name=request.bus_name,
object_path=request.object_path,
@ -316,8 +460,18 @@ class DbusScanDoneWrapper(BaseExternalWrapper[DbusScanDoneRequest, DbusScanDoneR
received_at=datetime.now(UTC),
details={
"payload": payload,
"timeout_seconds": request.timeout_seconds,
"backend": type(self.backend).__name__,
**_dbus_result_details(
bus_name=request.bus_name,
object_path=request.object_path,
interface=request.interface,
member=request.member,
signal_name=request.member,
sender=headers.get("sender"),
destination=headers.get("destination"),
unique_name=headers.get("unique_name"),
timeout_seconds=request.timeout_seconds,
backend=type(self.backend).__name__,
),
**_context_details(request.context),
},
)

View File

@ -109,6 +109,10 @@ class BaseAdapterRuntime(ABC):
def run_once(self) -> int:
"""Process one acquisition cycle and return the number of messages handled."""
@abstractmethod
def execute_command(self, request: CommandRequest) -> CommandResult:
"""Execute an application command and return the command result."""
@abstractmethod
def status_snapshot(self) -> StatusSnapshot:
"""Return the current adapter status snapshot."""

View File

@ -10,7 +10,19 @@ from typing import Any
def _freeze_mapping(value: Mapping[str, Any]) -> Mapping[str, Any]:
return MappingProxyType(dict(value))
return MappingProxyType({key: _freeze_value(item) for key, item in value.items()})
def _freeze_value(value: Any) -> Any:
if isinstance(value, Mapping):
return _freeze_mapping(value)
if isinstance(value, list):
return tuple(_freeze_value(item) for item in value)
if isinstance(value, tuple):
return tuple(_freeze_value(item) for item in value)
if isinstance(value, set):
return frozenset(_freeze_value(item) for item in value)
return value
@dataclass(slots=True, frozen=True)
@ -22,6 +34,10 @@ class RawMessage:
transport: str | None = None
received_at: datetime | None = None
encoding: str | None = None
details: Mapping[str, Any] = field(default_factory=dict)
def __post_init__(self) -> None:
object.__setattr__(self, "details", _freeze_mapping(self.details))
@dataclass(slots=True, frozen=True)

View File

@ -65,6 +65,16 @@ class MessageParserBase(BaseMessageParser[RawMessage, CanonicalMessage], ABC):
meta={} if meta is None else meta,
)
def merge_message_meta(
self,
message: RawMessage,
meta: Mapping[str, Any],
) -> dict[str, Any]:
merged = dict(meta)
if message.details:
merged.update(message.details)
return merged
def ensure_mapping(
self,
value: Any,

View File

@ -46,7 +46,11 @@ class JsonMessageParser(MessageParserBase):
if message.encoding is not None:
meta["encoding"] = message.encoding
return self.build_message(envelope=envelope, payload=payload, meta=meta)
return self.build_message(
envelope=envelope,
payload=payload,
meta=self.merge_message_meta(message, meta),
)
def _load_document(self, message: RawMessage) -> Any:
if isinstance(message.data, Mapping):

View File

@ -52,7 +52,11 @@ class TextMessageParser(MessageParserBase):
meta["transport"] = message.transport
if message.encoding is not None:
meta["encoding"] = message.encoding
return self.build_message(envelope=envelope, payload=payload, meta=meta)
return self.build_message(
envelope=envelope,
payload=payload,
meta=self.merge_message_meta(message, meta),
)
def _load_text(self, message: RawMessage) -> str:
value: Any = message.data

View File

@ -14,6 +14,7 @@ from uuid import uuid4
from app.adapters.skeleton.base import (
BaseAcquisitionStrategy,
BaseAdapterRuntime,
BaseCommandExecutor,
BaseConnectionDriver,
BaseMessageMarker,
BaseMessageParser,
@ -40,6 +41,7 @@ from app.adapters.skeleton.model import CanonicalMessage, RawMessage
from app.adapters.skeleton.parsing import ParserError
from app.adapters.skeleton.prefilter import PrefilterStub
from app.adapters.skeleton.validation import ValidationStub
from app.shared.contracts import CommandRequest, CommandResult
from app.shared.contracts import MessageExportPort, StatusSnapshot
from app.shared.observability import (
InMemoryObservabilityService,
@ -203,6 +205,7 @@ class UniversalAdapterRuntime(BaseAdapterRuntime):
acquisition_factory: AcquisitionFactoryProtocol
parser_factory: ParserFactoryProtocol
export_port: MessageExportPort
command_executor: BaseCommandExecutor | None = None
observability: InMemoryObservabilityService | None = None
validation: BaseMessageValidator[CanonicalMessage] | None = None
prefilter: BaseMessagePrefilter[CanonicalMessage] | None = None
@ -229,8 +232,11 @@ class UniversalAdapterRuntime(BaseAdapterRuntime):
_parse_errors: int = field(default=0, init=False)
_export_errors: int = field(default=0, init=False)
_reconnects: int = field(default=0, init=False)
_commands_executed: int = field(default=0, init=False)
_command_errors: int = field(default=0, init=False)
_last_received_at: datetime | None = field(default=None, init=False)
_last_exported_at: datetime | None = field(default=None, init=False)
_last_command_at: datetime | None = field(default=None, init=False)
_lock: RLock = field(default_factory=RLock, init=False, repr=False)
def __post_init__(self) -> None:
@ -331,6 +337,44 @@ class UniversalAdapterRuntime(BaseAdapterRuntime):
self._publish_status()
return handled
def execute_command(self, request: CommandRequest) -> CommandResult:
with self._lock:
self._emit_trace(
stage="command",
action="received",
severity=TraceSeverity.IMPORTANT,
command_name=request.name,
correlation_id=request.correlation_id,
)
result = self._execute_command_unlocked(request)
self._last_command_at = datetime.now(UTC)
self._commands_executed += 1
assert self.observability is not None
self.observability.increment_metric("commands_total")
if result.ok:
self._emit_trace(
stage="command",
action="completed",
severity=TraceSeverity.IMPORTANT,
command_name=request.name,
status=result.status,
correlation_id=request.correlation_id,
)
else:
self._command_errors += 1
self.observability.increment_metric("command_errors_total")
self._emit_trace(
stage="command",
action="failed",
severity=TraceSeverity.IMPORTANT,
command_name=request.name,
status=result.status,
message=result.message,
correlation_id=request.correlation_id,
)
self._publish_status()
return result
def status_snapshot(self) -> StatusSnapshot:
with self._lock:
self._publish_status()
@ -549,6 +593,7 @@ class UniversalAdapterRuntime(BaseAdapterRuntime):
connection_state=self.connection_state_machine.state.value.upper(),
last_received_at=self._last_received_at,
last_exported_at=self._last_exported_at,
last_command_at=self._last_command_at,
details=self._runtime_details(),
)
self.observability.update_status(snapshot)
@ -560,10 +605,50 @@ class UniversalAdapterRuntime(BaseAdapterRuntime):
"parse_errors": self._parse_errors,
"export_errors": self._export_errors,
"reconnects": self._reconnects,
"handled_commands": self._commands_executed,
"command_errors": self._command_errors,
"runtime_state": self.runtime_state_machine.state.value,
"connection_state": self.connection_state_machine.state.value,
}
def _execute_command_unlocked(self, request: CommandRequest) -> CommandResult:
if self.command_executor is None:
return CommandResult(
ok=False,
status="INVALID_REQUEST",
message="command execution is not implemented",
payload=dict(request.payload),
metadata={
"stage": "command",
"action": "stubbed",
"command_name": request.name,
"correlation_id": request.correlation_id,
},
)
try:
return self.command_executor.execute(request)
except Exception as exc: # pragma: no cover - defensive guard
self._emit_trace(
stage="command",
action="exception",
severity=TraceSeverity.IMPORTANT,
command_name=request.name,
error=type(exc).__name__,
correlation_id=request.correlation_id,
)
return CommandResult(
ok=False,
status="TRANSPORT_ERROR",
message=str(exc),
payload=dict(request.payload),
metadata={
"stage": "command",
"action": "exception",
"command_name": request.name,
"correlation_id": request.correlation_id,
},
)
def _emit_trace(
self,
*,

View File

@ -30,11 +30,22 @@ Wrapper strategy:
- `WpaCtrlIfaceWrapper` is the primary boundary for ctrl_iface commands.
- `WpaUnixSocketBackend` implements live ctrl_iface requests and ctrl_event
subscriptions over Linux UNIX datagram sockets.
- `WpaCtrlIfaceCommandExecutor` bridges application `CommandRequest` objects
into sync ctrl_iface request/reply calls and returns shared `CommandResult`
values.
- `WpaFileReadWrapper` is the shared boundary for file-backed config/status/event
reads.
- `WpaConfigReadWrapper`, `WpaStatusReadWrapper`, and `WpaEventReadWrapper`
are marker specializations that keep the channel boundaries explicit.
Runtime command path:
- application commands use `runtime.execute_command(...)`;
- `ctrl_iface` commands and `ctrl_event` subscriptions are separate control
channels even when they target the same interface;
- command replies stay on the `ctrl_iface` request/reply path and are not read
from the async event monitor.
Concrete components:
- `WpaSupplicantConnectionDriver` routes ctrl_iface, ctrl_event, and file

View File

@ -14,6 +14,7 @@ from .acquisition import (
)
from .connection import WpaSupplicantConnectionDriver
from .factory import WpaSupplicantAdapterFactory, create_wpa_supplicant_adapter_runtime
from .commands import WpaCtrlIfaceCommandExecutor
from .backend import WpaUnixSocketBackend
from .model import (
DEFAULT_CTRL_SOCKET_DIR,
@ -35,6 +36,7 @@ __all__ = [
"WpaConfigReadStrategy",
"WpaCtrlIfaceAcquisitionStrategy",
"WpaCtrlIfaceParser",
"WpaCtrlIfaceCommandExecutor",
"WpaCtrlIfacePollingStrategy",
"WpaCtrlEventReceiveStrategy",
"WpaEventReceiveStrategy",

View File

@ -0,0 +1,220 @@
"""Command execution helpers for the wpa_supplicant adapter."""
from __future__ import annotations
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from typing import Any
from app.adapters.skeleton.base import BaseCommandExecutor
from app.shared.contracts import CommandRequest, CommandResult
from ..wrappers import (
WpaWrapperBackend,
WpaWrapperConfigurationError,
WpaWrapperTransportError,
)
from ..wrappers.operations import _normalize_ctrl_iface_arguments
def _normalize_text(value: object | None) -> str:
if value is None:
return ""
return str(value)
def _normalize_timeout(value: object | None) -> float | None:
if value is None:
return None
if isinstance(value, bool):
raise WpaWrapperConfigurationError("timeout_seconds must be numeric")
if not isinstance(value, (int, float, str)):
raise WpaWrapperConfigurationError("timeout_seconds must be numeric")
try:
timeout = float(value)
except (TypeError, ValueError) as exc:
raise WpaWrapperConfigurationError("timeout_seconds must be numeric") from exc
if timeout < 0:
raise WpaWrapperConfigurationError("timeout_seconds must be >= 0")
return timeout
def _normalize_metadata_value(metadata: Mapping[str, Any], key: str) -> str:
value = metadata.get(key)
if value is None:
raise WpaWrapperConfigurationError(f"{key} is required")
text = str(value).strip()
if not text:
raise WpaWrapperConfigurationError(f"{key} must not be empty")
return text
def _normalize_ctrl_socket_dir(value: object | None) -> str | None:
if value is None:
return None
text = str(value).strip()
if not text:
raise WpaWrapperConfigurationError("ctrl_socket_dir must not be empty")
return text
def _command_result(
*,
ok: bool,
status: str,
message: str,
command: str,
interface_name: str,
arguments: tuple[str, ...],
reply: str | None,
backend: WpaWrapperBackend,
timeout_seconds: float | None,
ctrl_socket_dir: str | None,
details: Mapping[str, Any] | None = None,
) -> CommandResult:
payload: dict[str, Any] = {
"command": command,
"interface_name": interface_name,
"arguments": arguments,
}
if reply is not None:
payload["reply"] = reply
metadata: dict[str, Any] = {
"backend": type(backend).__name__,
"timeout_seconds": timeout_seconds,
}
if ctrl_socket_dir is not None:
metadata["ctrl_socket_dir"] = ctrl_socket_dir
if details is not None:
metadata["details"] = dict(details)
return CommandResult(
ok=ok,
status=status,
message=message,
payload=payload,
metadata=metadata,
)
def _extract_ctrl_iface_reply(response: object) -> tuple[str, bool, dict[str, Any]]:
if isinstance(response, Mapping):
reply = _normalize_text(response.get("reply"))
ok = bool(response.get("ok", False))
details = dict(response.get("details", {}))
return reply, ok, details
reply = _normalize_text(response)
normalized = reply.strip().upper()
ok = normalized == "OK" or not normalized.startswith("FAIL")
return reply, ok, {}
@dataclass(slots=True)
class WpaCtrlIfaceCommandExecutor(BaseCommandExecutor):
"""Execute ctrl_iface command/reply requests against wpa_supplicant."""
backend: WpaWrapperBackend
backend_factory: Callable[[str], WpaWrapperBackend] | None = None
def execute(self, request: CommandRequest) -> CommandResult:
raw_metadata = request.metadata if isinstance(request.metadata, Mapping) else {}
raw_payload = request.payload if isinstance(request.payload, Mapping) else {}
command = ""
interface_name = ""
arguments: tuple[str, ...] = ()
timeout_seconds: float | None = None
ctrl_socket_dir: str | None = None
backend = self.backend
try:
command = self._normalize_command(request.name)
metadata = self._normalize_request_metadata(raw_metadata)
interface_name = _normalize_metadata_value(metadata, "interface_name")
arguments = _normalize_ctrl_iface_arguments(raw_payload.get("arguments"))
timeout_seconds = _normalize_timeout(raw_payload.get("timeout_seconds"))
ctrl_socket_dir = _normalize_ctrl_socket_dir(
metadata.get("ctrl_socket_dir")
)
backend = self._select_backend(ctrl_socket_dir)
response = backend.ctrl_request(
interface_name,
command,
arguments,
timeout_seconds,
)
except WpaWrapperConfigurationError as exc:
return _command_result(
ok=False,
status="INVALID_REQUEST",
message=str(exc),
command=request.name if isinstance(request.name, str) else "",
interface_name=str(raw_metadata.get("interface_name", "")).strip(),
arguments=(),
reply=None,
backend=self.backend,
timeout_seconds=None,
ctrl_socket_dir=None,
)
except (WpaWrapperTransportError, OSError, TimeoutError) as exc:
return _command_result(
ok=False,
status="TRANSPORT_ERROR",
message=str(exc),
command=command,
interface_name=interface_name,
arguments=arguments,
reply=None,
backend=backend,
timeout_seconds=timeout_seconds,
ctrl_socket_dir=ctrl_socket_dir,
)
reply, ok, details = _extract_ctrl_iface_reply(response)
status = "OK" if ok else "FAIL"
message = (
"wpa_supplicant command completed"
if ok
else "wpa_supplicant returned FAIL"
)
return _command_result(
ok=ok,
status=status,
message=message,
command=command,
interface_name=interface_name,
arguments=arguments,
reply=reply,
backend=backend,
timeout_seconds=timeout_seconds,
ctrl_socket_dir=ctrl_socket_dir,
details=details,
)
def _normalize_command(self, value: object) -> str:
if not isinstance(value, str):
raise WpaWrapperConfigurationError("command must be a string")
command = value.strip()
if not command:
raise WpaWrapperConfigurationError("command must not be empty")
return command
def _normalize_request_metadata(
self, value: Mapping[str, Any] | object
) -> Mapping[str, Any]:
if not isinstance(value, Mapping):
raise WpaWrapperConfigurationError("metadata must be a mapping")
return value
def _select_backend(self, ctrl_socket_dir: str | None) -> WpaWrapperBackend:
if ctrl_socket_dir is None:
return self.backend
if self.backend_factory is not None:
return self.backend_factory(ctrl_socket_dir)
backend_type = type(self.backend)
try:
return backend_type(ctrl_socket_dir=ctrl_socket_dir) # type: ignore[misc]
except TypeError as exc:
raise WpaWrapperConfigurationError(
"backend does not support ctrl_socket_dir override"
) from exc
__all__ = ["WpaCtrlIfaceCommandExecutor"]

View File

@ -22,6 +22,7 @@ from app.adapters.skeleton.model import CanonicalMessage
from app.adapters.skeleton.prefilter import PrefilterStub
from app.adapters.skeleton.runtime import UniversalAdapterRuntime
from app.adapters.skeleton.validation import ValidationStub
from app.adapters.wpa_supplicant_adapter.commands import WpaCtrlIfaceCommandExecutor
from app.adapters.wpa_supplicant_adapter.acquisition.registry import (
WpaAcquisitionStrategyRegistry,
default_wpa_acquisition_strategy_registry,
@ -35,6 +36,7 @@ from app.adapters.wpa_supplicant_adapter.parsing.registry import (
default_wpa_parser_registry,
)
from app.adapters.wpa_supplicant_adapter.wrappers import WpaWrapperBackend
from app.adapters.wpa_supplicant_adapter.wrappers import WpaWrapperConfigurationError
from app.shared.contracts import MessageExportPort
from app.shared.observability import InMemoryObservabilityService
@ -61,6 +63,27 @@ def _build_connection_factory(
return factory
def _build_backend_factory(
backend: WpaWrapperBackend,
) -> Callable[[str], WpaWrapperBackend]:
def factory(ctrl_socket_dir: str) -> WpaWrapperBackend:
current_ctrl_socket_dir = getattr(backend, "ctrl_socket_dir", None)
if (
current_ctrl_socket_dir is not None
and str(current_ctrl_socket_dir) == str(ctrl_socket_dir)
):
return backend
backend_type = type(backend)
try:
return backend_type(ctrl_socket_dir=ctrl_socket_dir) # type: ignore[misc]
except TypeError as exc:
raise WpaWrapperConfigurationError(
"backend does not support ctrl_socket_dir override"
) from exc
return factory
@dataclass(slots=True)
class WpaSupplicantAdapterFactory(
BaseAdapterFactory[UniversalAdapterConfig, UniversalAdapterRuntime],
@ -115,12 +138,18 @@ class WpaSupplicantAdapterFactory(
parser = parser_registry.build(self.source_descriptor, **kwargs)
return cast(BaseMessageParser[Any, CanonicalMessage], parser)
command_executor = WpaCtrlIfaceCommandExecutor(
backend=self.backend,
backend_factory=_build_backend_factory(self.backend),
)
return UniversalAdapterRuntime(
config=config,
connection_factory=connection_factory,
acquisition_factory=acquisition_factory,
parser_factory=parser_factory,
export_port=self.export_port,
command_executor=command_executor,
observability=self.observability,
validation=self.validation or ValidationStub(self.observability),
prefilter=self.prefilter or PrefilterStub(self.observability),

View File

@ -3,6 +3,7 @@
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from app.adapters.skeleton.base import BaseExternalWrapper
@ -21,6 +22,36 @@ from .contracts import (
)
def _normalize_ctrl_iface_arguments(value: object) -> tuple[str, ...]:
if value is None:
return ()
if isinstance(value, tuple):
arguments = value
elif isinstance(value, list):
arguments = tuple(value)
else:
raise WpaWrapperConfigurationError(
"arguments must be a list or tuple of command arguments"
)
return tuple(str(argument) for argument in arguments)
def _normalize_ctrl_iface_reply(response: object) -> tuple[str, bool, dict[str, Any]]:
if isinstance(response, dict):
reply = response.get("reply")
if reply is None:
reply_text = ""
else:
reply_text = str(reply)
ok = bool(response.get("ok", False))
details = dict(response.get("details", {}))
return reply_text, ok, details
reply_text = str(response).strip()
normalized = reply_text.upper()
ok = normalized == "OK" or not normalized.startswith("FAIL")
return reply_text, ok, {}
@dataclass(slots=True)
class WpaCtrlIfaceWrapper(BaseExternalWrapper[WpaCtrlIfaceRequest, WpaCtrlIfaceResult]):
"""Boundary for ctrl_iface command execution."""
@ -36,41 +67,21 @@ class WpaCtrlIfaceWrapper(BaseExternalWrapper[WpaCtrlIfaceRequest, WpaCtrlIfaceR
request.arguments,
request.timeout_seconds,
)
if isinstance(response, dict):
ok = bool(response.get("ok", False))
reply = response.get("reply")
if reply is not None and not isinstance(reply, str):
reply = str(reply)
details = _merge_details(
response.get("details", {}),
reply, ok, details = _normalize_ctrl_iface_reply(response)
return WpaCtrlIfaceResult(
interface_name=request.interface_name,
command=request.command,
ok=ok,
reply=reply.strip(),
details=_merge_details(
details,
{
"backend": type(self.backend).__name__,
"arguments": request.arguments,
"timeout_seconds": request.timeout_seconds,
**_context_details(request.context),
},
)
return WpaCtrlIfaceResult(
interface_name=request.interface_name,
command=request.command,
ok=ok,
reply=reply,
details=details,
)
reply = str(response).strip()
normalized = reply.upper()
ok = normalized == "OK" or not normalized.startswith("FAIL")
return WpaCtrlIfaceResult(
interface_name=request.interface_name,
command=request.command,
ok=ok,
reply=reply,
details={
"backend": type(self.backend).__name__,
"arguments": request.arguments,
"timeout_seconds": request.timeout_seconds,
**_context_details(request.context),
},
),
)

View File

@ -90,9 +90,9 @@ class AdapterMetadataExportPort(MessageExportPort):
def export(self, message: ProtobufMessage) -> None:
if isinstance(message, wire.CanonicalMessage):
canonical = cast(Any, message)
canonical.meta["adapter_id"] = self.adapter_id
canonical.meta["adapter_kind"] = self.adapter_kind
canonical.meta["service_name"] = self.service_name
canonical.meta["adapter_id"].string_value = self.adapter_id
canonical.meta["adapter_kind"].string_value = self.adapter_kind
canonical.meta["service_name"].string_value = self.service_name
self.broker.export(message)

View File

@ -97,6 +97,13 @@ adapters:
path: .tmp/wpa_status.txt
content_type: text/plain
payload_kind: text
# Application command example for the same interface, separate from
# acquisition:
# command_request:
# name: SCAN
# metadata:
# interface_name: wlan0
# ctrl_socket_dir: /run/wpa_supplicant
# Live control socket examples:
# ctrl_iface:
# channel: ctrl_iface

View File

@ -10,6 +10,7 @@ from datetime import UTC, datetime, timedelta
from threading import RLock
from typing import Any, cast
from google.protobuf import json_format
from google.protobuf.message import Message as ProtobufMessage
from app.application.models import CacheConfig
from app.cache.models import CacheEvent
@ -23,6 +24,16 @@ def _utc_now() -> datetime:
return datetime.now(UTC)
def _meta_text_value(message: Any, key: str) -> str | None:
value = message.meta.get(key)
if value is None:
return None
if hasattr(value, "WhichOneof") and value.WhichOneof("kind") == "string_value":
return value.string_value or None
converted = json_format.MessageToDict(value, preserving_proto_field_name=True)
return converted if isinstance(converted, str) and converted else None
@dataclass(slots=True, frozen=True)
class CacheEntry:
"""Serialized cache entry with query metadata."""
@ -60,7 +71,7 @@ class InMemoryMessageCache(CacheReadPort):
payload=proto.SerializeToString(),
stored_at=now,
message_at=self._message_timestamp(proto, now),
adapter_id=proto.meta.get("adapter_id") or None,
adapter_id=_meta_text_value(proto, "adapter_id"),
source=proto.envelope.source,
)
self._entries.append(entry)

View File

@ -33,7 +33,7 @@ message CanonicalMessage {
Envelope envelope = 1;
Payload payload = 2;
map<string, string> meta = 3;
map<string, google.protobuf.Value> meta = 3;
}
message StatusSnapshot {

View File

@ -152,7 +152,12 @@ def _build_file_descriptor() -> descriptor_pb2.FileDescriptorProto:
canonical = file_proto.message_type.add()
canonical.name = "CanonicalMessage"
canonical.reserved_range.add(start=4, end=6)
_map_entry(canonical, "MetaEntry")
_map_entry(
canonical,
"MetaEntry",
value_type=descriptor_pb2.FieldDescriptorProto.TYPE_MESSAGE,
value_type_name=".google.protobuf.Value",
)
_field(
canonical,
"envelope",

View File

@ -44,7 +44,8 @@ def canonical_message_to_proto(message: CanonicalMessage) -> wire.CanonicalMessa
proto = wire.CanonicalMessage()
proto.envelope.CopyFrom(_envelope_to_proto(message.envelope))
proto.payload.CopyFrom(payload)
proto.meta.update(_string_map(message.meta))
for key, value in message.meta.items():
proto.meta[key].CopyFrom(_value_from_python(value))
return proto
@ -62,7 +63,11 @@ def canonical_message_from_proto(message: wire.CanonicalMessage) -> CanonicalMes
content_type=message.payload.content_type or None,
encoding=message.payload.encoding or None,
)
return CanonicalMessage(envelope=envelope, payload=payload, meta=dict(message.meta))
return CanonicalMessage(
envelope=envelope,
payload=payload,
meta={key: _python_from_value(value) for key, value in message.meta.items()},
)
def status_snapshot_to_proto(

View File

@ -31,7 +31,7 @@ def _message() -> ProtobufMessage:
message = cast(Any, wire.CanonicalMessage())
message.envelope.source = "src"
message.payload.text_value = "value"
message.meta["adapter_id"] = "file-a"
message.meta["adapter_id"].string_value = "file-a"
return message

View File

@ -87,7 +87,7 @@ def _message(
message.envelope.source = source
message.envelope.received_at.FromDatetime(received_at)
message.payload.text_value = value
message.meta["adapter_id"] = adapter_id
message.meta["adapter_id"].string_value = adapter_id
return message
@ -329,7 +329,8 @@ def test_cache_queries_work_for_multiple_live_adapters(tmp_path: Path) -> None:
)
assert len(list_response.list_response.messages) == 2
listed_ids = {
message.meta["adapter_id"] for message in list_response.list_response.messages
message.meta["adapter_id"].string_value
for message in list_response.list_response.messages
}
assert listed_ids == {"file-adapter", "dbus-adapter"}
@ -347,7 +348,7 @@ def test_cache_queries_work_for_multiple_live_adapters(tmp_path: Path) -> None:
)
assert len(filter_response.filter_response.messages) == 1
filtered = filter_response.filter_response.messages[0]
assert filtered.meta["adapter_id"] == "dbus-adapter"
assert filtered.meta["adapter_id"].string_value == "dbus-adapter"
assert filtered.envelope.source == "source-dbus"
finally:
supervisor.request_stop()

View File

@ -26,7 +26,7 @@ def _message(
if received_at is not None:
message.envelope.received_at.FromDatetime(received_at)
message.payload.text_value = value
message.meta["adapter_id"] = adapter_id
message.meta["adapter_id"].string_value = adapter_id
return message

View File

@ -13,7 +13,7 @@ def _sample_message() -> ProtobufMessage:
message = cast(Any, wire.CanonicalMessage())
message.envelope.source = "src"
message.payload.text_value = "hello"
message.meta["adapter_id"] = "file-a"
message.meta["adapter_id"].string_value = "file-a"
return message

View File

@ -25,6 +25,7 @@ def test_canonical_models_build_expected_shape():
transport="file",
received_at=datetime(2026, 4, 17, tzinfo=UTC),
encoding="utf-8",
details={"dbus": {"member": "Changed", "headers": {"sender": ":1.2"}}},
)
envelope = Envelope(
message_id="msg-1",
@ -38,7 +39,10 @@ def test_canonical_models_build_expected_shape():
message = CanonicalMessage(
envelope=envelope,
payload=payload,
meta={"raw_source": raw.source},
meta={
"raw_source": raw.source,
"dbus": {"member": "Changed", "headers": {"sender": ":1.2"}},
},
)
health = ConnectionHealth(state="CONNECTED", healthy=True)
status = AdapterStatus(
@ -56,13 +60,20 @@ def test_canonical_models_build_expected_shape():
)
assert raw.transport == "file"
assert raw.details["dbus"]["member"] == "Changed"
with pytest.raises(TypeError):
raw.details["dbus"]["headers"]["sender"] = "changed" # type: ignore[index]
assert message.envelope.message_id == "msg-1"
assert message.payload.data == {"hello": "world"}
assert message.meta["raw_source"] == "file:/tmp/input.json"
assert message.meta["dbus"]["member"] == "Changed"
assert status.connection.healthy is True
assert status.counters["messages_in_total"] == 1
assert wrapper.details["retry"] == 0
with pytest.raises(TypeError):
message.meta["dbus"]["headers"]["sender"] = "changed" # type: ignore[index]
def test_canonical_message_meta_is_immutable_mapping_reference():
meta = {"source": "local"}

View File

@ -43,6 +43,7 @@ from app.application.models import (
ServiceConfig,
)
from app.application.supervisor import ApplicationSupervisor
from app.shared.contracts.proto.v1 import canonical_message_from_proto
@dataclass
@ -257,6 +258,11 @@ def test_dbus_scan_snapshots_enter_cache_without_duplicates() -> None:
snapshot = supervisor.snapshot()
assert snapshot.details["cache"]["current_size"] == 1
assert snapshot.details["cache"]["metrics"]["cache_store_total"] == 1
cached_messages = supervisor._cache.list_messages() # type: ignore[attr-defined]
assert len(cached_messages) == 1
cached_message = canonical_message_from_proto(cached_messages[0])
assert cached_message.meta["dbus"]["interface_name"] == "wlan0"
assert cached_message.meta["dbus"]["monitored_ssid"] == "demo-net"
time.sleep(0.1)
snapshot = supervisor.snapshot()

View File

@ -535,13 +535,27 @@ def test_dbus_scan_snapshot_strategy_can_disable_ssid_filtering() -> None:
"demo-net",
"other-net",
]
assert payload["details"]["dbus_source"] == {
assert payload["details"]["dbus"] == {
"bus_name": "fi.w1.wpa_supplicant1",
"object_path": "/fi/w1/wpa_supplicant1/Interfaces/1",
"interface": "fi.w1.wpa_supplicant1.Interface",
"member": "ScanDone",
"signal_name": "ScanDone",
"source_uri": "wpa_supplicant://dbus/wlan0",
"identifier": "wlan0",
"interface_name": "wlan0",
"interface_path": "/fi/w1/wpa_supplicant1/Interfaces/1",
"monitored_ssid": "demo-net",
"filter_by_monitored_ssid": False,
"resolved_interface_path": "/fi/w1/wpa_supplicant1/Interfaces/1",
"scan_profile": {
"bands": [
{
"name": "2.4ghz",
"frequencies_mhz": [2412, 2437, 2462],
"channel_width_mhz": 20,
"passive": False,
}
]
},
}

View File

@ -75,7 +75,13 @@ class FakeDbusBackend:
if not self.connected:
raise RuntimeError("backend is not connected")
if self.received_messages:
return self.received_messages.pop(0)
return {
"payload": self.received_messages.pop(0),
"signal_name": member or "Changed",
"sender": ":1.2",
"destination": "org.example.Service",
"unique_name": ":1.99",
}
return None
def read_property(
@ -164,6 +170,10 @@ def test_dbus_connection_driver_round_trip_with_fake_backend():
)
assert message.transport == "d-bus"
assert message.received_at is not None
assert message.details["dbus"]["signal_name"] == "Ping"
assert message.details["dbus"]["sender"] == ":1.2"
assert message.details["dbus"]["destination"] == "org.example.Service"
assert message.details["dbus"]["unique_name"] == ":1.99"
payload = RawMessage(
data={"action": "ping"},

View File

@ -109,8 +109,11 @@ class FakeDbusBackend:
(bus_name, object_path, interface, member, timeout_seconds)
)
return {
"signal": member or "Signal",
"payload": {"value": 1},
"signal_name": member or "Signal",
"sender": ":1.2",
"destination": "org.example.Service",
"unique_name": ":1.99",
}
def read_property(
@ -228,6 +231,7 @@ def test_dbus_method_call_wrapper_invokes_methods_with_arguments() -> None:
"arguments": [1, "two"],
"keyword_arguments": {"flag": True},
}
assert result.details["dbus"]["member"] == "DoThing"
assert result.details["context"]["wrapper_name"] == "method"
@ -255,7 +259,11 @@ def test_dbus_signal_receive_wrapper_returns_signal_payload() -> None:
)
]
assert result.signal_name == "Changed"
assert result.payload == {"signal": "Changed", "payload": {"value": 1}}
assert result.payload == {"value": 1}
assert result.details["dbus"]["signal_name"] == "Changed"
assert result.details["dbus"]["sender"] == ":1.2"
assert result.details["dbus"]["destination"] == "org.example.Service"
assert result.details["dbus"]["unique_name"] == ":1.99"
def test_dbus_property_read_wrapper_reads_properties() -> None:

View File

@ -2,9 +2,31 @@
from __future__ import annotations
from app.adapters.skeleton.model import RawMessage
from app.adapters.skeleton.parsing import JsonMessageParser
from app.adapters.skeleton.parsing import JsonMessageParser as SkeletonJsonMessageParser
def test_json_parser_bridge_points_to_skeleton_implementation():
assert JsonMessageParser is SkeletonJsonMessageParser
def test_json_parser_merges_raw_details_into_canonical_meta() -> None:
parser = JsonMessageParser()
message = parser.parse(
RawMessage(
data={"value": 1},
source="dbus://scan",
details={
"dbus": {
"bus_name": "fi.w1.wpa_supplicant1",
"interface": "fi.w1.wpa_supplicant1.Interface",
"member": "ScanDone",
}
},
)
)
assert message.meta["parser"] == "json"
assert message.meta["dbus"]["member"] == "ScanDone"
assert message.meta["dbus"]["bus_name"] == "fi.w1.wpa_supplicant1"

View File

@ -61,17 +61,27 @@ def test_canonical_message_round_trip_and_payload_oneof_branches() -> None:
received_at=datetime(2026, 4, 18, 12, 0, tzinfo=UTC),
),
payload=payload,
meta={"adapter": "file", "parser": "json"},
meta={
"adapter": "file",
"parser": "json",
"dbus": {
"member": "Changed",
"sender": ":1.2",
"nested": {"unique_name": ":1.99"},
},
},
)
proto = canonical_message_to_proto(message)
roundtrip = canonical_message_from_proto(proto)
assert proto.payload.WhichOneof("kind") == expected_kind
assert proto.meta["dbus"].WhichOneof("kind") == "struct_value"
assert roundtrip.envelope == message.envelope
assert roundtrip.payload.content_type == message.payload.content_type
assert roundtrip.payload.data == message.payload.data
assert dict(roundtrip.meta) == dict(message.meta)
assert roundtrip.meta["dbus"]["nested"]["unique_name"] == ":1.99"
def test_status_snapshot_round_trip() -> None:

View File

@ -2,11 +2,125 @@
from __future__ import annotations
from dataclasses import dataclass, field
from app.adapters.skeleton.base import (
BaseAcquisitionStrategy,
BaseCommandExecutor,
BaseConnectionDriver,
BaseMessageParser,
)
from app.adapters.skeleton.config import UniversalAdapterConfig
from app.adapters.skeleton.model import CanonicalMessage, Envelope, Payload, RawMessage
from app.adapters.skeleton.runtime import UniversalAdapterRuntime
from app.adapters.skeleton.runtime import (
UniversalAdapterRuntime as SkeletonUniversalAdapterRuntime,
)
from app.shared.contracts import CommandRequest, CommandResult
from app.shared.observability import InMemoryObservabilityService
@dataclass
class FakeCommandExecutor(BaseCommandExecutor):
calls: list[CommandRequest] = field(default_factory=list)
def execute(self, request: CommandRequest) -> CommandResult:
self.calls.append(request)
return CommandResult(
ok=True,
status="OK",
message="completed",
payload={
"reply": "OK",
"command": request.name,
"interface_name": request.metadata.get("interface_name", ""),
"arguments": tuple(request.payload.get("arguments", ())),
},
metadata={"command_name": request.name},
)
@dataclass
class FakeExportPort:
messages: list[object] = field(default_factory=list)
def export(self, message: object) -> None:
self.messages.append(message)
class _NoopConnectionDriver(BaseConnectionDriver[RawMessage]):
def connect(self) -> None:
return None
def disconnect(self) -> None:
return None
def is_alive(self) -> bool:
return True
def receive(self) -> RawMessage | None:
return None
def send(self, message: RawMessage) -> None:
return None
class _NoopAcquisitionStrategy(BaseAcquisitionStrategy[RawMessage]):
def acquire(self, driver: BaseConnectionDriver[RawMessage]):
return []
class _NoopParser(BaseMessageParser[RawMessage, CanonicalMessage]):
def parse(self, message: RawMessage) -> CanonicalMessage:
return CanonicalMessage(
envelope=Envelope(source=message.source),
payload=Payload(data=message.data),
)
def test_external_runtime_bridge_points_to_skeleton_implementation():
assert UniversalAdapterRuntime is SkeletonUniversalAdapterRuntime
def test_runtime_execute_command_updates_observability_without_running_pipeline():
command_executor = FakeCommandExecutor()
export_port = FakeExportPort()
runtime = UniversalAdapterRuntime(
config=UniversalAdapterConfig(),
connection_factory=lambda _config, **_kwargs: _NoopConnectionDriver(),
acquisition_factory=lambda _connection, _acquisition, **_kwargs: _NoopAcquisitionStrategy(),
parser_factory=lambda _config, **_kwargs: _NoopParser(),
export_port=export_port,
command_executor=command_executor,
observability=InMemoryObservabilityService(
status_builder=runtime_observability_builder(),
),
)
result = runtime.execute_command(
CommandRequest(
name="PING",
payload={"arguments": ["verbose"]},
metadata={"interface_name": "wlan0"},
correlation_id="corr-1",
)
)
snapshot = runtime.status_snapshot()
assert result.ok is True
assert result.status == "OK"
assert command_executor.calls[0].name == "PING"
assert snapshot.last_command_at is not None
assert snapshot.details["handled_commands"] == 1
assert snapshot.details["command_errors"] == 0
assert runtime.observability is not None
assert runtime.observability.counters["commands_total"] == 1
assert runtime.observability.counters.get("command_errors_total", 0) == 0
assert export_port.messages == []
def runtime_observability_builder():
from app.shared.observability import StatusSnapshotBuilder
return StatusSnapshotBuilder(adapter_id="runtime-command")

View File

@ -85,6 +85,7 @@ class FakeAdapterRuntime(BaseAdapterRuntime):
self.started = False
self.stopped = False
self.cycles = 0
self.commands: list[CommandRequest] = []
def start(self) -> None:
self.started = True
@ -96,6 +97,10 @@ class FakeAdapterRuntime(BaseAdapterRuntime):
self.cycles += 1
return 1
def execute_command(self, request: CommandRequest) -> CommandResult:
self.commands.append(request)
return CommandResult(ok=True, status="handled", metadata={"name": request.name})
def status_snapshot(self) -> AdapterStatusSnapshot:
return AdapterStatusSnapshot(
adapter_id="adapter-1",

View File

@ -39,4 +39,4 @@ def test_stdout_proto_director_writes_length_delimited_frames() -> None:
decoded.ParseFromString(frames[0])
assert decoded.envelope.source == "source-1"
assert decoded.payload.WhichOneof("kind") == "json_value"
assert decoded.meta["adapter"] == "file"
assert decoded.meta["adapter"].string_value == "file"

View File

@ -2,9 +2,34 @@
from __future__ import annotations
from app.adapters.skeleton.model import RawMessage
from app.adapters.skeleton.parsing import TextMessageParser
from app.adapters.skeleton.parsing import TextMessageParser as SkeletonTextMessageParser
def test_text_parser_bridge_points_to_skeleton_implementation():
assert TextMessageParser is SkeletonTextMessageParser
def test_text_parser_merges_raw_details_into_canonical_meta() -> None:
parser = TextMessageParser()
message = parser.parse(
RawMessage(
data="CTRL-EVENT-CONNECTED\n",
source="wpa_supplicant://ctrl_event/wlan0",
details={
"dbus": {
"bus_name": "fi.w1.wpa_supplicant1",
"object_path": "/fi/w1/wpa_supplicant1/Interfaces/0",
"signal_name": "CTRL-EVENT-CONNECTED",
}
},
)
)
assert message.meta["parser"] == "text"
assert message.meta["dbus"]["signal_name"] == "CTRL-EVENT-CONNECTED"
assert (
message.meta["dbus"]["object_path"]
== "/fi/w1/wpa_supplicant1/Interfaces/0"
)

View File

@ -70,12 +70,22 @@ class UnixSocketFixture:
conn, _ = self.server_socket.accept()
with conn:
conn.settimeout(2)
conn.sendall(greeting)
if not self._safe_sendall(conn, greeting):
return
self.received.append(conn.recv(65536))
conn.sendall(response)
self._safe_sendall(conn, response)
finally:
self.finished.set()
def _safe_sendall(self, conn: socket.socket, payload: bytes) -> bool:
try:
conn.sendall(payload)
except BrokenPipeError:
return False
except OSError:
return False
return True
def test_unix_socket_connection_driver_round_trip():
socket_path = DATA_ROOT / "transport.sock"

View File

@ -23,6 +23,7 @@ class WpaCtrlSocketFixture:
socket_path: Path
status_reply: bytes = b"wpa_state=COMPLETED\nssid=demo\n"
event_reply: bytes = b"CTRL-EVENT-CONNECTED\n"
status_interleaved_event: bytes | None = None
server_socket: socket.socket | None = field(default=None, init=False)
thread: threading.Thread | None = field(default=None, init=False)
ready: threading.Event = field(default_factory=threading.Event, init=False)
@ -76,6 +77,8 @@ class WpaCtrlSocketFixture:
text = payload.decode("utf-8", errors="replace")
self.received_texts.append(text)
if text == "STATUS":
if self.status_interleaved_event is not None:
self._reply(addr, self.status_interleaved_event)
self._reply(addr, self.status_reply)
elif text == "PING":
self._reply(addr, b"OK\n")
@ -108,6 +111,23 @@ def test_ctrl_request_opens_expected_socket_path_and_sends_command(tmp_path: Pat
assert fixture.received_texts == ["STATUS"]
def test_ctrl_request_skips_interleaved_event_datagrams(tmp_path: Path) -> None:
socket_dir = tmp_path / "wpa_supplicant"
fixture = WpaCtrlSocketFixture(
socket_dir / "wlan0",
status_interleaved_event=b"<3>CTRL-EVENT-SCAN-STARTED\n",
)
fixture.start()
backend = WpaUnixSocketBackend(ctrl_socket_dir=str(socket_dir))
reply = backend.ctrl_request("wlan0", "STATUS", ())
fixture.stop()
assert reply == "wpa_state=COMPLETED\nssid=demo\n"
assert fixture.received_texts == ["STATUS"]
def test_ctrl_event_monitor_attaches_receives_and_detaches(tmp_path: Path) -> None:
socket_dir = tmp_path / "wpa_supplicant"
fixture = WpaCtrlSocketFixture(socket_dir / "wlan0")

View File

@ -0,0 +1,130 @@
"""Tests for the wpa_supplicant ctrl_iface command executor."""
from __future__ import annotations
from dataclasses import dataclass, field
from app.adapters.wpa_supplicant_adapter.commands import WpaCtrlIfaceCommandExecutor
from app.adapters.wpa_supplicant_adapter.wrappers import WpaWrapperTransportError
from app.shared.contracts import CommandRequest
@dataclass
class FakeCommandBackend:
ctrl_calls: list[tuple[str, str, tuple[str, ...], float | None]] = field(
default_factory=list
)
fail_on: str | None = None
reply_by_command: dict[str, str] = field(default_factory=dict)
def ctrl_request(
self,
interface_name: str,
command: str,
arguments: tuple[str, ...],
timeout_seconds: float | None = None,
) -> str | dict[str, object]:
self.ctrl_calls.append((interface_name, command, arguments, timeout_seconds))
if self.fail_on == command:
raise WpaWrapperTransportError("ctrl_iface transport failed")
if command in self.reply_by_command:
return self.reply_by_command[command]
if command == "STATUS":
return "wpa_state=COMPLETED\nssid=demo\n"
if command == "SCAN":
return "OK"
if command == "FAIL":
return "FAIL\n"
return "FAIL: unsupported command"
def test_command_executor_returns_raw_reply_and_normalizes_arguments() -> None:
backend = FakeCommandBackend()
executor = WpaCtrlIfaceCommandExecutor(backend=backend)
result = executor.execute(
CommandRequest(
name="STATUS",
payload={"arguments": [1, "verbose"], "timeout_seconds": 1.5},
metadata={"interface_name": "wlan0"},
correlation_id="corr-1",
)
)
assert backend.ctrl_calls == [("wlan0", "STATUS", ("1", "verbose"), 1.5)]
assert result.ok is True
assert result.status == "OK"
assert result.payload["reply"] == "wpa_state=COMPLETED\nssid=demo\n"
assert result.payload["arguments"] == ("1", "verbose")
assert result.payload["interface_name"] == "wlan0"
assert result.metadata["backend"] == "FakeCommandBackend"
def test_command_executor_marks_explicit_fail_reply_as_failed() -> None:
backend = FakeCommandBackend()
executor = WpaCtrlIfaceCommandExecutor(backend=backend)
result = executor.execute(
CommandRequest(name="FAIL", metadata={"interface_name": "wlan0"})
)
assert backend.ctrl_calls == [("wlan0", "FAIL", (), None)]
assert result.ok is False
assert result.status == "FAIL"
assert result.payload["reply"] == "FAIL\n"
def test_command_executor_reports_transport_error() -> None:
backend = FakeCommandBackend(fail_on="SCAN")
executor = WpaCtrlIfaceCommandExecutor(backend=backend)
result = executor.execute(
CommandRequest(name="SCAN", metadata={"interface_name": "wlan0"})
)
assert backend.ctrl_calls == [("wlan0", "SCAN", (), None)]
assert result.ok is False
assert result.status == "TRANSPORT_ERROR"
assert result.message == "ctrl_iface transport failed"
assert "reply" not in result.payload
def test_command_executor_supports_ctrl_socket_dir_override() -> None:
primary_backend = FakeCommandBackend()
override_backend = FakeCommandBackend(reply_by_command={"SCAN": "OK"})
seen_ctrl_socket_dirs: list[str] = []
def backend_factory(ctrl_socket_dir: str) -> FakeCommandBackend:
seen_ctrl_socket_dirs.append(ctrl_socket_dir)
return override_backend
executor = WpaCtrlIfaceCommandExecutor(
backend=primary_backend,
backend_factory=backend_factory,
)
result = executor.execute(
CommandRequest(
name="SCAN",
metadata={
"interface_name": "wlan0",
"ctrl_socket_dir": "/run/wpa_supplicant",
},
)
)
assert seen_ctrl_socket_dirs == ["/run/wpa_supplicant"]
assert primary_backend.ctrl_calls == []
assert override_backend.ctrl_calls == [("wlan0", "SCAN", (), None)]
assert result.ok is True
assert result.status == "OK"
def test_command_executor_rejects_missing_interface_name() -> None:
executor = WpaCtrlIfaceCommandExecutor(backend=FakeCommandBackend())
result = executor.execute(CommandRequest(name="STATUS"))
assert result.ok is False
assert result.status == "INVALID_REQUEST"
assert result.message == "interface_name is required"

View File

@ -18,6 +18,7 @@ from app.adapters.wpa_supplicant_adapter.model import (
file_descriptor,
)
from app.director.stdout_json import StdoutJsonMessageDirector
from app.shared.contracts import CommandRequest
from app.shared.observability import (
InMemoryObservabilityService,
StatusSnapshotBuilder,
@ -62,7 +63,7 @@ class FakeWpaBackend:
"reply": "wpa_state=COMPLETED\nssid=demo",
"details": {"state": "COMPLETED"},
}
if command == "PING":
if command in {"PING", "SCAN"}:
return "OK"
return "FAIL"
@ -129,6 +130,39 @@ def test_ctrl_iface_factory_runs_end_to_end_with_descriptor_metadata() -> None:
runtime.stop()
def test_ctrl_iface_factory_exposes_application_command_execution() -> None:
backend = FakeWpaBackend()
observability = InMemoryObservabilityService(
status_builder=StatusSnapshotBuilder(adapter_id="wpa-command")
)
descriptor = ctrl_iface_descriptor("wlan0")
factory = WpaSupplicantAdapterFactory(
source_descriptor=descriptor,
backend=backend,
export_port=StdoutJsonMessageDirector(stream=StringIO()),
observability=observability,
)
runtime = factory.create(_build_config("wpa-command"))
result = runtime.execute_command(
CommandRequest(
name="SCAN",
metadata={"interface_name": "wlan0"},
payload={"arguments": []},
)
)
snapshot = runtime.status_snapshot()
assert result.ok is True
assert result.status == "OK"
assert result.payload["reply"] == "OK"
assert backend.ctrl_calls == [("wlan0", "SCAN", (), None)]
assert snapshot.last_command_at is not None
assert snapshot.details["handled_commands"] == 1
assert observability.counters["commands_total"] == 1
def test_status_file_factory_runs_end_to_end(tmp_path: Path) -> None:
status_path = tmp_path / "wpa_status.txt"
status_path.write_text("wpa_state=COMPLETED\nssid=demo\n", encoding="utf-8")

View File

@ -77,6 +77,19 @@ def test_ctrl_iface_wrapper_normalizes_backend_response() -> None:
assert result.details["context"]["wrapper_name"] == "ctrl_iface"
def test_ctrl_iface_wrapper_marks_fail_reply_as_error() -> None:
backend = FakeWpaBackend()
wrapper = WpaCtrlIfaceWrapper(backend=backend)
result = wrapper.invoke(
WpaCtrlIfaceRequest(interface_name="wlan0", command="FAIL")
)
assert backend.ctrl_calls == [("wlan0", "FAIL", (), None)]
assert result.ok is False
assert result.reply == "FAIL"
def test_ctrl_iface_wrapper_rejects_empty_command() -> None:
wrapper = WpaCtrlIfaceWrapper(backend=FakeWpaBackend())