Use FrameTreeNode ID as frameId in extension APIs

chrome/common/extensions/docs/templates/intros/webNavigation.html

 <h2 id="manifest">Manifest</h2>
 <p>
 All <code>chrome.webNavigation</code> methods and events require you to declare
 the "webNavigation" permission in the <a href="manifest">extension
 manifest</a>.
 For example:
 </p>
 
 <pre data-filename="manifest.json">
 {
@@ skipping 85 matching lines @@
 It's important to note that some technical oddities in the OS's handling
 of distinct Chrome processes can cause the clock to be skewed between the
 browser itself and extension processes. That means that WebNavigation's events'
 <code>timeStamp</code> property is only guaranteed to be <i>internally</i>
 consistent. Comparing one event to another event will give you the correct
 offset between them, but comparing them to the current time inside the
 extension (via <code>(new Date()).getTime()</code>, for instance) might give
 unexpected results.
 </p>
 
-<h2 id="frame_ids">A note about frame and process IDs</h2>
+<h2 id="frame_ids">A note about frame IDs</h2>
 <p>
 Frames within a tab can be identified by a frame ID. The frame ID of the main
 frame is always 0, the ID of child frames is a positive number. Once a document

[Devlin, 2015/10/30 01:49:39]

If frame ID uniquely identifies the frame, it implies this needs to be updated.

[battre, 2015/11/02 13:54:57]

So this is a non-backwards compatible change, right? Do we have an update
process for that?

[Devlin, 2015/11/02 17:07:16]

I don't think this should really be a problem.  No one should be persisting
frame ids across sessions or reloads, I think (I'm pretty sure we make no
guarantees that frame ids are persistent at session restore or anything).  And
since frames are now uniquely identified, developers can still use the pair of
<process_id, frame_id> to uniquely identify the frame - it's just extra (but
everything should still work).  I'll let Rob confirm.

[battre, 2015/11/02 17:18:22]

My concern was the "The frame ID of the main frame is always 0" part. Is the
property maintained that the main frame will always carry the id 0?

[Devlin, 2015/11/02 17:28:47]

Oh, whoops (yay for Monday mornings).  Good point.

[robwu, 2015/11/02 19:08:34]

Done. I waited with updating this section until there is a test that actually
guarantees this behavior. I've now added this test
(WebNavigationApiTest.CrossProcessIframe).
This is a backwards-compatible change. I took much care to ensure that existing
extensions won't break (see the CL description and linked bug).
I've marked processId as deprecated, extension authors should use tabId +
frameId to uniquely identify a frame. We make no guarantees about the usefulness
of frameId across tabs, let alone sessions.

[battre, 2015/11/03 09:07:19]

My backwards compatibility concern is that in the past, an extension could have
written

if (details.frameId == 0)
  return "main_frame";

That could would break with this change, wouldn't it?

The WebRequest API has the following documentation:
"The value 0 indicates that the request happens in the main frame; a positive
value indicates the ID of a subframe in which the request happens. If the
document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId
indicates the ID of this frame, not the ID of the outer frame. Frame IDs are
unique within a tab [...]"

That would need to be updated as well.

[robwu, 2015/11/03 10:03:02]

frameId 0 is still the main frame. The semantics have not changed in that
respect. Here you can see how frameId is set:
https://codereview.chromium.org/1413543005/patch/60001/70042#newcode220
Currently, frames can be uniquely identified only by tabId + frameId +
processId. Now it is already unique for tabId + frameId (but adding processId in
the mix doesn't harm).
In patchset 4 I have added "As of Chrome 48, this ID is also constant for the
lifetime of the frame (across multiple navigations).".

 is constructed in a frame, its frame ID remains constant during the lifetime of
 the document.
 </p>
 <p>
-Due to the multi-process nature of Chrome, a tab might use different processes
-to render the source and destination of a web page. Therefore, if a navigation
-takes place in a new process, you might receive events both from the new and
-the old page until the new navigation is committed (i.e. the
-<code>onCommitted</code> event is send for the new main frame). Because frame
-IDs are only unique for a given process, the webNavigation events include a
-process ID, so you can still determine which frame a navigation came from.
-</p>
-<p>
 Also note that during a provisional load the process might be switched several
 times. This happens when the load is redirected to a different site. In this
 case, you will receive repeated <code>onBeforeNavigate</code> and
 <code>onErrorOccurred</code> events, until you receive the final
 <code>onCommitted</code> event.
 </p>
 
 <h2 id="transition_types">Transition types and qualifiers</h2>
 <p>
 The webNavigation API's <code>onCommitted</code> event has a
@@ skipping 30 matching lines @@
     The user used the Forward or Back button to initiate the navigation.
   </td>
 </tr>
 <tr>
   <td>"from_address_bar"</td>
   <td>
     The user initiated the navigation from the address bar (aka Omnibox).
   </td>
 </tr>
 </table>