Idea notes

1 files changed, 172 insertions, 0 deletions

diff --git a/developer-weekend/aug-2019.mdwn b/developer-weekend/aug-2019.mdwn
index 3edef0a..9cc6b2b 100644
--- a/developer-weekend/aug-2019.mdwn
+++ b/developer-weekend/aug-2019.mdwn
@@ -118,6 +118,178 @@ Vince
 * Completed `scale`ectomy in `browser_window_mouse_click()`, `browser_window_mouse_track()`, `browser_window_get_features()` `browser_window_set_scale()`.  And updated all of the callers and all of the front ends.
   - Now the front ends don't need to care about scale.
 
+Thoughts on shadow contents -- We decided that this was overcomplex and CANCELLED THIS IDEA
+===========================================================================================
+
+In order to complete the work we started my migrating queryies all the way up
+from the `llcache` to the `browser_window`, we need to come up with a way for
+the `browser_window` to load and display a real content which will represent
+the query to present to the user.
+
+Terms
+-----
+
+* **real content**: A real content if available (e.g. the current page when then
+  navigating away).
+* **loading content**: The content which is currently loading into the window.
+* **real loading content**: The _loading content_ which may trigger a query.
+* **query**: The callback from the _real loading content_ which needs user
+  input to decide on the action for.
+* **stored query**: A stored callback and private word for answering the
+  last _query_ which came for the _real loading content_.
+* **shadow loading content**: A holding space for a _real loading content_
+  which should not give any events unless something else unblocks the query in
+  another window.
+* **special navigation**: An attempt to navigate in such a way as it would
+  answer a _stored query_
+
+Events
+------
+
+The events we have to respond to are:
+
+1. The query event coming into the `browser_window_callback`
+2. Any attempt to `browser_window_navigate`
+3. Any attempt to `browser_window_reload`
+4. Any event coming from a _shadow loading content_
+5. Destroying a `browser_window`
+6. Any call to `browser_window_stop`
+
+States
+------
+
+The states we might be in are:
+
+1. **Not loading**: The normal state of being where we're not loading and as
+   such nothing interesting is going on.
+2. **Normal loading**: The process of loading is happening, there is no
+   _shadow loading content_ and the _real loading content_ is making progress.
+3. **Shadow loading**: The process of loading is paused, and a shadow page is
+   being loaded.  This implies there's a _stored query_.
+4. **Shadow loaded**: This is like the _not loading_ state, but there is a
+   _shadow loading content_ and a _stored query_ which mark it as different.
+
+State transitions
+-----------------
+
+1. Moving out of _not loading_ happens as normal on any of the usual events
+2. When _normal loading_ all the usual events behave in the current manner,
+   except if we receive a _query_.  On receipt of a _query_ the _real loading
+   content_ is moved from the _loading content_ into the _shadow loading
+   content_, and a new request is created in the _loading content_ for the
+   query page with requisite parameters.  Finally the _query_ parameters are
+   stored into the _stored query_.  This moves us to _shadow loading_.
+3. When _shadow loading_ and any of the navigation events occur, we first abort
+   the _loading content_ and move the _shadow loading content_ (which is the
+   _real loading content_) back into the _loading content_.  Then we refuse the
+   _stored query_ which will abort the _real loading content_.  Then we process
+   the navigation as before.
+4. When loading completes when we're in _shadow loading_  then we proceed as
+   "normal" to replace the current content with the converted shadow document,
+   we fire the query at the frontend, and we enter _shadow loaded_.
+5. When in _shadow loaded_ and normal navigation occurs, we behave essentially
+   like we would in _shadow loading_ and such an event occurred.
+6. When in _shadow loaded_ and we receive a _special navigation_ instruction,
+   then we gather the information from the URL to answer the _stored query_,
+   then close the query page content, move the _shadow loading content_ back to
+   the _loading content_, and then clear the _stored query_.  This transitions
+   us back into _normal loading_.  Finally we send the answer to the query
+   which will kick off normal fetch procedures once more.
+7. When in _shadow loaded_ or _shadow loading_ we receive any events from the
+   _shadow loading content_ we should assume that a decision was made in
+   another window and so we abort any _loading content_, or close any displayed
+   content, drop the _stored query_, put the _shadow loading content_ back into
+   the _loading content_, and return to _normal loading_
+
+Replacement query proposal
+==========================
+
+In order to simplify matters we decided instead that we would unwind the
+paused/callback mechanism and instead have the fetch stop with an appropriate
+error code indicating the query, allow the browser window to deal with that
+and then to restart the fetch from the top level.
+
+To do so, the browser window will have to retain the post data etc.  This
+allows for us to also implement the when reloading a page which was posted,
+query the user for whether or not to re-post. (but this is 'some future time')
+
+Then when we receive a query form `CONTENT_MSG_ERROR` the browser window can
+issue a special internal fetch for the query page it needs, passing the
+requisite information.  On `CONTENT_COMPLETE` it can then call the gui, giving
+it a chance to chime in.
+
+If a reload happens while we're on a special page, we redo the original fetch,
+if we navigate to the special try-again, we redo the original fetch.  If we
+navigate to the special proceed, we perform the update as needed, and redo
+the original fetch.
+
+Step one
+--------
+
+First, we need to clean up and unify `CONTENT_MSG_ERROR` and
+`CONTENT_MSG_ERRORCODE`.
+
+This will allow us to later use this unified thing to communicate more useful
+fetch errors upward toward the browser window.
+
+Step two
+--------
+
+We make `browser_window_navigate` store the fetch parameters so that
+redoing the fetch is possible
+
+Step three
+----------
+
+We change the fetch/llcache/hlcache layers to always pass SSL certificate
+chains upward when they are available.
+
+And we change the `browser_window` to store that chain alongside both the
+`current_content` and the `loading_content`.
+
+We may add APIs to access these later.
+
+Step four
+---------
+
+We change the fetch/llcache/hlcache layers to remove the `QUERY` concept
+entirely and to pass an appropriately structed `CONTENT_MSG_ERROR`.
+
+We change the `browser_window` to consume that error and call the current
+callbacks.  The `proceed` callback will have to be implemented in
+`browser_window` in a simplistic fashion.
+
+At this point, all the plumbing is in place, but the current behaviour in terms
+of GUI interaction and urldb remains the same.
+
+Step five
+---------
+
+We write a handler in about: to provide the query pages.  This is MVP to be
+able to get on with things.  At this point we allow `browser_window` to have
+the concept of a special fetch which does not update the fetch paramters, nor
+the url bar etc.  And when we stop a fetch because of the query errors, we
+navigate to that about: handler using the special fetch mode, thus we'll end up
+with both the new page *and* the GUI prompt still.  Ideally we move the gui
+prompt to be on `CONTENT_DONE` for the special load.
+
+Step six
+--------
+
+We handle the special `about:` URI which means 'proceed' and the one which
+means 'try-again' as per the descriptions in the summary of this proposal.
+
+Step seven
+----------
+
+Rework the gui/browser_window querying so that instead of proceed/cancel
+it is try-again/take-answer/proceed.
+
+Step eight
+----------
+
+Various sundry cleanups as a result of all of the above.
+
 Statement of work
 =================