What is Session Restore, why this page?

Session Restore is the service that saves the state of Firefox while the user is browsing so as to be able to restore it after a shutdown or a crash.

This service is extremely useful but is also quite expensive. It was designed a long time ago, when users only had a few tabs, when DOM Storage didn't exist and before people started uploading Gigabytes of data. For this reason, it is undergoing major refactorings and redesigns.

This page is about documenting things progressively.

Collecting and saving data

TBD

Data we collect

• Open windows and tabs
• Closed windows and tabs (closed tabs, tabs in closed windows, closed tabs in closed windows)
• Loaded pages before and after (back and forward buttons)
• Form data (for the case of a browser or system crash)
• ... (TBD)

Data we do *not* collect

• ... (TBD)

Data we forget while browsing

• Pages loaded before, that are more then set in browser.sessionstore.max_serialize_back (since Firefox 30);
• Pages loaded after, that are more then set in browser.sessionstore.max_serialize_forward (since Firefox 30);
• Tabs/windows that are closed a long time before, set in browser.sessionstore.cleanup.forget_closed_after (target for Firefox 32);
• Tabs that are closed and more then set in browser.sessionstore.max_tabs_undo (since Firefox ??);
• Windows that are closed and more then set in browser.sessionstore.max_windows_undo (since Firefox ??);
• ...

Data we forget on a manual close of the browser

• ...

Privacy

• ... (TBD)

Technicality informations

Paths and file

Windows XP: TBD
Windows 7: [system-drive]:\Users\[user-name]\AppData\Roaming\Mozilla\Firefox\Profiles\[profile-name[.default]]\
Linux: TBD
Mac OS X: TBD
... (TBP)

File: sessionstore.js

File type: JSON (https://en.wikipedia.org/wiki/JSON)

Save interval: The file is saved whenever a change that needs to be saved is detected, with a cap that forces at least 15 seconds (by default) between two successive changes.

Backups files:
- sessionstore.bak
- sessionstore.bak-[yyyymmddtttttt]

Backups interval: ??? (TBP)

Browser settings

Session Store settings can be set by experienced users via about:config.

browser.sessionhistory.max_entries:
The maximum number of session history entries to keep in working memory (which includes the 'current' page).
Default: 50
Since: Firefox 30

browser.sessionhistory.max_total_viewers:
TBP
Default: -1
Since: Firefox ??

browser.sessionstore.cleanup.forget_closed_after:
TBP
Default: ??? (TBP)
Since: Firefox 32 (target)

browser.sessionstore.debug:
TBP
Default: false
Since: Firefox ??

browser.sessionstore.interval:
TBP
Default: 15000ms
Since: Firefox ??

browser.sessionstore.max_resumed_crashes:
TBP
Default: 1
Since: Firefox ??

browser.sessionstore.max_serialize_back:
The maximum number of 'back button' session history entries to store in sessionstore.js.
Default: 10 (-1 = no limit / 0 = only the currently active entry will be saved)
Since: Firefox 30

browser.sessionstore.max_serialize_forward:
The maximum number of 'forward button' session history entries to store in sessionstore.js.
Default: -1 (-1 = no limit / 0 = only the currently active entry will be saved)
Since: Firefox 30

browser.sessionstore.max_tabs_undo:
The maximum number of closed tabs that get saved.
Default: 10
Since: Firefox ??

browser.sessionstore.max_windows_undo:
The maximum number of closed windows that get saved.
Default: 3
Since: Firefox ??

browser.sessionstore.privacy_level:
TBP
Default: 0
Since: Firefox ??

browser.sessionstore.privacy_level_deferred:
TBP
Default: 1
Since: Firefox ??

browser.sessionstore.restore_hidden_tabs:
TBP
Default: false
Since: Firefox ??

browser.sessionstore.restore_on_demand:
TBP
Default: true
Since: Firefox ??

browser.sessionstore.restore_pinned_tabs_on_demand:
TBP
Default: false
Since: Firefox ??

browser.sessionstore.resume_from_crash:
TBP
Default: true
Since: Firefox ??

browser.sessionstore.resume_session_once:
TBP
Default: false
Since: Firefox ??

browser.sessionstore.upgradeBackup.latestBuildID:
TBP
Value: yyyymmddtttttt
Since: Firefox ??

services.sync.prefs.sync.browser.sessionstore.restore_on_demand:
TBP
Default: true
Since: Firefox ??

View content

With a extension:
Add-on: https://addons.mozilla.org/en-US/firefox/addon/about-sessionstore/
Author: https://addons.mozilla.org/en-US/firefox/user/dtryse/
This extension shows the content of the Session Store as a page in a tab/window, when the user opens about:sessionstore.
The Extension is also be able to "Forget closed tabs" and "Forget closed windows" and shows settings, timings and size.

Restoring sessions

SR is designed for the following use cases:
1. Crash recovery without losing state;
2. Quit and restart from the same browsing position (either manually or automatically);
3. Upgrade Firefox or Extensions without losing state.

For 1. and 3., we need to be able to resume in the exact same state, or users are going to be really annoyed – users can forgive a crash or an update if it just means that they lose the few seconds needed to restart Firefox, but not if they also lose their work. This means that we need to write all the costly stuff, including DOM Session Storage (which is currently what takes most of the disk space, iirc), forms, etc. Since crashes can happen at any time, we are pretty much in a dead-end here.

For 2., since the user has quit and reopened manually, we can afford to save less (actually, we already do). We could probably remove closed tabs and windows.

Now, while 2. is the least-commonly-used codepath (used only once per session), it can certainly be used to shrink the size of sessionstore.js for users who restart Firefox manually.

Telemetry

Early Telemetry indicates that 75% percent of Nightly users have a sessionstore.js weighing 194kb or less and 95% of users have 1.2Mb or less:
http://telemetry.mozilla.org/#nightly/29/FX_SESSION_RESTORE_FILE_SIZE_BYTES

And 100k+ users have a sessionstore.js >10MB.

The disk writes to sessionstore.js over an 8 hour day can be big:
https://bugzilla.mozilla.org/attachment.cgi?id=8443670

For developers

https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage#sessionStorage
http://dev.w3.org/html5/webstorage/#the-sessionstorage-attribute

The structure of sessionstore.js

• windows the currently opened windows (array)
  • tabs the currently opened tabs (array)
    • attributes a set of attributes persisted for the tab (object)
      • ... (TBD) (unused?)
    • entries the history of the tab (array)
      • url (string)
      • title (string, optional)
      • subframe is this an entry in a subframe? (boolean, optional)
      • cacheKey TBD (string, optional, need to check whether this is still good/useful with cache v2)
      • ID TBD (string, optional, unused?)
      • docshellID ID of the document owning this entry (string, buggy and possibly useless)
      • refererrURI URI of the referrer (string, optional)
      • srcdocdata if the document was loaded from an inline srcdoc, the data that was loaded instead of the URI (string, optional)
      • isSrcdocEntry was the document loaded from an inline srcdoc? (boolean, optional, could apparently be removed)
      • baseURI used for srcdoc loads to give view-source knowledge of the load's base URI as this information isn't embedded in the load's URI.(string, optional)
      • scroll x, y coordinates (string, optional)
      • owner_b64 serialized owner (string, optional, no clue what it's for)
      • docIdentifier TBD, cache related (string, optional, need to check whether this is still good/useful with cache v2)
      • structuredCloneState pushState state (string, optional)
      • structuredCloneVersion version of the algorithm required to restore structuredCloneState (number, optional)
      • children if this document has frames, entries for each frame(array, optional)
        • structure is the same as entries
    • extData a key/value store used by clients of Session Restore to store permanent information (object, optional)
    • hidden
    • image URL of the favicon used for this tab (string)
    • index index of the currently active entry in entries(number)
    • lastAccessed date of the last interaction with this tab (number of ms since epoch)
    • pinned is the tab pinned? (boolean)
    • userTypedValue text entered by the user in the address bar (string, optional)
    • closedAt if the tab is closed, the date at which it was closed (optional, ms since epoch)
  • selected the index of the currently selected tab in tabs(number)
  • _closedTabs the currently closed tabs (array)
    • (structure is the same as tabs)
  • busy is the window currently busy restoring/duplicating a tab? (boolean)
  • cookies the Session Cookies set for this window (array)
    • expiry (number)
    • host (string)
    • name (string)
    • path (string)
    • value (string)
  • extData a key/value store used by clients of Session Restore to store permanent information (object, optional)
  • height height of the window in pixels (number)
  • width width of the window in pixels (number)
  • screenX horizontal position of the window in pixels (number)
  • screenY vertical position of the window in pixels(number)
  • sizemode (one of "minimized", "maximized", "normal")
• selectedWindow the index of the currently selected window in windows
• _closedWindows the currently closed windows (array)
  • (structure is the same as windows)
• session metadata on the session itself
  • lastUpdate date of the last update (milliseconds since epoch)
  • startTime date of the session start (ms since epoch)
  • recentCrashes number of crashes since the latest good start
• global a key/value store used by clients of Session Restore to store permanent information (object, optional)
• scratchpads state of the scratchpads (array, optional)
  • (out of the control of Session Restore)
• lastSessionState if we deferred restoring a session, a representation of this session (object, optional)
  • (same structure as sessionstore.js)
• deferredInitialState (optional not sure I understand what it's for)
  • (same structure as sessionstore.js)

Redesigning sessionstore.js

Session Store causes a number of performance issues. This is a large (several megabytes), monolithic file, which needs to be fully rewritten every few seconds, which needs to be fully loaded on startup, which needs to be fully rebuilt on shutdown, etc.
We can certainly redesign it for better performance.

Bug 669034 - (sessionRestoreJank) [meta] Re-architect session restore to avoid periodic freezes
Bug 669603 - large sessionStorage data causes session restore to block the UI
Bug 810932 - Investigate how to redesign sessionstore.js for improved performance
Bug 934934 - [meta][Session Restore] Track sites that spam sessionstore.js, find defensive strategies

Google Group "mozilla.dev.platform" with discussion topic "Session Restore (sessionstore)".

Our problems

During startup

We need to read + parse everything, even when we restore-on-demand or do not restore at all:

• Slower startup
• Much I/O
• CPU-hungry
• Memory-hungry

During runtime

We need to serialize + write everything, even when only a single tab has changed.

• Slower runtime
• Much I/O (Screenshot from the about:sessionstore-extension with high Disk writes to sessionstore.js over an 8 hour day.)
• CPU-hungry
• Memory-hungry

Some pages store a lot of data in the Session Store. (Bug 934934)

During shutdown

• During shutdown, final serialize + write everything
• Much I/O (annoying)
• Slower shutdown (less annoying)
• CPU-hungry (less annoying)
• Memory-hungry (less annoying)

Improvements

Reduce amount of data stored

Good for: everything.

Limitations: there is only so much data we can cull away.

Difficulty: 2/5.

Compress data

Good for:

• startup I/O;
• runtime I/O;
• shutdown I/O.

Bad for:

• CPU (not much);
• Memory (not much);
• Human readability (a lot);
• Backwards compatibility (a lot);
• Add-ons compatibility (a lot).

Difficulty: 1/5.

Journalize files, consolidate them on idle-daily and shutdown

Good for reducing serialize + write:

• runtime I/O;
• runtime CPU use;
• runtime memory use.

Bad for:

• shutdown CPU use (probably not a big deal);
• shutdown memory use;
• runtime I/O, CPU, memory in case of crash;
• addon-compat;
• getBrowserState() & co. use a different path from SessionSaver.run.
• HD fragmentation / lots of small files

The consolidated version would not hurt readability.

Difficulty: 3/5.

(Most likely.)

Save separately index (one file), tabs (one file per tab)

Good for:

• startup I/O (unless the user);
• startup CPU;
• startup memory;
• startup duration;
• runtime I/O;
• runtime CPU;
• runtime memory;
• runtime duration.

Bad for:

• garbage-collecting files may be difficult;
• addon-compat;
• getBrowserState() & co. use a different path from SessionSaver.run.
• HD fragmentation / lots of small files

Readability would be ok.

Difficulty: 4/5.

Binary format that can be loaded/modified piecewise

Good for:

• startup I/O;
• startup CPU;
• startup memory;
• startup duration;
• runtime I/O;
• runtime CPU;
• runtime memory;
• runtime duration;
• HD / file system

Bad for:

• debugging;
• extensibility;
• garbage-collecting will be difficult;
• getBrowserState() & co. use a different path from SessionSaver.run();
• readability.

Difficulty: 5/5.

SQLite

Good for:

• startup I/O;
• startup CPU;
• startup memory;
• startup duration;
• runtime I/O;
• runtime CPU;
• runtime memory;
• runtime duration.
• HD / file system

Bad for:

• backups;
• use of flush() is bad for battery & rest of the system;
• garbage-collection will be moderately difficult;
• getBrowserState() & co. use a different path from SessionSaver.run.

Difficulty: 3/5.

Bug 937651 - Replace the sessionstore.js with an sessionstore.sqlite

https://en.wikipedia.org/wiki/SQLite

Other DBMS

?

Reducing the amount of data we store

History entries

TBD

DOM Session Storage

TBD

POST data

TBD

Forgetting closed tabs/windows after a time

Done as part of bug 989393.
Forget tabs/windows after two weeks.
Statistics shows that this had no big effect on the size of sessionstore.js at the moment.

Forgetting closed tabs/windows when Firefox closes normal

Via bug 989393 ???