feat(aio): add API endpoint for notifying about PR updates

This commit adds an API endpoint for notifying the preview server about PR
updates (`/pr-updated`). According to the update, the preview server can take
several actions. Currently, it will only check and (if necessary) update the
PR's preview visibility (but more actions could be supported in the future).
The API can be used with an automatic trigger (e.g. a GitHub webhook) to
instantly update a PR's preview visibility when it changes.

Fixes #16526

aio/aio-builds-setup/docs/overview--general.md

@@ -80,13 +80,31 @@ More info on the possible HTTP status codes and their meaning can be found
 [here](overview--http-status-codes.md).
 
 
+### Updating PR visibility
+- nginx receives a natification that a PR has been updated and passes it through to the
+  upload-server. This could, for example, be sent by a GitHub webhook every time a PR's labels
+  change.
+  E.g.: `ngbuilds.io/pr-updated` (payload: `{"number":<PR>,"action":"labeled"}`)
+- The request contains the PR number (as `number`) and optionally the action that triggered the
+  request (as `action`) in the payload.
+- The upload-server verifies the payload and determines whether the `action` (if specified) could
+  have led to PR visibility changes. Only requests that omit the `action` field altogether or
+  specify an action that can affect visibility are further processed.
+  (Currently, the only actions that are considered capable of affecting visibility are `labeled` and
+  `unlabeled`.)
+- The upload-server re-checks and if necessary updates the PR's visibility.
+
+More info on the possible HTTP status codes and their meaning can be found
+[here](overview--http-status-codes.md).
+
+
 ### Serving build artifacts
 - nginx receives a request for an uploaded resource on a subdomain corresponding to the PR and SHA.
   E.g.: `pr<PR>-<SHA>.ngbuilds.io/path/to/resource`
 - nginx maps the subdomain to the correct sub-directory and serves the resource.
   E.g.: `/<PR>/<SHA>/path/to/resource`
 
-Again, more info on the possible HTTP status codes and their meaning can be found
+More info on the possible HTTP status codes and their meaning can be found
 [here](overview--http-status-codes.md).
 
 

aio/aio-builds-setup/docs/overview--http-status-codes.md

@@ -53,6 +53,28 @@ with a bried explanation of what they mean:
   Payload larger than size specified in `AIO_UPLOAD_MAX_SIZE`.
 
 
+## `https://ngbuilds.io/health-check`
+
+- **200 (OK)**:
+  The server is healthy (i.e. up and running and processing requests).
+
+
+## `https://ngbuilds.io/pr-updated`
+
+- **200 (OK)**:
+  Request processed successfully. Processing may or may not have resulted in further actions.
+
+- **400 (Bad Request)**:
+  No payload or no `number` field in payload.
+
+- **405 (Method Not Allowed)**:
+  Request method other than POST.
+
+- **409 (Conflict)**:
+  Request to overwrite existing directory (i.e. directories for both visibilities exist).
+  (Normally, this should not happen.)
+
+
 ## `https://*.ngbuilds.io/*`
 
 - **404 (Not Found)**: