Add support for query variables in preheat kernel mode

[trungleduc]

References

To benefit from the acceleration of preheating kernel mode, the notebooks need to be pre-rendered before users actually connect to Voilà. But in many real-world cases, the notebook requires some user-specific data to render correctly the widgets, which makes pre-rendering become impossible. To overcome this limit, Voilà offers a feature to treat the most used method for providing user data: the URL query string.

In normal mode, Voilà users can get the query string at run time through the QUERY_STRING environment variable:

   import os
   query_string = os.getenv('QUERY_STRING') 

In preheating kernel mode, users can just replace the os.getenv call with the helper get_query_string from voila.utils

   from voila.utils import get_query_string
   query_string = get_query_string()

get_query_string will pause the execution of notebook in the preheated kernel at its cell and wait for an actual user to connect to Voilà, then get_query_string will return the URL query string and continue the execution of remaining cells.

If Voilà WebSocket handler is not started at the default protocol (ws), the default IP address (127.0.0.1) or the default port (8866), users need to provide these values through the environment variables VOILA_APP_PROTOCOL, VOILA_APP_IP and VOILA_APP_PORT. The easiest way is to set these variables in voila.json configuration file, for example:

   # voila.json
   {
      ...
      "VoilaKernelManager": {
         "kernel_pools_config": { 
            "foo.ipynb": {
               "kernel_env_variables": { 
                  "VOILA_APP_IP": "192.168.1.1",
                  "VOILA_APP_PORT": "6789",
                  "VOILA_APP_PROTOCOL": "wss"
               }
            }
         },
      ...
      }
   } 

voila-qs.mp4

TODO

• Create a handler to provide the query string associated with each kernel id.
• Create a helper to pause the execution and wait for the query string in a notebook.
• Add documentation

Code changes

• A new WebSocket handler QueryStringSocketHandler is added at endpoint /voila/query/{kernel-id}
• A new functionget_query_string in voila.utils.
• New dependency websockets

User-facing changes

• Users now can use query string with preheating kernel mode.

Backwards-incompatible changes

N/A

[github-actions]

👈 Try it on binder (branch trungleduc/voila/ft/support-query-variable)

[github-actions]

Benchmark report

The execution time (in milliseconds) are grouped by test file, test type and browser.
For each case, the following values are computed: min <- [1st quartile - median - 3rd quartile] -> max.

Results table

Test file	basics.ipynb	bqplot.ipynb	dashboard.ipynb	gridspecLayout.ipynb	interactive.ipynb	ipympl.ipynb	ipyvolume.ipynb	multiple_widgets.ipynb	query-strings.ipynb
Render
chromium
actual	3175 <- [3352 - 3639 - 4371] -> 4781	2488 <- [2496 - 2529 - 2557] -> 2581	2696 <- [2709 - 2764 - 2800] -> 2820	3056 <- [3172 - 3181 - 3189] -> 3292	1807 <- [1880 - 1890 - 1908] -> 1933	3876 <- [3955 - 4043 - 4460] -> 6229	9117 <- [11303 - 12885 - 14473] -> 14768	9620 <- [9699 - 9737 - 9775] -> 9782	1269 <- [1277 - 1292 - 1293] -> 1312
expected	3379 <- [3442 - 3517 - 3701] -> 3876	2976 <- [3227 - 3321 - 3421] -> 3604	3608 <- [3623 - 3709 - 3793] -> 3825	4453 <- [4453 - 4523 - 4661] -> 4748	2559 <- [2655 - 2656 - 2660] -> 2674	3982 <- [4079 - 4213 - 4356] -> 4743	12183 <- [18509 - 19553 - 20811] -> 21515	15319 <- [15660 - 15796 - 15912] -> 16056	1517 <- [1920 - 1997 - 2103] -> 2113

❗ Test metadata have changed

--- /dev/fd/63	2021-10-14 08:19:25.253523727 +0000
+++ /dev/fd/62	2021-10-14 08:19:25.253523727 +0000
@@ -8,27 +8,27 @@
   },
   "systemInformation": {
     "cpu": {
-      "brand": "Xeon® Platinum 8272CL",
+      "brand": "Xeon® E5-2673 v3",
       "cache": {
         "l1d": 65536,
         "l1i": 65536,
-        "l2": 2097152,
-        "l3": 36700160
+        "l2": 524288,
+        "l3": 31457280
       },
       "cores": 2,
       "family": "6",
-      "flags": "fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl xtopology cpuid pni pclmulqdq ssse3 fma cx16 pcid sse4_1 sse4_2 movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch invpcid_single pti fsgsbase bmi1 hle avx2 smep bmi2 erms invpcid rtm mpx avx512f avx512dq rdseed adx smap clflushopt avx512cd avx512bw avx512vl xsaveopt xsavec xsaves md_clear",
+      "flags": "fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl xtopology cpuid pni pclmulqdq ssse3 fma cx16 pcid sse4_1 sse4_2 movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm invpcid_single pti fsgsbase bmi1 avx2 smep bmi2 erms invpcid xsaveopt md_clear",
       "governor": "",
       "manufacturer": "Intel®",
-      "model": "85",
+      "model": "63",
       "physicalCores": 2,
       "processors": 1,
       "revision": "",
       "socket": "",
-      "speed": 2.6,
+      "speed": 2.4,
       "speedMax": null,
       "speedMin": null,
-      "stepping": "7",
+      "stepping": "2",
       "vendor": "GenuineIntel",
       "virtualization": false,
       "voltage": ""
@@ -42,11 +42,11 @@
       "codename": "Focal Fossa",
       "codepage": "UTF-8",
       "distro": "Ubuntu",
-      "kernel": "5.8.0-1042-azure",
+      "kernel": "5.8.0-1040-azure",
       "logofile": "ubuntu",
       "platform": "linux",
       "release": "20.04.3 LTS",
-      "serial": "f87a2cd4ed534fea8f3ccb44ed7db74e",
+      "serial": "cfc067bfcb844f35865e279a1b0e66c5",
       "servicepack": "",
       "uefi": false
     }

[trungleduc]

This PR is ready for review, failed tests are reported in #961