Session

The browsing session shared by every browser in the application.

Cookies, caches, and other browsing data live in the session, so everything loaded by any BrowserView shares them.

import { session } from '@mobrowser/api';

Example 

import { session } from '@mobrowser/api';

console.log(session.storagePath)

Properties 

storagePath 

readonly storagePath: string;

The directory the session keeps its browsing data in, as an absolute path.

Cookies, caches, local storage, and the rest of the browsing data are stored under this directory. It is created when the application first starts, and its contents are not part of the public API — treat the path as a location to inspect or back up, not as a file layout to depend on.

Example 

import { session } from '@mobrowser/api';

console.log(`Browsing data lives in ${session.storagePath}`)

cookies 

readonly cookies: Cookies;

The cookie store of the session.

Example 

import { session } from '@mobrowser/api';

const cookies = await session.cookies.get({ url: 'https://example.com' })
console.log(`${cookies.length} cookies for example.com`)

proxyConfig 

readonly proxyConfig: ProxyConfig;

How the session is currently configured to reach the network.

This is what setProxy() was last given — in this run, or in an earlier one when the session is persistent and carried the setting over — and { mode: 'system' } when it has never been called. It reports the session’s own setting rather than the proxy a particular request ends up using, which also depends on the operating system, on any command-line switch the application was started with, and — in pacScript and autoDetect modes — on a script that is evaluated per URL. Use resolveProxy() to ask what a given URL would actually go through.

Example 

import { session } from '@mobrowser/api';

if (session.proxyConfig.mode === 'fixedServers') {
  console.log(`Proxying through ${session.proxyConfig.proxyRules}`)
}

userAgent 

readonly userAgent: string;

The user agent the session identifies itself with.

This is the string setUserAgent() was last given, or the one Chromium derives from its version and the platform when the application has not replaced it.

Example 

import { session } from '@mobrowser/api';

console.log(session.userAgent)

Methods 

isPersistent() 

isPersistent(): boolean;

Checks whether the session writes browsing data to disk.

A persistent session keeps cookies, caches, and local storage across restarts. A non-persistent session holds them in memory only and discards them when the application quits.

Return value 

True if the session writes browsing data to disk, false otherwise.

Example 

import { session } from '@mobrowser/api';

if (!session.isPersistent()) {
  console.log('Browsing data will be discarded on quit')
}

setUserAgent() 

setUserAgent(userAgent: string): void;

Replaces the user agent the session identifies itself with.

The new user agent reaches the pages that are already open as well as the ones loaded afterwards, but a page that has already loaded keeps reporting the previous value from navigator.userAgent until it navigates again.

@throws TypeError if userAgent is missing, empty, or not a string.

Example 

import { session } from '@mobrowser/api';

session.setUserAgent('MyApp/1.0')

getCacheSize() 

getCacheSize(): Promise<number>;

Measures how much disk space the HTTP cache is using.

Return value 

The size of the cache in bytes, as a promise. The figure is an estimate and may be an upper bound.

Example 

import { session } from '@mobrowser/api';

const bytes = await session.getCacheSize()
console.log(`The cache is using ${Math.round(bytes / 1e6)} MB`)

clearCache() 

clearCache(): Promise<void>;

Empties the HTTP cache.

Cookies, local storage, and the other browsing data are left alone. Use clearData() to remove those as well.

Return value 

A promise that resolves once the cache has been emptied.

Example 

import { session } from '@mobrowser/api';

await session.clearCache()

clearData() 

clearData(options?: ClearDataOptions): Promise<void>;

Removes browsing data.

Called with no options, it removes every kind of browsing data, for every site, of every age.

Return value 

A promise that resolves once the data has been removed. It is rejected when some of the data could not be removed. @throws TypeError if options is not an object, if one of its fields has the wrong type, if dataTypes names an unknown type, if an origin is not a valid URL, or if both origins and excludeOrigins are given.

Example 

import { session } from '@mobrowser/api';

// Sign the user out of one site.
await session.clearData({
  dataTypes: ['cookies', 'storage'],
  origins: ['https://example.com']
})

// Clear everything from the last hour.
await session.clearData({ since: Date.now() / 1000 - 3600 })

clearAuthCache() 

clearAuthCache(): Promise<void>;

Forgets the credentials the application has cached for HTTP authentication.

A site that asked for credentials earlier in the run asks again after this, which is what makes it the way to sign a user out of a site that uses HTTP authentication.

Return value 

A promise that resolves once the cached credentials are gone.

Example 

import { session } from '@mobrowser/api';

await session.clearAuthCache()

clearHostResolverCache() 

clearHostResolverCache(): Promise<void>;

Empties the cache of resolved host names.

The next request to each host resolves it again, which is what makes this useful after the machine changes network or its DNS records change.

Return value 

A promise that resolves once the cache has been emptied.

Example 

import { session } from '@mobrowser/api';

await session.clearHostResolverCache()

clearCodeCaches() 

clearCodeCaches(options?: ClearCodeCachesOptions): Promise<void>;

Drops the compiled code the engine has cached for scripts and WebAssembly modules.

The code is compiled again the next time a page runs it, so this costs only the time to recompile. It is worth doing when an application has replaced scripts that its pages load from a custom scheme, where the usual HTTP cache validation does not apply.

Return value 

A promise that resolves once the caches have been dropped. @throws TypeError if options is not an object, if urls is not an array of strings, or if one of them is not a valid URL.

Example 

import { session } from '@mobrowser/api';

await session.clearCodeCaches({ urls: ['app://bundle/main.js'] })

setProxy() 

setProxy(config: ProxyConfig): void;

Chooses how the session reaches the network.

The configuration is a session preference rather than a one-off request, so it stays in force until it is replaced and governs what the session loads from then on. Requests already in flight are not rerouted.

The preference is written before the call returns, but it reaches the network stack asynchronously, so a load started on the very next line may still go through the previous configuration. Await forceReloadProxyConfig() in between when a particular load has to use the new one; ordinary application code, where a navigation follows some later user action, does not need it.

A persistent session stores the preference alongside its browsing data, so it also survives relaunches: a configuration set in one run is still in force the next time the application starts, even if that run never calls setProxy(). An application that wants the default back has to ask for it with setProxy({ mode: 'system' }) rather than by leaving the call out. A non-persistent session keeps the preference in memory only and starts from the system configuration every time.

@throws TypeError if config is not an object, if mode is not one of the five modes, or if a field the chosen mode requires is missing or of the wrong type.

Example 

import { session } from '@mobrowser/api';

session.setProxy({
  mode: 'fixedServers',
  proxyRules: 'proxy.example.com:8080',
  exceptions: 'localhost'
})

resolveProxy() 

resolveProxy(url: string): Promise<string>;

Works out which proxy would be used to reach url.

Return value 

The proxy in PAC format, as a promise. It is either 'DIRECT' or a list such as 'PROXY proxy.example.com:8080; DIRECT'. The promise is rejected when url is not a valid URL, or when the lookup fails.

A proxy chain that PAC syntax cannot express, such as the pair of proxies IP Protection routes through, is reported in brackets instead — for example '[https://a.example.com:443, https://b.example.com:443]'. Treat the result as a string to show or log rather than one to parse.

Example 

import { session } from '@mobrowser/api';

const proxy = await session.resolveProxy('https://example.com')
console.log(`example.com is reached through ${proxy}`)

forceReloadProxyConfig() 

forceReloadProxyConfig(): Promise<void>;

Re-reads the proxy configuration and applies it.

Worth doing when the settings the session depends on may have changed underneath it — after the machine moves network in system mode, or when a PAC script has been replaced at the address it is served from.

It is also the sync point after setProxy(): awaiting it is how to be sure the next load uses the configuration just set, rather than the one it replaced. Note that this costs a re-fetch of the PAC script in pacScript mode, so it is worth awaiting where it matters rather than after every call.

Return value 

A promise that resolves once the configuration has been applied.

Example 

import { session } from '@mobrowser/api';

await session.forceReloadProxyConfig()