feat(ocpp-cp): page v201 NotifyReport / NotifyMonitoringReport across tbc pages (M7)

[duyhuynh-vn]

Summary

Chunk the OCPP 2.0.1 device-model report streams into multiple correlated pages with toBeContinued (tbc) paging, so a large report is streamed faithfully instead of being silently capped at one WebSocket frame. Advances M7 — OCPP 2.0.1.

Closes #574

Real use case

A back office asks a charging station for its full device model — GetBaseReport(FullInventory) — to reconcile firmware/config before a maintenance window. A real station's device model is dozens to hundreds of variables, far more than fits in one practical WebSocket message. OCPP 2.0.1 defines paging precisely for this: the station streams several NotifyReport CALLs, each carrying a monotonic seqNo and tbc: true until the final page, all correlated by requestId. Until now the simulator emitted a single page regardless of size, so a large inventory (or a large GetMonitoringReport monitor set) was silently truncated — the operator would see only the first frame's worth of variables and reconcile against an incomplete picture. This makes the station report the whole model, in order, across as many pages as it takes.

What changed

crates/ocpp-cp only.

• v201_command — two pure page-splitters, v201_notify_report_pages and v201_notify_monitoring_report_pages, sharing a v201_report_pages core. Each chunks the snapshot into pages of at most V201_REPORT_ENTRIES_PER_PAGE (25) entries, numbers them with a monotonic seqNo from 0, and flags tbc: Some(true) on every page but the last. Every page echoes the triggering requestId and shares one generatedAt (the snapshot instant, passed in so the builder stays pure and clock-free).
• Empty report → still exactly one final page (seqNo 0, tbc omitted), with the array omitted rather than sent as []: the reportData / monitor arrays are minItems: 1 when present. No zero-page emission.
• Failure mode / trust boundary — seqNo is i32 on the wire; an i32::try_from(..).unwrap_or(i32::MAX) guard means a pathologically long report can never panic on the cast. Report contents are the station's own computed snapshot (not attacker-supplied); an oversized individual entry still surfaces as an outbound-schema Err from call(), never a panic or silent truncation — the same guarantee as the single-page path.
• lib.rs — rewired send_v201_notify_report / send_v201_notify_monitoring_report to emit each page in order via self.call(..), preserving requestId correlation and the command-consumer ordering guarantee (pages sent only after the triggering CALLRESULT is flushed, off the inbound-CALL path). Page size (25) sits comfortably above the seeded standard profile (~10 entries), so the default station still reports in a single page — the existing GetBaseReport(FullInventory) "exactly one page" test is unchanged.

What was ported

mobilityhouse/ocpp is protocol-only, so the paging behavior is the Charging Station's, not a Python module; the wire types being paged are already ported. Faithful to the paging contract of ocpp.v201.call.NotifyReport / NotifyMonitoringReport (tbc, seq_no, request_id, generated_at) and ocpp/v201/datatypes.py ReportDataType / MonitoringDataType. Mirrors the in-repo v201_notify_customer_information_pages / v201_report_charging_profiles_pages idiom.

Test plan

• cargo fmt --all --check ✅
• cargo clippy --all-targets -- -D warnings ✅
• cargo test --workspace ✅ (all green)

New tests:

• Pure builders (v201_command), both streams: small report → one unpaged page (seqNo 0, tbc omitted); large report (2*page+1 / page+1 entries) → correct page count, tbc: Some(true) on all but the last, monotonic seqNo, requestId echoed, one shared generatedAt, entries preserved in order across the boundary; empty → exactly one final page with the array omitted; every built page (incl. the empty page) is schema-valid.
• Integration (lib, capturing mock CSMS): grow the device model past one page, stream a real FullInventory report, and assert the ordered multi-page NotifyReport stream on the wire (per-page seqNo / tbc / requestId).

Acceptance criteria

• Both emitters emit multi-page streams: tbc: true on every page but the last, monotonic seqNo from 0, correlated by requestId, in order, off the command-consumer task.
• Pure page-splitters with schema-validity + tbc/seqNo unit tests, mirroring v201_notify_customer_information_pages.
• Small and empty reports keep today's single-page behavior; no zero-page emission.
• seqNo cast cannot panic; oversized entries surface as an outbound-schema Err, never a panic/truncation.
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test --workspace all green.

Known gaps / notes

• Page size is a fixed entry count (25), not a byte-accurate frame budget negotiated from the transport MTU — sufficient for the simulator; real frame-size negotiation is a later slice, as the issue notes.
• NotifyEvent (the third tbc-capable stream, single-page today per port(m7): CP simulator 2.0.1 — emit NotifyEvent when a CSMS-installed variable monitor trips #545/feat(ocpp-cp): emit v201 NotifyEvent when a variable monitor trips (M7) #570) is intentionally out of scope — it trips on a different trigger; a separate follow-up if a per-trip event set ever outgrows a frame.
• No new dependencies.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CiC3yVXvLLuCQMfknqv4vb

---

Generated by Claude Code

[duyhuynh-vn]

🌙 Nightly dev — 2026-09-12: resolved the merge conflict against main.

This PR had drifted to dirty after #576 (v201 SetVariables auto-trip monitor) landed on main. Both PRs appended test code to the same anchor in crates/ocpp-cp/src/lib.rs, and git interleaved the two tests on an identical ChargePoint::new(..) block they happen to share, producing the conflict.

Resolution (merge commit b3f088c, no history rewrite):

• De-interleaved the two tests, reconstructing each intact — send_v201_notify_report_streams_ordered_tbc_pages_over_the_wire (this PR) and v201_set_variables_crossing_emits_notify_event_after_response (feat(ocpp-cp): auto-trip a v201 variable monitor on a threshold-crossing SetVariables write (M7) #576) — and kept both helper blocks.
• Merged main in via a merge commit so existing checkouts stay valid.

Verified locally on the merge result:

• cargo fmt --all --check ✅
• cargo clippy --all-targets -- -D warnings ✅
• cargo test --workspace ✅ — all green; both formerly-conflicting tests pass.

mergeable_state is now clean. No product logic changed — the conflict was confined to the test module. Ready for your review.

---

Generated by Claude Code