Gecko:Prerendering/API Review Guidelines

Pre-rendering API Review Guidelines

Our prerendering implementation relies on opportunistically allowing to prerender web pages, unless they do something bad, in which case we stop running the page, and throw away its resources etc. This page attempts to define some simple criteria on what needs to be considered as unsafe in prerendering. If you are reviewing a WebIDL change, please try to pay attention to these guidelines and request the patch authors to mark APIs as [UnsafeInPrerendering] as needed.

Rules of thumb

Our goal is to prerender as many pages as we possibly can. The most important thing to note is that the prerendered pages are invisible to the user and therefore we should try to avoid surprising the user if a page attempts to try something with externally visible side effects.

Also, note that prerendering is an optimization, and we can always fall back on doing a normal navigation, so when in doubt, it's probably OK to mark an API as [UnsafeInPrerendering] to err on the side of caution.

Also, in a lot of cases, the API has an entry point without which you won't be able to use any other part of the API. If the API is unsafe for prerendering, often it is enough to blacklist its entry point, so we don't need to eagerly put [UnsafeInPrerendering] annotations on all interfaces, etc. But please use caution to make sure you have thought about all entry points. When in doubt, opt for adding [UnsafeInPrerendering] annotations.

Red flags to look for

• APIs that allow the changes visible in the UI must be disallowed in all cases. Examples:
  • Window.open
  • Window.close
  • Element.requestFullScreen
  • Window.print
  • Navigator.getUserMedia

• APIs that allow changes visible in the external world even if they do not incur a UI
  • Making a phone call
  • Sending a text message
  • Audio/video playback

• APIs that can have unwanted side effects for the content being visibly rendered
  • Screen.lockOrientation

• APIs that can have unwanted side effects if invoked from an invisible page
  • Bluetooth API

• APIs that might be very difficult to get to work correctly in prerendering mode
  • NPAPI plugins

Things that we explicitly allow

There are some things that we explicitly allow here, even thought they can be considered an action with side effects. The most prominent examples are setting cookies, and storage APIs. The important thing to note is that these APIs have access to the data from the same origin as the prerendered page, so the possibility of unwanted side effects is minimal. Chrome and IE seem to have gotten away with allowing this too.