apollo_propeller: add backpressure flood test

[sirandreww-starkware]

Note

Medium Risk
Mostly test-only, but it expands the crate’s public API by exposing protocol, which could create unintended external dependencies and future compatibility obligations.

Overview
Adds a new integration test (tests/backpressure_test.rs) that spins up a custom libp2p FloodHandler to send many PropellerUnitBatch frames as fast as yamux allows, asserting the sender can complete without being blocked (documenting the current lack of end-to-end back-pressure).

Makes protocol a public module (pub mod protocol) so the test can construct PropellerProtocol/PropellerCodec and write raw frames into the receiver’s real Behaviour.

^{Written by Cursor Bugbot for commit 159516a. This will update automatically on new commits. Configure here.}

[reviewable-StarkWare]

This change is 

[sirandreww-starkware]

• apollo_propeller: handler fixes #13291
• apollo_propeller: handler tests #13290
• apollo_propeller: rate-limit invalid unit warnings in handler #13583
• apollo_propeller: remove HandlerOut::Unit from behaviour event path #13351
• apollo_propeller: guard inbound reads on non-empty unsent_units buffer #13582
• apollo_propeller: route inbound units through bounded channel #13350
• apollo_propeller: buffer unsent units from partial batches #13349
• apollo_propeller: wire bounded unit channels between handler and engine #13348
• apollo_propeller: add RegisterHandler command and inbound unit SelectAll #13347
• apollo_propeller: add inbound_channel_capacity config field #13346
• apollo_propeller: add backpressure flood test #13345 👈 (View in Graphite)
• apollo_propeller: wake poll from on_behaviour_event #13334
• apollo_propeller: drain send queue on DialUpgradeError #13332
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[guy-starkware]

@guy-starkware reviewed 2 files and all commit messages, and made 2 comments.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on ShahakShama and sirandreww-starkware).

---

crates/apollo_propeller/tests/backpressure_test.rs line 9 at r1 (raw file):

//! When full back-pressure is implemented (handler + behaviour), the sender's writes will return
//! Pending (yamux window closes because the receiver stops reading) and the assertion should be
//! flipped to verify the sender was blocked.

👍 💯

BTW if this didn't have an M-dash I would be more impressed.

Code quote:

//! Tests that demonstrate the lack of inbound back-pressure in the propeller stack.
//!
//! A custom FloodHandler writes raw PropellerUnitBatch frames as fast as yamux allows on a
//! propeller substream. The receiver runs the real propeller Behaviour. The test asserts that the
//! sender was able to write all batches without being slowed — documenting the vulnerability.
//!
//! When full back-pressure is implemented (handler + behaviour), the sender's writes will return
//! Pending (yamux window closes because the receiver stops reading) and the assertion should be
//! flipped to verify the sender was blocked.

---

crates/apollo_propeller/tests/backpressure_test.rs line 132 at r1 (raw file):

                unreachable!();
            };
            let mut framed = framed;

Suggestion:

            let FloodOutboundState::Sending(mut framed) =
                std::mem::replace(&mut self.outbound, FloodOutboundState::Done)
            else {
                unreachable!();
            };

[cursor]

PR Summary

Medium Risk
Changes are mostly test-only, but the new time/throughput-based integration test may be flaky in CI and the newly public protocol module expands the crate’s public API surface.

Overview
Makes apollo_propeller::protocol public so external code/tests can use PropellerProtocol/PropellerCodec.

Adds backpressure_test.rs, an integration test that spins up a custom libp2p FloodHandler to rapidly send PropellerUnitBatch frames to a real Behaviour and asserts the sender can complete TARGET_BATCHES within a timeout, explicitly documenting the current lack of inbound backpressure (and noting the assertion should flip once backpressure is implemented).

^{Reviewed by Cursor Bugbot for commit 0aa1086. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a6b2d65. Configure here.}

[cursor]

Internal module made unconditionally public for test

Low Severity

The protocol module was the only deliberately private non-test module in this crate. It's now made unconditionally pub solely so the integration test can import PropellerCodec and PropellerProtocol. The crate already defines an unused testing feature in Cargo.toml that could gate this visibility, avoiding leaking wire-level implementation details to all downstream consumers.

Additional Locations (1)

• crates/apollo_propeller/tests/backpressure_test.rs#L17-L18

 

^{Reviewed by Cursor Bugbot for commit a6b2d65. Configure here.}

[github-actions]

There hasn't been any activity on this pull request recently, and in order to prioritize active work, it has been marked as stale.
This PR will be closed and locked in 7 days if no further activity occurs.
Thank you for your contributions!