Merge pull request #8068 from magento/hg-gh8021-weballow

Cloud: update key value list for web locations

Author: hguthrie

src/cloud/project/magento-app-properties.md

@@ -73,20 +73,26 @@ See [Services]({{ site.baseurl }}/cloud/project/services.html) for a full list o
 
 ### `web`
 
-The `web` property defines how your application is exposed to the web (in HTTP). It determines how the web application serves content— from the front-controller script to a non-static request to an `index.php` file on the root. We support any directory structure so the static file can be in a sub directory, and the `index.php` file can be further down.
+The `web` property defines how your application is exposed to the web (in HTTP), determines how the web application serves content, and controls how the application container responds to incoming requests by setting rules in each location _block_. A block represents an absolute path leading with a forward slash (`/`).
 
-You can specify the following attributes for the `web` property:
+```yaml
+web:
+    locations:
+        "/":
+            # The public directory of the app, relative to its root.
+```
+
+You can fine-tune your `locations` configuration using the following key values for each `locations` block:
 
 Attribute | Description
 --------- | -----------
-`root` | The path relative to the root of the application that is exposed on the web. Typical values include `/public` and `/web`.
-`passthru` | The URL used in the event that a static file or PHP file cannot be found. This URL is typically the front controller for your applications, often `/index.php` or `/app.php`.
-`index` | Static files, such as `index.html`, to serve your application. This key expects a collection. You must include the static file(s) in the whitelist as an index file, like `- \.html$`.
-`blacklist` | A list of files that should never be executed. Has no effect on static files.
-`whitelist` | A list of static files (as regular expressions) that can be served. Dynamic files (for example, PHP files) are treated as static files and have their source code served, but they are not executed.
-`expires` | The number of seconds to cache whitelisted content in the browser. This attribute enables the cache-control and expires headers for static content. If this value is not set, the `expires` directive and resulting headers are not included when serving static content files.
-
-Contrary to standard `.htaccess` approaches that accept a _blacklist_ and allow access to everything not on a specific list, we accept a _whitelist_, which means that any request that does not match triggers a 404 error and passes through to the  URL specified by the `passthru` attribute.
+`allow` | Serve files that do not match "rules". Default value = `true`
+`expires` | Set the number of seconds to cache content in the browser. This key enables the `cache-control` and `expires` headers for static content. If this value is not set, the `expires` directive and resulting headers are not included when serving static content files. A negative 1 (`-1`) value results in no caching and is the default value. You can express time value with the following units:  `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months, 30d), or `y` (years, 365d)
+`index` | List the static files to serve your application, such as the `index.html` file. This key expects a collection. This only works if access to the file or files is "allowed" by the `allow` or `rules` key for this location.
+`rules` | Specify overrides for a location. Use a regular expression to match a request. If an incoming request matches the rule, then regular handling of the request is overridden by the keys used in the rule.
+`passthru` | Set the URL used in the event that a static file or PHP file cannot be found. Typically, this URL is the front controller for your applications, such as `/index.php` or `/app.php`.
+`root` | Set the path relative to the root of the application that is exposed on the web. The public directory (location "/") for a Cloud project is set to "pub" by default.
+`scripts` | Allow loading scripts in this location. Set the value to `true` to allow scripts.
 
 Our default configuration allows the following: