API: introduce ability to watch a VM (#351)

* API: introduce ability to watch a VM

* Document ?watch=true for GET /vms/{name} in the OpenAPI specification

* WatchVM: ensure that goroutine is terminated on early return with error

* WatchVM: close channels on goroutine exit

* WatchVM: ensure that we wait for the goroutine after additional barriers

* WatchVM: ignore unexpected keys instead of throwing an error

* WatchVM: perform context-aware writes to a bounded channel

* WatchVM: don't forget to close errCh on goroutine exit too

* WatchVM: don't close readyCh in goroutine to avoid ambiguity

* WatchVM: filter out spurious KVs that signify VM deletion

api/openapi.yaml

@@ -256,9 +256,15 @@ paths:
     parameters:
       - in: path
         name: name
+        description: VM name to retrieve
         required: true
         schema:
           type: string
+      - in: query
+        name: watch
+        description: Watch for changes a VM resource and return them a stream of ADDED, MODIFIED and DELETED notifications
+        schema:
+          type: boolean
     get:
       summary: "Retrieve a VM"
       tags:
@@ -270,6 +276,15 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VM'
+            application/x-ndjson:
+              schema:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    enum: [ADDED, MODIFIED, DELETED]
+                  object:
+                    $ref: '#/components/schemas/VM'
         '404':
           description: VM resource with the given name doesn't exist
     put: