Feature/session

[jmercouris]

This expands cl-electron to support Session objects and DownloadItem objects.

[jmercouris]

@aadcg This design is not without compromise. I tried to create a listener within a listener dynamically to fulfill the example shown here:

const win = new BrowserWindow()
win.webContents.session.on('will-download', (event, item, webContents) => {
  // Set the save path, making Electron not to prompt a save dialog.
  item.setSavePath('/tmp/save.pdf')

  item.on('updated', (event, state) => {
    if (state === 'interrupted') {
      console.log('Download is interrupted but can be resumed')
    } else if (state === 'progressing') {
      if (item.isPaused()) {
        console.log('Download is paused')
      } else {
        console.log(`Received bytes: ${item.getReceivedBytes()}`)
      }
    }
  })
...

https://www.electronjs.org/docs/latest/api/download-item#class-downloaditem

This proved to be very complicated, and prone to strange deadlocks. Having nested electron:add-listener, was quite confusing, and involved another eval. As such, I compromised and created a specialization of add-listener for event :download-item-updated. This is a fictional event type. It does not exist within Electron. It is however where all of the magic happens.

Within this method, we'll establish listeners for will-download and then for the child item's updated and done signals. Then we'll listen to all three signals and do different things depending on each.

Additionally, we'll wrap the callback lambda to automatically update the session download-items slot, and keep the download-items up to date.

I hope that all makes sense! Please let me know if any of this is unclear! I am sure as we add more listeners we'll discover more compromises in our design, and things we must change. I resisted the urge to change many things already with this PR.

[jmercouris]

P.S. I suggest reading through this PR by going through the commits iteratively.

[aadcg]

I understand the implementation and I'd like to build upon it.

1. session should be a slot of web-contents, just like the latter is a slot of window or view. This allows re-using references from the JS process.
2. There seems to be no need to create a fictional event type. add-listener will specialize against will-download.
3. In the example, I'd like to show how to cancel the download once it has been started (by the user, from the REPL).

I'll finish this PR, thanks!

[jmercouris]

I understand the implementation and I'd like to build upon it.

1. `session` should be a slot of `web-contents`, just like the latter is a slot of `window` or `view`. This allows re-using references from the JS process.

Agreed!

2. There seems to be no need to create a fictional event type. `add-listener` will specialize against `will-download`.

I didn't want to shadow will-download because technically I am only interested in the download item updated event! However, you are right, we will probably not use will-download by itself ever, and thus it is OK to shadow it.

3. In the example, I'd like to show how to cancel the download once it has been started (by the user, from the REPL).

That is how it already works in the example!

I'll finish this PR, thanks!

thank you!

[aadcg]

I didn't want to shadow will-download because technically I am only interested in the download item updated event! However, you are right, we will probably not use will-download by itself ever, and thus it is OK to shadow it.

This is a good point. Let's keep keep download-item-updated then.