User:Zeniko/Toolkit SessionStore Proposal

This is a proposal for generalizing Firefox's Session Restore component for all Toolkit applications.

Rationale

As of now, Session Restore is very browser specific. It doesn't (allow to) handle neither utility windows such as the Download Manager nor other applications such as Thunderbird. Factoring out the generally useful bits of the nsSessionStore component into a new mozISessionStore component living in Toolkit should make implementing crash recovering and session resuming simpler in all kinds of applications.

Overview

The non-browser specific bits of nsSessionStore mostly handle the update timing and a few general properties of the (browser) windows. This functionality will be exposed to applications/extensions through one single new interface: #mozISessionStore.

By itself, the new mozSessionStore component will track for all windows that opt-in:

• URI (needed for identification/restoration)
• dimensions
• name and features (as used when opening the window)
• owner (that one's AFAIK not serializable yet)
• virtual desktop (not yet exposed through DOM or XPCOM, either)

After a crash, all windows will then be (offered to be) restored to their correct place, but probably with default content. If an application/extension wants further data to be tracked, it can either associate that data with the window through the mozISessionStore interface - or it can use a data provider (see #mozISessionDataProvider) for dynamically updating a more complex state.

Interfaces

mozISessionStore

This core interface will be implemented by the "@mozilla.org/toolkit/sessionstore;1" component (mozSessionStore.js). It mainly provides methods for accessing/restoring session states from extensions and for integration into an application's UI.

interface mozISessionStore : nsISupports
{
	// Returns the current application state serialized as a JSON string,
	// resp. restores a session from such a state, closing all open windows
	// (unless they've been stickied)
	AString getApplicationState();
	void setApplicationState(in AString aState);

	// Allows to manually add/remove session data providers - which is
	// mostly needed for components and modules
	void addDataProvider(in mozISessionDataProvider aDataProvider);
	void removeDataProvider(in mozISessionDataProvider aDataProvider);

	// Retrieves/restores the state of a single window as far as data is available
	// (passing in |null| to setWindowState will create a new window)
	AString getWindowState(in nsIDOMWindow aWindow);
	nsIDOMWindow setWindowState(in nsIDOMWindow aWindow, in AString aState);

	// Allows extensions to annotate windows without having to implement
	// their own mozISessionDataProvider
	AString getWindowValue(in nsIDOMWindow aWindow, in AString aKey);
	void setWindowValue(in nsIDOMWindow aWindow, in AString aKey, in AString aStringValue);
	void deleteWindowValue(in nsIDOMWindow aWindow, in AString aKey);

 	// Gets/sets window session specific flags (flags can be combined)
 	// (these flags can also be set on a window's root element)
 	unsinged long getWindowFlags(in nsIDOMWindow aWindow);
	void setWindowFlags(in nsIDOMWindow aWindow, in unsinged long aFlags);
	// Tracked windows will be restored after restarts/crashes
	// (this flag will be set implicitly for windows that implement a data provider)
	const long WINDOW_TRACK = 1;
	// Stickied windows won't be closed by setApplicationState
	// (windows not being tracked will be sticky by default)
	const long WINDOW_STICKY = 2;

	// File listeners can modify the data before it's used at startup and
	// right before it's written to disk (allowing for encryption, etc.).
	// (file listeners added atStart are less likely to encounter garbled data)
	void addFileListener(in mozISessionFileListener aListener, in boolean aAtStart);
	void removeFileListener(in mozISessionFileListener aListener);

	// Requests session data to be updated and written to disk
	void scheduleSave();

	// Restarts collecting all data from scratch and instantly updates the file
	void clearPrivateData();

	// Command line handlers shouldn't open a default window when startupState isn't 0
	readonly attribute long startupState;
	const long STATE_NORMAL = 0;
	const long STATE_RESUMING = 1;
	const long STATE_RECOVERING = 2;
};

mozISessionDataProvider

Windows and components wanting to save session data will have to implement this interface. Components also have to register themselves with mozISessionStore. OTOH if an object named WindowStore present on the global window object implements this interfaces, it's implicitly used.

interface mozISessionDataProvider : nsISupports
{
	// Data serialized as a string (should be JSON); getting this should update
	// the hasChanged attribute, setting it should trigger state restoration
	attribute AString data;

	// Indicates mozISessionStore whether updating data is needed at all
	readonly attribute boolean hasChanged;

	// The ID is used for re-identifying a provider when updating state data
	// and when restoring a session (can be an empty string for implicit data providers)
	readonly attribute AString ID;
}

mozISessionFileListener

File listeners can be used e.g. for encrypting/decrypting session data or for sanitizing data before it hits the disk.

interface mozISessionFileListener : nsISupports
{
	// Process the serialized state and return it for usage/writing to disk
	// (returning an empty string will abort session restoring/file writing)
	aString processRead(in AString aState);
	aString processWrite(in AString aState);
}

mozISessionRecoveryHandler

Recovery handler are responsible for UI for the case of a crash. The mozSessionStore component as shipped with Toolkit will use a simple prompt for this (as Firefox currently does), while e.g. Firefox might use its own recovery handler for displaying an error page instead.

interface mozISessionRecoveryHandler : nsISupports
{
	// Handle the crashed session state in an appropriate way and
	// return whether recovering should continue
	boolean recoverState(in AString aState);
}

mozISessionTabbedDataProvider

Windows offering tabbed interfaces can implement this interface for offering extensions a predictable API for tab handling.

interface mozISessionTabbedDataProvider : mozISessionDataProvider
{
	// cf. mozISessionStore::getWindowState / mozISessionStore::setWindowState
	AString getTabState(in nsIDOMNode aTab);
	nsIDOMNode setTabState(in nsIDOMNode aTab, in AString aState);

	// API stub for implementing undo-close-tab functionality
	AString getClosedTabData();
	void undoCloseTab(in unsigned long aIndex);

	// Clone a tab as thoroughly as possible (ignoring privacy settings)
	nsIDOMNode duplicateTab(in nsIDOMNode aTab);

	// cf. mozISessionStore::getWindowValue, et al.
	AString getTabValue(in nsIDOMNode aTab, in AString aKey);
	void setTabValue(in nsIDOMNode aTab, in AString aKey, in AString aStringValue);
	void deleteTabValue(in nsIDOMNode aTab, in AString aKey);

	// Persists a specific attribute on all tabs for this data provider
	void persistTabAttribute(in AString aName);
}

Note: This interface might not be shipped with Toolkit, as it's not required for mozSessionStore to work. Shipping it nonetheless might help extensions, though - else it'll probably be included at least in Firefox.

Settings

A mozISessionStore implementation could use the following preferences:

Note: Not registering any data provider will effectively disable the component (except for a "domwindowopened" observer waiting for windows registering themselves implicitly), hence there should be no need for toolkit.sessionstore.enabled.

Notifications and Events

A mozISessionStore implementation should also dispatch the following notifications:

Furthermore the WindowRestored event should be dispatched on all restored windows' root element, notifying extensions that setWindowValue now might return new values.

Code examples

A Window's Data Provider

A simple data provider which saves/restores the Download Manager's search state.

// These two modules aren't always needed
Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");
Components.utils.import("resource://gre/modules/JSON.jsm");

// Implicit data provider
var WindowStore = {
	QueryInterface: XPCOMUtils.generateQI([Components.interfaces.mozISessionDataProvider]),

	ID:         "",   // data provider will be identified through the window's URI only
	hasChanged: true, // we always dynamically update the value (no caching implemented)

	get data() {
		return JSON.toString({
			search: document.getElementById("searchbar").value
		});
	},
	set data(aValue) {
		document.getElementById("searchbar").value = JSON.fromString(aValue).search;
		buildDownloadList();
	}
};

Minimal Code For Having a Window Restored

For simplicity, flags for a XUL window/dialog can also be set through a DOM attribute, e.g.:

<window sessionstore="track">
</window>

These flags are however not dynamically updated - instead they're just read once onLoad and then handled internally. They will then have to be changed through mozISessionStore::setWindowFlags.

Future of Firefox's Session Restore

nsSessionStore will still offer the same API, although most of it will be proxy methods for either the here proposed mozSessionStore component or the browser windows' mozISessionTabbedDataProvider implementations. These latter will contain most code related to actually saving/restoring the browser's session state.

nsSessionStore will further implement it's own mozISessionRecoveryHandler in order to offer an error page inside a browser tab from which tabs/windows of the crashed session can be unselected before the session is restored.

nsSessionStartup will go away, as mozSessionStore will take over most of it and nsSessionStore the rest. The only reason for nsSessionStartup was start-up performance - and with much code being moved into (an overlay to) browser.xul, there's no further reason for component splitting.

End users should however only note that utility windows such as the Downloads Manager are now restored as well.