ios/chrome/browser/sessions/model/README.md

## Session saving and restoration.

A *Session* is the data Chrome saves to an iOS device's storage that preserves
the state of open tabs in a given Browser. On a device that only supports a 
single Chrome window, there will be one saved session for the regular tabs,
and one saved session for the Incognito tabs. On devices that support multiple
windows, there will be one or two (two if there are Incognito tabs) saved 
sessions for each window. 

Sessions are the mechanism by which a user's open tabs are restored when they
laucnh Chrome. Given that iOS can terminate Chrome in the background at any 
time -- and can disconnect individual scenes when there are multiple windows --
it's critical that sessions are saved and restored in a way that is quick and
lossless for the user.

(Don't confuse this Chrome-specific sense of *session* with the UIKit concept 
of a *scene session*, implemented in the `UISceneSession` class. While both are
concerned with persisting application state data, they are not interchangeable,
and Chrome's sessions are not implemented using UISceneSessions for storage.)

### Session saving

The design intent is that sessions are saved before Chrome enters a state where
it might be suddenly terminated. 

Saving a session is done by means of the `SessionRestorationBrowserAgent` for
the browser being saved, using the `SaveSession()` method. Calling this saves
the session for the browser the agent is attached to.

<!-- Add details on how sessions are saved; this depends on if the iOS15 APIs
for saving WKWebView interactionState are being used or not. Also describe
how per-window session saving is done. -->

`SaveSession()` is called in the following circumstances:
1. Whenever a sene moves to the background, `SaveSession()` is called on its 
   browsers. 
2. When the UI for a scene is destroyed (when the scene's `SceneController` is 
   shutting down), `SaveSession()` is called if it hasn't been called aready.
3. When a tab is inserted, removed, activated, replaced, re-ordered, or 
   completes a navigation, `SaveSession()` on the Browser that owns its
   WebStateList.
4. When a prerendered tab is loaded, replacing an existing webState, 
   `SaveSession()` on the browser whose WebStateList contains the new tab.

Case (1) is handled by `SessionSavingSceneAgent`, which watches for scene state
changes and tracks if the current scene has been foregrounded since the last 
time it was saved. Such scenes are marked as needing to have their sessions 
saved the next time they background.

Case (2) is handled by `SceneController` itself when it shuts down; it in turn
asks its `SessionSavingSceneAgent` to save its sessions if needed.

Case (3) is handled by `SessionRestorationBrowserAgent` via WebState and 
WebStateList observation.

Case (4) is handled by the `PrerenderService`; it directly calls 
`SaveSession()`, regardless of whether the session is in the background.

Cases (3) and (4) save after a short delay, and repeated session saves within
that delay are ignored. Cases (1) and (2) save immediately (canceling any 
pending delayed saves). `SessionServiceIOS` handles this. 

### Session Restoration

TODO: Describe when sessions are restored.

### Session Recovery

TODO: Describe the logic for post-crash session recovery and how sessions are
set aside and (possibly) discarded.

### Incognito Sessions

TODO: Describe how Incognito sessions are stored, and how it differs from how
regular session are.