QUICKSTART: multiple alternative endpoints

docs/QUICKSTART.md

@@ -176,7 +176,7 @@ Next time that same visitor loads that particular resource, it will be served fr
 
 For the time being, let's keep using the `fetch`-then-`cache` option, though.
 
-## 3. Alternative transport
+## 3. An alternative transport
 
 We have a working Service Worker, we have it configured to retrieve content using the standard HTTPS fetch, and we made sure that successful requests are stashed for later use (using the `cache` stashing plugin). This makes it possible for our visitors to access content they have already accessed, even if our website is unavailable for whatever reason.
 
@@ -247,7 +247,50 @@ From the perspective of the visitor, the site will work normally, some content w
  
 > #### Note on content versions
 > 
-> LibResilient does not have a reliable way of comparing versions of content available through different transport plugins. If the content available through configured alternative transports is *older* than the content available directly on the original website, that *older* content will be provided to the visitor if the original website happens to be down.
+> LibResilient does not have a reliable way of comparing versions of content available through different transport plugins. When the original website happens to be down or unavailable, the content from alternative transports will be provided to the user even if it is *older* than what was available on the website.
 > 
 > From the visitors' perspecive stale content might still be better than no content. It is up to the website admins to ensure that the configured alternative transports do not serve stale content.
 
+## 4. Multiple different alternative endpoints
+
+Having one alternative endpoint is good. But having multiple is better! The `alt-fetch` plugin can be onfigured to use multiple endpoints simultaneously.
+
+Let's say we have:
+ - a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) node (like [Fasada](https://0xacab.org/rysiek/fasada/)), using our main site as the back-end, running an additional VPS under:\
+   `https://somevps1.hostingprovider.example`;
+ - an endpoint on a big service like [CloudFront](https://en.wikipedia.org/wiki/Amazon_CloudFront), where we can host static content of our site, available under:\
+   `https://d11ipsexample.cloudfront.net`.
+
+We can add these endpoints to our `config.json`:
+
+```json
+{
+    "plugins": [{
+        "name": "fetch"
+    },{
+        "name": "cache"
+    },{
+        "name": "alt-fetch",
+        "endpoints": [
+            "https://example.gitlab.io/",
+            "https://somevps1.hostingprovider.example/",
+            "https://d11ipsexample.cloudfront.net"
+        ],
+        concurrency: 2
+    }],
+    "loggedComponents": ["service-worker", "fetch", "cache"],
+    "defaultPluginTimeout": 1000
+}
+```
+
+Of course this requires us to push our static website content also to our CloudFront account when publishing, and to manage the reverse proxy node. This up to the website administrator and is out of scope for this document.
+
+In the `alt-fetch` plugin config, note the VPS and CloudFront addresses in the `endpoints` key; also there, note the `concurrency` key. This key defines how many requests *simultaneously* are made to the configured endpoints. In our case, the value `concurrency: 2` means that out of the three endpoints configured for `alt-fetch`, each time LibResilient uses this plugin to try and retrieve content, *two* random endpoints will be used simultaneously. The response to the first request that returns successfully is then used (and other responses are discarded).
+
+This allows us to have some additional resilience in case any of the endpoints fail. The downside is additional use of resources on the user side. Making two simultaneous connections is almost certainly fine, making ten would probably be ill-advised.
+
+At this point, for anyone who has visited our site once in a given browser, if our main website `example.org` is unavailable for whatever reason, each request will be made to two of the three alternative endpoints, and response stashed locally for offline use.
+
+Even if one of the alternative endpoints starts experiencing issues, such visitors will still be able to use the site and access new content, none the wiser that the website is experiencing an outage.
+
+On the other hand, anyone who would want to maliciously take our website down, would need to inspect our `config.json`, make a list of alternative endpoints configured there, and make sure they are also taken down — which might be difficult in case of large providers like CloudFront or GitLab.