From 66088fef1a57f119917f3478c8dd712769567134 Mon Sep 17 00:00:00 2001 From: Georgios Kalpakas Date: Mon, 19 Jun 2017 14:52:58 +0300 Subject: [PATCH] docs(aio): document preview server HTTP status codes --- aio/aio-builds-setup/docs/_TOC.md | 3 +- .../docs/overview--general.md | 6 ++ .../docs/overview--http-status-codes.md | 66 +++++++++++++++++++ .../docs/overview--scripts-and-commands.md | 7 +- 4 files changed, 78 insertions(+), 4 deletions(-) create mode 100644 aio/aio-builds-setup/docs/overview--http-status-codes.md diff --git a/aio/aio-builds-setup/docs/_TOC.md b/aio/aio-builds-setup/docs/_TOC.md index 97ec20a2b9..ebf1a4e84c 100644 --- a/aio/aio-builds-setup/docs/_TOC.md +++ b/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 diff --git a/aio/aio-builds-setup/docs/overview--general.md b/aio/aio-builds-setup/docs/overview--general.md index cca024ee11..9ec2c1be41 100644 --- a/aio/aio-builds-setup/docs/overview--general.md +++ b/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.: `///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 diff --git a/aio/aio-builds-setup/docs/overview--http-status-codes.md b/aio/aio-builds-setup/docs/overview--http-status-codes.md new file mode 100644 index 0000000000..dff11ae01f --- /dev/null +++ b/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-.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//` + +- **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. diff --git a/aio/aio-builds-setup/docs/overview--scripts-and-commands.md b/aio/aio-builds-setup/docs/overview--scripts-and-commands.md index 5a219ee459..72d8062d81 100644 --- a/aio/aio-builds-setup/docs/overview--scripts-and-commands.md +++ b/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 `/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