wf-agent3

wf-agent3 - это рабочий репозиторий для Linux-демона, который собирает несколько адаптеров в один runtime, получает данные из разных источников и передаёт их через общий слой контрактов и директор-синки.

Этот README.md является основным документом по архитектуре, структуре репозитория, связям модулей и способам запуска. Отдельный ARCHITECTURE.md оставлен только как указатель на этот файл.

Назначение

Проект решает задачу skeleton-first архитектуры для адаптеров:

• общий каркас app.adapters.skeleton переиспользуется разными concrete adapter package;
• внутри adapter pipeline каноническая runtime-модель выражена Python dataclass;
• для внешнего application-facing wire contract используется versioned protobuf v1;
• director получает готовый export payload и не занимается source-specific parsing;
• shared contracts и observability живут в app.shared и остаются узкими точками интеграции;
• runtime рассчитан на Linux и systemd-oriented deployment.

Архитектурные решения

Ключевые решения в текущей версии кода:

1. Внутренний поток данных в адаптере построен на Python dataclass.
2. Общий wire contract для экспорта сообщений, статусов и observability использует protobuf v1 в src/app/shared/contracts/proto/v1/.
3. director является sink-слоем и не должен превращаться в parser layer.
4. Конкретные адаптеры строятся на базе skeleton через wrappers, factories и inheritance/composition, а не через дублирование логики.
5. Adapter core не импортирует concrete director implementations напрямую.
6. app.shared.contracts остаётся узкой, стабильной границей интеграции.
7. app.shared.observability собирает trace, metric и status snapshot модели.
8. Runtime и deployment ориентированы на Linux, foreground CLI и systemd.

Графическая схема

Ниже приведена упрощённая схема архитектуры и потоков между основными модулями. Если просмотрщик не поддерживает Mermaid, ориентируйтесь на текстовые разделы выше.

flowchart LR
    CLI[app.application.cli] --> CFG[app.application.config]
    CLI --> SUP[app.application.supervisor]
    CFG --> SUP

    SUP --> BRK[app.application.broker]
    SUP --> CCH[app.cache]
    SUP --> DRV[app.derivator.stub]
    SUP --> CCS[CacheControlServer]
    SUP --> ADS[app.adapters.* runtimes]

    ADS --> SKL[app.adapters.skeleton]
    SKL -. depends on .-> SHD[app.shared.contracts\nисточник типов]
    SKL --> OBS[app.shared.observability]
    SKL --> EXP[MessageExportPort]
    EXP --> BRK

    BRK --> DIR[app.director.*]
    BRK --> CCH
    BRK -. depends on .-> SHD
    DIR --> OUT[stdout_json / stdout_proto]

    CCS --> CTRL[Unix control socket]
    CLI --> CTRL

    OBS -. depends on .-> SHD
    CCH -. depends on .-> SHD
    DIR -. depends on .-> SHD
    DRV -. depends on .-> SHD
    OBS --> STAT[status snapshot / traces / metrics]
    DRV --> STAT

Основные модули и связи

src/app/application/

Слой композиции приложения и точка входа для CLI.

• cli.py разбирает команды serve, status/observability и cache.
• config.py загружает top-level YAML конфиг и строит application config.
• supervisor.py собирает broker, cache, derivator stub, control server и adapter runtimes.
• broker.py связывает export port, director и cache.
• models.py содержит application-level модели, состояния и типы конфигурации.

Связь: cli -> config -> supervisor -> broker -> director/cache.

src/app/cache/

Встроенный in-memory cache и локальный Unix control socket для admin/read операций.

• store.py хранит и выдаёт protobuf messages.
• control.py реализует control server/client поверх Unix socket.
• models.py содержит cache trace/events модели.

Связь: supervisor поднимает cache и control server, cli cache обращается к нему через локальный сокет.

src/app/derivator/

Сейчас это read-only cache-backed stub.

• stub.py даёт слой чтения/выборки поверх CacheReadPort.

Связь: supervisor подключает derivator stub рядом с cache, чтобы статус и операторские операции могли видеть кеш-состояние.

src/app/director/

Слой sink-ов для экспортированных сообщений.

• stdout_json остаётся compatibility sink.
• stdout_proto пишет length-delimited protobuf frames в stdout.

Связь: broker выбирает director по конфигу и отправляет туда готовый export payload.

src/app/shared/

Набор узких shared contracts и observability primitives.

• contracts/ports.py описывает MessageExportPort, ObservabilityPort, StatusSnapshotPort, cache contracts и command contracts.
• contracts/proto/v1/ содержит protobuf wire contract и converters.
• observability/ содержит in-memory observability service, trace/metric модели и builder статусов.

Связь: адаптеры и application layer используют эти контракты как стабильную границу интеграции.

src/app/adapters/skeleton/

Универсальный каркас адаптера.

• base/ содержит абстрактные интерфейсы stage-слоёв.
• model/ содержит canonical dataclass models.
• config/ содержит typed YAML schema, loader, validator и примеры.
• connection/ содержит connection state machine, reconnect policy и универсальные transport drivers.
• acquisition/ содержит acquisition strategies, progress snapshots и фабрики.
• parsing/ содержит parser helpers, errors, registry/factory и JSON/text parsers.
• validation/, prefilter/, marking/, commands/ содержат stub-слои и hook points.
• export/ содержит bridge к MessageExportPort.
• runtime/ содержит universal runtime lifecycle.
• factory/ содержит composition root для сборки runtime.
• wrappers/ содержит shared wrapper contracts и контекстные helper-объекты.

Связь: concrete adapters используют skeleton как универсальную основу и расширяют его через wrappers, factories и source-specific specialization.

src/app/adapters/file_adapter/

Concrete adapter package для файловых источников.

• содержит file-specific connection, acquisition, parsing, runtime и wrappers;
• ориентирован на polling/tail сценарии и local file fixtures.

src/app/adapters/dbus_adapter/

Concrete adapter package для D-Bus интеграций.

• содержит dbus-specific wrappers, connection, acquisition, parsing, runtime и factory;
• сохраняет source-specific logic внутри своего пакета.

src/app/adapters/wpa_supplicant_adapter/

Concrete adapter package для wpa_supplicant.

• содержит source/channel model, wrappers, connection, acquisition, parsing, runtime и factory;
• использует wrapper layer для взаимодействия с backend и file-backed test scenarios;
• поддерживает 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/

Общие stage interfaces, которые разделяются между реализациями адаптеров.

Структура репозитория

C:\Work\wf-agent3
├─ README.md
├─ ARCHITECTURE.md
├─ docs/
├─ deploy/
├─ src/
│  └─ app/
│     ├─ application/
│     ├─ cache/
│     ├─ derivator/
│     ├─ director/
│     ├─ shared/
│     └─ adapters/
└─ tests/

Назначение ключевых каталогов:

• docs/ содержит пользовательские и deployment-гайды.
• deploy/systemd/ содержит unit template для systemd.
• src/app/application/ содержит CLI, config loader, broker и supervisor.
• src/app/cache/ содержит cache/control plane.
• src/app/derivator/ содержит cache-backed derivator stub.
• src/app/director/ содержит sink-реализации.
• src/app/shared/ содержит shared contracts и observability.
• src/app/adapters/ содержит skeleton и concrete adapters.
• tests/ содержит unit и integration coverage для этих слоёв.

Поток выполнения

Типичный путь выполнения выглядит так:

1. CLI читает --config, WF_AGENT3_CONFIG или fallback /etc/wf-agent3/app.yaml.
2. ApplicationConfigLoader собирает top-level config.
3. ApplicationSupervisorBuilder создаёт supervisor.
4. Supervisor поднимает broker, cache, derivator stub и adapter runtimes.
5. Adapter runtime получает raw transport data.
6. Skeleton превращает данные в canonical dataclass model.
7. Данные проходят validation, prefilter и marking stub-слои.
8. Export bridge передаёт payload в MessageExportPort.
9. Broker отправляет данные в director и cache.
10. Observability service обновляет traces, metrics и status snapshot.

Как запускать

Основная команда:

wf-agent3 serve --config /etc/wf-agent3/app.yaml

Дополнительные команды:

wf-agent3 status
wf-agent3 observability
wf-agent3 cache status
wf-agent3 cache list --limit 100
wf-agent3 cache filter --adapter-id file-polling-json
wf-agent3 cache clear

Особенности CLI:

• wf-agent3 без subcommand эквивалентен wf-agent3 serve.
• Если не задан --config и не установлен WF_AGENT3_CONFIG, используется /etc/wf-agent3/app.yaml.
• status и observability показывают агрегированный application status snapshot в JSON.
• cache команды работают только если включён cache и задан service.control_socket_path.

Быстрый smoke-run

Для быстрого локального запуска используйте пример конфигурации:

wf-agent3 serve --config src/app/application/examples/daemon_multi_adapter.yaml

Для файла ввода можно использовать пример из src/app/adapters/skeleton/config/examples/.

Документация

• docs/usage_guide.md - подробное руководство по CLI и операциям приложения.
• docs/debian_deployment.md - развёртывание на Debian с systemd и virtualenv.
• docs/protobuf_wire_contract.md - wire contract protobuf v1.
• docs/adapter_extension_guide.md - правила расширения skeleton и wrapper model.

Примечание по архитектуре

Подробная архитектурная справка перенесена в этот README.md. Файл ARCHITECTURE.md сохранён как короткий указатель и не должен содержать дублирующее описание.