Improve engine events to expose internal workflow

[seia-soto]

fixes #3876

[chrmod]

Few things to address:

1. To have a better overview we should also emit information of the exceptions (unHide), similarly to how it is being done for the network matches.
2. how about we have one new event, lets call it match that would fire for both network and cosmetic filters. It's params should look alike for both types. (don't remove old event, they important for backwards compatibility)

I see it like this:

const context = { tabId: 1, frameId: 2 };
engine.getCosmeticsFilters(oldParams, withMetadata, context);
engine.match(request, withMetadata, context);
engine.on('match', (context, result) => {
  console.log(context, result.match, result.exception, result.metadata); 
});

Notice withMetadata for getCosmeticsFilters this is another capability to remember about. The result for the cosmetic filters should include the metadata in the same way the network result does.

[seia-soto]

@remusao I'd like to get a feedback about the way passing "context" to matching functions. It might help a lot for extension developers often used to involve tabId.

@chrmod This is actually an off-topic but if we involve devTools API, we can avoid involving tabId. The devtools apis are already provided in scope of the page, so we don't need to take care about the tabs.

Passing an external context can solve many complex situations but I'd like to go simple as possible. For example, we could decorate the passed Request object and many other things. Also, we're already passing request as an argument for network filter matches.

[remusao]

I wonder if we could make it clearer in the naming that this is a hostname-based march of a cosmetic rule. Also, that it does not mean it marched in the page, just that it was selected by the engine as a candidate to be injected (I think it’s important to make this clear to avoid confusion)

[chrmod]

Not sure if we need that many new events. How about we introduce one filter-matched which would emit:

• a filter, cosmetic or network
• a function name used to acquire the filter, like match, getHtmlFilters, getCosmeticsFilters
• function arguments, which can include additional info like the context: any. For network filters it is most important to get the request.

Additionally, would like to set a naming convention for the public interfaces for the filters. Sometimes we call those things rules (for instance in context of Cosmetic bucket), but on the interface level I would strony suggest we always call both network and cosmetic "rule" with a name of filters.
This will be a contrast to the DNR, where after conversion the filters become the rules.

[seia-soto]

In the last changes, the events were narrowed down to two: filter-matched and filter-excluded. Note that this idea was built top on the idea of adblocker debugger ui implementation.

Also, the commit addresses the followings:

• Proper naming of EngineEventContext (renamed to MatchingContext): this variable name is expected to cause a lot of confusions.
• MatchingContext was updated to the union type with a proper enum typing to support the sole and integrated event kinds: filter-matched and filter-excluded.
• The additional argument can be passed to methods was renamed to reference instead of context to reduce confusion.

[chrmod]

should we add filter-matched for network filters as well? that would be in engine.match and engine.matchAll

[chrmod]

Looks like while we develop this feature it started to change direction. All good, but it also got a bit complex. Lets try to simplify a bit before moving forward.

To recap the goal: We want to introduce new events that would allow us to implement a logger that is able to list matched filters and exceptions in a context of a given tab.

[chrmod]

shouldn't we emit redirects as well?

[seia-soto]

This is treated as a normal filter (result.filter) before being registered as result.redirect. The event should be triggered right after the filter match.

[chrmod]

LGTM, let me test it locally before merging.