Chromium Docs

Modifying Session History Serialization

Note: Please expand these steps as needed. See also NavigationEntryImpl comments for how to save and restore values outside of PageState, which is less common.

Overview

The following (non-exhaustive) steps are required to add new values to the PageState data serialization process, which is used for saving and restoring values in session restore across different versions of Chromium, as well as tab restore and tab duplication within a running instance of Chromium.

Note that changing the serialization format is high risk and should be approached carefully. Mistakes or missed steps can cause backwards compatibility problems, because the effects can continue to live on disk between different versions of Chromium. For this reason, it is important to make these changes carefully, minimizing the risk of reverts (e.g., not as part of much larger CLs) or other back-and-forth between formats (e.g., not as part of an A/B experiment).

Please ask the CL reviewer to also consult this checklist to ensure no steps have been missed.

PageState Modification Checklist

  • Update NavigationEntryImpl's RecursivelyGenerateFrameEntries and RecursivelyGenerateFrameState in content/browser/renderer_host/navigation_entry_impl.cc to save and restore the new value from appropriate locations in Chromium.
  • Update any member declaration comments for the new value in content/browser/renderer_host/frame_navigation_entry.h, indicating if the new value is persisted if necessary (e.g. here).
  • Update third_party/blink/public/mojom/page_state/page_state.mojom, following the current instructions and warnings in the comments. These include (but are not limited to):
    • Search for Next MinVersion in the comments and increment it.
    • Add the new value under the appropriate section, remembering to increment the Next Ordinal value for that section. Include [MinVersion=<N>] in front of the mojom declaration for the newly added value. E.g. if adding a value to ExplodedFrameState, update the Next Ordinal value for the struct FrameState section.
  • Add the new element to ExplodedFrameState in third_party/blink/public/common/page_state/page_state_serialization.h.
  • Update the value of kCurrentVersion in third_party/blink/common/page_state/page_state_serialization.cc, and modify the comment above to explain what’s new in this version.
  • Update the WriteFrameState and ReadFrameState functions in third_party/blink/common/page_state/page_state_serialization.cc to save and restore the new value in the persistence format.
  • Update ExplodedFrameState::assign() to copy the new element so that its copy constructor and assignment operator works as expected.
  • Update the ExplodedFrameState-specialization of ExpectEquality() in third_party/blink/common/page_state/page_state_serialization_unittest.cc.
  • Update PopulateFrameStateForBackwardsCompatTest, for cases where the version value equals/exceeds the new kCurrentVersion set earlier.
  • Update PopulateFrameState to include the newly-added value.
  • Add a backwards compatibility test, TEST_F(PageStateSerializationTest, BackwardsCompat_v<NN>), where <NN> is replaced by the new kCurrentVersion value.
  • Add a new baseline data file third_party/blink/common/page_state/test_data/serialized_v<NN>.dat, using the following steps:
    • In third_party/blink/common/page_state/page_state_serialization_unittest.cc, find the #if 0 directive before TEST_F(PageStateSerializationTest, DumpExpectedPageStateForBackwardsCompat), and temporarily change it to #if 1.
    • Compile blink_common_unittests then run with --gtest_filter=PageStateSerializationTest.DumpExpectedPageStateForBackwardsCompat
    • This will create a file expected.dat in the temp directory (e.g. /tmp on Linux). Copy this file to third_party/blink/common/page_state/test_data/serialized_v<NN>.dat and run git add.
    • Remember to undo the #if 1 change made to page_state_serialization_unittest.cc above once the new baseline data has been created.

Example CLs modifying the format:

Example bugs from missing steps: