78916d8455
Benchmarks (`python/bench/`, pytest-benchmark — opt-in via --benchmark-only): | Hot path | Mean | Ops/sec | % of 100 Hz budget | |---|---|---|---| | BfldFrame HT20 1×1×52 | 800 ns | 1.25 Mops | 0.008% | | BfldFrame HE20 2×1×242 | 1.3 μs | 750 kops | 0.013% | | BfldFrame HE80 2×1×996 | 4.2 μs | 236 kops | 0.042% | | BfldFrame HE160 2×2×1992 | 14 μs | 71 kops | 0.14% | | BfldFrame.feedback_matrix() | 2.8 μs | 352 kops | — | | WS edge_vitals decode | 7.4 μs | 134 kops | 0.074% | | WS pose_data decode (3 persons) | 23 μs | 42 kops | 0.24% | | BreathingExtractor.extract() 56sc | 28 μs | 35 kops | 0.28% | | BreathingExtractor.extract() 114sc | 44 μs | 23 kops | 0.44% | | BreathingExtractor.extract() 242sc | 79 μs | 13 kops | 0.79% | | HeartRateExtractor.extract() 56sc | 105 μs | 9.5 kops | 1.05% | All hot paths well under the 100 Hz ESP32 frame budget (10 ms). Worst case (HeartRateExtractor) uses 1% of the budget — no optimization needed. Scaling on n_subcarriers is sub-quadratic (56→242 = 4.3× input, 2.8× time) — catches future O(n²) regressions. Security & robustness tests (`tests/test_security.py`, +27 tests): - WS decoder: rejects non-object roots cleanly, survives 1 MB string values, handles non-ASCII node IDs, survives deeply-nested JSON (Python's json.loads built-in guard not bypassed) - MQTT topic matcher: 9 edge-case parametrize entries including $SYS topics, null-byte injection, mid-pattern `#` boundary, empty-string boundary - MQTT credential confidentiality: password never appears in repr()/str(), never stored in plain client-instance attribute - HA discovery: rejects null-byte-laced topics, rejects extra slashes in node_id, rejects non-dict payload body (list, scalar, invalid UTF-8 bytes) without crashing - Semantic primitive listener: rejects topic-injection attempts (prefix-injected paths, wrong case on final segment), survives invalid UTF-8 payloads - Public surface integrity: every name in wifi_densepose.__all__ AND wifi_densepose.client.__all__ resolves — catches accidental re-export breakage between phases - Multi-handler MQTT exception isolation: a crashing handler in the middle of the registered list doesn't stop later handlers from firing Test count: 156 → 183 (+27). All passing. Bench results steady-state confirm no Rust-binding-layer optimization is needed before the v2.0.0 publish. Refs: docs/adr/ADR-117-pip-wifi-densepose-modernization.md Refs: #785 Co-Authored-By: claude-flow <ruv@ruv.net> |
||
|---|---|---|
| .. | ||
| bench | ||
| src | ||
| tests | ||
| tombstone | ||
| wifi_densepose | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| README.md | ||
| pyproject.toml | ||
README.md
wifi-densepose v2.x — PyO3 bindings for the Rust core
This directory contains the source for the wifi-densepose PyPI wheel
(v2.0+). It's a PyO3 + maturin build that wraps the Rust crates in
v2/crates/ and replaces the legacy pure-Python
wifi-densepose==1.1.0 (released 2025-06-07).
See ADR-117 for the full modernization plan.
Build locally
# Install maturin + dev deps
pip install maturin pytest
# Develop-install — builds the Rust extension in-place
cd python
maturin develop
# Run the smoke tests
pytest tests/
The maturin develop command produces a debug-build wheel installed
into your current Python environment. For release builds:
maturin build --release --strip
The wheel lands under python/target/wheels/.
Layout
python/
├── Cargo.toml # PyO3 + abi3-py310 + Rust deps
├── pyproject.toml # maturin backend + Python metadata
├── README.md # this file
├── src/
│ └── lib.rs # #[pymodule] — Rust binding glue
├── wifi_densepose/ # pure-Python facade (the user-facing API)
│ ├── __init__.py # re-exports compiled module symbols
│ └── py.typed # PEP 561 typed-package marker
└── tests/
└── test_smoke.py # P1 acceptance tests
Phase status (per ADR-117 §6)
- ✅ P1 — Scaffold: module loads, version constant exposed,
6 smoke tests pass via
maturin develop. - ✅ P2 — Core type bindings:
Keypoint,KeypointType,BoundingBox,PersonPose,PoseEstimate. 51 additional tests. - ✅ P3 — Vitals + signal DSP:
VitalStatus,VitalEstimate,VitalReading,BreathingExtractor,HeartRateExtractorwithpy.allow_threadsGIL release on hot loops (Q5 tokio audit on 2026-05-24 confirmed core/vitals/signal are pure-sync). 17 tests. - ✅ P3.5 — BFLD bindings (stub Rust):
BfldKind,BfldFrame,BfldReport— forward-compatible Python surface for 802.11ac/ax/be Beamforming Feedback Loop Data. numpy Complex64 bridge. 19 tests. Real Rust ingestion lands post-v2.0 in awifi-densepose-bfldcrate (see ADR-117 §11.11/12); the Python API does not change. - ✅ P4 — WS/MQTT client: pure-Python
wifi_densepose.clientextra (no Rust).SensingClient(asyncio websockets),RuViewMqttClient(paho-mqtt v2 with VERSION2 callbacks),HABlueprintHelper(HA discovery payload parser),SemanticPrimitiveListener(typed router for the 10 HA-MIND primitives from ADR-115 §3.12). 63 tests including end-to-end against an in-processwebsockets.servefixture. - ⏳ P5 — cibuildwheel + PyPI publish (workflow shipped): GH Actions
workflow
.github/workflows/pip-release.ymlships the 5-wheel matrix (manylinux x86_64+aarch64, macosx x86_64+arm64, win amd64) plus sdist viacibuildwheel@2.21. Publish via PyPI Trusted Publisher (OIDC) onv2.X.Y-piptags or manual dispatch. One-time PyPI Trusted Publisher registration required before the first publish can fire. Q3 (witness hash v2 — ADR-117 §11.3) remains the hard gate before tagging. - ✅ P-tomb — v1.99.0 tombstone wheel: pure-Python wheel
(
python/tombstone/) whosewifi_densepose/__init__.pyraises ImportError with the migration URL on import. Verified locally (2.7 KB wheel) —pip install wifi_densepose-1.99.0-py3-none-any.whlthenpython -c "import wifi_densepose"raises ImportError as expected. Samepip-release.ymlworkflow publishes the tombstone onv1.99.0-piptag. Per ADR-117 §7.3, publish the tombstone BEFORE the first v2.0.0 publish to claim the "current" slot in pip's resolver.
Each phase ends with a checkbox PR. Tests are additive — every phase's smoke tests must still pass after later phases land.
Migrating from v1.x
The v1 line was a separate pure-Python implementation. v2 is a hard break (semver-justified by 11.5 months of stack drift). Migration guide ships in docs/migrations/wifi-densepose-1-to-2.md (landing in P5).