docs(gossipsub): document subscription-filter hardening defaults#6452
Open
tonghuaroot wants to merge 2 commits into
Open
docs(gossipsub): document subscription-filter hardening defaults#6452tonghuaroot wants to merge 2 commits into
tonghuaroot wants to merge 2 commits into
Conversation
The default `AllowAllSubscriptionFilter` selected by `Behaviour::new` does not bound per-peer or per-RPC subscription growth. This is intentional -- subscription policy is owned by `TopicSubscriptionFilter`, not by the codec -- but operators wiring a fresh deployment can miss the requirement to opt into a bounded filter for untrusted-peer networks. Add user-facing documentation: - Crate root docs gain a "Production hardening" section recommending `MaxCountSubscriptionFilter` (or `WhitelistSubscriptionFilter` when the topic set is known up-front) with a minimal worked example using `Behaviour::new_with_subscription_filter_and_transform`. - `AllowAllSubscriptionFilter` doc comment is expanded to make the no-bound semantics explicit and to direct production users to the hardened constructor. - `Behaviour::new` docstring cross-links the hardened constructor and the filter chapter. - `WhitelistSubscriptionFilter` and `MaxCountSubscriptionFilter` doc comments call out their intended deployment scenarios. Discussed in the libp2p/rust-libp2p discussion thread following the review of PRs libp2p#6409 and libp2p#6428. Signed-off-by: tonghuaroot <tonghuaroot@gmail.com>
Signed-off-by: tonghuaroot <tonghuaroot@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Document the default subscription-filter behaviour and recommend a hardened production setup. No runtime / API changes — docs only.
Motivation
Behaviour::newselectsAllowAllSubscriptionFilterviaF::default(). That filter imposes no bound on per-RPC subscription entries or per-peer subscribed-topic accumulation. This is intentional design —TopicSubscriptionFilterowns subscription policy, codec-level truncation would silently bypass it — but the no-bound semantics are not currently surfaced in the user-facing docs, so a fresh deployment that callsBehaviour::newwithout further configuration is exposed to unbounded subscription growth from untrusted peers.Changes
protocols/gossipsub/src/lib.rs— new "Production hardening" section in the crate root docs, recommendingMaxCountSubscriptionFilter(orWhitelistSubscriptionFilterwhen the topic set is known up-front) and showing a minimalBehaviour::new_with_subscription_filter_and_transformexample.protocols/gossipsub/src/subscription_filter.rs— expanded doc comments onAllowAllSubscriptionFilter(explicit no-bound warning + production deployment guidance),WhitelistSubscriptionFilter(calls out the Eth2 use case as a canonical example), andMaxCountSubscriptionFilter(intended-use guidance and a worked snippet).protocols/gossipsub/src/behaviour.rs—Behaviour::newdocstring now cross-links the hardened constructor and the filter chapter.Testing
cargo doc --no-deps -p libp2p-gossipsubwithRUSTDOCFLAGS=-D warningsruns clean. No code changes; the existing test suite is unaffected.Notes for reviewers
The doc text frames the recommendation around the deployment model, not around a specific threat class, to match the project's preferred framing: subscription policy is the filter's responsibility, and operators choose the policy that fits their deployment.
Discussed with @jxs in the rust-libp2p discussion thread following the review of #6409 / #6428.