Document stale-while-revalidate

docs/dependencies/aliases.md

@@ -14,8 +14,7 @@ When we left [our `lodash` example](/docs/dependencies/npm) we had
 version `4.17.21` published to the URL
 `https://eik.store.com/npm/lodash/4.17.21/index.js`.
 
-The `alias` command in the [Eik CLI](/docs/reference/at-eik-cli)
-creates a URL that redirects to a specific version of a library.
+The [Eik CLI](/docs/reference/at-eik-cli) has an `alias` command that works like so:
 
 ```sh
 eik login --key YOUR_EIK_KEY --server https://eik.store.com
@@ -30,7 +29,15 @@ Let's break down the alias command a bit.
 
 The `--server` argument lets you run the `login` and `alias` commands without having `eik.json` in the current directory.
 
-Now you should be able to go to `https://eik.store.com/npm/lodash/v4/index.js`, and your browser should be redirected to the version you aliased.
+Now you can go to `https://eik.store.com/npm/lodash/v4/index.js` in a browser, and you should be redirected to the version you aliased.
+
+:::tip
+
+On servers running `@eik/service` 5.1.0 or newer you can also go to `https://eik.store.com/npm/lodash/~4/index.js` (~4 instead of v4) to get the file directly with [stale-while-revalidate cache headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate), saving the browser from following a redirect.
+
+This is particularly useful for assets on the critical path, like global CSS and font files.
+
+:::
 
 ## Updating an alias
 

docs/server/http-api.md

@@ -418,12 +418,13 @@ An alias is a shorthand between a major version of a package / import map and th
 
 ### Endpoint Summary Table
 
-| Name                                  | Verb   | Endpoint                       | Form Fields |
-| ------------------------------------- | ------ | ------------------------------ | ----------- |
-| [Public Alias URL](#public-alias-url) | GET    | `/:type/:name/v:alias/:extras` |             |
-| [Create Alias](#create-alias)         | PUT    | `/:type/:name/v:alias`         | `version`   |
-| [Update Alias](#update-alias)         | POST   | `/:type/:name/v:alias`         | `version`   |
-| [Delete Alias](#delete-alias)         | DELETE | `/:type/:name/v:alias`         |             |
+| Name                                                                                | Verb   | Endpoint                       | Form Fields |
+| ----------------------------------------------------------------------------------- | ------ | ------------------------------ | ----------- |
+| [Public Alias URL](#public-alias-url)                                               | GET    | `/:type/:name/v:alias/:extras` |             |
+| [Public stale-while-revalidate alias URL](#public-stale-while-revalidate-alias-url) | GET    | `/:type/:name/~:alias/:extras` |             |
+| [Create Alias](#create-alias)                                                       | PUT    | `/:type/:name/v:alias`         | `version`   |
+| [Update Alias](#update-alias)                                                       | POST   | `/:type/:name/v:alias`         | `version`   |
+| [Delete Alias](#delete-alias)                                                       | DELETE | `/:type/:name/v:alias`         |             |
 
 ### Public Alias URL
 
@@ -454,6 +455,37 @@ curl -X GET -L http://localhost:4001/pkg/fuzz/v8/main/index.js
 curl -X GET -L http://localhost:4001/map/buzz/v4
 ```
 
+### Public stale-while-revalidate Alias URL
+
+**Method:** `GET`
+
+Available since [`@eik/service@5.1.0`](https://github.com/eik-lib/service/releases/tag/v5.1.0).
+
+Retrieves files from a package and serves them without a redirect, using [`stale-while-revalidate`](http://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate).
+
+```bash
+https://:assetServerUrl:port/:type/:name/~:alias/:extras
+```
+
+URL parameters:
+
+- `:type` is the type to retrieve from. Validator: `pkg`, `npm` or `img`.
+- `:name` is the name of the package. Validator: Comply with [npm package names](https://github.com/npm/validate-npm-package-name).
+- `:alias` is the major version of the package, prefixed by tilde (`~`).
+- `:extras` whildcard pathname to any file in a package.
+
+Status codes:
+
+- `200` if aliased file exist
+- `302` if alias exists and `:extras` was not specified (same behavior as [Public Alias URL](#public-alias-url))
+- `404` if alias is not found
+
+Example:
+
+```bash
+curl -X GET -L http://localhost:4001/pkg/fuzz/~8/main/index.js
+```
+
 ### Create Alias
 
 **Method:** `PUT`