created FAQ; ref. #42

docs/FAQ.md

@@ -0,0 +1,67 @@
+# Frequently Asked Questions
+
+## General questions
+
+### Can LibResilient handle dynamic content?
+
+Yes, but that depends on what alternative transports are used and how. For example, if the particular website uses the [`alt-fetch` plugin](../plugins/alt-fetch/), and all the alternative endpoints configured for it are just reverse proxies that hit the original back-end server, dynamic content would be served perfectly fine.
+
+That approach has the downside, however, that if the original backend is completely down (for example, due to hardware failure), LibResilient would not be able to fetch the content. For this reason it is recommended to either use static sites (that is, websites whose content is served as static files, often generated with the help of generated using a static site generator) or at least build the website in a way such that it lends itself to caching or serving out as static files.
+
+### Can LibResilient handle posting comments or other forms of user-initiated interactivity?
+
+LibResilient focuses on making sure that content stays online. For this it needs to make certain assumptions. One of those assumtpions is that the content is not interactive in a way that it requires live contact with the back-end of a LibResilient-enabled website.
+
+Assuming a pretty standard set-up, where the [`fetch` plugin](../plugins/fetch/) is configured as the first plugin in the config file, website functionality will not differ from how it would have worked without LibResilient deployed — as long as the original domain remains accessible. When it goes down, and other plugins kick-in, interactivity that requires the back-end to be available will not work as expected.
+
+LibResilient *only* handles `GET` requests. This is by design. `POST` requests, websocket connections, and the like are left for the browser to handle. This is done to not interfere with website functionality that cannot be handled by LibResilient.
+
+This is explored more in depth [here](./PHILOSOPHY.md).
+
+Of course, any third-party dynamic interfaces (a comment section hanlded by a third party comment interface provider, a "chat with agent" provided by a third party, etc) should work fine. LibResilient only handles requests that go to the original domain.
+
+## Service workers
+
+### What is a service worker?
+
+Service worker is a piece of JavaScript code that is served by the website and registered with the browser, and runs whenever the user tries to visit a website. Service workers can do many things, but most importantly they can manage caches and they can handle `fetch` events. The latter means that the service worker for a given website can be made to handle *all* requests originating from that website, which would otherwise be handled by the browser's built-in `fetch` handler.
+
+More information on the Service Worker API [is available in MDN](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API).
+
+### Can the service worker be updated when the original domain is not accessible?
+
+No, it cannot. This is clearly specified in the API. Until the website on the original domain becomes available again, the code associated with the service worker cannot be updated or modified.
+
+In the context of LibResilient, this means that even when LibResilient is deployed on a website, and works as expected (pulling content from alternative endpoints or through alternative transports), as long as the original domain is down it is *impossible* to update the service worker or load new plugins.
+
+It is, however, possible to change LibResilient's configuration (including configuration of already loaded plugins), as `config.json` is not a JavaScript file and therefore it is *not* treated as code by browsers. You can read more on updating LibResilient's configuration during disruption [here](./UPDATING_DURING_DISRUPTION.md).
+
+### Can a buggy service worker be removed from clients?
+
+Yes, as long as the website on the original domain is up. The Service Worker API only allows installing, updating, and removing service workers for a given website from that website directly.
+
+### If the original domain is down and the service worker is buggy, how long until it gets automatically removed by the browser?
+
+Eventually the browser will remove a service worker. It is unlcear after how long, exactly, but probably a few weeks.
+
+### Can the service worker be deployed only for a specific subdirectory of a website?
+
+Yes, in two ways:
+
+ - Implicitly by simply placing the `libresilient.js` loader file and the `service-worker.js` service worker in a subdirectory of the website;
+ - By using the `scope` init parameter when registering the service worker; see the [`libresilient.js` loader script](../libresilient.js) for example how that parameter is used.
+
+Important note: the Service Worker API does not allow a service worker to handle any requests that originate higher in the directory structure than where the service worker script is hosted itself. In other words, a service worker script under `/some-place/service-worker.js` will *not* be allowed to handle requests for `/some-file.png`, nor `/other-place/index.html`.
+
+By using the `scope` parameter you can further limit the scope of Libresilient's service worker. For example, with the service worker script at `/some-place/service-worker.js` and scope set to `/some-place/go-deeper/`, LibResilient will *only* handle requests for `/some-place/go-deeper/` and below.
+
+### What if the original domain is irrevocably lost/made inaccessible, but the service worker makes the website still work for visitors who had visited before?
+
+The correct way to deal with that is by redirecting them to the new domain using the [`redirect` plugin](../plugins/redirect/).
+
+Crucially, that plugin needs to have been loaded by the service worker when the original website was still up. This means that if you expect that at some point the website might become permanently inaccessible, make sure to add the `redirect` plugin to your LibResilient `config.json` file, but set `enabled` configuration field for that plugin to `false`. That way the plugin code gets loaded into the service worker, but plugin is not actually used to handle any requests.
+
+This gives you the chance to update the `config.json` file when the website is down (using any of the alternative transport plugins that were configured and enabled) to enable the `redirect` plugin and configuring where the redirect should lead.
+
+A deeper dive into updating LibResilient during disruption is available [here](./UPDATING_DURING_DISRUPTION.md).
+

docs/QUICKSTART.md

@@ -241,7 +241,7 @@ The `alt-fetch` plugin *requires* the `endpoints` configuration key. That key co
 
 > #### Note on making content available on alternative entpoints
 > 
-> We need to also make sure that our content is available `https://example.gitlab.io/`.
+> We need to also make sure that our content is available at `https://example.gitlab.io/`.
 >
 > LibResilient can't really help with that, it's up to the website administrator to make sure that content ends up where it needs to be for LibResilient to be able to access and retrieve it.