docs(aio): document preview server HTTP status codes

aio/aio-builds-setup/docs/_TOC.md

@@ -4,7 +4,8 @@
 ## Overview
 - [General overview](overview--general.md)
 - [Security model](overview--security-model.md)
-- [Available Commands](overview--scripts-and-commands.md)
+- [Available scripts and commands](overview--scripts-and-commands.md)
+- [HTTP status codes](overview--http-status-codes.md)
 
 
 ## Setting up the VM

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

@@ -74,6 +74,9 @@ More info on how to set things up on CI can be found [here](misc--integrate-with
 - If the PR is publicly accessible, the upload-server posts a comment on the corresponding PR on
   GitHub mentioning the SHA and the link where the preview can be found.
 
+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.
@@ -81,6 +84,9 @@ More info on how to set things up on CI can be found [here](misc--integrate-with
 - 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
+[here](overview--http-status-codes.md).
+
 
 ### Removing obsolete artifacts
 In order to avoid flooding the disk with unnecessary build artifacts, there is a cronjob that runs a

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

@@ -0,0 +1,66 @@
+# Overview - HTTP Status Codes
+
+
+This is a list of all the possible HTTP status codes returned by the nginx anf upload servers, along
+with a bried explanation of what they mean:
+
+
+## `http://*.ngbuilds.io/*`
+
+- **307 (Temporary Redirect)**:
+  All non-HTTPS requests. 308 (Permanent Redirect) would be more appropriate, but is not supported
+  by all agents (e.g. cURL).
+
+
+## `https://pr<pr>-<sha>.ngbuilds.io/*`
+
+- **200 (OK)**:
+  File was found or URL was rewritten to `/index.html` (i.e. all paths that have no `.` in final
+  segment).
+
+- **403 (Forbidden)**:
+  Trying to access a sub-directory.
+
+- **404 (Not Found)**:
+  File not found.
+
+
+## `https://ngbuilds.io/create-build/<pr>/<sha>`
+
+- **201 (Created)**:
+  Build deployed successfully and is publicly available.
+
+- **202 (Accepted)**:
+  Build not automatically verifiable. Stored for later deployment (after re-verification).
+
+- **400 (Bad Request)**:
+  No payload.
+
+- **401 (Unauthorized)**:
+  No `AUTHORIZATION` header.
+
+- **403 (Forbidden)**:
+  Unable to verify build (e.g. invalid JWT token, or unable to talk to 3rd-party APIs, etc).
+
+- **404 (Not Found)**:
+  Tried to change PR visibility but the source directory did not exist.
+  (Currently, this can only happen as a rare race condition during build deployment.)
+
+- **405 (Method Not Allowed)**:
+  Request method other than POST.
+
+- **409 (Conflict)**:
+  Request to overwrite existing directory (e.g. deploy existing build or change PR visibility when
+  the destination directory does already exist).
+
+- **413 (Payload Too Large)**:
+  Payload larger than size specified in `AIO_UPLOAD_MAX_SIZE`.
+
+
+## `https://*.ngbuilds.io/*`
+
+- **404 (Not Found)**:
+  Request not matched by the above rules.
+
+- **500 (Internal Server Error)**:
+  Error while processing a request matched by the above rules.

aio/aio-builds-setup/docs/overview--scripts-and-commands.md

@@ -12,21 +12,22 @@ available:
   Can be used for creating a preconfigured docker image.
   See [here](vm-setup--create-docker-image.md) for more info.
 
-- `test.sh`
+- `test.sh`:
   Can be used for running the tests for `<aio-builds-setup-dir>/dockerbuild/scripts-js/`. This is
   useful for CI integration. See [here](misc--integrate-with-ci.md) for more info.
 
-- `travis-preverify-pr.sh`
+- `travis-preverify-pr.sh`:
   Can be used for "pre-verifying" a PR before uploading the artifacts to the server. It checks
   whether the author of the PR is a member of one of the specified GitHub teams (therefore allowed
   to upload build artifacts) or the PR has the specified "trusted PR" label (meaning it has been
   manually verified by a trusted member). This is useful for CI integration.
   See [here](misc--integrate-with-ci.md) for more info.
 
-- `update-preview-server.sh`
+- `update-preview-server.sh`:
   Can be used for updating the docker container (and image) based on the latest changes checked out
   from a git repository. See [here](vm-setup--update-docker-container.md) for more info.
 
+
 ## Commands
 The following commands are available globally from inside the docker container. They are either used
 by the container to perform its various operations or can be used ad-hoc, mainly for testing