Document webview debug mode as a copy/paste workaround if needed

Author: simonrob

README.md

@@ -77,9 +77,10 @@ On macOS the setup and installation instructions above should automatically inst
 
 When first launching on Linux you may encounter errors similar to `Namespace […] not available`. This is caused by missing dependencies for [pystray](https://github.com/moses-palmer/pystray/) and [pywebview](https://github.com/r0x0r/pywebview/), which are used to display the menu bar icon and login windows. See the [pywebview dependencies](https://pywebview.flowrl.com/guide/installation.html#dependencies) page and [issue 1](https://github.com/simonrob/email-oauth2-proxy/issues/1#issuecomment-831746642) in this repository for a summary and suggestions about how to resolve this.
 
-A similar issue may occur on Windows with the [pythonnet](https://github.com/pythonnet/pythonnet) package, which is required for pywebview. If you are unable to resolve this by following the [pythonnet installation instructions](https://github.com/pythonnet/pythonnet/wiki/Installation), you may find that installing a [prebuilt wheel](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pythonnet) helps fix the issue. Note that pythonnet can take some time to be compatible with the latest major python release, so it can be worth using a slightly older version of python.
+A similar issue may occur on Windows with the [pythonnet](https://github.com/pythonnet/pythonnet) package, which is required by [pywebview](https://github.com/r0x0r/pywebview). If you are unable to resolve this by following the [pythonnet installation instructions](https://github.com/pythonnet/pythonnet/wiki/Installation), you may find that installing a [prebuilt wheel](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pythonnet) helps fix the issue. Note that the public releases of pythonnet can take some time to be compatible with the latest major python release, so it can be worth using a slightly older version of python, or a prerelease version of pythonnet. This should be handled by the proxy's `requirements.txt`, but see [issue 45](https://github.com/simonrob/email-oauth2-proxy/issues/45) for a workaround if needed.
 
 ### Known issues
+- With some combinations of operating systems, web engines and virtual environments, keyboard control or input to the proxy's popup authorisation window may not always work. On Windows this is normally limited to keyboard shortcuts (i.e., copy/paste), but in some virtual environments on macOS the entire keyboard may not work. As a workaround, the proxy will enable pywebview's debug mode when you run the proxy in debug mode, which should allow you to use the right-click context menu to copy/paste to enter text.
 - On more recent macOS versions (10.14 and later), you may find that you need to manually load the proxy's launch agent in order to trigger a file access permission prompt when first running as a service. You will know if intervention is necessary if the proxy exits (rather than restarts) the first time you click `Start at login` from its menu bar icon. To resolve this, exit the proxy and then run `launchctl load ~/Library/LaunchAgents/ac.robinson.email-oauth2-proxy.plist` from a terminal. A permission pop-up should appear requesting file access for python. Once this has been approved, the proxy's menu bar icon will appear as normal. In some cases — particularly when running the proxy in a virtual environment, or using the built-in macOS python, rather than the python.org version, or installations managed by, e.g., homebrew, pyenv, etc — the permission prompt does not appear. If this happens it is worth first trying to `unload` and then `load` the service via `launchctl`. If this still does not cause the prompt to appear, the only currently-known resolution is to run the proxy outside of a virtual environment and manually grant Full Disk Access to your python executable via the privacy settings in the macOS System Preferences. You may also need to edit the proxy's launch agent plist file, which is found at the location given in the command above, to set the path to your python executable – it must be the real path rather than a symlink (the `readlink` command can help here). Fortunately this is a one-time fix, and once the proxy loads successfully via this method you will not need to adjust its startup configuration again (except perhaps when upgrading to a newer major macOS version, in which case just repeat the procedure).
 - On Windows, [pywebview](https://github.com/r0x0r/pywebview/) versions prior to 3.5 had a [bug](https://github.com/r0x0r/pywebview/issues/720) which caused a crash when the proxy's authentication window was opened. To fix this, make sure you have version 3.5 or later of pywebview (which is automatic if you use the proxy's `requirements.txt`).
 

emailproxy.py

@@ -4,7 +4,7 @@
 __author__ = 'Simon Robinson'
 __copyright__ = 'Copyright (c) 2022 Simon Robinson'
 __license__ = 'Apache 2.0'
-__version__ = '2022-08-03'  # ISO 8601 (YYYY-MM-DD)
+__version__ = '2022-08-17'  # ISO 8601 (YYYY-MM-DD)
 
 import argparse
 import asyncore
@@ -1753,15 +1753,18 @@ def authorise_account(self, _, item):
                 if not self.web_view_started:
                     # pywebview on macOS needs start() to be called only once, so we use a dummy window to keep it open
                     # Windows is the opposite - the macOS technique freezes the tray icon; Linux is fine either way
+                    # (we also set pywebview debug mode to match our own mode because copy/paste via keyboard shortcuts
+                    # can be unreliable with 'mshtml'; and, python virtual environments sometimes break keyboard entry
+                    # entirely on macOS - debug mode works around this in both cases via the right-click context menu)
                     self.create_authorisation_window(request)
                     if sys.platform == 'darwin':
-                        webview.start(self.handle_authorisation_windows)
+                        webview.start(self.handle_authorisation_windows, debug=Log.get_level() == logging.DEBUG)
                         self.web_view_started = True  # note: not set for other platforms so we start() every time
                     else:
                         # on Windows, most pywebview engine options return None for get_current_url() on pages created
                         # using 'html=' even on redirection to an actual URL; 'mshtml', though archaic, does work
                         forced_gui = 'mshtml' if sys.platform == 'win32' and self.args.external_auth else None
-                        webview.start(gui=forced_gui)
+                        webview.start(gui=forced_gui, debug=Log.get_level() == logging.DEBUG)
                 else:
                     WEBVIEW_QUEUE.put(request)  # future requests need to use the same thread
                 return
@@ -1828,6 +1831,9 @@ def authorisation_window_loaded(self):
                     RESPONSE_QUEUE.put({'connection': request['connection'], 'response_url': url})
                     self.authorisation_requests.remove(request)
                     completed_request = request
+                else:
+                    Log.debug('Waiting for URL matching `redirect_uri`; following browser redirection to',
+                              '%s/[...]' % urllib.parse.urlparse(url).hostname)
 
             if completed_request is None:
                 continue  # no requests processed for this window - nothing to do yet