From 47d7d49d192e79770c2dd4b73e2279a199d450cd Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 20:47:11 +0800 Subject: [PATCH 1/7] Add session module --- atom/browser/api/lib/app.coffee | 6 ------ atom/browser/api/lib/exports/electron.coffee | 3 +++ atom/browser/api/lib/session.coffee | 17 +++++++++++++++++ atom/browser/api/lib/web-contents.coffee | 2 +- filenames.gypi | 1 + 5 files changed, 22 insertions(+), 7 deletions(-) create mode 100644 atom/browser/api/lib/session.coffee diff --git a/atom/browser/api/lib/app.coffee b/atom/browser/api/lib/app.coffee index 3db4582abc7..9f9f5811d76 100644 --- a/atom/browser/api/lib/app.coffee +++ b/atom/browser/api/lib/app.coffee @@ -2,7 +2,6 @@ electron = require 'electron' {EventEmitter} = require 'events' bindings = process.atomBinding 'app' -sessionBindings = process.atomBinding 'session' downloadItemBindings = process.atomBinding 'download_item' app = bindings.app @@ -61,11 +60,6 @@ deprecate.event app, 'activate-with-no-open-windows', 'activate', (event, hasVis deprecate.event app, 'select-certificate', 'select-client-certificate' # Wrappers for native classes. -wrapSession = (session) -> - # session is an EventEmitter. - session.__proto__ = EventEmitter.prototype -sessionBindings._setWrapSession wrapSession - wrapDownloadItem = (downloadItem) -> # downloadItem is an EventEmitter. downloadItem.__proto__ = EventEmitter.prototype diff --git a/atom/browser/api/lib/exports/electron.coffee b/atom/browser/api/lib/exports/electron.coffee index f0c3b87c987..3f7d9b1a13f 100644 --- a/atom/browser/api/lib/exports/electron.coffee +++ b/atom/browser/api/lib/exports/electron.coffee @@ -42,6 +42,9 @@ Object.defineProperties module.exports, screen: enumerable: true get: -> require '../screen' + session: + enumerable: true + get: -> require '../session' Tray: enumerable: true get: -> require '../tray' diff --git a/atom/browser/api/lib/session.coffee b/atom/browser/api/lib/session.coffee new file mode 100644 index 00000000000..e0fc7b6e0bc --- /dev/null +++ b/atom/browser/api/lib/session.coffee @@ -0,0 +1,17 @@ +{EventEmitter} = require 'events' + +bindings = process.atomBinding 'session' + +PERSIST_PERFIX = 'persist:' + +exports.fromPartition = (partition='') -> + if partition.startsWith PERSIST_PERFIX + bindings.fromPartition partition.substr(PERSIST_PERFIX.length), false + else + bindings.fromPartition partition, true + +wrapSession = (session) -> + # session is an EventEmitter. + session.__proto__ = EventEmitter.prototype + +bindings._setWrapSession wrapSession diff --git a/atom/browser/api/lib/web-contents.coffee b/atom/browser/api/lib/web-contents.coffee index 1a224c7416f..335928dcea8 100644 --- a/atom/browser/api/lib/web-contents.coffee +++ b/atom/browser/api/lib/web-contents.coffee @@ -1,5 +1,5 @@ {EventEmitter} = require 'events' -{deprecate, ipcMain, NavigationController, Menu} = require 'electron' +{deprecate, ipcMain, session, NavigationController, Menu} = require 'electron' binding = process.atomBinding 'web_contents' diff --git a/filenames.gypi b/filenames.gypi index 7e1f3e1827e..7157079178e 100644 --- a/filenames.gypi +++ b/filenames.gypi @@ -26,6 +26,7 @@ 'atom/browser/api/lib/power-monitor.coffee', 'atom/browser/api/lib/power-save-blocker.coffee', 'atom/browser/api/lib/protocol.coffee', + 'atom/browser/api/lib/session.coffee', 'atom/browser/api/lib/screen.coffee', 'atom/browser/api/lib/tray.coffee', 'atom/browser/api/lib/web-contents.coffee', From 1392873cbc2c522877448cec2990c73517f29912 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 21:03:42 +0800 Subject: [PATCH 2/7] Add session.defaultSession and remove app.defaultSession The latter has never been a public API, no need to keep it. --- atom/browser/api/atom_api_app.cc | 18 +----------------- atom/browser/api/atom_api_app.h | 3 --- atom/browser/api/lib/app.coffee | 10 +++++----- atom/browser/api/lib/browser-window.coffee | 4 +++- atom/browser/api/lib/session.coffee | 6 ++++++ 5 files changed, 15 insertions(+), 26 deletions(-) diff --git a/atom/browser/api/atom_api_app.cc b/atom/browser/api/atom_api_app.cc index 28c3b4c1598..697d6eca6aa 100644 --- a/atom/browser/api/atom_api_app.cc +++ b/atom/browser/api/atom_api_app.cc @@ -206,14 +206,6 @@ void App::OnWillFinishLaunching() { } void App::OnFinishLaunching() { - // Create the defaultSession. - v8::Locker locker(isolate()); - v8::HandleScope handle_scope(isolate()); - auto browser_context = static_cast( - AtomBrowserMainParts::Get()->browser_context()); - auto handle = Session::CreateFrom(isolate(), browser_context); - default_session_.Reset(isolate(), handle.ToV8()); - Emit("ready"); } @@ -325,13 +317,6 @@ std::string App::GetLocale() { return l10n_util::GetApplicationLocale(""); } -v8::Local App::DefaultSession(v8::Isolate* isolate) { - if (default_session_.IsEmpty()) - return v8::Null(isolate); - else - return v8::Local::New(isolate, default_session_); -} - bool App::MakeSingleInstance( const ProcessSingleton::NotificationCallback& callback) { if (process_singleton_.get()) @@ -382,8 +367,7 @@ mate::ObjectTemplateBuilder App::GetObjectTemplateBuilder( .SetMethod("allowNTLMCredentialsForAllDomains", &App::AllowNTLMCredentialsForAllDomains) .SetMethod("getLocale", &App::GetLocale) - .SetMethod("makeSingleInstance", &App::MakeSingleInstance) - .SetProperty("defaultSession", &App::DefaultSession); + .SetMethod("makeSingleInstance", &App::MakeSingleInstance); } // static diff --git a/atom/browser/api/atom_api_app.h b/atom/browser/api/atom_api_app.h index ee7e0207912..a6f99d65e0a 100644 --- a/atom/browser/api/atom_api_app.h +++ b/atom/browser/api/atom_api_app.h @@ -87,9 +87,6 @@ class App : public AtomBrowserClient::Delegate, bool MakeSingleInstance( const ProcessSingleton::NotificationCallback& callback); std::string GetLocale(); - v8::Local DefaultSession(v8::Isolate* isolate); - - v8::Global default_session_; scoped_ptr process_singleton_; diff --git a/atom/browser/api/lib/app.coffee b/atom/browser/api/lib/app.coffee index 9f9f5811d76..c2116fb7bca 100644 --- a/atom/browser/api/lib/app.coffee +++ b/atom/browser/api/lib/app.coffee @@ -1,4 +1,4 @@ -electron = require 'electron' +{deprecate, session, Menu} = require 'electron' {EventEmitter} = require 'events' bindings = process.atomBinding 'app' @@ -8,10 +8,10 @@ app = bindings.app app.__proto__ = EventEmitter.prototype app.setApplicationMenu = (menu) -> - electron.Menu.setApplicationMenu menu + Menu.setApplicationMenu menu app.getApplicationMenu = -> - electron.Menu.getApplicationMenu() + Menu.getApplicationMenu() app.commandLine = appendSwitch: bindings.appendSwitch, @@ -35,7 +35,8 @@ app.getAppPath = -> appPath # Helpers. -app.resolveProxy = (url, callback) -> @defaultSession.resolveProxy url, callback +app.resolveProxy = (url, callback) -> + session.defaultSession.resolveProxy url, callback # Routes the events to webContents. for name in ['login', 'certificate-error', 'select-client-certificate'] @@ -44,7 +45,6 @@ for name in ['login', 'certificate-error', 'select-client-certificate'] webContents.emit name, event, args... # Deprecated. -{deprecate} = electron app.getHomeDir = deprecate 'app.getHomeDir', 'app.getPath', -> @getPath 'home' app.getDataPath = deprecate 'app.getDataPath', 'app.getPath', -> diff --git a/atom/browser/api/lib/browser-window.coffee b/atom/browser/api/lib/browser-window.coffee index 99921372f14..4cdffae87a6 100644 --- a/atom/browser/api/lib/browser-window.coffee +++ b/atom/browser/api/lib/browser-window.coffee @@ -1,10 +1,12 @@ -{app, ipcMain, deprecate} = require 'electron' +{ipcMain, deprecate} = require 'electron' {EventEmitter} = require 'events' {BrowserWindow} = process.atomBinding 'window' BrowserWindow::__proto__ = EventEmitter.prototype BrowserWindow::_init = -> + {app} = require 'electron' # avoid recursive require. + # Simulate the application menu on platforms other than OS X. if process.platform isnt 'darwin' menu = app.getApplicationMenu() diff --git a/atom/browser/api/lib/session.coffee b/atom/browser/api/lib/session.coffee index e0fc7b6e0bc..6abfe7925e6 100644 --- a/atom/browser/api/lib/session.coffee +++ b/atom/browser/api/lib/session.coffee @@ -4,12 +4,18 @@ bindings = process.atomBinding 'session' PERSIST_PERFIX = 'persist:' +# Returns the Session from |partition| string. exports.fromPartition = (partition='') -> if partition.startsWith PERSIST_PERFIX bindings.fromPartition partition.substr(PERSIST_PERFIX.length), false else bindings.fromPartition partition, true +# Returns the default session. +Object.defineProperty exports, 'defaultSession', + enumerable: true + get: -> exports.fromPartition '' + wrapSession = (session) -> # session is an EventEmitter. session.__proto__ = EventEmitter.prototype From dd8ef33e42e46bf5d80776b77ab457d1761bbc33 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 21:10:50 +0800 Subject: [PATCH 3/7] docs: webContents.savePage is placed at wrong place --- docs/api/web-contents.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index be22d947c75..2b2efb7d47b 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -678,17 +678,6 @@ is in 32bit ARGB format). End subscribing for frame presentation events. -## Instance Properties - -`WebContents` objects also have the following properties: - -### `webContents.devToolsWebContents` - -Get the `WebContents` of DevTools for this `WebContents`. - -**Note:** Users should never store this object because it may become `null` -when the DevTools has been closed. - ### `webContents.savePage(fullPath, saveType, callback)` * `fullPath` String - The full file path. @@ -711,3 +700,14 @@ win.webContents.on('did-finish-load', function() { }); }); ``` + +## Instance Properties + +`WebContents` objects also have the following properties: + +### `webContents.devToolsWebContents` + +Get the `WebContents` of DevTools for this `WebContents`. + +**Note:** Users should never store this object because it may become `null` +when the DevTools has been closed. From 44c562ebd9ec14a421b85dd63967bae2f3166373 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 21:31:39 +0800 Subject: [PATCH 4/7] docs: New session methods --- docs/api/session.md | 79 +++++++++++++++++++++++++++++++++------------ 1 file changed, 58 insertions(+), 21 deletions(-) diff --git a/docs/api/session.md b/docs/api/session.md index 450be7b08e1..b921fc4839b 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -1,8 +1,10 @@ # session -The `session` object is a property of [`webContents`](web-contents.md) which is -a property of [`BrowserWindow`](browser-window.md). You can access it through an -instance of `BrowserWindow`. For example: +The `session` module can be used to create new `Session` objects. + +You can also access the `session` of existing pages by using the `session` +property of [`webContents`](web-contents.md) which is a property of +[`BrowserWindow`](browser-window.md). ```javascript const BrowserWindow = require('electron').BrowserWindow; @@ -10,12 +12,47 @@ const BrowserWindow = require('electron').BrowserWindow; var win = new BrowserWindow({ width: 800, height: 600 }); win.loadURL("http://github.com"); -var session = win.webContents.session +var ses = win.webContents.session ``` -## Events +## Methods -### Event: 'will-download' +The `session` module has the following methods: + +### session.fromPartition(partition) + +* `partition` String + +Returns a new `Session` instance from `partition` string. + +If `partition` starts with `persist:`, the page will use a persistent session +available to all pages in the app with the same `partition`. if there is no +`persist:` prefix, the page will use an in-memory session. If the `partition` is +empty then default session of the app will be returned. + +## Properties + +The `session` module has the following properties: + +### session.defaultSession + +Returns the default session object of the app. + +## Class: Session + +You can create a `Session` object in the `session` module: + +```javascript +const session = require('electron').session; + +var ses = session.fromPartition('persist:name'); +``` + +### Instance Events + +The following events are available on instances of `Session`: + +#### Event: 'will-download' * `event` Event * `item` [DownloadItem](download-item.md) @@ -34,11 +71,11 @@ session.on('will-download', function(event, item, webContents) { }); ``` -## Methods +### Instance Methods -The `session` object has the following methods: +The following methods are available on instances of `Session`: -### `session.cookies` +#### `ses.cookies` The `cookies` gives you ability to query and modify cookies. For example: @@ -74,7 +111,7 @@ win.webContents.on('did-finish-load', function() { }); ``` -### `session.cookies.get(details, callback)` +#### `ses.cookies.get(details, callback)` `details` Object, properties: @@ -102,7 +139,7 @@ win.webContents.on('did-finish-load', function() { the number of seconds since the UNIX epoch. Not provided for session cookies. -### `session.cookies.set(details, callback)` +#### `ses.cookies.set(details, callback)` `details` Object, properties: @@ -121,23 +158,23 @@ win.webContents.on('did-finish-load', function() { * `callback` Function - function(error) * `error` Error -### `session.cookies.remove(details, callback)` +#### `ses.cookies.remove(details, callback)` -* `details` Object, proprties: +* `details` Object * `url` String - The URL associated with the cookie * `name` String - The name of cookie to remove * `callback` Function - function(error) * `error` Error -### `session.clearCache(callback)` +#### `ses.clearCache(callback)` * `callback` Function - Called when operation is done Clears the session’s HTTP cache. -### `session.clearStorageData([options, ]callback)` +#### `ses.clearStorageData([options, ]callback)` -* `options` Object (optional), proprties: +* `options` Object (optional) * `origin` String - Should follow `window.location.origin`’s representation `scheme://host:port`. * `storages` Array - The types of storages to clear, can contain: @@ -149,7 +186,7 @@ Clears the session’s HTTP cache. Clears the data of web storages. -### `session.setProxy(config, callback)` +#### `ses.setProxy(config, callback)` * `config` String * `callback` Function - Called when operation is done. @@ -187,14 +224,14 @@ proxy-uri = ["://"][":"] URLs. ``` -### `session.setDownloadPath(path)` +#### `ses.setDownloadPath(path)` * `path` String - The download location Sets download saving directory. By default, the download directory will be the `Downloads` under the respective app folder. -### `session.enableNetworkEmulation(options)` +#### `ses.enableNetworkEmulation(options)` * `options` Object * `offline` Boolean - Whether to emulate network outage. @@ -216,12 +253,12 @@ window.webContents.session.enableNetworkEmulation({ window.webContents.session.enableNetworkEmulation({offline: true}); ``` -### `session.disableNetworkEmulation` +#### `ses.disableNetworkEmulation()` Disables any network emulation already active for the `session`. Resets to the original network configuration. -### `session.setCertificateVerifyProc(proc)` +#### `ses.setCertificateVerifyProc(proc)` * `proc` Function From 08c13cf446d509c79770e8ad635f7d4b339092bb Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 21:32:46 +0800 Subject: [PATCH 5/7] Deprecate app.resolveProxy There is now a public API to get default session, this helper is no longer necessary. --- atom/browser/api/lib/app.coffee | 6 ++---- docs/api/app.md | 8 -------- docs/api/session.md | 8 ++++++++ 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/atom/browser/api/lib/app.coffee b/atom/browser/api/lib/app.coffee index c2116fb7bca..a2fdb847e1c 100644 --- a/atom/browser/api/lib/app.coffee +++ b/atom/browser/api/lib/app.coffee @@ -34,10 +34,6 @@ app.setAppPath = (path) -> app.getAppPath = -> appPath -# Helpers. -app.resolveProxy = (url, callback) -> - session.defaultSession.resolveProxy url, callback - # Routes the events to webContents. for name in ['login', 'certificate-error', 'select-client-certificate'] do (name) -> @@ -51,6 +47,8 @@ app.getDataPath = deprecate 'app.getDataPath', 'app.getPath', -> @getPath 'userData' app.setDataPath = deprecate 'app.setDataPath', 'app.setPath', (path) -> @setPath 'userData', path +app.resolveProxy = deprecate 'app.resolveProxy', 'session.defaultSession.resolveProxy', (url, callback) -> + session.defaultSession.resolveProxy url, callback deprecate.rename app, 'terminate', 'quit' deprecate.event app, 'finish-launching', 'ready', -> setImmediate => # give default app a chance to setup default menu. diff --git a/docs/api/app.md b/docs/api/app.md index d7850c4cb92..a1d87d2fe99 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -311,14 +311,6 @@ preferred over `name` by Electron. Returns the current application locale. -### `app.resolveProxy(url, callback)` - -* `url` URL -* `callback` Function - -Resolves the proxy information for `url`. The `callback` will be called with -`callback(proxy)` when the request is performed. - ### `app.addRecentDocument(path)` _OS X_ _Windows_ * `path` String diff --git a/docs/api/session.md b/docs/api/session.md index b921fc4839b..a69c5939ed6 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -224,6 +224,14 @@ proxy-uri = ["://"][":"] URLs. ``` +### `ses.resolveProxy(url, callback)` + +* `url` URL +* `callback` Function + +Resolves the proxy information for `url`. The `callback` will be called with +`callback(proxy)` when the request is performed. + #### `ses.setDownloadPath(path)` * `path` String - The download location From 611f87d17f3fa80529e667199de112954c8d9982 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 21:42:22 +0800 Subject: [PATCH 6/7] spec: Use session.defaultSession in tests --- spec/api-session-spec.coffee | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/api-session-spec.coffee b/spec/api-session-spec.coffee index bf91bdd6fc7..6d0a8ac167c 100644 --- a/spec/api-session-spec.coffee +++ b/spec/api-session-spec.coffee @@ -4,7 +4,7 @@ path = require 'path' fs = require 'fs' {ipcRenderer, remote} = require 'electron' -{app, ipcMain, BrowserWindow} = remote.require 'electron' +{app, ipcMain, session, BrowserWindow} = remote describe 'session module', -> @timeout 10000 @@ -35,9 +35,9 @@ describe 'session module', -> done('Can not find cookie') it 'should over-write the existent cookie', (done) -> - app.defaultSession.cookies.set {url: url, name: '1', value: '1'}, (error) -> + session.defaultSession.cookies.set {url: url, name: '1', value: '1'}, (error) -> return done(error) if error - app.defaultSession.cookies.get {url: url}, (error, list) -> + session.defaultSession.cookies.get {url: url}, (error, list) -> return done(error) if error for cookie in list when cookie.name is '1' if cookie.value is '1' @@ -47,11 +47,11 @@ describe 'session module', -> done('Can not find cookie') it 'should remove cookies', (done) -> - app.defaultSession.cookies.set {url: url, name: '2', value: '2'}, (error) -> + session.defaultSession.cookies.set {url: url, name: '2', value: '2'}, (error) -> return done(error) if error - app.defaultSession.cookies.remove {url: url, name: '2'}, (error) -> + session.defaultSession.cookies.remove {url: url, name: '2'}, (error) -> return done(error) if error - app.defaultSession.cookies.get {url: url}, (error, list) -> + session.defaultSession.cookies.get {url: url}, (error, list) -> return done(error) if error for cookie in list when cookie.name is '2' return done('Cookie not deleted') From 1b464c82e1e99dce6d95f0ac302d601c8e268b3d Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 19 Nov 2015 21:48:45 +0800 Subject: [PATCH 7/7] docs: Put webContents.session under Properties --- docs/api/web-contents.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 2b2efb7d47b..a716bdc593a 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -225,12 +225,6 @@ The usage is the same with [the `login` event of `app`](app.md#event-login). The `webContents` object has the following instance methods: -### `webContents.session` - -Returns the `session` object used by this webContents. - -See [session documentation](session.md) for this object's methods. - ### `webContents.loadURL(url[, options])` * `url` URL @@ -705,6 +699,10 @@ win.webContents.on('did-finish-load', function() { `WebContents` objects also have the following properties: +### `webContents.session` + +Returns the [session](session.md) object used by this webContents. + ### `webContents.devToolsWebContents` Get the `WebContents` of DevTools for this `WebContents`.