From 5d66896981330892284543a16e10a0858deff1a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81rni=20Dagur?= Date: Tue, 7 Apr 2020 19:29:53 -0400 Subject: [PATCH] Add documentation for BlockerResult --- src/blocker.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/blocker.rs b/src/blocker.rs index 09533ed..33db9b6 100644 --- a/src/blocker.rs +++ b/src/blocker.rs @@ -22,11 +22,39 @@ pub struct BlockerOptions { #[derive(Debug, Serialize)] pub struct BlockerResult { pub matched: bool, + /// Normally, Brave Browser returns `200 OK` with an empty body when + /// `matched` is `true`, except if `explicit_cancel` is also `true`, in + /// which case the request is cancelled. pub explicit_cancel: bool, + /// Important is used to signal that a rule with the `important` option + /// matched. An `important` match means that exceptions should not apply + /// and no further checking is neccesary--the request should be blocked + /// (empty body or cancelled). + /// + /// Brave Browser keeps seperate instances of [`Blocker`] for default + /// lists and regional ones, so `important` here is used to correct + /// behaviour between them: checking should stop instead of moving to the + /// next instance iff an `important` rule matched. pub important: bool, + /// Iff the blocker matches a rule which has the `redirect` option, as per + /// [uBlock Origin's redirect syntax][1], the `redirect` is `Some`. The + /// `redirect` field contains the body of the redirect to be injected. + /// + /// [1]: https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#redirect pub redirect: Option, + /// Exception is `Some` when the blocker matched on an exception rule. + /// Effectively this means that there was a match, but the request should + /// not be blocked. It is a non-empty string if the blocker was initialized + /// from a list of rules with debugging enabled, otherwise the original + /// string representation is discarded to reduce memory use. pub exception: Option, + /// Filter--similarly to exception--includes the string representation of + /// the rule when there is a match and debugging is enabled. Otherwise, on + /// a match, it is `Some`. pub filter: Option, + /// The `error` field is only used to signal that there was an error in + /// parsing the provided URLs when using the simpler + /// [`crate::engine::Engine::check_network_urls`] method. pub error: Option, }