Noissue - Add webrtc filter type to filter documentation

pages/filters.html

 title=Writing Adblock Plus filters
 
 
 <p>{{s1 Current Adblock Plus versions allow you to "tweak" your filters in many different ways. This document explains the choices that you have and how they can be used.}}</p>
 
   <p>{{s2 <em>Disclaimer</em>: All filter examples given here are really only examples and are not meant to be used.}}</p>
 
   <h2 id="introduction">{{s3 Introduction to Adblock Plus filters}}</h2>
 
   <p>{{s4 The options described in this section should be enough for users who have to create a filter occasionally.}}</p>
@@ skipping 134 matching lines @@
       <ul>
         <li>{{s57 <code><fix>script</fix></code> — external scripts loaded via HTML script tag}}</li>
         <li>{{s58 <code><fix>image</fix></code> — regular images, typically loaded via HTML img tag}}</li>
         <li>{{s59 <code><fix>stylesheet</fix></code> — external CSS stylesheet files}}</li>
         <li>{{s60 <code><fix>object</fix></code> — content handled by browser plugins, e.g. Flash or Java}}</li>
         <li>{{xmlhttprequest <code><fix>xmlhttprequest</fix></code> — requests started using the <a href="https://xhr.spec.whatwg.org/"><code><fix>XMLHttpRequest</fix></code> object</a> or <a href="https://fetch.spec.whatwg.org/"><code><fix>fetch()</fix></code> API</a>}}</li>
         <li>{{s63 <code><fix>object-subrequest</fix></code> — requests started by plugins like Flash}}</li>
         <li>{{s64 <code><fix>subdocument</fix></code> — embedded pages, usually included via HTML frames}}</li>
         <li>{{ping <code><fix>ping</fix></code> — requests started by <a href="https://developer.mozilla.org/docs/Web/HTML/Element/a#attr-ping"><code><fix>&lt;a ping&gt;</fix></code></a> or <a href="https://developer.mozilla.org/docs/Web/API/Navigator/sendBeacon"><code><fix>navigator.sendBeacon()</fix></code></a> (Adblock Plus 2.7.1 or higher required)}}</li>
         <li>{{websocket <code><fix>websocket</fix></code> — requests initiated via <a href="https://developer.mozilla.org/docs/Web/API/WebSocket"><code><fix>WebSocket</fix></code> object</a> (Adblock Plus 2.8 or higher required)}}</li>
-        <li>{{webrtc <code><fix>webrtc</fix></code> — requests initiated via <a href="https://developer.mozilla.org/docs/Web/API/RTCPeerConnection"><code><fix>RTCPeerConnection</fix></code> object</a> (Adblock Plus for Chrome and Opera 1.13.3 or higher required, Adblock Plus for Firefox and Safari not yet supported)}}</li>

[Sebastian Noack, 2017/05/22 13:59:37]

While it's probably not worth to add support for the legacy blocking mode on
Safari, I wonder whether connection to WebRTC ICE servers are actually blocked
through Content Blockers? If not done, yet all it would take is mapping $webrtc
filters to "raw". Same for $websocket. Manish, can you check this?

Also, I wonder whether we should specifically mention ICE servers here, as the
$webrtc option is essentially blocking requests to ICE servers, not to the
actual peers.

[kzar, 2017/05/22 14:06:41]

I see what you mean, but equally I'm trying to keep this short and simple. I've
made a small tweak to make it clearer that the connections are being made via a
peer connection instance, what do you think?

[Sebastian Noack, 2017/05/22 14:23:07]

Why not using the correct terminology and talk about ICE servers? In fact one
could argue that the actual peer connection (which is not blocked) is made by
the same instance (after all that's what the API is named like), based on the
peers discovered through the ICE server(s).

[kzar, 2017/05/22 14:26:44]

Do you have a suggestion of how we can do that without making it unclear to
someone who isn't a developer who's familiar with how the WebRTC API works?

[Sebastian Noack, 2017/05/22 14:55:32]

I don't have a particular suggestion, but how is mentioning the
RTCPeerConnection API/class any less technical than the existence of ICE
servers? I probably would keep mentioning both, so if you know about WebRTC but
not about ICE servers, you still know what this is about.

[Manish Jethani, 2017/05/29 13:38:19]

Safari does not support RTCPeerConnection. I just checked WebSocket, and it does
indeed block it.

I think we can map $websocket filters directly.

[Sebastian Noack, 2017/05/29 13:47:06]

So I guess let's map both, $websocket and $webrtc to "raw", in abp2blocklist.
Even if RTCPeerConnection isn't supported yet by Safari, when they add support
it might be blocked by the "raw" type as well.

As for the documentation change here, let's just not mention Safari.

+        <li>{{webrtc <code><fix>webrtc</fix></code> — connections opened via <a href="https://developer.mozilla.org/docs/Web/API/RTCPeerConnection"><code><fix>RTCPeerConnection</fix></code> instances</a> to ICE servers (Adblock Plus for Chrome and Opera 1.13.3 or higher required, Adblock Plus for Firefox and Safari not yet supported)}}</li>
         <li>{{s65 <code><fix>document</fix></code> — the page itself (only <a href="#whitelist">exception rules</a> can be applied to the page)}}</li>
         <li>{{s66 <code><fix>elemhide</fix></code> — for exception rules only, similar to <code><fix>document</fix></code> but only disables <a href="#elemhide">element hiding rules</a> on the page rather than all filter rules (Adblock Plus 1.2 or higher required)}}</li>
         <li>{{generichide <code><fix>generichide</fix></code> — for exception rules only, similar to <code><fix>elemhide</fix></code> but only disables <a href="#generic-specific">generic</a> element hiding rules on the page (Adblock Plus 2.6.12 or higher required)}}</li>
         <li>{{genericblock <code><fix>genericblock</fix></code> — for exception rules only, just like <code><fix>generichide</fix></code> but disables <a href="#generic-specific">generic</a> blocking rules (Adblock Plus 2.6.12 or higher required)}}</li>
         <li>{{s67 <code><fix>other</fix></code> — types of requests not covered in the list above}}</li>
       </ul>
       {{deprecated-options The type options <code><fix>background</fix></code>,
       <code><fix>xbl</fix></code> and <code><fix>dtd</fix></code> are outdated
       and should no longer be used.}}
     </li>
@@ skipping 105 matching lines @@
   {{s110 The data used for creating the signature is a concatenated list of request variables (namely URI, host and user agent) separated by the <code><fix>NUL</fix></code> character "\0". For example:}}
 </p>
 
 <pre>
   /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:30.0) Gecko/20100101 Firefox/30.0
 </pre>
 
 <p>
   {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
 </p>