component/headless-chromium: update some comments

component/headless-chromium/buildout.cfg

@@ -18,14 +18,16 @@ extends =
 parts =
   chromium-wrapper
 
-# TODO: it may be more appropriate to manage our own copy of depot_tools, because I think some of the "gclient sync" commands may modify depot_tools, which could be problematic if other components or software releases depend on a shared copy, and at any rate it causes some build errors: when updating depot_tools, git complains because HEAD has been moved. Is there a way to guarantee a private copy? (This may be a moot point, since I don't think it's used by anything else, anyway, and trying again fixes the git issue.)
+# Note that we'll need to proxy the websocket connection to the headless
+# Chromium shell, for several reasons. The web server that Chromium
+# spins up refuses HTTP requests unless the Host header is localhost or
+# an IP address [0], but we need SSL (i.e. wss://) because the frontend
+# page is loaded over HTTPS, and the mixed-content policy prevents us
+# from loading an ordinary ws:// connection.
+# [0] Security issue; see
+# https://bugs.chromium.org/p/chromium/issues/detail?id=813540
 
-# TODO: so there's a funny little issue: because we didn't clone the full repository history, some automated tools can't figure out the version number (well, actually the appropriate commit hash). This causes the frontend for the remote debugging port to crash, because it was expecting a version number. I see a few possible fixes:
-# 1. Clone the full repository. But this blows up the size, from ~25 GB to ~100 GB.
-# 2. Patch the C++ version API (see src/components/version_info) before compiling, to hard-code the number in.
-# 3. Patch the frontend JS (not sure where it is) before compiling.
-# 4. Proxy the connection and patch the server's response on the fly.
-# The correct commit hash for this particular version should be 3aad95ffffff0767e9b7d161885aa811de1f2195, which you can verify at https://github.com/chromium/chromium/commit/3aad95ffffff0767e9b7d161885aa811de1f2195 and find by searching on https://chromium-review.googlesource.com/c/chromium/src/.
+# TODO: it may be more appropriate to manage our own copy of depot_tools, because I think some of the "gclient sync" commands may modify depot_tools, which could be problematic if other components or software releases depend on a shared copy, and at any rate it causes some build errors: when updating depot_tools, git complains because HEAD has been moved. Is there a way to guarantee a private copy? (This may be a moot point, since I don't think it's used by anything else, anyway, and trying again fixes the git issue.)
 
 # There's nothing special about version 91.0.4472.132. It just happened to be
 # the current Chromium stable version at the time of writing.
@@ -81,6 +83,9 @@ configure-command =
 
 # You can run the headless Chromium shell using
 # ${:location}/headless-chromium --remote-debugging-port=1234
+# Note that your client browser must be Chromium-based, since Firefox
+# and Safari do not support constructible stylesheets yet (see e.g.
+# https://bugzilla.mozilla.org/show_bug.cgi?id=1520690).
 make-binary =
 # This is most certainly a massive hack, but retrying possibly works...
   autoninja -C ${:location} headless_shell || autoninja -C ${:location} headless_shell