README.md
1# DOM Storage
2
3*Under Contruction*
4
5# Session Storage (Mojo)
6
7*Under Contruction*
8
9The browser manages the lifetime of session storage namespaces with
10[SessionStorageNamespaceImpl](
11https://cs.chromium.org/chromium/src/content/browser/dom_storage/session_storage_namespace_impl.h).
12
13The object calls [`SessionStorageContextMojo::CreateSessionNamespace`](
14https://cs.chromium.org/chromium/src/content/browser/dom_storage/session_storage_context_mojo.h?dr=CSs&l=50)
15when it is created, and [`SessionStorageContextMojo::DeleteSessionNamespace`](
16https://cs.chromium.org/chromium/src/content/browser/dom_storage/session_storage_context_mojo.h?dr=CSs&l=53)
17when it's destructed.
18
19
20This object is primarily held by both the [`NavigationControllerImpl`](
21https://cs.chromium.org/chromium/src/content/browser/renderer_host/navigation_controller_impl.h?dr=CSs&l=426)
22and in the [`ContentPlatformSpecificTabData`](
23https://cs.chromium.org/chromium/src/components/sessions/content/content_platform_specific_tab_data.h?dr=C&l=35)
24which is used to restore tabs. The services stores recent tab
25closures for possible browser restore [here](
26https://cs.chromium.org/chromium/src/components/sessions/core/tab_restore_service_helper.h?dr=C&l=186).
27
28In the future when it's fully mojo-ified, the lifetime will be managed by the
29mojo [`SessionStorageNamespace`](
30https://cs.chromium.org/chromium/src/content/common/storage_partition_service.mojom)
31which can be passed to the renderer and the session restore service. There will
32always need to be an ID though as we save this ID to disk in the session
33restore service.
34
35## High Level Access And Lifetime Flow
36
37 1. Before a renderer tab is opened, a `SessionStorageNamespaceImpl` object is
38 created, which in turn calls
39 `SessionStorageContextMojo::CreateSessionNamespace`.
40 * This can happen by either navigation or session restore.
41 1. The following can happen in any order:
42 * Renderer creation, usage, and destruction
43 * The `session_namespace_id` is sent to the renderer, which uses
44 `StorageParitionService` to access storage.
45 * The renderer is destroyed, calling
46 `SessionStorageContextMojo::DeleteSessionNamespace`.
47 * If `SetShouldPersist(true)` was not called (or called with false),
48 then the data is deleted from disk.
49 * `SetShouldPersist(true)` is called from the session restores service,
50 which means the data should NOT be deleted on disk when the namespace is
51 destroyed. This is called for all tabs that the session restore services
52 wants to persist to disk.
53 * The session restore service calls
54 `DomStorageContext::StartScavengingUnusedSessionStorage` to clean up any
55 namespaces that are on disk but were not used by any recreated tab. This
56 is an 'after startup task', and usually happens before `SetShouldPesist`
57 is called.
58
59## Possible Edge Case: Persisted Data vs Stale Disk Data
60
61Namespace is created, persisted, destroyed, and then we scavange unused session
62storage.
63
64Flow:
65 1. `SessionStorageContextMojo::CreateSessionNamespace`
66 1. `SetShouldPersist(true)`
67 1. `SessionStorageContextMojo::DeleteSessionNamespace`
68 1. `DomStorageContext::StartScavengingUnusedSessionStorage`
69 1. The data should still reside on disk after scavenging.
70
71The namespace could accidentally be considered a 'leftover' namespace by the
72scavenging algorithm and deleted from disk.
73
74## Navigation Details
75
76When navigating from a previous frame, the previous frame will allocate a new
77session storage id for the new frame, as well as issue the 'clone' call [here](https://cs.chromium.org/chromium/src/content/renderer/render_view_impl.cc?q=RenderViewImpl::RenderViewImpl&l=1273).
78
79The `session_namespace_id` for a frame's session storage is stored in the
80`CreateNewWindowParams` object in [frame.mojom](https://cs.chromium.org/chromium/src/content/common/frame.mojom).
81
82If the frame wasn't created from a previous frame, the SessionStorage namespace
83object is created [here](https://cs.chromium.org/chromium/src/content/browser/renderer_host/navigation_controller_impl.cc?type=cs&l=1904)
84and the id is accessed [here](https://cs.chromium.org/chromium/src/content/browser/renderer_host/render_view_host_impl.cc?type=cs&l=321).
85
86## Renderer Connection to Session Storage
87
88Renderers use the `session_namespace_id` from the `CreateNewWindowParams`. They
89access session storage by using [`StoragePartitionService::OpenSessionStorage`](
90https://cs.chromium.org/chromium/src/content/common/storage_partition_service.mojom),
91and then `SessionStorageNamespace::OpenArea` with the `session_namespace_id`.
92
93They can then bind to a `LevelDBWrapper` on a per-origin basis.
94
95## Session Restore Service Interaction
96
97A reference to the session is stored in the [`ContentPlatformSpecificTabData`](
98https://cs.chromium.org/chromium/src/components/sessions/content/content_platform_specific_tab_data.h?dr=C&l=35)
99which is used to restore recently closed tabs. The services stores recent tab
100closures for possible browser restore [here](
101https://cs.chromium.org/chromium/src/components/sessions/core/tab_restore_service_helper.h?dr=C&l=186).
102
103When tabs are inserted, the session storage service saves the id to disk [here](https://cs.chromium.org/chromium/src/chrome/browser/sessions/session_service.cc?type=cs&l=313)
104using the `commands` (which are saved to disk). The session id is also accessed
105here for saving in `commands` in `TabClosing` and `BuildCommandsForTab`.
106